feat: add DuckDB store support

- Add DuckDBStore implementation with BaseStore and BaseContextManagerStore
- Support both in-memory (:memory:) and persistent (file-based) storage
- Include seed support following current store patterns
- Add comprehensive test suite (294 tests passing)
- Update pyproject.toml with duckdb>=1.0.0 optional dependency
- Mark as unstable API (_stable_api = False)

Implements #11

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

Co-authored-by: William Easton <[email protected]>

Author: github-actions[bot]

key-value/key-value-aio/pyproject.toml

@@ -48,6 +48,7 @@ rocksdb = [
     "rocksdict>=0.3.24 ; python_version >= '3.12'", # RocksDB 0.3.24 is the first version to support Python 3.13
     "rocksdict>=0.3.2 ; python_version < '3.12'"
 ]
+duckdb = ["duckdb>=1.0.0"]
 wrappers-encryption = ["cryptography>=45.0.0"]
 
 [tool.pytest.ini_options]
@@ -67,7 +68,7 @@ env_files = [".env"]
 
 [dependency-groups]
 dev = [
-    "py-key-value-aio[memory,disk,redis,elasticsearch,memcached,mongodb,vault,dynamodb,rocksdb]",
+    "py-key-value-aio[memory,disk,redis,elasticsearch,memcached,mongodb,vault,dynamodb,rocksdb,duckdb]",
     "py-key-value-aio[valkey]; platform_system != 'Windows'",
     "py-key-value-aio[keyring]",
     "py-key-value-aio[pydantic]",

key-value/key-value-aio/src/key_value/aio/stores/duckdb/__init__.py

@@ -0,0 +1,3 @@
+from key_value.aio.stores.duckdb.store import DuckDBStore
+
+__all__ = ["DuckDBStore"]

key-value/key-value-aio/src/key_value/aio/stores/duckdb/store.py

@@ -0,0 +1,188 @@
+from pathlib import Path
+from typing import overload
+
+from key_value.shared.utils.managed_entry import ManagedEntry
+from typing_extensions import override
+
+from key_value.aio.stores.base import SEED_DATA_TYPE, BaseContextManagerStore, BaseStore
+
+try:
+    import duckdb
+except ImportError as e:
+    msg = "DuckDBStore requires py-key-value-aio[duckdb]"
+    raise ImportError(msg) from e
+
+
+class DuckDBStore(BaseContextManagerStore, BaseStore):
+    """A DuckDB-based key-value store supporting both in-memory and persistent storage.
+
+    DuckDB is an in-process SQL OLAP database that provides excellent performance
+    for analytical workloads while supporting standard SQL operations. This store
+    can operate in memory-only mode or persist data to disk.
+    """
+
+    _connection: duckdb.DuckDBPyConnection
+    _is_closed: bool
+
+    @overload
+    def __init__(
+        self,
+        *,
+        connection: duckdb.DuckDBPyConnection,
+        default_collection: str | None = None,
+        seed: SEED_DATA_TYPE | None = None,
+    ) -> None:
+        """Initialize the DuckDB store with an existing connection.
+
+        Args:
+            connection: An existing DuckDB connection to use.
+            default_collection: The default collection to use if no collection is provided.
+            seed: Optional seed data to pre-populate the store.
+        """
+
+    @overload
+    def __init__(
+        self,
+        *,
+        database_path: Path | str | None = None,
+        default_collection: str | None = None,
+        seed: SEED_DATA_TYPE | None = None,
+    ) -> None:
+        """Initialize the DuckDB store with a database path.
+
+        Args:
+            database_path: Path to the database file. If None or ':memory:', uses in-memory database.
+            default_collection: The default collection to use if no collection is provided.
+            seed: Optional seed data to pre-populate the store.
+        """
+
+    def __init__(
+        self,
+        *,
+        connection: duckdb.DuckDBPyConnection | None = None,
+        database_path: Path | str | None = None,
+        default_collection: str | None = None,
+        seed: SEED_DATA_TYPE | None = None,
+    ) -> None:
+        """Initialize the DuckDB store.
+
+        Args:
+            connection: An existing DuckDB connection to use.
+            database_path: Path to the database file. If None or ':memory:', uses in-memory database.
+            default_collection: The default collection to use if no collection is provided.
+            seed: Optional seed data to pre-populate the store.
+        """
+        if connection is not None and database_path is not None:
+            msg = "Provide only one of connection or database_path"
+            raise ValueError(msg)
+
+        if connection is not None:
+            self._connection = connection
+        else:
+            # Convert Path to string if needed
+            if isinstance(database_path, Path):
+                database_path = str(database_path)
+
+            # Use in-memory database if no path specified
+            if database_path is None or database_path == ":memory:":
+                self._connection = duckdb.connect(":memory:")
+            else:
+                self._connection = duckdb.connect(database=database_path)
+
+        self._is_closed = False
+        self._stable_api = False
+
+        super().__init__(default_collection=default_collection, seed=seed)
+
+    @override
+    async def _setup(self) -> None:
+        """Initialize the database schema for key-value storage."""
+        # Create the main table for storing key-value entries
+        self._connection.execute("""
+            CREATE TABLE IF NOT EXISTS kv_entries (
+                collection VARCHAR NOT NULL,
+                key VARCHAR NOT NULL,
+                value_json TEXT NOT NULL,
+                created_at DOUBLE,
+                ttl DOUBLE,
+                expires_at DOUBLE,
+                PRIMARY KEY (collection, key)
+            )
+        """)
+
+        # Create index for efficient collection queries
+        self._connection.execute("""
+            CREATE INDEX IF NOT EXISTS idx_kv_collection
+            ON kv_entries(collection)
+        """)
+
+        # Create index for expiration-based queries
+        self._connection.execute("""
+            CREATE INDEX IF NOT EXISTS idx_kv_expires_at
+            ON kv_entries(expires_at)
+        """)
+
+    @override
+    async def _get_managed_entry(self, *, key: str, collection: str) -> ManagedEntry | None:
+        """Retrieve a managed entry by key from the specified collection."""
+        result = self._connection.execute(
+            "SELECT value_json FROM kv_entries WHERE collection = ? AND key = ?",
+            [collection, key],
+        ).fetchone()
+
+        if result is None:
+            return None
+
+        value_json = result[0]
+        return ManagedEntry.from_json(json_str=value_json)
+
+    @override
+    async def _put_managed_entry(
+        self,
+        *,
+        key: str,
+        collection: str,
+        managed_entry: ManagedEntry,
+    ) -> None:
+        """Store a managed entry by key in the specified collection."""
+        # Insert or replace the entry
+        self._connection.execute(
+            """
+            INSERT OR REPLACE INTO kv_entries
+            (collection, key, value_json, created_at, ttl, expires_at)
+            VALUES (?, ?, ?, ?, ?, ?)
+        """,
+            [
+                collection,
+                key,
+                managed_entry.to_json(),
+                managed_entry.created_at.timestamp() if managed_entry.created_at else None,
+                managed_entry.ttl,
+                managed_entry.expires_at.timestamp() if managed_entry.expires_at else None,
+            ],
+        )
+
+    @override
+    async def _delete_managed_entry(self, *, key: str, collection: str) -> bool:
+        """Delete a managed entry by key from the specified collection."""
+        result = self._connection.execute(
+            "DELETE FROM kv_entries WHERE collection = ? AND key = ? RETURNING key",
+            [collection, key],
+        )
+
+        # Check if any rows were deleted by counting returned rows
+        deleted_rows = result.fetchall()
+        return len(deleted_rows) > 0
+
+    @override
+    async def _close(self) -> None:
+        """Close the DuckDB connection."""
+        if not self._is_closed:
+            self._connection.close()
+            self._is_closed = True
+
+    def __del__(self) -> None:
+        """Clean up the DuckDB connection on deletion."""
+        if not self._is_closed:
+            self._connection.close()
+            self._is_closed = True

key-value/key-value-aio/tests/stores/duckdb/__init__.py

@@ -0,0 +1 @@
+# DuckDB store tests

key-value/key-value-aio/tests/stores/duckdb/test_duckdb.py

@@ -0,0 +1,142 @@
+from collections.abc import AsyncGenerator
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+import pytest
+from typing_extensions import override
+
+from key_value.aio.stores.base import BaseStore
+from key_value.aio.stores.duckdb import DuckDBStore
+from tests.stores.base import BaseStoreTests, ContextManagerStoreTestMixin
+
+
+class TestDuckDBStore(ContextManagerStoreTestMixin, BaseStoreTests):
+    @override
+    @pytest.fixture
+    async def store(self) -> AsyncGenerator[DuckDBStore, None]:
+        """Test with in-memory DuckDB database."""
+        duckdb_store = DuckDBStore()
+        yield duckdb_store
+        await duckdb_store.close()
+
+    @pytest.mark.skip(reason="Local disk stores are unbounded")
+    @override
+    async def test_not_unbounded(self, store: BaseStore): ...
+
+
+class TestDuckDBStorePersistent(ContextManagerStoreTestMixin, BaseStoreTests):
+    @override
+    @pytest.fixture
+    async def store(self) -> AsyncGenerator[DuckDBStore, None]:
+        """Test with persistent DuckDB database file."""
+        with TemporaryDirectory() as temp_dir:
+            db_path = Path(temp_dir) / "test.db"
+            duckdb_store = DuckDBStore(database_path=db_path)
+            yield duckdb_store
+            await duckdb_store.close()
+
+    @pytest.mark.skip(reason="Local disk stores are unbounded")
+    @override
+    async def test_not_unbounded(self, store: BaseStore): ...
+
+
+class TestDuckDBStoreSpecific:
+    """Test DuckDB-specific functionality."""
+
+    @pytest.fixture
+    async def store(self) -> AsyncGenerator[DuckDBStore, None]:
+        """Provide DuckDB store instance."""
+        duckdb_store = DuckDBStore()
+        yield duckdb_store
+        await duckdb_store.close()
+
+    async def test_database_path_initialization(self):
+        """Test that store can be initialized with different database path options."""
+        # In-memory (default)
+        store1 = DuckDBStore()
+        await store1.put(collection="test", key="key1", value={"test": "value1"})
+        result1 = await store1.get(collection="test", key="key1")
+        assert result1 == {"test": "value1"}
+        await store1.close()
+
+        # Explicit in-memory
+        store2 = DuckDBStore(database_path=":memory:")
+        await store2.put(collection="test", key="key2", value={"test": "value2"})
+        result2 = await store2.get(collection="test", key="key2")
+        assert result2 == {"test": "value2"}
+        await store2.close()
+
+    async def test_persistent_database(self):
+        """Test that data persists across store instances when using file database."""
+        with TemporaryDirectory() as temp_dir:
+            db_path = Path(temp_dir) / "persist_test.db"
+
+            # Store data in first instance
+            store1 = DuckDBStore(database_path=db_path)
+            await store1.put(collection="test", key="persist_key", value={"data": "persistent"})
+            await store1.close()
+
+            # Create second instance with same database file
+            store2 = DuckDBStore(database_path=db_path)
+            result = await store2.get(collection="test", key="persist_key")
+            await store2.close()
+
+            assert result == {"data": "persistent"}
+
+    async def test_sql_injection_protection(self, store: DuckDBStore):
+        """Test that the store is protected against SQL injection attacks."""
+        malicious_collection = "test'; DROP TABLE kv_entries; --"
+        malicious_key = "key'; DELETE FROM kv_entries; --"
+
+        # These operations should not cause SQL injection
+        await store.put(collection=malicious_collection, key=malicious_key, value={"safe": "data"})
+        result = await store.get(collection=malicious_collection, key=malicious_key)
+        assert result == {"safe": "data"}
+
+        # Verify the table still exists and other data is safe
+        await store.put(collection="normal", key="normal_key", value={"normal": "data"})
+        normal_result = await store.get(collection="normal", key="normal_key")
+        assert normal_result == {"normal": "data"}
+
+    async def test_large_data_storage(self, store: DuckDBStore):
+        """Test storing and retrieving large data values."""
+        # Create a large value (1MB of data)
+        large_value = {"large_data": "x" * (1024 * 1024)}
+
+        await store.put(collection="test", key="large_key", value=large_value)
+        result = await store.get(collection="test", key="large_key")
+
+        assert result == large_value
+
+    async def test_unicode_support(self, store: DuckDBStore):
+        """Test that the store properly handles Unicode characters."""
+        unicode_data = {
+            "english": "Hello World",
+            "chinese": "你好世界",
+            "japanese": "こんにちは世界",
+            "arabic": "مرحبا بالعالم",
+            "emoji": "🌍🚀💻",
+            "special": "Special chars: !@#$%^&*()_+-={}[]|\\:;\"'<>?,./",
+        }
+
+        await store.put(collection="unicode_test", key="unicode_key", value=unicode_data)
+        result = await store.get(collection="unicode_test", key="unicode_key")
+
+        assert result == unicode_data
+
+    async def test_connection_initialization(self):
+        """Test that store can be initialized with existing DuckDB connection."""
+        import duckdb
+
+        conn = duckdb.connect(":memory:")
+        store = DuckDBStore(connection=conn)
+
+        await store.put(collection="test", key="conn_test", value={"test": "value"})
+        result = await store.get(collection="test", key="conn_test")
+        assert result == {"test": "value"}
+
+        await store.close()
+
+    @pytest.mark.skip(reason="Local disk stores are unbounded")
+    @override
+    async def test_not_unbounded(self, store: BaseStore): ...