Add Usage Examples

examples/batch/.gitignore

@@ -0,0 +1 @@
+local.db-journal

examples/batch/README.md

@@ -0,0 +1,19 @@
+# Local
+
+This example demonstrates how to use libSQL to execute a batch of SQL statements.
+
+## Install Dependencies
+
+```bash
+pip install libsql-experimental
+```
+
+## Running
+
+Execute the example:
+
+```bash
+python3 main.py
+```
+
+This will create a local database, execute a batch of SQL statements (creating tables, inserting data, etc.), and then query the results.

examples/batch/main.py

@@ -0,0 +1,16 @@
+import libsql_experimental as libsql
+
+conn = libsql.connect("local.db")
+cur = conn.cursor()
+
+cur.executescript(
+    """
+        DROP TABLE IF EXISTS users;
+        CREATE TABLE users (id INTEGER, name TEXT);
+        INSERT INTO users VALUES (1, '[email protected]');
+        INSERT INTO users VALUES (2, '[email protected]');
+        INSERT INTO users VALUES (3, '[email protected]');
+    """
+)
+
+print(conn.execute("select * from users").fetchall())

examples/encryption/.gitignore

@@ -0,0 +1 @@
+local.db-journal

examples/encryption/README.md

@@ -0,0 +1,19 @@
+# Local
+
+This example demonstrates how to create and use an encrypted SQLite database with libSQL.
+
+## Install Dependencies
+
+```bash
+pip install libsql-experimental
+```
+
+## Running
+
+Execute the example:
+
+```bash
+python3 main.py
+```
+
+This will setup an encrypted SQLite database, execute a batch of SQL statements, and then query the results.

examples/encryption/main.py

@@ -0,0 +1,16 @@
+import libsql_experimental as libsql
+
+# You should set the ENCRYPTION_KEY in a environment variable
+# For demo purposes, we're using a fixed key
+encryption_key= "my-safe-encryption-key";
+
+conn = libsql.connect("local.db", encryption_key=encryption_key)
+cur = conn.cursor()
+
+conn.execute("CREATE TABLE IF NOT EXISTS users (name TEXT);")
+conn.execute("INSERT INTO users VALUES ('[email protected]');")
+conn.execute("INSERT INTO users VALUES ('[email protected]');")
+conn.execute("INSERT INTO users VALUES ('[email protected]');")
+
+
+print(conn.execute("select * from users").fetchall())

examples/local/.gitignore

@@ -0,0 +1 @@
+local.db-journal

examples/local/README.md

@@ -0,0 +1,19 @@
+# Local
+
+This example demonstrates how to use libSQL with a local SQLite file.
+
+## Install Dependencies
+
+```bash
+pip install libsql-experimental
+```
+
+## Running
+
+Execute the example:
+
+```bash
+python3 main.py
+```
+
+This will connect to a local SQLite, insert some data, and query it.

examples/local/main.py

@@ -0,0 +1,12 @@
+import libsql_experimental as libsql
+
+conn = libsql.connect("local.db")
+cur = conn.cursor()
+
+conn.execute("CREATE TABLE IF NOT EXISTS users (name TEXT);")
+conn.execute("INSERT INTO users VALUES ('[email protected]');")
+conn.execute("INSERT INTO users VALUES ('[email protected]');")
+conn.execute("INSERT INTO users VALUES ('[email protected]');")
+
+
+print(conn.execute("select * from users").fetchall())

examples/memory/README.md

@@ -0,0 +1,19 @@
+# Local
+
+This example demonstrates how to use libSQL with an in-memory SQLite database.
+
+## Install Dependencies
+
+```bash
+pip install libsql-experimental
+```
+
+## Running
+
+Execute the example:
+
+```bash
+python3 main.py
+```
+
+This will create an in-memory SQLite database, insert some data, and then query the results.

examples/memory/main.py

@@ -0,0 +1,12 @@
+import libsql_experimental as libsql
+
+conn = libsql.connect(":memory:")
+cur = conn.cursor()
+
+conn.execute("CREATE TABLE IF NOT EXISTS users (name TEXT);")
+conn.execute("INSERT INTO users VALUES ('[email protected]');")
+conn.execute("INSERT INTO users VALUES ('[email protected]');")
+conn.execute("INSERT INTO users VALUES ('[email protected]');")
+
+
+print(conn.execute("select * from users").fetchall())

examples/remote/README.md

@@ -0,0 +1,19 @@
+# Local
+
+This example demonstrates how to use libSQL with a remote database.
+
+## Install Dependencies
+
+```bash
+pip install libsql-experimental
+```
+
+## Running
+
+Execute the example:
+
+```bash
+TURSO_DATABASE_URL="..." TURSO_AUTH_TOKEN="..." python3 main.py
+```
+
+This will connect to a remote database, insert some data, and query it.

examples/remote/main.py

