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
Use caseLocal / embedded database, syncExisting libSQL codebases
EngineTurso Database (rewrite)libSQL (SQLite fork)
Concurrent writesYes (MVCC)Not supported
Syncpush/pull (local-first)Embedded Replicas (writes go to cloud primary)
APIPython sqlite3-compatiblePython sqlite3-compatible
Starting a new project? Use pyturso — it is built on the Turso Database engine with concurrent writes and 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 (libSQL)

The libsql package is built on libSQL, the open-source fork of SQLite that powers Turso Cloud today. It is production-ready and battle-tested, and is the right choice when you are working with an existing libsql-based codebase.
With libsql Embedded Replicas, reads are local and writes are sent to the cloud primary, then reflected back to the replica. Embedded Replicas are fully supported. For new projects that need sync, we recommend turso.sync — see the quickstart.

​
Embedded Replicas

For workloads that need offline writes, bidirectional sync, or multi-writer convergence, we recommend turso.sync — both reads and writes are local, and you sync explicitly with push() / pull(). 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.