Running the Performance Test¶

pg_relay includes a performance test script that shows how many events the Processor can handle per second on your specific hardware and database configuration. It is a good way to build confidence in pg_relay before putting it into production.

The results are indicative only — running the test several times will give noticeably different numbers. This comes down to timing: sometimes your query checking "how many are left" lands just after the Processor has cleared the queue, and sometimes it lands mid-way through the Processor's work. We recommend running the test 5–7 times and taking an average. Even on modest hardware, you should find the Processor capable of handling 300 or more notifications per second.

What the test does¶

The test registers a set of channels and tables, then sends increasing numbers of events across several loops. Each loop sends more events than the last (loop 1 sends 100 events, loop 2 sends 200, and so on). Once all the events are sent, it waits for the queue to drain completely and reports the throughput.

The test cleans up everything it created when it finishes — your database is returned to the state it was in beforehand, apart from records in pgrelay.log and pgrelay.queue, which you can purge afterwards.

Before you run the test¶

Make sure the Processor is running and connected to your database.
Connect to your database in psql as a superuser (the test needs to create temporary tables and functions).

If you would rather connect as a non-superuser, make sure that user has been granted access to all the pgrelay functions and tables — the performance test is not typical usage of pg_relay and needs broader access than normal, since it queries pgrelay.log directly.

Running the test¶

From inside psql:

\i /your_pgrelay_directory/test/pg_relay_performance_test.sql

The script will ask two questions:

Press Enter to continue — confirms you have read the setup information. You can cancel at this point if you wish.
Enter number of loops (10–999) — start with 10 or 20 loops for a first run.

What the output looks like¶

Count 100, Remaining 0
Count 200, Remaining 0
Count 300, Remaining 0
Count 400, Remaining 47
Count 500, Remaining 112
...
The Processor is able to process between 200 and 300 notifications per second
Now waiting for Queue to drain...
Wait 1, Remaining 650
Wait 2, Remaining 470
...
Average Notifications processed per second: 280.000

Count is the number of events sent in that loop. Remaining is the backlog — how many events had not been processed by the start of the next loop. When Remaining is 0, the Processor is keeping up with every event before the next loop begins. Once Remaining starts growing, you have found the limit of how fast this configuration can process events.

Breakeven is the highest point where the Processor was still keeping up with everything queued. You may see some smaller loops show a backlog too, purely because of small timing differences between when the Processor starts its work and when each loop begins — so results will vary a little. The overall range is a good indicator of how many events per second this Processor can handle for this type of workload.

Larger workloads have a negative effect on throughput, because processing here is not asynchronous (it does not overlap work the way some systems do). Treat the performance test as indicative of lightweight notification workloads specifically.

Tips¶

Refer to The Security Model in the Technical Guide for more on some of the concepts mentioned below.

Run with --workers 2 or higher to see the difference extra workers make:
```
pg_relay --workers 2
```
Try 10 loops first for a quick result (5,500 total events), then increase to 20 or more for a more sustained measurement.
A development laptop will show lower numbers than a dedicated server — that is expected.
The test creates between 400 and 3,000 tables, depending on how many loops you choose. This is normal, and they are all removed at the end.
Try running more than one Processor at once. Two instances is usually the sweet spot — three or four can actually be slower, because of contention between the duplicate work the test itself creates. On a 4-core development laptop, two instances each running two workers tends to perform best. Results vary, but you can generally expect 700–2,500 notifications processed per second with two instances. Running a second instance is also a sensible default in production, since it gives you redundancy: if one Processor stops, the other keeps working.

Continue to Keeping the Audit Log Tidy for guidance on purging old records.