@@ -0,0 +1,18 @@
+import libsql_experimental as libsql
+import os
+
+url = os.getenv("TURSO_DATABASE_URL")
+auth_token = os.getenv("TURSO_AUTH_TOKEN")
+
+conn = libsql.connect(url, auth_token=auth_token)
+cur = conn.cursor()
+
+
+conn.execute("DROP TABLE IF EXISTS users;")
+conn.execute("CREATE TABLE IF NOT EXISTS users (name TEXT);")
+conn.execute("INSERT INTO users VALUES ('[email protected]');")
+conn.execute("INSERT INTO users VALUES ('[email protected]');")
+conn.execute("INSERT INTO users VALUES ('[email protected]');")
+
+
+print(conn.execute("select * from users").fetchall())

examples/sync/.gitignore

@@ -0,0 +1 @@
+local.db*

examples/sync/README.md

@@ -0,0 +1,19 @@
+# Local
+
+This example demonstrates how to use libSQL with a synced database (local file synced with a remote database).
+
+## Install Dependencies
+
+```bash
+pip install libsql-experimental
+```
+
+## Running
+
+Execute the example:
+
+```bash
+TURSO_DATABASE_URL="..." TURSO_AUTH_TOKEN="..." python3 main.py
+```
+
+This will create a local database file that syncs with a remote database, insert some data, and query it.

examples/sync/main.py

@@ -0,0 +1,19 @@
+import libsql_experimental as libsql
+import os
+
+url = os.getenv("TURSO_DATABASE_URL")
+auth_token = os.getenv("TURSO_AUTH_TOKEN")
+
+conn = libsql.connect("local.db", sync_url=url, auth_token=auth_token)
+conn.sync()
+
+cur = conn.cursor()
+
+conn.execute("DROP TABLE IF EXISTS users;")
+conn.execute("CREATE TABLE IF NOT EXISTS users (name TEXT);")
+conn.execute("INSERT INTO users VALUES ('[email protected]');")
+conn.execute("INSERT INTO users VALUES ('[email protected]');")
+conn.execute("INSERT INTO users VALUES ('[email protected]');")
+
+
+print(conn.execute("select * from users").fetchall())

examples/transaction/.gitignore

@@ -0,0 +1 @@
+local.db-journal

examples/transaction/README.md

@@ -0,0 +1,27 @@
+# Local
+
+This example demonstrates how to create and use an encrypted SQLite database with libSQL.
+
+## Install Dependencies
+
+```bash
+pip install libsql-experimental
+```
+
+## Running
+
+Execute the example:
+
+```bash
+python3 main.py
+```
+
+This example will:
+
+1. Create a new table called `users`.
+2. Start a transaction.
+3. Insert multiple users within the transaction.
+4. Demonstrate how to rollback a transaction.
+5. Start another transaction.
+6. Insert more users and commit the transaction.
+7. Query and display the final state of the `users` table.

examples/transaction/main.py

@@ -0,0 +1,15 @@
+import libsql_experimental as libsql
+
+conn = libsql.connect("local.db")
+cur = conn.cursor()
+
+conn.execute("DROP TABLE IF EXISTS users")
+conn.execute("CREATE TABLE users (name TEXT);")
+conn.execute("INSERT INTO users VALUES ('[email protected]');")
+conn.execute("INSERT INTO users VALUES ('[email protected]');")
+
+conn.rollback()
+
+conn.execute("INSERT INTO users VALUES ('[email protected]');")
+
+print(conn.execute("select * from users").fetchall())

examples/vector/.gitignore

@@ -0,0 +1 @@
+local.db-journal

examples/vector/README.md

@@ -0,0 +1,19 @@
+# Local
+
+This example demonstrates how to use libSQL vector search with a local database.
+
+## Install Dependencies
+
+```bash
+pip install libsql-experimental
+```
+
+## Running
+
+Execute the example:
+
+```bash
+python3 main.py
+```
+
+This will setup a local SQLite database, insert some data, and then query the results using the vector similarity search function.

examples/vector/main.py

@@ -0,0 +1,10 @@
+import libsql_experimental as libsql
+
+conn = libsql.connect("local.db")
+
+conn.execute("DROP TABLE IF EXISTS movies")
+conn.execute("CREATE TABLE IF NOT EXISTS movies (title TEXT, year INT, embedding F32_BLOB(3))")
+conn.execute("CREATE INDEX movies_idx ON movies (libsql_vector_idx(embedding))")
+conn.execute("INSERT INTO movies (title, year, embedding) VALUES ('Napoleon', 2023, vector32('[1,2,3]')), ('Black Hawk Down', 2001, vector32('[10,11,12]')), ('Gladiator', 2000, vector32('[7,8,9]')), ('Blade Runner', 1982, vector32('[4,5,6]'))")
+
+print(conn.execute("SELECT title, year FROM vector_top_k('movies_idx', '[4,5,6]', 3) JOIN movies ON movies.rowid = id").fetchall())