DOCSEARCHbyAlgolia
Submit Docs

libSQL Python SDK

repository·main·Indexed 42 days ago

https://github.com/tursodatabase/libsql-python

Python SDK (pylibsql v0.1.11) for interacting with Turso and libSQL databases. Supports executing SQL queries against local SQLite files, in-memory databases, and remote Turso instances. Features include batch operations, encrypted SQLite databases, remote synchronization, vector similarity search, and transaction management via Connection context managers.

Tokens
3.9K
Snippets
19
Records
23
Agent score
52%

What's inside libSQL

  1. Overview of Turso and libSQL

    main

    Turso is a SQLite-compatible database built on libSQL, which is an Open Contribution fork of SQLite. It is designed for production use, enabling organizations to scale to hundreds of thousands of databases and supporting replication to any location (including your own servers) to achieve microsecond-latency access. Key features include:

    • Embedded Replicas: Local replicas for low-latency access.
    • Platform API: Programmatic control over your databases.
    • Branching: Creating isolated environments for database changes.
    • Point-in-Time Recovery: Restoring databases to specific moments in time.

  2. Manage transactions using Connection context managers

    main

    Connection objects can be used as context managers to ensure transactions are handled safely. This behavior is compatible with Python's sqlite3 module:

    • Successful exit: If the block completes without an exception, the transaction is automatically committed.
    • Exception exit: If an exception occurs within the block, the transaction is automatically rolled back.

    Context managers work in both transactional and autocommit modes. If you manually call commit() or rollback() inside the context, the context manager will still apply its logic (commit or rollback) to any active transaction upon exiting.

    import libsql

with libsql.connect("example.db") as conn:
    conn.execute("INSERT INTO users (name) VALUES (?)", ("Alice",))
    # Transaction is committed automatically here

# Example with rollback on error
try:
    with libsql.connect("example.db") as conn:
        conn.execute("INSERT INTO users (name) VALUES (?)", ("Bob",))
        raise ValueError("Something went wrong")
except ValueError:
    # Transaction was automatically rolled back
    pass

  4. Run the libSQL local sync example

    main

    This example demonstrates how to use libSQL to manage a local database file that is synchronized with a remote database. The process involves creating a local file, syncing it with the remote instance, inserting data, and performing queries.

    # Install the library
pip install libsql

# Run the sync example with your remote credentials
TURSO_DATABASE_URL="..." TURSO_AUTH_TOKEN="..." python3 main.py

  5. Use libSQL vector search with a local database

    main

    This example demonstrates how to perform vector similarity searches using a local libSQL database. The process involves setting up a local SQLite database, inserting vector data, and executing queries using vector similarity search functions.

    # Install the required package
pip install libsql

# Run the vector search example
python3 main.py

  6. Use libSQL with an in-memory SQLite database

    main

    You can use libsql to manage an in-memory SQLite database. This is useful for testing or transient data storage where you do not need to persist the database to disk. The workflow typically involves creating the in-memory database, inserting data, and performing queries.

    # Install the package
pip install libsql

# Run the example
python3 main.py

  11. Configure transaction behavior with isolation_level

    main

    The isolation_level property controls how transactions are handled:

    • "DEFERRED", "IMMEDIATE", or "EXCLUSIVE": Transactions begin implicitly and must be committed manually.
    • None: The database operates in auto-commit mode, where every individual statement is executed in its own transaction.

  12. Use transactions in libSQL

    main

    This example demonstrates the lifecycle of a transaction using libSQL, including creating tables, performing multiple inserts, rolling back changes, and committing changes.

    Typical workflow demonstrated:

    1. Create a table (e.g., users).
    2. Start a transaction.
    3. Perform multiple operations (e.g., INSERT).
    4. Rollback the transaction if needed to undo changes.
    5. Start a new transaction and COMMIT to persist changes.
    6. Query the database to verify the final state.
    python3 main.py