A high-performance, fully asynchronous Python wrapper for libSQL, built with Rust and PyO3.

This is an async fork of the official libsql-python SDK, designed to fix database locking issues in asyncio applications like Discord bots.

• True Async/Await — All database operations are non-blocking coroutines
• High-Performance Connection Pool — Rust-native pooling with automatic read/write splitting
• True Concurrency — Round-robin multiple reader connections while writing
• Async Context Manager — async with await aiolibsql.connect(...) as conn:
• Thread-Safe — Uses Arc<Mutex> for concurrent access
• Multiple Backends — Local files, remote Turso, embedded replicas, encrypted databases
• Full Type Support — TEXT, INTEGER, REAL, BLOB, NULL
• DB-API 2.0 Style — Familiar execute, fetchone, fetchall, cursor interface
• SQLAlchemy Compatible — Use with create_engine("sqlite+aiolibsql://")

pip install "aiolibsql @ git+https://github.com/fuhnut/aiolibsql"

Since this package compiles native Rust code, you need the following installed:

import asyncio
import aiolibsql

async def main():
    async with await aiolibsql.connect("hello.db") as conn:
        await conn.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")
        await conn.execute("INSERT INTO users (name) VALUES (?)", ("Alice",))

        cursor = await conn.execute("SELECT * FROM users")
        rows = await cursor.fetchall()
        print(rows)

asyncio.run(main())

# Local file
conn = await aiolibsql.connect("data.db")

# In-memory
conn = await aiolibsql.connect(":memory:")

# Remote Turso
conn = await aiolibsql.connect("libsql://your-db.turso.io", auth_token="...")

# Embedded replica (local + remote sync)
conn = await aiolibsql.connect("local.db", sync_url="libsql://your-db.turso.io", auth_token="...")

# Encrypted local
conn = await aiolibsql.connect("secret.db", encryption_key="my-key")

# Connection Pool (Recommended for high load)
# Size=10 creates 1 writer + 9 reader connections
pool = await aiolibsql.create_pool("bot.db", size=10)

aiolibsql v0.2.0 introduces a native Rust ConnectionPool designed for major scalability on local .db files.

• Read/Write Splitting: SELECT queries are round-robbined across reader connections. INSERT/UPDATE/DELETE are funneled through a high-priority writer.
• Concurrent Reads: Multiple readers can run truly in parallel without blocking the writer (WAL mode).
• Atomic Batches: Use pool.executebatch() to group multiple writes into a single high-speed transaction.
• Auto-Optimization: Pools auto-apply optimal PRAGMAs (WAL, synchronous=NORMAL, mmap_size, etc.).

Estimated Scale: A single .db file can now comfortably support 2,000 - 3,000 discord servers (depending on hardware/IOPS) without SQLITE_BUSY errors.

aiolibsql includes a SQLAlchemy dialect. Use sqlite+aiolibsql:// as the connection URL:

import aiolibsql_sqlalchemy  # registers the dialect

from sqlalchemy import create_engine, text
from sqlalchemy.orm import Session

engine = create_engine("sqlite+aiolibsql://", echo=True)  # in-memory
# engine = create_engine("sqlite+aiolibsql:///data.db")    # local file

with Session(engine) as session:
    session.execute(text("CREATE TABLE t (x INTEGER)"))
    session.execute(text("INSERT INTO t VALUES (:x)"), {"x": 42})
    session.commit()
    result = session.execute(text("SELECT * FROM t"))
    print(result.fetchall())

See examples/sqlalchemy/ for a full ORM example.

1. Import: import aiolibsql instead of import libsql
2. Await everything: Every database call is a coroutine
3. Connection: aiolibsql.connect() returns a coroutine — use await
4. Context manager: Use async with instead of with

MIT