Skip to content

Add PostgreSQL data store #175

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add PostgreSQL data store #175

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6211f03
feat: add PostgreSQL store as async-only implementation
github-actions[bot] Nov 9, 2025
38a059d
refactor: optimize PostgreSQL store to use one-time table setup
github-actions[bot] Nov 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions docs/stores.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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 |

Expand Down Expand Up @@ -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.

Check failure on line 578 in docs/stores.md

View workflow job for this annotation

GitHub Actions / markdown_lint

Line length 

docs/stores.md:578:81 MD013/line-length Line length [Expected: 80; Actual: 107] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md013.md
Copy link
Contributor

@coderabbitai coderabbitai bot Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix line length violation flagged by linter.

The markdown linter expects lines to be ≤80 characters, but this line is 107 characters.

Apply this diff to fix the line length:

-**Note:** PostgreSQL is async-only. This store uses `asyncpg` which provides native async/await operations.
+**Note:** PostgreSQL is async-only. This store uses `asyncpg` which
+provides native async/await operations.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
**Note:** PostgreSQL is async-only. This store uses `asyncpg` which provides native async/await operations.
**Note:** PostgreSQL is async-only. This store uses `asyncpg` which
provides native async/await operations.
🧰 Tools
🪛 GitHub Actions: Run Tests

[error] 578-578: MD013/line-length Line length [Expected: 80; Actual: 107]. Linting failed as part of 'make lint' (exit code 2).

🪛 GitHub Check: markdown_lint

[failure] 578-578: Line length
docs/stores.md:578:81 MD013/line-length Line length [Expected: 80; Actual: 107] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md013.md

🤖 Prompt for AI Agents 
In docs/stores.md around line 578, the "**Note:** PostgreSQL is async-only. This
store uses `asyncpg` which provides native async/await operations." line exceeds
the 80-character limit; split or reword it into two shorter lines while
preserving the note formatting and backticks (for example keep "**Note:**
PostgreSQL is async-only." on one line and put "This store uses `asyncpg`, which
provides native async/await operations." on the following line), ensuring each
resulting line is ≤80 characters.


```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.
Expand Down
3 changes: 2 additions & 1 deletion key-value/key-value-aio/pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -69,7 +70,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]",
Expand Down
9 changes: 9 additions & 0 deletions key-value/key-value-aio/src/key_value/aio/stores/postgresql/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"]
Loading
Loading