Add PostgreSQL data store

docs/stores.md

@@ -34,6 +34,7 @@
 | Memory | N/A | ✅ | ✅ | Fast in-memory storage for development and caching |
 | Disk | Stable | ☑️ | ✅ | Persistent file-based storage in a single file |
 | Disk (Per-Collection) | Stable | ☑️ | ✅ | Persistent storage with separate files per collection |
+| DuckDB | Unstable | ☑️ | ✅ | In-process SQL OLAP database with native JSON storage |
 | FileTree (test) | Unstable | ☑️ | ✅ | Directory-based storage with JSON files for visual inspection |
 | Null (test) | N/A | ✅ | ✅ | No-op store for testing without side effects |
 | RocksDB | Unstable | ☑️ | ✅ | High-performance embedded database |
@@ -400,6 +401,7 @@
 | Elasticsearch | Unstable | ✅ | ✅ | Full-text search with key-value capabilities |
 | Memcached | Unstable | ✅ | ✖️ | High-performance distributed memory cache |
 | MongoDB | Unstable | ✅ | ✅ | Document database used as key-value store |
+| PostgreSQL | Unstable | ✅ | ✖️ | PostgreSQL database with JSONB storage |
 | Redis | Stable | ✅ | ✅ | Popular in-memory data structure store |
 | Valkey | Stable | ✅ | ✅ | Open-source Redis fork |
 
@@ -569,6 +571,55 @@
 
 ---
 
+### PostgreSQLStore
+
+PostgreSQL database with JSONB storage for flexible key-value data.
+
+**Note:** PostgreSQL is async-only. This store uses `asyncpg` which provides native async/await operations.
+
+```python
+from key_value.aio.stores.postgresql import PostgreSQLStore
+
+# Using connection URL
+store = PostgreSQLStore(url="postgresql://localhost:5432/mydb")
+
+# Using connection parameters
+store = PostgreSQLStore(
+    host="localhost",
+    port=5432,
+    database="mydb",
+    user="myuser",
+    password="mypass"
+)
+
+async with store:
+    await store.put(key="user_1", value={"name": "Alice"}, collection="users")
+    user = await store.get(key="user_1", collection="users")
+```
+
+**Installation:**
+
+```bash
+pip install py-key-value-aio[postgresql]
+```
+
+**Use Cases:**
+
+- Applications already using PostgreSQL
+- Need for SQL querying on stored data
+- ACID transaction requirements
+- Complex data relationships
+
+**Characteristics:**
+
+- JSONB storage for efficient querying
+- TTL support via expiration timestamps
+- Single table design (collections as column values)
+- Async-only (uses asyncpg)
+- Stable storage format: **Unstable**
+
+---
+
 ### MemcachedStore
 
 High-performance distributed memory caching system.

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

@@ -50,6 +50,7 @@ rocksdb = [
     "rocksdict>=0.3.2 ; python_version < '3.12'"
 ]
 duckdb = ["duckdb>=1.1.1", "pytz>=2025.2"]
+postgresql = ["asyncpg>=0.30.0"]
 wrappers-encryption = ["cryptography>=45.0.0"]
 
 [tool.pytest.ini_options]
@@ -70,7 +71,7 @@ env_files = [".env"]
 
 [dependency-groups]
 dev = [
-    "py-key-value-aio[memory,disk,filetree,redis,elasticsearch,memcached,mongodb,vault,dynamodb,rocksdb,duckdb]",
+    "py-key-value-aio[memory,disk,filetree,redis,elasticsearch,memcached,mongodb,vault,dynamodb,rocksdb,duckdb,postgresql]",
     "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/postgresql/__init__.py

@@ -0,0 +1,9 @@
+"""PostgreSQL store for py-key-value-aio."""
+
+try:
+    from key_value.aio.stores.postgresql.store import PostgreSQLStore
+except ImportError as e:
+    msg = 'PostgreSQLStore requires the "postgresql" extra. Install via: pip install "py-key-value-aio[postgresql]"'
+    raise ImportError(msg) from e
+
+__all__ = ["PostgreSQLStore"]