> ## 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.

# Reference

> Python Reference for Turso

Turso offers two Python packages:

|                       | `pyturso`                       | `libsql`                                       |
| --------------------- | ------------------------------- | ---------------------------------------------- |
| **Use case**          | Local / embedded database, sync | Existing libSQL codebases                      |
| **Engine**            | Turso Database (rewrite)        | libSQL (SQLite fork)                           |
| **Concurrent writes** | Yes (MVCC)                      | Not supported                                  |
| **Sync**              | push/pull (local-first)         | Embedded Replicas (writes go to cloud primary) |
| **API**               | Python `sqlite3`-compatible     | Python `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

```bash theme={null}
pip install pyturso
```

### Connecting

```py theme={null}
import turso

conn = turso.connect("app.db")
```

In-memory databases are also supported:

```py theme={null}
conn = turso.connect(":memory:")
```

### Querying

```py theme={null}
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:

```py theme={null}
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.

<Info>
  Turso Cloud databases can also be encrypted with bring-your-own-key — [learn more](/cloud/encryption).
</Info>

## libsql (libSQL)

The `libsql` package is built on [libSQL](https://github.com/tursodatabase/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.

<Info>
  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](/sdk/python/quickstart).
</Info>

## Embedded Replicas

<Info>
  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](/sdk/python/quickstart).
</Info>

You can work with [embedded replicas](/features/embedded-replicas) that can sync from the remote database to a local SQLite file, and delegate writes to the remote primary database:

```py theme={null}
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())
```

<Snippet file="embedded-replicas-warning.mdx" />

### 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:

```py theme={null}
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:

```py theme={null}
conn.execute("INSERT INTO users(id) VALUES (2);")
conn.commit()
conn.sync()
```

## Encryption

<Warning>
  For new projects, we recommend [`pyturso`](#pyturso) for local encryption — it is built on the Turso Database engine with better performance and concurrent write support.
</Warning>

To enable encryption on a SQLite file, pass the encryption secret to the `encryption_key` option:

```py theme={null}
conn = libsql.connect("encrypted.db", sync_url=os.getenv("LIBSQL_URL"),
                      auth_token=os.getenv("LIBSQL_AUTH_TOKEN"),
                      encryption_key=os.getenv("ENCRYPTION_KEY"))
```

<Info>
  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](/libsql#encryption-at-rest).
</Info>