feat: add PostgreSQL store as async-only implementation

- Add PostgreSQL-based key-value store using asyncpg
- Uses JSONB for value storage with TTL support
- Implements optimized bulk operations
- Includes comprehensive test suite
- Marked as async-only (no sync version due to asyncpg being async-only)
- Added to codegen exclude list to prevent sync generation

Closes #48

Co-authored-by: William Easton <strawgate@users.noreply.github.com>

Author: github-actions[bot]

docs/stores.md

@@ -34,7 +34,6 @@ Local stores are stored in memory or on disk, local to the application.
 | 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 |
-| 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 |
 | Simple (test) | N/A | ✅ | ✅ | Simple in-memory store for testing |
@@ -141,74 +140,6 @@ pip install py-key-value-aio[disk]
 
 ---
 
-### FileTreeStore
-
-Directory-based storage for visual inspection and debugging.
-
-```python
-from key_value.aio.stores.filetree import FileTreeStore
-
-store = FileTreeStore(directory="./debug-store")
-```
-
-**Installation:**
-
-```bash
-pip install py-key-value-aio[filetree]
-```
-
-**Use Cases:**
-
-- Visual inspection of store contents
-- Debugging store behavior
-- Development and testing
-- Understanding data structure
-
-**Characteristics:**
-
-- Collections as directories
-- Keys as JSON files (`{key}.json`)
-- Human-readable filesystem layout
-- Easy to inspect and modify
-- **NOT for production use**
-
-**Directory Structure:**
-
-```text
-{base_directory}/
-  {collection_1}/
-    {key_1}.json
-    {key_2}.json
-  {collection_2}/
-    {key_3}.json
-```
-
-**Important Limitations:**
-
-- Poor performance with many keys
-- No atomic operations
-- No automatic cleanup of expired entries
-- Filesystem path length constraints
-- Subject to filesystem limitations
-
-**When to Use:**
-
-Use FileTreeStore when you need to:
-
-- Visually inspect what's being stored
-- Debug complex data structures
-- Understand how the store organizes data
-- Manually modify stored data for testing
-
-**When NOT to Use:**
-
-- Production environments
-- High-performance requirements
-- Large datasets
-- Concurrent access scenarios
-
----
-
 ### RocksDBStore
 
 High-performance embedded database using RocksDB.
@@ -400,6 +331,7 @@ Distributed stores provide network-based storage for multi-node applications.
 | 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-based key-value storage |
 | Redis | Stable | ✅ | ✅ | Popular in-memory data structure store |
 | Valkey | Stable | ✅ | ✅ | Open-source Redis fork |
 
@@ -569,6 +501,52 @@ pip install py-key-value-aio[mongodb]
 
 ---
 
+### PostgreSQLStore
+
+PostgreSQL relational database used as a key-value store.
+
+**Note:** PostgreSQL store is **async-only** because it uses the `asyncpg` library,
+which is async-only. There is no sync version available.
+
+```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"
+)
+```
+
+**Installation:**
+
+```bash
+pip install py-key-value-aio[postgresql]
+```
+
+**Use Cases:**
+
+- Applications already using PostgreSQL
+- Need for SQL query capabilities
+- ACID compliance requirements
+- Relational data with key-value access pattern
+
+**Characteristics:**
+
+- JSONB storage for values
+- TTL support via expires_at timestamps
+- Optimized bulk operations
+- Lazy cleanup of expired entries
+- Stable storage format: **Unstable**
+
+---
+
 ### MemcachedStore
 
 High-performance distributed memory caching system.

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

@@ -34,9 +34,9 @@ py-key-value-shared-test = { workspace = true }
 [project.optional-dependencies]
 memory = ["cachetools>=5.0.0"]
 disk = ["diskcache>=5.0.0", "pathvalidate>=3.3.1",]
-filetree = ["aiofile>=3.5.0", "anyio>=4.4.0"]
 redis = ["redis>=4.3.0"]
 mongodb = ["pymongo>=4.0.0"]
+postgresql = ["asyncpg>=0.30.0"]
 valkey = ["valkey-glide>=2.1.0"]
 vault = ["hvac>=2.3.0", "types-hvac>=2.3.0"]
 memcached = ["aiomcache>=0.8.0"]
@@ -68,7 +68,7 @@ env_files = [".env"]
 
 [dependency-groups]
 dev = [
-    "py-key-value-aio[memory,disk,filetree,redis,elasticsearch,memcached,mongodb,vault,dynamodb,rocksdb]",
+    "py-key-value-aio[memory,disk,redis,elasticsearch,memcached,mongodb,postgresql,vault,dynamodb,rocksdb]",
     "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, PostgreSQLV1CollectionSanitizationStrategy
+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", "PostgreSQLV1CollectionSanitizationStrategy"]