refactor(turso): migrate from libsql-client to libsql package (#37)

* refactor(turso): migrate from libsql-client to libsql package

libsql-client is deprecated; switch to the new libsql package with
updated API patterns (connect instead of create_client_sync, cursor-based
query execution with fetchall/description instead of result.rows).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(turso): use direct HTTP mode and add commit() for write persistence

The libsql package has two connection modes:
1. Embedded replica mode (local file + sync_url) - for read-heavy caching
2. Direct HTTP mode (url only) - for immediate read/write operations

The previous implementation used embedded replica mode which:
- Writes to a local temp file that gets deleted on close
- sync() only pulls FROM server, doesn't push writes back
- Missing commit() meant writes weren't persisted

This fix:
- Uses direct HTTP mode: libsql.connect(url, auth_token=token)
- Adds conn.commit() in execute_non_query() like all other adapters
- Converts libsql:// URLs to https:// as required by the package

Tested against both Turso Cloud and local Docker (libsql-server).

* fix(tests): update Turso fixtures to use direct HTTP mode

Update test fixtures to match the adapter's direct HTTP mode:
- _create_turso_connection() now uses libsql.connect(url, auth_token=token)
- _setup_turso_test_tables() uses commit() instead of sync()
- _cleanup_turso_test_tables() uses commit() instead of sync()

This ensures test setup/teardown works consistently with the adapter
for both Turso Cloud and local Docker environments.

* test(turso): add write persistence test and fix cloud mode handling

- Add test_write_persistence_across_connections() to verify writes
  persist to the remote server across separate connections
- Fix test_create_turso_connection() to handle cloud mode (tuple)
- Fix test_delete_turso_connection() to handle cloud mode (tuple)
- Add test_expand_tables_folder(), test_expand_table_node(), and
  test_expand_views_folder() to test tree expansion operations

The persistence test catches the bug where embedded replica mode
doesn't actually persist writes to the remote server.

* chore: add .env.example and protect secrets in tests/.env

- Add tests/.env to .gitignore to prevent accidental commit of secrets
- Add tests/.env.example as template for Turso Cloud configuration

To test against Turso Cloud instead of local Docker:
1. Copy tests/.env.example to tests/.env
2. Fill in your Turso Cloud URL and auth token
3. Run: pytest tests/test_turso.py -v

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Peter Adams <18162810+Maxteabag@users.noreply.github.com>

Author: 3 people

.github/workflows/ci.yml

@@ -576,7 +576,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install -e ".[test]"
-          pip install libsql-client
+          pip install libsql
 
       - name: Start Turso (libsql-server)
         run: |

.gitignore

@@ -57,3 +57,6 @@ assets/favorites/*
 !assets/favorites/logo_sqlit.png
 .worktrees/
 .obsidian/
+
+# Test environment files with secrets
+tests/.env

README.md

@@ -245,7 +245,7 @@ Most of the time you can just run `sqlit` and connect. If a Python driver is mis
 | Oracle                              | `oracledb`                   | `pipx inject sqlit-tui oracledb`                   | `python -m pip install oracledb`                   |
 | DuckDB                              | `duckdb`                     | `pipx inject sqlit-tui duckdb`                     | `python -m pip install duckdb`                     |
 | ClickHouse                          | `clickhouse-connect`         | `pipx inject sqlit-tui clickhouse-connect`         | `python -m pip install clickhouse-connect`         |
-| Turso                               | `libsql-client`              | `pipx inject sqlit-tui libsql-client`              | `python -m pip install libsql-client`              |
+| Turso                               | `libsql`                     | `pipx inject sqlit-tui libsql`                     | `python -m pip install libsql`                     |
 | Cloudflare D1                       | `requests`                   | `pipx inject sqlit-tui requests`                   | `python -m pip install requests`                   |
 | Snowflake                           | `snowflake-connector-python` | `pipx inject sqlit-tui snowflake-connector-python` | `python -m pip install snowflake-connector-python` |
 | Firebird                            | `firebirdsql`                | `pipx inject sqlit-tui firebirdsql`                | `python -m pip install firebirdsql`                |

pyproject.toml

@@ -44,7 +44,7 @@ all = [
     "duckdb>=1.1.0",  # min avoids known CVEs
     "clickhouse-connect>=0.7.0",
     "requests>=2.32.4",  # min avoids known CVEs
-    "libsql-client>=0.1.0",
+    "libsql>=0.1.0",
     "firebirdsql>=1.3.5",
     "sshtunnel>=0.4.0",
     "paramiko>=2.0.0,<4.0.0",
@@ -59,7 +59,7 @@ oracle = ["oracledb>=2.0.0"]
 duckdb = ["duckdb>=1.1.0"]  # min avoids known CVEs
 clickhouse = ["clickhouse-connect>=0.7.0"]
 d1 = ["requests>=2.32.4"]  # min avoids known CVEs
-turso = ["libsql-client>=0.1.0"]
+turso = ["libsql>=0.1.0"]
 firebird = ["firebirdsql>=1.3.5"]
 snowflake = ["snowflake-connector-python>=3.7.0"]
 ssh = [
@@ -158,7 +158,7 @@ module = [
     "oracledb",
     "duckdb",
     "clickhouse_connect",
-    "libsql_client",
+    "libsql",
     "snowflake.connector",
     "sshtunnel",
     "docker",

sqlit/db/adapters/turso.py

@@ -1,4 +1,4 @@
-"""Turso adapter using libsql-client."""
+"""Turso adapter using libsql."""
 
 from __future__ import annotations
 
@@ -13,7 +13,7 @@
 class TursoAdapter(DatabaseAdapter):
     """Adapter for Turso (libSQL) databases.
 
-    Turso is a distributed SQLite-compatible database. Uses the libsql_client
+    Turso is a distributed SQLite-compatible database. Uses the libsql
     package for connections via HTTP/HTTPS URLs with optional token authentication.
     """
 
@@ -67,11 +67,11 @@ def install_extra(self) -> str:
 
     @property
     def install_package(self) -> str:
-        return "libsql-client"
+        return "libsql"
 
     @property
     def driver_import_names(self) -> tuple[str, ...]:
-        return ("libsql_client",)
+        return ("libsql",)
 
     @property
     def supports_multiple_databases(self) -> bool:
@@ -92,69 +92,71 @@ def connect(self, config: ConnectionConfig) -> Any:
         """Connect to Turso database.
 
         Uses config.server for the database URL and config.password for the auth token.
-        Supports libsql://, https://, and http:// URLs.
+        Accepts libsql://, https://, and http:// URLs (libsql:// is converted to https://).
+        Uses direct HTTP mode for immediate read/write operations.
         """
-        libsql_client = import_driver_module(
-            "libsql_client",
+        libsql = import_driver_module(
+            "libsql",
             driver_name=self.name,
             extra_name=self.install_extra,
             package_name=self.install_package,
         )
 
         url = config.server
-        # Ensure URL has proper scheme
-        if not url.startswith(("libsql://", "https://", "http://")):
-            url = f"libsql://{url}"
+        # Convert URL scheme (libsql package requires http:// or https://)
+        if url.startswith("libsql://"):
+            url = url.replace("libsql://", "https://", 1)
+        elif not url.startswith(("https://", "http://")):
+            url = f"https://{url}"
 
-        auth_token = config.password if config.password else None
-        client = libsql_client.create_client_sync(url, auth_token=auth_token)
-        return client
+        auth_token = config.password if config.password else ""
+        return libsql.connect(url, auth_token=auth_token)
 
     def get_databases(self, conn: Any) -> list[str]:
         """Turso doesn't support multiple databases - return empty list."""
         return []
 
     def get_tables(self, conn: Any, database: str | None = None) -> list[TableInfo]:
         """Get list of tables from Turso. Returns (schema, name) with empty schema."""
-        result = conn.execute(
+        rows = conn.execute(
             "SELECT name FROM sqlite_master WHERE type='table' "
             "AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '_litestream_%' "
             "ORDER BY name"
-        )
-        return [("", row[0]) for row in result.rows]
+        ).fetchall()
+        return [("", row[0]) for row in rows]
 
     def get_views(self, conn: Any, database: str | None = None) -> list[TableInfo]:
         """Get list of views from Turso. Returns (schema, name) with empty schema."""
-        result = conn.execute("SELECT name FROM sqlite_master WHERE type='view' ORDER BY name")
-        return [("", row[0]) for row in result.rows]
+        rows = conn.execute("SELECT name FROM sqlite_master WHERE type='view' ORDER BY name").fetchall()
+        return [("", row[0]) for row in rows]
 
     def get_columns(
         self, conn: Any, table: str, database: str | None = None, schema: str | None = None
     ) -> list[ColumnInfo]:
         """Get columns for a table from Turso. Schema parameter is ignored."""
         quoted_table = self.quote_identifier(table)
-        result = conn.execute(f"PRAGMA table_info({quoted_table})")
+        rows = conn.execute(f"PRAGMA table_info({quoted_table})").fetchall()
         # PRAGMA table_info returns: cid, name, type, notnull, dflt_value, pk
         # pk > 0 indicates column is part of primary key
-        return [ColumnInfo(name=row[1], data_type=row[2] or "TEXT", is_primary_key=row[5] > 0) for row in result.rows]
+        return [ColumnInfo(name=row[1], data_type=row[2] or "TEXT", is_primary_key=row[5] > 0) for row in rows]
 
     def get_procedures(self, conn: Any, database: str | None = None) -> list[str]:
         """Turso doesn't support stored procedures - return empty list."""
         return []
 
     def get_indexes(self, conn: Any, database: str | None = None) -> list[IndexInfo]:
         """Get indexes from Turso (SQLite-compatible)."""
-        result = conn.execute(
+        rows = conn.execute(
             "SELECT name, tbl_name FROM sqlite_master "
             "WHERE type='index' AND name NOT LIKE 'sqlite_%' "
             "ORDER BY tbl_name, name"
-        )
+        ).fetchall()
         results = []
-        for row in result.rows:
+        for row in rows:
             # Check if index is unique using PRAGMA
-            idx_result = conn.execute(f"PRAGMA index_list({self.quote_identifier(row[1])})")
+            idx_result = conn.execute(f"PRAGMA index_list({self.quote_identifier(row[1])})").fetchall()
             is_unique = False
-            for idx_info in idx_result.rows:
+            for idx_info in idx_result:
                 if idx_info[1] == row[0]:  # idx_info: seq, name, unique, origin, partial
                     is_unique = idx_info[2] == 1
                     break
@@ -163,12 +165,12 @@ def get_indexes(self, conn: Any, database: str | None = None) -> list[IndexInfo]
 
     def get_triggers(self, conn: Any, database: str | None = None) -> list[TriggerInfo]:
         """Get triggers from Turso (SQLite-compatible)."""
-        result = conn.execute(
+        rows = conn.execute(
             "SELECT name, tbl_name FROM sqlite_master "
             "WHERE type='trigger' "
             "ORDER BY tbl_name, name"
-        )
-        return [TriggerInfo(name=row[0], table_name=row[1]) for row in result.rows]
+        ).fetchall()
+        return [TriggerInfo(name=row[0], table_name=row[1]) for row in rows]
 
     def get_sequences(self, conn: Any, database: str | None = None) -> list[SequenceInfo]:
         """Turso/SQLite doesn't support sequences - return empty list."""
@@ -188,16 +190,20 @@ def build_select_query(self, table: str, limit: int, database: str | None = None
 
     def execute_query(self, conn: Any, query: str, max_rows: int | None = None) -> tuple[list[str], list[tuple], bool]:
         """Execute a query on Turso with optional row limit."""
-        result = conn.execute(query)
-        if result.columns:
-            columns = list(result.columns)
-            rows = [tuple(row) for row in result.rows]
+        cur = conn.cursor()
+        rows = cur.execute(query).fetchall()
+        columns = [col[0] for col in cur.description]
+        if columns:
+            rows = [tuple(row) for row in rows]
             if max_rows is not None and len(rows) > max_rows:
                 return columns, rows[:max_rows], True
             return columns, rows, False
         return [], [], False
 
     def execute_non_query(self, conn: Any, query: str) -> int:
         """Execute a non-query on Turso."""
-        result = conn.execute(query)
-        return int(result.rows_affected or 0)
+        cur = conn.cursor()
+        cur.execute(query)
+        rowcount = int(cur.rowcount or 0)
+        conn.commit()
+        return rowcount

tests/.env.example

@@ -0,0 +1,19 @@
+# Turso Test Configuration
+# Copy this file to .env and fill in your values
+#
+# To run tests against Turso Cloud instead of local Docker:
+#   1. Copy this file to tests/.env
+#   2. Fill in your Turso Cloud URL and auth token
+#   3. Run: pytest tests/test_turso.py -v
+#
+# To run tests against local Docker (default):
+#   1. Start libsql-server: docker run -d --name turso -p 8080:8080 ghcr.io/tursodatabase/libsql-server:latest
+#   2. Run: TURSO_PORT=8080 pytest tests/test_turso.py -v
+
+# Turso Cloud settings (uncomment and fill in to use cloud instead of Docker)
+# TURSO_CLOUD_URL=libsql://your-database.turso.io
+# TURSO_CLOUD_AUTH_TOKEN=your-auth-token-here
+
+# Local Docker settings (defaults shown)
+# TURSO_HOST=localhost
+# TURSO_PORT=8081