Skip to content

Commit 4bd2bb6

Browse files
glommerclaude
glommer
and
claude
committed
Add new Turso package documentation and Python quickstart rewrite
- Add package decision table to introduction.mdx (with libsql for Python remote) - Add @tursodatabase/database, sync, serverless sections to reference.mdx - Move @libsql/client to Legacy section in reference.mdx - Restructure TS quickstart to lead with database (local) then serverless (remote) - Fix async await on database prepare().run()/all() and serverless conn.prepare() - Rewrite Python quickstart: lead with pyturso, add turso.sync, add libsql remote - Use uv as primary install method in Python quickstart - Note Drizzle ORM support for @tursodatabase/database - Add context about libSQL as battle-tested fallback Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent c7f42cd commit 4bd2bb6

File tree

5 files changed

+528
-199
lines changed

5 files changed

+528
-199
lines changed

‎sdk/introduction.mdx‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,35 @@
11
---
22
sidebarTitle: Introduction
3-
title: Turso Cloud SDKs
3+
title: Turso SDKs
44
---
55

6-
Turso provides multiple SDKs that you can use to connect a local SQLite file or remote Turso Cloud database, as well as support for embedded databases. If you're using a language or framework that isn't supported with an official driver, you can use Turso over HTTP.
6+
## Which package should I use?
7+
8+
| Use case | TypeScript | Python |
9+
| --- | --- | --- |
10+
| **Local database** (embedded, on-device, offline) | `@tursodatabase/database` | `pyturso` |
11+
| **Local database + cloud sync** (push/pull) | `@tursodatabase/sync` | `pyturso` (with sync) |
12+
| **Remote access** (servers, Docker, serverless, edge — any over-the-wire) | `@tursodatabase/serverless` | `libsql` |
13+
| **Legacy (libSQL)** — battle-tested, ORM support | `@libsql/client` | `libsql` |
14+
15+
**Starting a new project?** Use `@tursodatabase/database` (TypeScript) or `pyturso` (Python). These are built on the Turso Database engine — the ground-up rewrite of SQLite with concurrent writes, async I/O, and true local-first sync.
16+
17+
**Need sync?** Use [Turso Sync](/sync/usage) for local reads and writes with explicit `push()` / `pull()` to Turso Cloud.
18+
19+
**Migrating from SQLite?** Turso Database is a drop-in replacement. Your existing SQL, schema, and queries work unchanged.
20+
21+
**Already using `@libsql/client` or `libsql`?** These packages are built on [libSQL](https://github.com/tursodatabase/libsql), our open-source fork of SQLite that predated the Turso Database engine. They are fully supported and battle-tested. Consider migrating to the Turso Database packages for better sync support and concurrent writes — but if you run into something that doesn't work yet with the newer packages, `@libsql/client` and `libsql` are reliable fallbacks.
22+
23+
### Why multiple packages in TypeScript?
24+
25+
Keeping `@tursodatabase/database` and `@tursodatabase/serverless` separate means minimal bundle size. `@tursodatabase/serverless` uses only `fetch` — zero native dependencies, so it works in Node.js, Docker containers, serverless functions, edge runtimes, and browsers.
726

827
<Info>
928
**Need sync?** If you want local reads and writes with push/pull sync to the cloud, use [Turso Sync](/sync/usage). The SDKs below connect to Turso Cloud using libSQL, where embedded replica sync only replicates reads locally — writes go to the cloud.
1029
</Info>
1130

1231
## Official SDKs
1332

14-
Turso SDKs are fully compatible with [libSQL](/libsql), so you can use the same SDK to connect to a local database ([SQLite](/local-development#sqlite)), [libSQL server](/local-development#libsql-server), a remote database, or an [embedded replica](/features/embedded-replicas).
15-
1633
<Snippet file="official-sdks.mdx" />
1734

1835
## Community SDKs

‎sdk/python/quickstart.mdx‎

Lines changed: 101 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,97 +1,147 @@
11
---
22
title: Turso Quickstart (Python)
33
sidebarTitle: Quickstart
4-
description: Get started with Turso and Python using the libSQL client in a few simple steps.
4+
description: Get started with Turso and Python in a few simple steps.
55
---
66

77
In this Python quickstart we will learn how to:
88

9-
- Retrieve database credentials
10-
- Install the libSQL package
11-
- Connect to a Turso database
9+
- Install the Turso package
10+
- Connect to a local or remote database
1211
- Execute a query using SQL
1312
- Sync changes to local database
1413

14+
## Recommended: pyturso (Local / Embedded)
15+
16+
`pyturso` is the recommended package for local and embedded use cases. It is built on the Turso Database engine — a ground-up rewrite of SQLite with concurrent writes (MVCC) and async I/O. The API follows the standard Python `sqlite3` interface, so it works as a drop-in replacement.
17+
1518
<Steps>
16-
<Step title="Retrieve database credentials">
19+
<Step title="Install">
1720

18-
You will need an existing database to continue. If you don't have one, [create one](/quickstart).
21+
```bash
22+
uv add pyturso
23+
```
1924

20-
<Snippet file="retrieve-database-credentials.mdx" />
25+
Or with pip:
2126

22-
<Info>You will want to store these as environment variables.</Info>
27+
```bash
28+
pip install pyturso
29+
```
2330

2431
</Step>
32+
<Step title="Connect">
2533

26-
<Step title="Install">
34+
```py
35+
import turso
2736

28-
First begin by adding libSQL to your project:
37+
db = turso.connect("app.db")
38+
```
2939

30-
```bash
31-
pip install libsql
32-
```
40+
In-memory databases are also supported:
41+
42+
```py
43+
db = turso.connect(":memory:")
44+
```
3345

3446
</Step>
47+
<Step title="Execute">
3548

36-
<Step title="Connect">
49+
```py
50+
db.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")
51+
db.execute("INSERT INTO users (name) VALUES (?)", ("Alice",))
52+
db.commit()
53+
54+
for row in db.execute("SELECT * FROM users"):
55+
print(row)
56+
```
57+
58+
</Step>
59+
<Step title="Sync (push and pull)">
60+
61+
If you need to sync your local database with Turso Cloud, use `turso.sync`:
62+
63+
```py
64+
import os
65+
import turso.sync
3766

38-
Then import the package:
67+
db = turso.sync.connect(
68+
"app.db",
69+
remote_url=os.environ["TURSO_DATABASE_URL"],
70+
auth_token=os.environ["TURSO_AUTH_TOKEN"],
71+
)
3972

40-
```py
41-
import libsql
42-
```
73+
db.execute("INSERT INTO users (name) VALUES (?)", ("Bob",))
74+
db.commit()
4375

44-
Now connect to your local or remote database using the libSQL connector:
76+
# Push local writes to Turso Cloud
77+
db.push()
4578

46-
<AccordionGroup>
47-
<Accordion title="Embedded Replicas">
48-
```py
49-
url = os.getenv("TURSO_DATABASE_URL")
50-
auth_token = os.getenv("TURSO_AUTH_TOKEN")
79+
# Pull remote changes to local database
80+
db.pull()
81+
```
5182

52-
conn = libsql.connect("hello.db", sync_url=url, auth_token=auth_token)
53-
conn.sync()
54-
```
83+
All reads and writes happen against the local database file — fast, offline-capable. `push()` sends your changes to the cloud. `pull()` brings remote changes down. See [Turso Sync](/sync/usage) for details on conflict resolution, checkpointing, and more.
5584

56-
</Accordion>
85+
</Step>
86+
</Steps>
5787

58-
<Accordion title="Local only">
59-
```py
60-
conn = libsql.connect("hello.db")
61-
cur = conn.cursor()
62-
```
88+
## Remote Access (Over-the-Wire)
6389

64-
</Accordion>
90+
If your application needs to query a Turso Cloud database directly over the network (e.g., from a web server or serverless function), you can use the `libsql` package. It connects to your database via HTTP — no local file needed.
6591

66-
{/* <Accordion title="Remote only">
67-
```py
68-
url = os.getenv("TURSO_DATABASE_URL")
69-
auth_token = os.getenv("TURSO_AUTH_TOKEN")
92+
<Info>
7093

71-
conn = libsql.connect(database=url, auth_token=auth_token)
72-
```
94+
For most applications, we recommend running a local database with [Turso Sync](/sync/usage) (`turso.sync`) instead — it gives you faster reads, offline support, and lower latency. Remote access is useful when you cannot store a local database file (e.g., stateless serverless environments).
7395

74-
</Accordion> */}
75-
</AccordionGroup>
96+
</Info>
7697

77-
</Step>
98+
<Steps>
99+
<Step title="Retrieve database credentials">
78100

79-
<Step title="Execute">
101+
You will need an existing database to continue. If you don't have one, [create one](/quickstart).
80102

81-
You can execute SQL queries against your existing database as follows:
103+
<Snippet file="retrieve-database-credentials.mdx" />
82104

83-
```py
84-
conn.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER);")
85-
conn.execute("INSERT INTO users(id) VALUES (10);")
105+
<Info>You will want to store these as environment variables.</Info>
86106

87-
print(conn.execute("select * from users").fetchall())
107+
</Step>
108+
<Step title="Install">
109+
110+
```bash
111+
uv add libsql
112+
```
113+
114+
Or with pip:
115+
116+
```bash
117+
pip install libsql
88118
```
89119

90120
</Step>
121+
<Step title="Connect and query">
122+
123+
```py
124+
import os
125+
import libsql
126+
127+
conn = libsql.connect(
128+
database=os.environ["TURSO_DATABASE_URL"],
129+
auth_token=os.environ["TURSO_AUTH_TOKEN"],
130+
)
91131

92-
<Step title="Sync">
132+
conn.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")
133+
conn.execute("INSERT INTO users (name) VALUES (?)", ("Alice",))
134+
conn.commit()
93135

94-
If you need to sync your local database with a remote Turso Cloud database (local reads and writes with push/pull to the cloud), use [Turso Sync](/sync/usage). Turso Sync is built on the Turso Database engine and provides true local-first sync with explicit `push()` and `pull()` operations.
136+
rows = conn.execute("SELECT * FROM users").fetchall()
137+
print(rows)
138+
```
95139

96140
</Step>
97141
</Steps>
142+
143+
## Legacy: libsql (Embedded Replicas)
144+
145+
The `libsql` package also supports embedded replicas, where reads are local but **writes go to the remote database**. For true local-first writes with push/pull sync, use `turso.sync` instead.
146+
147+
See the [reference](/sdk/python/reference) for full documentation on embedded replicas, encryption, and periodic sync.

‎sdk/python/reference.mdx‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,96 @@
11
---
22
title: Reference
3+
description: Python Reference for Turso
34
---
45

6+
Turso offers two Python packages:
7+
8+
| | `pyturso` | `libsql` (legacy) |
9+
| --- | --- | --- |
10+
| **Use case** | Local / embedded database, sync | Legacy — embedded replicas |
11+
| **Engine** | Turso Database (rewrite) | libSQL (SQLite fork) |
12+
| **Concurrent writes** | Yes (MVCC) | Not supported |
13+
| **Sync** | push/pull (true local-first) | Embedded replicas (writes go to remote) |
14+
| **API** | Python `sqlite3`-compatible | Python `sqlite3`-compatible |
15+
16+
**Starting a new project?** Use `pyturso` — it is built on the Turso Database engine with better performance, concurrent writes, and true local-first sync.
17+
18+
## pyturso
19+
20+
For local and embedded use. Built on the Turso Database engine with concurrent writes (MVCC) and async I/O.
21+
22+
### Installing
23+
24+
```bash
25+
pip install pyturso
26+
```
27+
28+
### Connecting
29+
30+
```py
31+
import turso
32+
33+
conn = turso.connect("app.db")
34+
```
35+
36+
In-memory databases are also supported:
37+
38+
```py
39+
conn = turso.connect(":memory:")
40+
```
41+
42+
### Querying
43+
44+
```py
45+
conn.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")
46+
conn.execute("INSERT INTO users (name) VALUES (?)", ("Alice",))
47+
conn.commit()
48+
49+
for row in conn.execute("SELECT * FROM users"):
50+
print(row)
51+
```
52+
53+
### Encryption
54+
55+
Encrypt local databases at rest using the `encryption` option:
56+
57+
```py
58+
from turso import connect, EncryptionOpts
59+
60+
conn = connect("encrypted.db",
61+
experimental_features="encryption",
62+
encryption=EncryptionOpts(cipher="aegis256",
63+
hexkey="b1bbfda4f589dc9daaf004fe21111e00dc00c98237102f5c7002a5669fc76327"))
64+
```
65+
66+
Supported ciphers: `aegis256`, `aegis256x2`, `aegis128l`, `aegis128x2`, `aegis128x4`, `aes256gcm`, `aes128gcm`.
67+
68+
Encrypted databases cannot be read as standard SQLite databases — you must use the Turso Database engine to open them.
69+
70+
<Info>
71+
72+
Turso Cloud databases can also be encrypted with bring-your-own-key — [learn more](/cloud/encryption).
73+
74+
</Info>
75+
76+
## libsql (Legacy)
77+
78+
The `libsql` package is built on [libSQL](https://github.com/tursodatabase/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.
79+
80+
<Info>
81+
82+
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](/sdk/python/quickstart).
83+
84+
</Info>
85+
586
## Embedded Replicas
687

88+
<Warning>
89+
90+
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](/sdk/python/quickstart).
91+
92+
</Warning>
93+
794
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:
895

996
```py
@@ -43,6 +130,12 @@ conn.sync()
43130

44131
## Encryption
45132

133+
<Warning>
134+
135+
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.
136+
137+
</Warning>
138+
46139
To enable encryption on a SQLite file, pass the encryption secret to the `encryption_key` option:
47140

48141
```py

0 commit comments

Comments
 (0)