diff --git a/docs/index.rst b/docs/index.rst index dd81b05..84ba4aa 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,5 +18,5 @@ The repository is hosted on `github ` setup configuration strategies - pgb + pged examples diff --git a/docs/pgb.md b/docs/pgb.md deleted file mode 100644 index f143ed7..0000000 --- a/docs/pgb.md +++ /dev/null @@ -1,44 +0,0 @@ -## PG-Bouncer Service - -The new PG-Bouncer service, is designed to enhance PGCacheWatch by enabling efficient distribution of PostgreSQL notifications to multiple clients. This service acts as a middleware, receiving notifications from PostgreSQL and broadcasting them to connected clients via WebSockets. This "fan-out" effect ensures real-time cache invalidation across all clients with minimal database connections. - -### Key Benefits: - -- **Scalability**: Handles numerous clients without increasing load on the PostgreSQL server. -- **Efficiency**: Reduces the need for multiple direct connections to PostgreSQL for NOTIFY/LISTEN. -- **Real-time**: Ensures immediate cache invalidation across services upon database changes. - -### Illustration: - -``` - +-------------------+ - | PostgreSQL DB | - | - NOTIFY on event | - +---------+---------+ - | - | NOTIFY - | - +---------v---------+ - | PG-Bouncer | - | Service | - | - Fan-out NOTIFY | - +---------+---------+ - | - +-------------+-------------+ - | | - +-------v-------+ +-------v-------+ - | WebSocket | | WebSocket | - | Client 1 | | Client N | - | - Invalidate | | - Invalidate | - | Cache | | Cache | - +---------------+ +---------------+ -``` - -To leverage the PG-Bouncer service within your PGCacheWatch setup, ensure it's running and accessible by your application. Configure PGCacheWatch to connect to PG-Bouncer instead of directly to PostgreSQL for notifications. This setup amplifies the effectiveness of your cache invalidation strategy by ensuring timely updates across all client caches with optimized resource usage. - -### Running the PG-Bouncer Service -To start the PG-Bouncer service, use the following command in your terminal. This command utilizes uvicorn, an ASGI server, to run the service defined in the `pgcachewatch.pg_bouncer:main` module. The --factory flag is used to indicate that uvicorn should call the provided application factory function to get the ASGI application instance. - -```bash -uvicorn pgcachewatch.pg_bouncer:main --factory -``` diff --git a/docs/pged.md b/docs/pged.md new file mode 100644 index 0000000..1cd7f0f --- /dev/null +++ b/docs/pged.md @@ -0,0 +1,44 @@ +## PG Event Distributor + +The PG event distributor, is designed to enhance PGCacheWatch by enabling efficient distribution of PostgreSQL notifications to multiple clients. This service acts as a middleware, receiving notifications from PostgreSQL and broadcasting them to connected clients via WebSockets. This "fan-out" effect ensures real-time cache invalidation across all clients with minimal database connections. + +### Key Benefits: + +- **Scalability**: Handles numerous clients without increasing load on the PostgreSQL server. +- **Efficiency**: Reduces the need for multiple direct connections to PostgreSQL for NOTIFY/LISTEN. +- **Real-time**: Ensures immediate cache invalidation across services upon database changes. + +### Illustration: + +``` + +-------------------+ + | PostgreSQL DB | + | - NOTIFY on event | + +---------+---------+ + | + | NOTIFY + | + +---------v-------------+ + | PG Event Distributor | + | Service | + | - Fan-out NOTIFY | + +---------+-------------+ + | + +-------------+-------------+ + | | + +-------v-------+ +-------v-------+ + | WebSocket | | WebSocket | + | Client 1 | | Client N | + | - Invalidate | | - Invalidate | + | Cache | | Cache | + +---------------+ +---------------+ +``` + +To leverage the PG Event Distributor within your PGCacheWatch setup, ensure it's running and accessible by your application. Configure PGCacheWatch to connect to the PG Event Distributor instead of directly to PostgreSQL for notifications. This setup amplifies the effectiveness of your cache invalidation strategy by ensuring timely updates across all client caches with optimized resource usage. + +### Running the PG Event Distributor +To start the PG Event Distributor service, use the following command in your terminal. This command utilizes uvicorn, an ASGI server, to run the service defined in the `pgcachewatch.pg_event_distributor:main` module. The --factory flag is used to indicate that uvicorn should call the provided application factory function to get the ASGI application instance. + +```bash +uvicorn pgcachewatch.pg_event_distributor:main --factory +``` diff --git a/src/pgcachewatch/pg_bouncer.py b/src/pgcachewatch/pg_event_distributor.py similarity index 97% rename from src/pgcachewatch/pg_bouncer.py rename to src/pgcachewatch/pg_event_distributor.py index e6e376d..7fa59d7 100644 --- a/src/pgcachewatch/pg_bouncer.py +++ b/src/pgcachewatch/pg_event_distributor.py @@ -4,7 +4,7 @@ among multiple clients Usage example: -`uvicorn pgcachewatch.pg_bouncer:main --factory` +`uvicorn pgcachewatch.pg_event_distributor:main --factory` """ import asyncio diff --git a/tests/conftest.py b/tests/conftest.py index c8f0840..ca4b9a3 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -14,7 +14,7 @@ def pgb_address() -> str: return "127.0.0.1:8000" -async def pg_bouncer_isup() -> bool: +async def pg_event_distributor_isup() -> bool: timeout = timedelta(seconds=1) deadline = datetime.now() + timeout @@ -61,13 +61,13 @@ def set_pg_envs(monkeypatch: pytest.MonkeyPatch) -> None: @pytest.fixture(scope="function") -async def pgbapp() -> AsyncGenerator[Popen, None]: +async def pgedapp() -> AsyncGenerator[Popen, None]: with Popen( - "uvicorn pgcachewatch.pg_bouncer:main --factory".split(), + "uvicorn pgcachewatch.pg_event_distributor:main --factory".split(), stderr=PIPE, stdout=PIPE, ) as p: - await pg_bouncer_isup() + await pg_event_distributor_isup() try: yield p finally: diff --git a/tests/test_listeners.py b/tests/test_listeners.py index 0336bb6..9e43578 100644 --- a/tests/test_listeners.py +++ b/tests/test_listeners.py @@ -48,7 +48,7 @@ async def test_eventqueue_and_pglistner( @pytest.mark.parametrize("N", (1, 8, 32)) @pytest.mark.parametrize("operation", get_args(models.OPERATIONS)) async def test_eventqueue_and_wslistner( - pgbapp: Popen, + pgedapp: Popen, N: int, operation: models.OPERATIONS, pgpool: asyncpg.Pool, diff --git a/tests/test_pg_bouncer.py b/tests/test_pg_event_distributor.py similarity index 95% rename from tests/test_pg_bouncer.py rename to tests/test_pg_event_distributor.py index ccb728a..a472725 100644 --- a/tests/test_pg_bouncer.py +++ b/tests/test_pg_event_distributor.py @@ -6,18 +6,18 @@ import asyncpg import pytest import websockets -from conftest import pg_bouncer_isup, pgb_address +from conftest import pg_event_distributor_isup, pgb_address from pgcachewatch import listeners, models, utils -async def test_up_endpoint(pgbapp: Popen) -> None: - assert await pg_bouncer_isup() +async def test_up_endpoint(pgedapp: Popen) -> None: + assert await pg_event_distributor_isup() @pytest.mark.parametrize("operation", get_args(models.OPERATIONS)) @pytest.mark.parametrize("N", (1, 8)) async def test_ws_broadcast( - pgbapp: Popen, + pgedapp: Popen, N: int, pgpool: asyncpg.Pool, operation: models.OPERATIONS, @@ -99,7 +99,7 @@ async def test_put_ws_event_queue( @pytest.mark.parametrize("operation", get_args(models.OPERATIONS)) @pytest.mark.parametrize("N", (1, 64)) async def test_put_on_event_ws_event_queue( - pgbapp: Popen, + pgedapp: Popen, N: int, pgpool: asyncpg.Pool, operation: models.OPERATIONS, @@ -133,7 +133,7 @@ async def test_put_on_event_ws_event_queue( async def test_ws_event_queue_connection_healthy( - pgbapp: Popen, + pgedapp: Popen, channel: models.PGChannel = models.PGChannel( "test_ws_event_queue_connection_healthy" ),