Add Postgres table adapter with TableRepositoryInterface.

Introduce PostgresAdapter for dict-based row CRUD via psycopg3, including config, lazy exports, unit/integration tests with testcontainers, and an example UserTableRepository.

Co-authored-by: Cursor <[email protected]>

tests/conftest.py

@@ -1,6 +1,6 @@
 """Shared test configuration constants."""
 
-from python_repositories.config import MinioConfig, RedisConfig
+from python_repositories.config import MinioConfig, PostgresConfig, RedisConfig
 
 TEST_REDIS_CONFIG = RedisConfig(uri="redis://localhost:6379")
 TEST_MINIO_CONFIG = MinioConfig(
@@ -10,3 +10,8 @@ TEST_MINIO_CONFIG = MinioConfig(
     bucket="test-bucket",
     secure=False,
 )
+TEST_POSTGRES_CONFIG = PostgresConfig(
+    uri="postgresql://localhost/mydb",
+    table="test_items",
+    primary_key="id",
+)

tests/integration/examples/conftest.py

@@ -6,7 +6,7 @@ from minio import Minio
 import pytest
 import redis
 
-from python_repositories.config import MinioConfig, RedisConfig
+from python_repositories.config import MinioConfig, PostgresConfig, RedisConfig
 from tests.integration.minio._containers import (
     minio_config_from_env,
     minio_env,
@@ -17,6 +17,11 @@ from tests.integration.redis._containers import (
     redis_config_from_container,
     redis_uri,
 )
+from tests.integration.postgres._containers import (
+    postgres_config_from_container,
+    postgres_uri,
+    raw_postgres_client_from_container,
+)
 
 
 @pytest.fixture(scope="session")
@@ -53,3 +58,23 @@ def minio_config(minio_container: dict[str, str]) -> MinioConfig:
 def raw_minio_client(minio_container: dict[str, str]) -> Generator[Minio, None, None]:
     """Provide a raw Minio client connected to the test Minio container."""
     yield from raw_minio_client_from_env(minio_container)
+
+
+@pytest.fixture(scope="session")
+def postgres_container() -> Generator[str, None, None]:
+    """Set up a Postgres container for testing and yield the Postgres URI."""
+    yield from postgres_uri()
+
+
+@pytest.fixture(scope="session")
+def postgres_config(postgres_container: str) -> PostgresConfig:
+    """Provide PostgresConfig built from the test container."""
+    return postgres_config_from_container(postgres_container)
+
+
+@pytest.fixture(scope="session")
+def raw_postgres_client(
+    postgres_container: str,
+) -> Generator[object, None, None]:
+    """Provide a raw Postgres client connected to the test Postgres container."""
+    yield from raw_postgres_client_from_container(postgres_container)

tests/integration/examples/examples_test.py

@@ -6,12 +6,15 @@ import os
 import random
 
 from minio import Minio
+import psycopg
 import pytest
 
 from python_repositories.examples.artifact_object_repository import (
     ArtifactObjectRepository,
 )
 from python_repositories.examples.user_json_repository import UserJsonRepository
+from python_repositories.examples.user_table_repository import UserTableRepository
+from tests.integration.postgres._containers import TEST_TABLE
 
 pytestmark = [
     pytest.mark.integration,
@@ -36,6 +39,24 @@ def set_example_env(
         _ = os.environ.pop(key, default=None)
 
 
+@pytest.fixture(scope="module", autouse=True)
+def set_postgres_example_env(
+    postgres_container: str,
+    raw_postgres_client: psycopg.Connection,
+) -> Generator[None, None, None]:
+    """Set Postgres env vars for example repositories using from_env() defaults."""
+    env_vars = {
+        "POSTGRES_URI": postgres_container,
+        "POSTGRES_TABLE": TEST_TABLE,
+        "POSTGRES_PRIMARY_KEY": "id",
+    }
+    for key, value in env_vars.items():
+        os.environ[key] = value
+    yield
+    for key in env_vars:
+        _ = os.environ.pop(key, default=None)
+
+
 @pytest.fixture(scope="module")
 def user_data() -> Generator[dict[str, str], None, None]:
     """Provide sample user data for tests."""
@@ -77,3 +98,27 @@ def test_artifact_object_repository_store_and_get(
         assert received is not None
         artifact_data.seek(0)
         assert received.read() == artifact_data.read()
+
+
+@pytest.mark.needs_postgres
+def test_user_table_repository_save_and_get(
+    user_data: dict[str, str],
+) -> None:
+    """Test that UserTableRepository can save and retrieve a user."""
+    with UserTableRepository() as repo:
+        repo.save_user("alice", user_data)
+        user = repo.get_user("alice")
+        assert user is not None
+        assert user["name"] == user_data["name"]
+        assert user["email"] == user_data["email"]
+
+
+@pytest.mark.needs_postgres
+def test_user_table_repository_delete(
+    user_data: dict[str, str],
+) -> None:
+    """Test that UserTableRepository can delete a user."""
+    with UserTableRepository() as repo:
+        repo.save_user("alice", user_data)
+        repo.delete_user("alice")
+        assert repo.get_user("alice") is None

tests/integration/postgres/_containers.py

@@ -0,0 +1,76 @@
+"""Postgres container session helpers for integration tests."""
+
+from collections.abc import Generator
+
+import psycopg
+from psycopg.rows import dict_row
+from testcontainers.postgres import PostgresContainer
+
+from python_repositories.config import PostgresConfig
+
+POSTGRES_IMAGE = "postgres:16"
+TEST_TABLE = "test_items"
+
+
+_postgres_uri: str | None = None
+_postgres_container: PostgresContainer | None = None
+_raw_postgres_client: psycopg.Connection | None = None
+_postgres_uri_refs = 0
+_raw_postgres_client_refs = 0
+
+
+def postgres_uri() -> Generator[str, None, None]:
+    """Yield a session-scoped Postgres URI, starting the container once."""
+    global _postgres_uri, _postgres_container, _postgres_uri_refs
+    if _postgres_uri is None:
+        _postgres_container = PostgresContainer(POSTGRES_IMAGE, driver=None)
+        _postgres_container.start()
+        _postgres_uri = _postgres_container.get_connection_url()
+
+    _postgres_uri_refs += 1
+    yield _postgres_uri
+    _postgres_uri_refs -= 1
+
+    if _postgres_uri_refs == 0 and _postgres_container is not None:
+        _postgres_container.stop()
+        _postgres_container = None
+        _postgres_uri = None
+
+
+def postgres_config_from_container(uri: str) -> PostgresConfig:
+    """Build PostgresConfig from a container URI."""
+    return PostgresConfig(uri=uri, table=TEST_TABLE, primary_key="id")
+
+
+def raw_postgres_client_from_container(
+    uri: str,
+) -> Generator[psycopg.Connection, None, None]:
+    """Yield a session-scoped raw Postgres client, reusing one client per session."""
+    global _raw_postgres_client, _raw_postgres_client_refs
+    if _raw_postgres_client is None:
+        _raw_postgres_client = psycopg.connect(
+            uri,
+            row_factory=dict_row,  # type: ignore[arg-type]
+            autocommit=True,
+        )
+        with _raw_postgres_client.cursor() as cursor:
+            cursor.execute(
+                f"""
+                CREATE TABLE IF NOT EXISTS {TEST_TABLE} (
+                    id TEXT PRIMARY KEY,
+                    name TEXT NOT NULL,
+                    value INTEGER,
+                    email TEXT
+                )
+                """
+            )
+
+    _raw_postgres_client_refs += 1
+    yield _raw_postgres_client
+    _raw_postgres_client_refs -= 1
+
+    if _raw_postgres_client_refs == 0 and _raw_postgres_client is not None:
+        with _raw_postgres_client.cursor() as cursor:
+            cursor.execute(f"TRUNCATE TABLE {TEST_TABLE}")
+        _raw_postgres_client.close()
+        _raw_postgres_client = None

tests/integration/postgres/conftest.py

@@ -0,0 +1,33 @@
+"""Postgres integration test fixtures."""
+
+from collections.abc import Generator
+
+import psycopg
+import pytest
+
+from python_repositories.config import PostgresConfig
+from tests.integration.postgres._containers import (
+    postgres_config_from_container,
+    postgres_uri,
+    raw_postgres_client_from_container,
+)
+
+
+@pytest.fixture(scope="session")
+def postgres_container() -> Generator[str, None, None]:
+    """Set up a Postgres container for testing and yield the Postgres URI."""
+    yield from postgres_uri()
+
+
+@pytest.fixture(scope="session")
+def postgres_config(postgres_container: str) -> PostgresConfig:
+    """Provide PostgresConfig built from the test container."""
+    return postgres_config_from_container(postgres_container)
+
+
+@pytest.fixture(scope="session")
+def raw_postgres_client(
+    postgres_container: str,
+) -> Generator[psycopg.Connection, None, None]:
+    """Provide a raw Postgres client connected to the test container."""
+    yield from raw_postgres_client_from_container(postgres_container)

tests/integration/postgres/postgres_adapter_test.py

@@ -0,0 +1,318 @@
+"""Integration tests for the PostgresAdapter."""
+
+from collections.abc import Generator
+import logging
+
+import psycopg
+import pytest
+
+from python_repositories.adapters.postgres_adapter import PostgresAdapter
+from python_repositories.config import PostgresConfig
+from tests.integration.postgres._containers import TEST_TABLE
+
+pytestmark = [pytest.mark.integration, pytest.mark.needs_postgres]
+
+
+@pytest.fixture(scope="module")
+def row() -> Generator[dict[str, object], None, None]:
+    """Provide a sample row for tests."""
+    yield {"id": "test-id", "name": "Alice", "value": 42}
+
+
+@pytest.fixture(scope="function")
+def row_in_postgres(
+    raw_postgres_client: psycopg.Connection,
+    row: dict[str, object],
+) -> Generator[tuple[str, dict[str, object]], None, None]:
+    """Fixture to set up a known row in Postgres before each test."""
+    with raw_postgres_client.cursor() as cursor:
+        cursor.execute(
+            f"INSERT INTO {TEST_TABLE} (id, name, value) VALUES (%s, %s, %s)",
+            (row["id"], row["name"], row["value"]),
+        )
+
+    yield str(row["id"]), row
+
+    with raw_postgres_client.cursor() as cursor:
+        cursor.execute(f"DELETE FROM {TEST_TABLE} WHERE id = %s", (row["id"],))
+
+
+@pytest.fixture(scope="module")
+def postgres_adapter(
+    postgres_config: PostgresConfig,
+    raw_postgres_client: psycopg.Connection,
+) -> Generator[PostgresAdapter, None, None]:
+    """Fixture to provide a connected PostgresAdapter instance."""
+    _ = raw_postgres_client  # ensure test table exists before connect probe
+    adapter = PostgresAdapter(config=postgres_config)
+    adapter.connect()
+    yield adapter
+    adapter.disconnect()
+
+
+@pytest.fixture(scope="function", autouse=True)
+def clear_postgres(raw_postgres_client: psycopg.Connection) -> None:
+    """Fixture to clear all rows before each test."""
+    with raw_postgres_client.cursor() as cursor:
+        cursor.execute(f"TRUNCATE TABLE {TEST_TABLE}")
+
+
+def test_should_log_info_when_already_connected(
+    postgres_adapter: PostgresAdapter,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Test that PostgresAdapter logs info when connect is called while connected."""
+    with caplog.at_level(logging.INFO):
+        postgres_adapter.connect()
+    assert "Already connected" in caplog.text
+    assert "Postgres" in caplog.text
+
+
+def test_should_raise_connection_error_when_unable_to_connect() -> None:
+    """Test that PostgresAdapter raises ConnectionError when unable to connect."""
+    adapter = PostgresAdapter(
+        config=PostgresConfig(
+            uri="postgresql://invalid:5432/nodb",
+            table=TEST_TABLE,
+        )
+    )
+    with pytest.raises(ConnectionError):
+        adapter.connect()
+    assert adapter._client is None
+    assert not adapter.is_connected()
+
+
+def test_should_raise_connection_error_when_table_missing(
+    postgres_config: PostgresConfig,
+) -> None:
+    """Test that PostgresAdapter raises ConnectionError when the table is missing."""
+    config = PostgresConfig(
+        uri=postgres_config.uri,
+        table="missing_table",
+        primary_key="id",
+    )
+    adapter = PostgresAdapter(config=config)
+    with pytest.raises(ConnectionError, match="does not exist"):
+        adapter.connect()
+
+
+def test_should_log_error_on_exception_during_exit(
+    postgres_config: PostgresConfig,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Test that PostgresAdapter logs an error when an exception occurs during exit."""
+    try:
+        with PostgresAdapter(config=postgres_config) as adapter:
+            assert adapter.is_connected()
+            raise ValueError("Simulated error")
+    except ValueError:
+        pass
+    assert "Error while exiting context" in caplog.text
+
+
+def test_should_have_context_manager(postgres_config: PostgresConfig) -> None:
+    """Test that PostgresAdapter can be used as a context manager."""
+    with PostgresAdapter(config=postgres_config) as adapter:
+        assert adapter._client is not None
+    assert adapter._client is None
+
+
+def test_should_fetch_one(
+    row_in_postgres: tuple[str, dict[str, object]],
+    postgres_adapter: PostgresAdapter,
+) -> None:
+    """Test that PostgresAdapter can fetch a row by primary key."""
+    pk, row = row_in_postgres
+    fetched = postgres_adapter.fetch_one(pk)
+    assert fetched is not None
+    assert fetched["id"] == row["id"]
+    assert fetched["name"] == row["name"]
+    assert fetched["value"] == row["value"]
+
+
+def test_should_fetch_none_for_missing_row(
+    postgres_adapter: PostgresAdapter,
+) -> None:
+    """Test that fetching a non-existent row returns None."""
+    assert postgres_adapter.fetch_one("missing-id") is None
+
+
+def test_should_raise_value_error_on_invalid_fetch_one_pk(
+    postgres_adapter: PostgresAdapter,
+) -> None:
+    """Test that PostgresAdapter raises ValueError for an invalid primary key."""
+    with pytest.raises(ValueError):
+        postgres_adapter.fetch_one(None)
+
+
+def test_should_raise_connection_error_on_fetch_one_when_not_connected(
+    postgres_config: PostgresConfig,
+) -> None:
+    """Test that fetch_one raises ConnectionError when not connected."""
+    adapter = PostgresAdapter(config=postgres_config)
+    with pytest.raises(ConnectionError):
+        adapter.fetch_one("some-id")
+
+
+def test_should_upsert_row(
+    row: dict[str, object],
+    postgres_adapter: PostgresAdapter,
+) -> None:
+    """Test that PostgresAdapter can insert a row."""
+    assert postgres_adapter.fetch_one(row["id"]) is None
+    postgres_adapter.upsert(row)
+    fetched = postgres_adapter.fetch_one(row["id"])
+    assert fetched is not None
+    assert fetched["name"] == row["name"]
+
+
+def test_should_update_row(
+    row_in_postgres: tuple[str, dict[str, object]],
+    postgres_adapter: PostgresAdapter,
+) -> None:
+    """Test that PostgresAdapter can update an existing row."""
+    pk, _ = row_in_postgres
+    new_row = {"id": pk, "name": "Bob", "value": 99}
+    postgres_adapter.upsert(new_row)
+    fetched = postgres_adapter.fetch_one(pk)
+    assert fetched is not None
+    assert fetched["name"] == "Bob"
+    assert fetched["value"] == 99
+
+
+def test_should_raise_value_error_on_invalid_upsert_row(
+    postgres_adapter: PostgresAdapter,
+) -> None:
+    """Test that PostgresAdapter raises ValueError for invalid upsert data."""
+    with pytest.raises(ValueError):
+        postgres_adapter.upsert({"name": "Alice"})  # missing primary key
+
+
+def test_should_raise_value_error_on_non_dict_upsert_row(
+    postgres_adapter: PostgresAdapter,
+) -> None:
+    """Test that PostgresAdapter raises ValueError when upsert row is not a dict."""
+    with pytest.raises(ValueError):
+        postgres_adapter.upsert("not-a-dict")  # type: ignore[arg-type]
+
+
+def test_should_raise_connection_error_on_upsert_when_not_connected(
+    postgres_config: PostgresConfig,
+    row: dict[str, object],
+) -> None:
+    """Test that upsert raises ConnectionError when not connected."""
+    adapter = PostgresAdapter(config=postgres_config)
+    with pytest.raises(ConnectionError):
+        adapter.upsert(row)
+
+
+def test_should_fetch_all_rows(
+    postgres_adapter: PostgresAdapter,
+) -> None:
+    """Test that PostgresAdapter can fetch all rows."""
+    postgres_adapter.upsert({"id": "a", "name": "Alice", "value": 1})
+    postgres_adapter.upsert({"id": "b", "name": "Bob", "value": 2})
+    rows = postgres_adapter.fetch_all()
+    assert len(rows) == 2
+    ids = {row["id"] for row in rows}
+    assert ids == {"a", "b"}
+
+
+def test_should_fetch_all_with_limit(
+    postgres_adapter: PostgresAdapter,
+) -> None:
+    """Test that PostgresAdapter respects fetch_all limit."""
+    postgres_adapter.upsert({"id": "a", "name": "Alice", "value": 1})
+    postgres_adapter.upsert({"id": "b", "name": "Bob", "value": 2})
+    rows = postgres_adapter.fetch_all(limit=1)
+    assert len(rows) == 1
+
+
+def test_should_return_empty_list_for_empty_table(
+    postgres_adapter: PostgresAdapter,
+) -> None:
+    """Test that fetch_all returns an empty list for an empty table."""
+    assert postgres_adapter.fetch_all() == []
+
+
+def test_should_raise_value_error_on_invalid_fetch_all_limit(
+    postgres_adapter: PostgresAdapter,
+) -> None:
+    """Test that PostgresAdapter raises ValueError for an invalid limit."""
+    with pytest.raises(ValueError):
+        postgres_adapter.fetch_all(limit=-1)
+
+
+def test_should_raise_connection_error_on_fetch_all_when_not_connected(
+    postgres_config: PostgresConfig,
+) -> None:
+    """Test that fetch_all raises ConnectionError when not connected."""
+    adapter = PostgresAdapter(config=postgres_config)
+    with pytest.raises(ConnectionError):
+        adapter.fetch_all()
+
+
+def test_should_delete_row(
+    row_in_postgres: tuple[str, dict[str, object]],
+    postgres_adapter: PostgresAdapter,
+) -> None:
+    """Test that deleting a row removes it from the table."""
+    pk, _ = row_in_postgres
+    assert postgres_adapter.fetch_one(pk) is not None
+    postgres_adapter.delete(pk)
+    assert postgres_adapter.fetch_one(pk) is None
+
+
+def test_should_delete_idempotently(
+    postgres_adapter: PostgresAdapter,
+) -> None:
+    """Test that deleting a missing row does not raise."""
+    postgres_adapter.delete("missing-id")
+
+
+def test_should_raise_value_error_on_invalid_delete_pk(
+    postgres_adapter: PostgresAdapter,
+) -> None:
+    """Test that PostgresAdapter raises ValueError for an invalid delete pk."""
+    with pytest.raises(ValueError):
+        postgres_adapter.delete(None)
+
+
+def test_should_raise_connection_error_on_delete_when_not_connected(
+    postgres_config: PostgresConfig,
+) -> None:
+    """Test that delete raises ConnectionError when not connected."""
+    adapter = PostgresAdapter(config=postgres_config)
+    with pytest.raises(ConnectionError):
+        adapter.delete("some-id")
+
+
+def test_should_execute_sql(
+    row_in_postgres: tuple[str, dict[str, object]],
+    postgres_adapter: PostgresAdapter,
+) -> None:
+    """Test that PostgresAdapter can execute read SQL."""
+    pk, _ = row_in_postgres
+    rows = postgres_adapter.execute(
+        f"SELECT * FROM {TEST_TABLE} WHERE id = %s",
+        (pk,),
+    )
+    assert len(rows) == 1
+    assert rows[0]["id"] == pk
+
+
+def test_should_raise_value_error_on_invalid_execute_sql(
+    postgres_adapter: PostgresAdapter,
+) -> None:
+    """Test that PostgresAdapter raises ValueError for invalid SQL."""
+    with pytest.raises(ValueError):
+        postgres_adapter.execute("")
+
+
+def test_should_raise_connection_error_on_execute_when_not_connected(
+    postgres_config: PostgresConfig,
+) -> None:
+    """Test that execute raises ConnectionError when not connected."""
+    adapter = PostgresAdapter(config=postgres_config)
+    with pytest.raises(ConnectionError):
+        adapter.execute("SELECT 1")

tests/unit/adapters_test.py

@@ -45,6 +45,7 @@ from python_repositories import JsonRepositoryInterface
 assert JsonRepositoryInterface is not None
 assert "python_repositories.adapters.redis_adapter" not in sys.modules
 assert "python_repositories.adapters.minio_adapter" not in sys.modules
+assert "python_repositories.adapters.postgres_adapter" not in sys.modules
 """
     result = subprocess.run(
         [sys.executable, "-c", script],
@@ -58,10 +59,11 @@ assert "python_repositories.adapters.minio_adapter" not in sys.modules
 
 def test_lazy_adapter_load_succeeds_when_extra_present() -> None:
     """Adapters load when their optional dependencies are installed."""
-    from python_repositories import MinioAdapter, RedisAdapter
+    from python_repositories import MinioAdapter, PostgresAdapter, RedisAdapter
 
     assert RedisAdapter.__name__ == "RedisAdapter"
     assert MinioAdapter.__name__ == "MinioAdapter"
+    assert PostgresAdapter.__name__ == "PostgresAdapter"
 
 
 def test_redis_adapter_import_error_without_extra() -> None:
@@ -86,6 +88,17 @@ def test_minio_adapter_import_error_without_extra() -> None:
     importlib.reload(minio_adapter_module)
 
 
+def test_postgres_adapter_import_error_without_extra() -> None:
+    """Missing postgres extra raises ImportError with install hint."""
+    import python_repositories.adapters.postgres_adapter as postgres_adapter_module
+
+    with patch.object(builtins, "__import__", new=_block_backend_import("psycopg")):
+        with pytest.raises(ImportError, match=r"python-repositories\[postgres\]"):
+            importlib.reload(postgres_adapter_module)
+
+    importlib.reload(postgres_adapter_module)
+
+
 def test_top_level_lazy_import_propagates_redis_import_error() -> None:
     """Top-level RedisAdapter access surfaces adapter import errors."""
     with patch(
@@ -112,6 +125,19 @@ def test_top_level_lazy_import_propagates_minio_import_error() -> None:
             _ = python_repositories.MinioAdapter
 
 
+def test_top_level_lazy_import_propagates_postgres_import_error() -> None:
+    """Top-level PostgresAdapter access surfaces adapter import errors."""
+    with patch(
+        "importlib.import_module",
+        side_effect=ImportError(
+            "Postgres support requires the postgres extra. "
+            "Install with: pip install python-repositories[postgres]"
+        ),
+    ):
+        with pytest.raises(ImportError, match=r"python-repositories\[postgres\]"):
+            _ = python_repositories.PostgresAdapter
+
+
 def test_adapters_subpackage_lazy_import_succeeds() -> None:
     """Adapter subpackage imports delegate to the same lazy loader."""
     from python_repositories.adapters import RedisAdapter
@@ -123,7 +149,7 @@ def test_adapters_dir_exposes_lazy_exports() -> None:
     """dir(adapters) includes lazy adapter names for tab completion."""
     import python_repositories.adapters as adapters
 
-    assert {"RedisAdapter", "MinioAdapter"}.issubset(set(dir(adapters)))
+    assert {"RedisAdapter", "MinioAdapter", "PostgresAdapter"}.issubset(set(dir(adapters)))
 
 
 def test_adapters_getattr_raises_for_unknown() -> None:
@@ -138,3 +164,4 @@ def test_top_level_dir_exposes_lazy_exports() -> None:
     """dir(python_repositories) includes lazy adapter names for tab completion."""
     assert "RedisAdapter" in dir(python_repositories)
     assert "MinioAdapter" in dir(python_repositories)
+    assert "PostgresAdapter" in dir(python_repositories)

tests/unit/conftest.py

@@ -5,12 +5,14 @@ from __future__ import annotations
 from unittest.mock import MagicMock
 
 from minio import Minio
+import psycopg
 import pytest
 import redis
 
 from python_repositories.adapters.minio_adapter import MinioAdapter
+from python_repositories.adapters.postgres_adapter import PostgresAdapter
 from python_repositories.adapters.redis_adapter import RedisAdapter
-from tests.conftest import TEST_MINIO_CONFIG, TEST_REDIS_CONFIG
+from tests.conftest import TEST_MINIO_CONFIG, TEST_POSTGRES_CONFIG, TEST_REDIS_CONFIG
 
 
 @pytest.fixture
@@ -25,3 +27,14 @@ def minio_adapter() -> MinioAdapter:
     """Provide a MinioAdapter with an injected mock client."""
     mock_client = MagicMock(spec=Minio)
     return MinioAdapter(config=TEST_MINIO_CONFIG, client=mock_client)
+
+
+@pytest.fixture
+def postgres_adapter() -> PostgresAdapter:
+    """Provide a PostgresAdapter with an injected mock client."""
+    mock_client = MagicMock(spec=psycopg.Connection)
+    mock_cursor = MagicMock()
+    mock_cursor.__enter__ = MagicMock(return_value=mock_cursor)
+    mock_cursor.__exit__ = MagicMock(return_value=False)
+    mock_client.cursor.return_value = mock_cursor
+    return PostgresAdapter(config=TEST_POSTGRES_CONFIG, client=mock_client)

tests/unit/connection_aware_adapter_test.py

@@ -6,10 +6,12 @@ from typing import cast
 from unittest.mock import MagicMock, patch
 
 import redis
+import psycopg
 
 from python_repositories.adapters.minio_adapter import MinioAdapter
+from python_repositories.adapters.postgres_adapter import PostgresAdapter
 from python_repositories.adapters.redis_adapter import RedisAdapter
-from tests.conftest import TEST_MINIO_CONFIG, TEST_REDIS_CONFIG
+from tests.conftest import TEST_MINIO_CONFIG, TEST_POSTGRES_CONFIG, TEST_REDIS_CONFIG
 
 
 class TestRedisConnectionHealth:
@@ -161,3 +163,74 @@ class TestMinioConnectionHealth:
             assert reinjected.is_connected()
 
         assert mock_client.bucket_exists.call_count == 2
+
+
+class TestPostgresConnectionHealth:
+    def test_not_connected_when_no_client(self) -> None:
+        adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG)
+        assert not adapter.is_connected()
+
+    def test_connected_when_probe_succeeds(
+        self, postgres_adapter: PostgresAdapter
+    ) -> None:
+        assert postgres_adapter.is_connected()
+        cast(MagicMock, postgres_adapter._client).cursor.assert_called()
+
+    def test_stale_connection_when_probe_fails(
+        self, postgres_adapter: PostgresAdapter
+    ) -> None:
+        mock_cursor = cast(MagicMock, postgres_adapter._client).cursor.return_value
+        mock_cursor.execute.side_effect = psycopg.OperationalError("connection lost")
+
+        assert not postgres_adapter.is_connected()
+
+    def test_cache_hit_avoids_second_probe(
+        self, postgres_adapter: PostgresAdapter
+    ) -> None:
+        mock_client = cast(MagicMock, postgres_adapter._client)
+
+        with patch(
+            "python_repositories.adapters.connection_aware_adapter.time.monotonic",
+            return_value=100.0,
+        ):
+            assert postgres_adapter.is_connected()
+            assert postgres_adapter.is_connected()
+
+        assert mock_client.cursor.call_count == 1
+
+    def test_cache_miss_runs_probe_again(
+        self, postgres_adapter: PostgresAdapter
+    ) -> None:
+        mock_client = cast(MagicMock, postgres_adapter._client)
+
+        with patch(
+            "python_repositories.adapters.connection_aware_adapter.time.monotonic",
+            side_effect=[100.0, 102.0],
+        ):
+            assert postgres_adapter.is_connected()
+            assert postgres_adapter.is_connected()
+
+        assert mock_client.cursor.call_count == 2
+
+    def test_disconnect_clears_cache(self, postgres_adapter: PostgresAdapter) -> None:
+        mock_client = cast(MagicMock, postgres_adapter._client)
+
+        with patch(
+            "python_repositories.adapters.connection_aware_adapter.time.monotonic",
+            return_value=100.0,
+        ):
+            assert postgres_adapter.is_connected()
+
+        postgres_adapter.disconnect()
+        reinjected = PostgresAdapter(
+            config=postgres_adapter._config,
+            client=mock_client,
+        )
+
+        with patch(
+            "python_repositories.adapters.connection_aware_adapter.time.monotonic",
+            return_value=100.0,
+        ):
+            assert reinjected.is_connected()
+
+        assert mock_client.cursor.call_count == 2

tests/unit/postgres_adapter_test.py

@@ -0,0 +1,235 @@
+"""Unit tests for PostgresAdapter instantiation and injection."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import psycopg
+import pytest
+
+from python_repositories.adapters.postgres_adapter import PostgresAdapter
+from python_repositories.interfaces import TableRepositoryInterface
+from tests.conftest import TEST_POSTGRES_CONFIG
+
+
+def _mock_cursor() -> MagicMock:
+    mock_cursor = MagicMock()
+    mock_cursor.__enter__ = MagicMock(return_value=mock_cursor)
+    mock_cursor.__exit__ = MagicMock(return_value=False)
+    return mock_cursor
+
+
+def _mock_client(*, probe_raises: Exception | None = None) -> MagicMock:
+    mock_client = MagicMock(spec=psycopg.Connection)
+    mock_cursor = _mock_cursor()
+    if probe_raises is not None:
+        mock_cursor.execute.side_effect = probe_raises
+    mock_client.cursor.return_value = mock_cursor
+    return mock_client
+
+
+def test_should_adhere_to_interface() -> None:
+    assert issubclass(PostgresAdapter, TableRepositoryInterface)
+    _ = PostgresAdapter(config=TEST_POSTGRES_CONFIG)
+
+
+def test_should_have_logger_when_instantiated() -> None:
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG)
+    assert hasattr(adapter, "logger")
+    assert adapter.logger is not None
+
+
+def test_should_not_be_connected_when_instantiated() -> None:
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG)
+    assert adapter._client is None
+    assert not adapter.is_connected()
+
+
+def test_constructs_with_injected_config_without_env(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("POSTGRES_URI", raising=False)
+    monkeypatch.delenv("POSTGRES_TABLE", raising=False)
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG)
+    assert adapter._config == TEST_POSTGRES_CONFIG
+
+
+def test_constructs_with_injected_client_without_env(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("POSTGRES_URI", raising=False)
+    monkeypatch.delenv("POSTGRES_TABLE", raising=False)
+    mock_client = _mock_client()
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG, client=mock_client)
+    assert adapter._client is mock_client
+    assert adapter._client_injected is True
+
+
+def test_raises_when_client_provided_without_config() -> None:
+    mock_client = MagicMock(spec=psycopg.Connection)
+    with pytest.raises(ValueError, match="config is required"):
+        PostgresAdapter(client=mock_client)
+
+
+def test_disconnect_does_not_close_injected_client() -> None:
+    mock_client = _mock_client()
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG, client=mock_client)
+    adapter.disconnect()
+    mock_client.close.assert_not_called()
+    assert adapter._client is None
+
+
+class CustomEnvPostgresAdapter(PostgresAdapter):
+    uri_env_var_name = "CUSTOM_POSTGRES_URI"
+    table_env_var_name = "CUSTOM_POSTGRES_TABLE"
+    primary_key_env_var_name = "CUSTOM_POSTGRES_PRIMARY_KEY"
+
+
+def test_subclass_custom_env_var_names(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("CUSTOM_POSTGRES_URI", "postgresql://custom/mydb")
+    monkeypatch.setenv("CUSTOM_POSTGRES_TABLE", "items")
+    monkeypatch.setenv("CUSTOM_POSTGRES_PRIMARY_KEY", "item_id")
+    adapter = CustomEnvPostgresAdapter()
+    assert adapter._config.uri == "postgresql://custom/mydb"
+    assert adapter._config.table == "items"
+    assert adapter._config.primary_key == "item_id"
+
+
+def test_connect_with_injected_client_succeeds_when_probe_ok() -> None:
+    mock_client = _mock_client()
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG, client=mock_client)
+
+    adapter.connect()
+
+    assert mock_client.cursor.return_value.execute.call_count == 2
+
+
+def test_connect_with_injected_client_raises_on_probe_failure() -> None:
+    mock_client = _mock_client(probe_raises=psycopg.OperationalError("connection lost"))
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG, client=mock_client)
+
+    with pytest.raises(ConnectionError, match="Could not connect to Postgres"):
+        adapter.connect()
+
+
+def test_connect_with_injected_client_skips_validation_when_client_cleared() -> None:
+    mock_client = _mock_client()
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG, client=mock_client)
+    adapter.disconnect()
+
+    adapter.connect()
+
+    mock_client.cursor.assert_not_called()
+
+
+def test_connect_reconnects_when_existing_client_unhealthy(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    stale_client = _mock_client(probe_raises=psycopg.OperationalError("connection lost"))
+    new_client = _mock_client()
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG)
+    adapter._client = stale_client
+
+    monkeypatch.setattr("psycopg.connect", lambda *args, **kwargs: new_client)
+
+    adapter.connect()
+
+    stale_client.close.assert_called_once()
+    assert adapter._client is new_client
+
+
+def test_connect_skips_reconnect_when_already_connected(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    healthy_client = _mock_client()
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG)
+    adapter._client = healthy_client
+
+    connect = MagicMock()
+    monkeypatch.setattr("psycopg.connect", connect)
+
+    adapter.connect()
+
+    healthy_client.close.assert_not_called()
+    connect.assert_not_called()
+    assert adapter._client is healthy_client
+
+
+def test_fetch_one_raises_value_error_on_invalid_pk() -> None:
+    mock_client = _mock_client()
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG, client=mock_client)
+
+    with pytest.raises(ValueError, match="Primary key must not be None"):
+        adapter.fetch_one(None)
+
+
+def test_fetch_one_raises_connection_error_when_not_connected() -> None:
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG)
+
+    with pytest.raises(ConnectionError):
+        adapter.fetch_one("some-id")
+
+
+def test_upsert_raises_value_error_on_invalid_row() -> None:
+    mock_client = _mock_client()
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG, client=mock_client)
+
+    with pytest.raises(ValueError, match="Row must be a dictionary"):
+        adapter.upsert("not-a-dict")  # type: ignore[arg-type]
+
+
+def test_upsert_raises_value_error_when_primary_key_missing() -> None:
+    mock_client = _mock_client()
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG, client=mock_client)
+
+    with pytest.raises(ValueError, match="Row must include primary key column 'id'"):
+        adapter.upsert({"name": "Alice"})
+
+
+def test_upsert_raises_connection_error_when_not_connected() -> None:
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG)
+
+    with pytest.raises(ConnectionError):
+        adapter.upsert({"id": "alice", "name": "Alice"})
+
+
+def test_fetch_all_raises_value_error_on_invalid_limit() -> None:
+    mock_client = _mock_client()
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG, client=mock_client)
+
+    with pytest.raises(ValueError, match="Limit must be a non-negative integer"):
+        adapter.fetch_all(limit=-1)
+
+
+def test_execute_raises_value_error_on_invalid_sql() -> None:
+    mock_client = _mock_client()
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG, client=mock_client)
+
+    with pytest.raises(ValueError, match="SQL must be a non-empty string"):
+        adapter.execute("")
+
+
+def test_execute_raises_value_error_on_invalid_params() -> None:
+    mock_client = _mock_client()
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG, client=mock_client)
+
+    with pytest.raises(ValueError, match="Params must be a tuple"):
+        adapter.execute("SELECT 1", [])  # type: ignore[arg-type]
+
+
+def test_upsert_with_primary_key_only_uses_do_nothing() -> None:
+    mock_client = _mock_client()
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG, client=mock_client)
+
+    adapter.upsert({"id": "pk-only"})
+
+    mock_cursor = mock_client.cursor.return_value.__enter__.return_value
+    insert_call = mock_cursor.execute.call_args_list[-1]
+    assert insert_call[0][1] == ("pk-only",)
+
+
+def test_execute_raises_connection_error_when_not_connected() -> None:
+    adapter = PostgresAdapter(config=TEST_POSTGRES_CONFIG)
+
+    with pytest.raises(ConnectionError):
+        adapter.execute("SELECT 1")

