close
Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.turso.tech/llms.txt

Use this file to discover all available pages before exploring further.

Turso offers two Python packages:
pytursolibsql (legacy)
Use caseLocal / embedded database, syncLegacy — embedded replicas
EngineTurso Database (rewrite)libSQL (SQLite fork)
Concurrent writesYes (MVCC)Not supported
Syncpush/pull (true local-first)Embedded replicas (writes go to remote)
APIPython sqlite3-compatiblePython sqlite3-compatible
Starting a new project? Use pyturso — it is built on the Turso Database engine with better performance, concurrent writes, and true local-first sync.

​
pyturso

For local and embedded use. Built on the Turso Database engine with concurrent writes (MVCC) and async I/O.

​
Installing

pip install pyturso

​
Connecting

import turso

conn = turso.connect("app.db")
In-memory databases are also supported: 
conn = turso.connect(":memory:")

​
Querying

conn.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")
conn.execute("INSERT INTO users (name) VALUES (?)", ("Alice",))
conn.commit()

for row in conn.execute("SELECT * FROM users"):
    print(row)

​
Encryption

Encrypt local databases at rest using the encryption option: 
from turso import connect, EncryptionOpts

conn = connect("encrypted.db",
               experimental_features="encryption",
               encryption=EncryptionOpts(cipher="aegis256",
                                         hexkey="b1bbfda4f589dc9daaf004fe21111e00dc00c98237102f5c7002a5669fc76327"))
Supported ciphers: aegis256, aegis256x2, aegis128l, aegis128x2, aegis128x4, aes256gcm, aes128gcm. Encrypted databases cannot be read as standard SQLite databases — you must use the Turso Database engine to open them.
Turso Cloud databases can also be encrypted with bring-your-own-key — learn more.

​
libsql (Legacy)

The libsql package is built on libSQL, our open-source fork of SQLite that predated the Turso Database engine. It is fully supported — if you run into something that doesn’t work yet with pyturso, libsql is a reliable fallback.
With libsql embedded replicas, reads are local but writes go to the remote database. For true local-first writes with push/pull sync, use turso.sync — see the quickstart.

​
Embedded Replicas

For new projects, we recommend turso.sync for sync use cases — it is built on the Turso Database engine with better performance, true local-first writes, and concurrent write support. See the quickstart.
You can work with embedded replicas that can sync from the remote database to a local SQLite file, and delegate writes to the remote primary database: 
import os

import libsql

conn = libsql.connect("local.db", sync_url=os.getenv("LIBSQL_URL"),
                      auth_token=os.getenv("LIBSQL_AUTH_TOKEN"))
conn.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER);")
conn.execute("INSERT INTO users(id) VALUES (1);")
conn.commit()

print(conn.execute("select * from users").fetchall())
Embedded Replicas only works where you have access to the file system.

​
Periodic Sync

You can automatically sync at intervals by passing time in seconds to the sync_interval option. For example, to sync every minute, you can use the following code: 
conn = libsql.connect("local.db", sync_interval=60, sync_url=os.getenv("LIBSQL_URL"),
                      auth_token=os.getenv("LIBSQL_AUTH_TOKEN"))

​
Manual Sync

The Sync function allows you to sync manually the local database with the remote counterpart: 
conn.execute("INSERT INTO users(id) VALUES (2);")
conn.commit()
conn.sync()

​
Encryption

For new projects, we recommend pyturso for local encryption — it is built on the Turso Database engine with better performance and concurrent write support.
To enable encryption on a SQLite file, pass the encryption secret to the encryption_key option: 
conn = libsql.connect("encrypted.db", sync_url=os.getenv("LIBSQL_URL"),
                      auth_token=os.getenv("LIBSQL_AUTH_TOKEN"),
                      encryption_key=os.getenv("ENCRYPTION_KEY"))
Encrypted databases appear as raw data and cannot be read as standard SQLite databases. You must use the libSQL client for any operations — learn more.