Skip to main content

Python SDK for libSQL

Project description

Python SDK for libSQL

API reference | Github | PyPI

This is the source repository of the Python SDK for libSQL. You can either connect to a local SQLite database or to a remote libSQL server (sqld).

NOTE: If you want to use libSQL with SQLAlchemy, you should check out the libSQL dialect.


pip install libsql-client

Getting Started

Connecting to a local SQLite database:

import asyncio
import libsql_client

async def main():
    url = "file:local.db"
    async with libsql_client.create_client(url) as client:
        result_set = await client.execute("SELECT * from users")
        print(len(result_set.rows), "rows")
        for row in result_set.rows:

To connect to a remote libSQL server (sqld), just change the URL:

url = "ws://localhost:8080"

Supported URLs

The client can connect to the database using different methods depending on the scheme (protocol) of the passed URL:

  • file: connects to a local SQLite database (using the builtin sqlite3 package)
    • file:/absolute/path or file:///absolute/path is an absolute path on local filesystem
    • file:relative/path is a relative path on local filesystem
    • (file://path is not a valid URL)
  • ws: or wss: connect to sqld using WebSockets (the Hrana protocol).
  • http: or https: connect to sqld using HTTP. The transaction() API is not available in this case.
  • libsql: is equivalent to wss:.

Synchronous API

This package also provides a synchronous version of the client, which can be created by calling create_client_sync(). It supports the same methods as the default asyncio client, except that they block the calling thread:

import libsql_client

url = "file:local.db"
with libsql_client.create_client_sync(url) as client:
    result_set = client.execute("SELECT * from users")
    print(len(result_set.rows), "rows")
    for row in result_set.rows:

The synchronous client is just a thin wrapper around the asynchronous client, but it runs the event loop in a background thread.

Contributing to this package

First, please install Python and Poetry. To install all dependencies for local development to a virtual environment, run:

poetry install --with dev

To run the tests, use:

poetry run pytest

To check types with MyPy, use:

poetry run mypy


This project is licensed under the MIT license.


Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in libsql-client by you, shall be licensed as MIT, without any additional terms or conditions.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

libsql_client-0.3.1.tar.gz (39.6 kB view hashes)

Uploaded Source

Built Distribution

libsql_client-0.3.1-py3-none-any.whl (46.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page