tests/unit/postgres_config_test.py

@@ -0,0 +1,69 @@
+"""Unit tests for PostgresConfig."""
+
+from __future__ import annotations
+
+import pytest
+
+from python_repositories.config import PostgresConfig
+
+
+def _set_required_postgres_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("POSTGRES_URI", "postgresql://localhost/mydb")
+    monkeypatch.setenv("POSTGRES_TABLE", "users")
+
+
+def test_from_env_loads_all_fields(monkeypatch: pytest.MonkeyPatch) -> None:
+    _set_required_postgres_env(monkeypatch)
+    config = PostgresConfig.from_env(use_dotenv=False)
+    assert config.uri == "postgresql://localhost/mydb"
+    assert config.table == "users"
+    assert config.primary_key == "id"
+
+
+def test_from_env_reads_primary_key_from_env(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _set_required_postgres_env(monkeypatch)
+    monkeypatch.setenv("POSTGRES_PRIMARY_KEY", "user_id")
+    config = PostgresConfig.from_env(use_dotenv=False)
+    assert config.primary_key == "user_id"
+
+
+def test_from_env_defaults_primary_key_to_id_when_unset(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _set_required_postgres_env(monkeypatch)
+    monkeypatch.delenv("POSTGRES_PRIMARY_KEY", raising=False)
+    config = PostgresConfig.from_env(use_dotenv=False)
+    assert config.primary_key == "id"
+
+
+def test_from_env_raises_when_uri_missing(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("POSTGRES_URI", raising=False)
+    monkeypatch.setenv("POSTGRES_TABLE", "users")
+    with pytest.raises(Exception):
+        PostgresConfig.from_env(use_dotenv=False)
+
+
+def test_from_env_raises_when_table_missing(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("POSTGRES_URI", "postgresql://localhost/mydb")
+    monkeypatch.delenv("POSTGRES_TABLE", raising=False)
+    with pytest.raises(Exception):
+        PostgresConfig.from_env(use_dotenv=False)
+
+
+def test_from_env_respects_custom_env_var_names(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CUSTOM_POSTGRES_URI", "postgresql://custom/mydb")
+    monkeypatch.setenv("CUSTOM_POSTGRES_TABLE", "items")
+    monkeypatch.setenv("CUSTOM_POSTGRES_PRIMARY_KEY", "item_id")
+    config = PostgresConfig.from_env(
+        "CUSTOM_POSTGRES_URI",
+        "CUSTOM_POSTGRES_TABLE",
+        "CUSTOM_POSTGRES_PRIMARY_KEY",
+        use_dotenv=False,
+    )
+    assert config.uri == "postgresql://custom/mydb"
+    assert config.table == "items"
+    assert config.primary_key == "item_id"

tests/unit/table_repository_interface_test.py

@@ -0,0 +1,162 @@
+"""Unit tests for TableRepositoryInterface."""
+
+from typing import Any
+
+import pytest
+
+from python_repositories.interfaces.table_repository_interface import (
+    TableRepositoryInterface,
+)
+
+
+class InMemoryTableRepo:
+    """Plain class that satisfies TableRepositoryInterface without inheritance."""
+
+    def fetch_one(self, pk: Any) -> dict[str, Any] | None:
+        return None
+
+    def fetch_all(self, *, limit: int | None = None) -> list[dict[str, Any]]:
+        del limit
+        return []
+
+    def upsert(self, row: dict[str, Any]) -> None:
+        pass
+
+    def delete(self, pk: Any) -> None:
+        pass
+
+    def execute(
+        self,
+        sql: str,
+        params: tuple[Any, ...] = (),
+    ) -> list[dict[str, Any]]:
+        del sql, params
+        return []
+
+
+def accepts_table_repo(repo: TableRepositoryInterface) -> None:
+    """Type-checking hook for TableRepositoryInterface structural subtyping."""
+    repo.fetch_one("pk")
+
+
+def test_instantiation_fails_when_fetch_one_not_implemented() -> None:
+    """Test that instantiation fails if fetch_one is not implemented."""
+
+    class Incomplete(TableRepositoryInterface):
+        def fetch_all(self, *, limit: int | None = None) -> list[dict[str, Any]]:
+            return []
+
+        def upsert(self, row: dict[str, Any]) -> None:
+            pass
+
+        def delete(self, pk: Any) -> None:
+            pass
+
+        def execute(
+            self,
+            sql: str,
+            params: tuple[Any, ...] = (),
+        ) -> list[dict[str, Any]]:
+            return []
+
+    with pytest.raises(TypeError):
+        _ = Incomplete()  # type: ignore
+
+
+def test_instantiation_fails_when_fetch_all_not_implemented() -> None:
+    """Test that instantiation fails if fetch_all is not implemented."""
+
+    class Incomplete(TableRepositoryInterface):
+        def fetch_one(self, pk: Any) -> dict[str, Any] | None:
+            return None
+
+        def upsert(self, row: dict[str, Any]) -> None:
+            pass
+
+        def delete(self, pk: Any) -> None:
+            pass
+
+        def execute(
+            self,
+            sql: str,
+            params: tuple[Any, ...] = (),
+        ) -> list[dict[str, Any]]:
+            return []
+
+    with pytest.raises(TypeError):
+        _ = Incomplete()  # type: ignore
+
+
+def test_instantiation_fails_when_upsert_not_implemented() -> None:
+    """Test that instantiation fails if upsert is not implemented."""
+
+    class Incomplete(TableRepositoryInterface):
+        def fetch_one(self, pk: Any) -> dict[str, Any] | None:
+            return None
+
+        def fetch_all(self, *, limit: int | None = None) -> list[dict[str, Any]]:
+            return []
+
+        def delete(self, pk: Any) -> None:
+            pass
+
+        def execute(
+            self,
+            sql: str,
+            params: tuple[Any, ...] = (),
+        ) -> list[dict[str, Any]]:
+            return []
+
+    with pytest.raises(TypeError):
+        _ = Incomplete()  # type: ignore
+
+
+def test_instantiation_fails_when_delete_not_implemented() -> None:
+    """Test that instantiation fails if delete is not implemented."""
+
+    class Incomplete(TableRepositoryInterface):
+        def fetch_one(self, pk: Any) -> dict[str, Any] | None:
+            return None
+
+        def fetch_all(self, *, limit: int | None = None) -> list[dict[str, Any]]:
+            return []
+
+        def upsert(self, row: dict[str, Any]) -> None:
+            pass
+
+        def execute(
+            self,
+            sql: str,
+            params: tuple[Any, ...] = (),
+        ) -> list[dict[str, Any]]:
+            return []
+
+    with pytest.raises(TypeError):
+        _ = Incomplete()  # type: ignore
+
+
+def test_instantiation_fails_when_execute_not_implemented() -> None:
+    """Test that instantiation fails if execute is not implemented."""
+
+    class Incomplete(TableRepositoryInterface):
+        def fetch_one(self, pk: Any) -> dict[str, Any] | None:
+            return None
+
+        def fetch_all(self, *, limit: int | None = None) -> list[dict[str, Any]]:
+            return []
+
+        def upsert(self, row: dict[str, Any]) -> None:
+            pass
+
+        def delete(self, pk: Any) -> None:
+            pass
+
+    with pytest.raises(TypeError):
+        _ = Incomplete()  # type: ignore
+
+
+def test_structural_subtyping() -> None:
+    """Test that a plain class satisfies TableRepositoryInterface structurally."""
+    repo: TableRepositoryInterface = InMemoryTableRepo()
+    accepts_table_repo(repo)
+    assert isinstance(repo, TableRepositoryInterface)