feat(logging): add logging support and examples

* Implement built-in logging using Python's logging module.
* Configure log level via environment variable or programmatically.
* Add logging_example.py to demonstrate logging configuration.
* Update README.md with logging instructions.
* Enhance SQLiteVecClient with logging for various operations.
* Create tests for logging functionality.

Author: atasoglu

README.md

@@ -67,6 +67,34 @@ client.close()
 ## How it works
 `SQLiteVecClient` stores data in `{table}` and mirrors embeddings in `{table}_vec` (a `vec0` virtual table). SQLite triggers keep both in sync when rows are inserted, updated, or deleted. Embeddings are serialized as packed float32 bytes for compact storage.
 
+## Logging
+
+The library includes built-in logging support using Python's standard logging module. By default, logging is set to WARNING level.
+
+**Configure log level via environment variable:**
+```bash
+export SQLITE_VEC_CLIENT_LOG_LEVEL=DEBUG  # Linux/macOS
+set SQLITE_VEC_CLIENT_LOG_LEVEL=DEBUG     # Windows
+```
+
+**Or programmatically:**
+```python
+import logging
+from sqlite_vec_client import get_logger
+
+logger = get_logger()
+logger.setLevel(logging.DEBUG)  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+```
+
+**Available log levels:**
+- `DEBUG`: Detailed information for diagnosing issues
+- `INFO`: General informational messages about operations
+- `WARNING`: Warning messages (default)
+- `ERROR`: Error messages
+- `CRITICAL`: Critical error messages
+
+See [examples/logging_example.py](examples/logging_example.py) for a complete example.
+
 ## Testing
 
 The project has comprehensive test coverage (91%+) with 75 tests covering:
@@ -148,6 +176,8 @@ ruff check . && ruff format . && mypy sqlite_vec_client/ && pytest
 - [CHANGELOG.md](CHANGELOG.md) - Version history
 - [TESTING.md](TESTING.md) - Testing documentation
 - [Examples](examples/) - Usage examples
+  - [basic_usage.py](examples/basic_usage.py) - Basic CRUD operations
+  - [logging_example.py](examples/logging_example.py) - Logging configuration
 
 ## Contributing
 

TODO

@@ -30,6 +30,7 @@
 - [x] examples/batch_operations.py
 - [x] examples/context_manager.py
 - [x] examples/real_world_scenario.py
+- [x] examples/logging_example.py
 
 ### Documentation
 - [x] Create CONTRIBUTING.md
@@ -54,10 +55,9 @@
 - [ ] Linting and type checking
 
 ### Logging
-- [ ] Python logging module integration
-- [ ] Log level configuration
-- [ ] Debug mode support
-- [ ] Query logging (optional)
+- [x] Python logging module integration
+- [x] Log level configuration
+- [x] Debug mode support
 
 ## 🔵 Low Priority (New Features)
 

examples/logging_example.py

@@ -0,0 +1,49 @@
+"""Example demonstrating logging configuration in sqlite-vec-client."""
+
+import logging
+import os
+
+from sqlite_vec_client import SQLiteVecClient, get_logger
+
+# Example 1: Enable DEBUG logging via environment variable
+os.environ["SQLITE_VEC_CLIENT_LOG_LEVEL"] = "DEBUG"
+
+# Reload logger to pick up new level
+logger = get_logger()
+logger.setLevel(logging.DEBUG)
+
+print("=== Example 1: DEBUG logging ===\n")
+
+client = SQLiteVecClient(table="docs", db_path=":memory:")
+client.create_table(dim=3, distance="cosine")
+
+texts = ["hello", "world"]
+embeddings = [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]]
+rowids = client.add(texts=texts, embeddings=embeddings)
+
+results = client.similarity_search(embedding=[0.1, 0.2, 0.3], top_k=2)
+client.close()
+
+print("\n=== Example 2: INFO logging ===\n")
+
+# Change to INFO level
+os.environ["SQLITE_VEC_CLIENT_LOG_LEVEL"] = "INFO"
+logger.setLevel(logging.INFO)
+
+client2 = SQLiteVecClient(table="articles", db_path=":memory:")
+client2.create_table(dim=3)
+client2.add(texts=["test"], embeddings=[[0.1, 0.2, 0.3]])
+client2.close()
+
+print("\n=== Example 3: WARNING logging (default) ===\n")
+
+# Default level (WARNING) - minimal output
+os.environ["SQLITE_VEC_CLIENT_LOG_LEVEL"] = "WARNING"
+logger.setLevel(logging.WARNING)
+
+client3 = SQLiteVecClient(table="items", db_path=":memory:")
+client3.create_table(dim=3)
+client3.add(texts=["silent"], embeddings=[[0.1, 0.2, 0.3]])
+client3.close()
+
+print("Done! (No logs shown at WARNING level for normal operations)")

