README.md

libSQL API for Python

libSQL is an open source, open contribution fork of SQLite. We aim to evolve it to suit many more use cases than SQLite was originally designed for.

This source repository contains libSQL API bindings for Python, which aim to be compatible with the sqlite3 module.

Install

You can install the current release (MacOS and Linux):

$ pip install libsql-experimental

Documentation

• API reference

Getting Started

To try out your first libsql program, start the Python interpreter:

$ python

and then:

>>> import libsql_experimental as libsql
>>> con = libsql.connect("hello.db")
>>> cur = con.cursor()
>>> cur.execute("CREATE TABLE users (id INTEGER, email TEXT);")
<builtins.Result object at 0x102dcf8d0>
>>> cur.execute("INSERT INTO users VALUES (1, '[email protected]')")
<builtins.Result object at 0x102dcf4b0>
>>> cur.execute("SELECT * FROM users").fetchone()
(1, '[email protected]')

Connecting to a database

import libsql_experimental as libsql

con = libsql.connect("hello.db")
cur = con.cursor()

Remote database

import libsql_experimental as libsql

url = os.getenv("LIBSQL_URL")
auth_token = os.getenv("LIBSQL_AUTH_TOKEN")

con = libsql.connect(database=url, auth_token=auth_token)
cur = con.cursor()

Embedded replica

import libsql_experimental as libsql

url = os.getenv("LIBSQL_URL")
auth_token = os.getenv("LIBSQL_AUTH_TOKEN")

con = libsql.connect("hello.db", sync_url=url, auth_token=auth_token)
con.sync()

Creating a table

cur.execute("CREATE TABLE users (id INTEGER, email TEXT);")

Inserting rows into a table

cur.execute("INSERT INTO users VALUES (1, '[email protected]')")

Querying rows from a table

print(cur.execute("SELECT * FROM users").fetchone())

Developing

Setup the development environment:

python3 -m venv .env
source .env/bin/activate
pip3 install maturin pyperf pytest

Or you can use NIX to drop you into a shell with everything installed

nix-shell

Build the development version and use it:

maturin develop && python3 example.py

Run the tests:

pytest

Run the libSQL benchmarks:

python3 perf-libsql.py

Run the SQLite benchmarks for comparison:

python3 perf-sqlite3.py

License

This project is licensed under the MIT license.

Contribution

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