sqlite_vec_client/__init__.py

@@ -12,6 +12,7 @@
     ValidationError,
     VecClientError,
 )
+from .logger import get_logger
 
 __all__ = [
     "SQLiteVecClient",
@@ -21,4 +22,5 @@
     "TableNotFoundError",
     "ConnectionError",
     "DimensionMismatchError",
+    "get_logger",
 ]

sqlite_vec_client/base.py

@@ -16,6 +16,7 @@
 
 from .exceptions import ConnectionError as VecConnectionError
 from .exceptions import TableNotFoundError
+from .logger import get_logger
 from .types import Embeddings, Metadata, Result, Rowids, SimilaritySearchResult, Text
 from .utils import deserialize_f32, serialize_f32
 from .validation import (
@@ -27,6 +28,8 @@
     validate_top_k,
 )
 
+logger = get_logger()
+
 
 class SQLiteVecClient:
     """Manage a text+embedding table and its sqlite-vec index.
@@ -52,15 +55,19 @@ def create_connection(db_path: str) -> sqlite3.Connection:
             VecConnectionError: If connection or extension loading fails
         """
         try:
+            logger.debug(f"Connecting to database: {db_path}")
             connection = sqlite3.connect(db_path)
             connection.row_factory = sqlite3.Row
             connection.enable_load_extension(True)
             sqlite_vec.load(connection)
             connection.enable_load_extension(False)
+            logger.info(f"Successfully connected to database: {db_path}")
             return connection
         except sqlite3.Error as e:
+            logger.error(f"Failed to connect to database {db_path}: {e}")
             raise VecConnectionError(f"Failed to connect to database: {e}") from e
         except Exception as e:
+            logger.error(f"Failed to load sqlite-vec extension: {e}")
             raise VecConnectionError(f"Failed to load sqlite-vec extension: {e}") from e
 
     @staticmethod
@@ -89,6 +96,7 @@ def __init__(self, table: str, db_path: str) -> None:
         """
         validate_table_name(table)
         self.table = table
+        logger.debug(f"Initializing SQLiteVecClient for table: {table}")
         self.connection = self.create_connection(db_path)
 
     def __enter__(self) -> SQLiteVecClient:
@@ -119,6 +127,9 @@ def create_table(
             ValidationError: If dimension is invalid
         """
         validate_dimension(dim)
+        logger.info(
+            f"Creating table '{self.table}' with dim={dim}, distance={distance}"
+        )
         self.connection.execute(
             f"""
             CREATE TABLE IF NOT EXISTS {self.table}
@@ -174,6 +185,7 @@ def create_table(
             """
         )
         self.connection.commit()
+        logger.debug(f"Table '{self.table}' and triggers created successfully")
 
     def similarity_search(
         self,
@@ -194,6 +206,7 @@ def similarity_search(
             TableNotFoundError: If table doesn't exist
         """
         validate_top_k(top_k)
+        logger.debug(f"Performing similarity search with top_k={top_k}")
         try:
             cursor = self.connection.cursor()
             cursor.execute(
@@ -212,9 +225,11 @@ def similarity_search(
                 [serialize_f32(embedding), top_k],
             )
             results = cursor.fetchall()
+            logger.debug(f"Similarity search returned {len(results)} results")
             return [(row["rowid"], row["text"], row["distance"]) for row in results]
         except sqlite3.OperationalError as e:
             if "no such table" in str(e).lower():
+                logger.error(f"Table '{self.table}' not found during similarity search")
                 raise TableNotFoundError(
                     f"Table '{self.table}' or '{self.table}_vec' does not exist. "
                     "Call create_table() first."
@@ -242,6 +257,7 @@ def add(
             TableNotFoundError: If table doesn't exist
         """
         validate_embeddings_match(texts, embeddings, metadata)
+        logger.debug(f"Adding {len(texts)} records to table '{self.table}'")
         try:
             max_id = self.connection.execute(
                 f"SELECT max(rowid) as rowid FROM {self.table}"
@@ -266,9 +282,12 @@ def add(
             results = self.connection.execute(
                 f"SELECT rowid FROM {self.table} WHERE rowid > {max_id}"
             )
-            return [row["rowid"] for row in results]
+            rowids = [row["rowid"] for row in results]
+            logger.info(f"Added {len(rowids)} records to table '{self.table}'")
+            return rowids
         except sqlite3.OperationalError as e:
             if "no such table" in str(e).lower():
+                logger.error(f"Table '{self.table}' not found during add operation")
                 raise TableNotFoundError(
                     f"Table '{self.table}' does not exist. Call create_table() first."
                 ) from e
@@ -380,6 +399,7 @@ def update(
         embedding: Embeddings | None = None,
     ) -> bool:
         """Update fields of a record by rowid; return True if a row changed."""
+        logger.debug(f"Updating record with rowid={rowid}")
         sets = []
         params: list[Any] = []
         if text is not None:
@@ -400,31 +420,43 @@ def update(
         cur = self.connection.cursor()
         cur.execute(sql, params)
         self.connection.commit()
-        return cur.rowcount > 0
+        updated = cur.rowcount > 0
+        if updated:
+            logger.debug(f"Successfully updated record with rowid={rowid}")
+        return updated
 
     def delete_by_id(self, rowid: int) -> bool:
         """Delete a single record by rowid; return True if a row was removed."""
+        logger.debug(f"Deleting record with rowid={rowid}")
         cur = self.connection.cursor()
         cur.execute(f"DELETE FROM {self.table} WHERE rowid = ?", [rowid])
         self.connection.commit()
-        return cur.rowcount > 0
+        deleted = cur.rowcount > 0
+        if deleted:
+            logger.debug(f"Successfully deleted record with rowid={rowid}")
+        return deleted
 
     def delete_many(self, rowids: list[int]) -> int:
         """Delete multiple records by rowids; return number of rows removed."""
         if not rowids:
             return 0
+        logger.debug(f"Deleting {len(rowids)} records")
         placeholders = ",".join(["?"] * len(rowids))
         cur = self.connection.cursor()
         cur.execute(
             f"DELETE FROM {self.table} WHERE rowid IN ({placeholders})",
             rowids,
         )
         self.connection.commit()
-        return cur.rowcount
+        deleted_count = cur.rowcount
+        logger.info(f"Deleted {deleted_count} records from table '{self.table}'")
+        return deleted_count
 
     def close(self) -> None:
         """Close the underlying SQLite connection, suppressing close errors."""
         try:
+            logger.debug(f"Closing connection for table '{self.table}'")
             self.connection.close()
-        except Exception:
-            pass
+            logger.info(f"Connection closed for table '{self.table}'")
+        except Exception as e:
+            logger.warning(f"Error closing connection: {e}")

sqlite_vec_client/logger.py

@@ -0,0 +1,29 @@
+"""Logging configuration for sqlite-vec-client."""
+
+import logging
+import os
+
+# Get log level from environment variable, default to WARNING
+LOG_LEVEL = os.environ.get("SQLITE_VEC_CLIENT_LOG_LEVEL", "WARNING").upper()
+
+# Create logger
+logger = logging.getLogger("sqlite_vec_client")
+logger.setLevel(LOG_LEVEL)
+
+# Only add handler if none exists (avoid duplicate handlers)
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    )
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+
+
+def get_logger() -> logging.Logger:
+    """Get the configured logger instance.
+
+    Returns:
+        Logger instance for sqlite-vec-client
+    """
+    return logger

tests/test_logger.py

@@ -0,0 +1,46 @@
+"""Tests for logging functionality."""
+
+import logging
+
+from sqlite_vec_client import get_logger
+
+
+class TestLogger:
+    """Test logging configuration."""
+
+    def test_get_logger_returns_logger(self):
+        """Test that get_logger returns a Logger instance."""
+        logger = get_logger()
+        assert isinstance(logger, logging.Logger)
+        assert logger.name == "sqlite_vec_client"
+
+    def test_logger_has_handler(self):
+        """Test that logger has at least one handler."""
+        logger = get_logger()
+        assert len(logger.handlers) > 0
+
+    def test_logger_default_level(self):
+        """Test that logger respects environment variable."""
+        logger = get_logger()
+        # Default is WARNING if not set
+        assert logger.level in [
+            logging.WARNING,
+            logging.DEBUG,
+            logging.INFO,
+            logging.ERROR,
+            logging.CRITICAL,
+        ]
+
+    def test_logger_level_can_be_changed(self):
+        """Test that logger level can be changed programmatically."""
+        logger = get_logger()
+        original_level = logger.level
+
+        logger.setLevel(logging.DEBUG)
+        assert logger.level == logging.DEBUG
+
+        logger.setLevel(logging.INFO)
+        assert logger.level == logging.INFO
+
+        # Restore original level
+        logger.setLevel(original_level)