allows you to listen to changes in your PostgreSQL database via logical replication and then broadcast those changes over websockets.
Realtime server works by:
- listening to PostgreSQL's logical replication (here using Wal2Json).
- filtering the incoming message
- broadcasting the message over websocket
Explaination
You probably know that Postgresql is not a realtime databse. So if we want to stream the change of it to a websocket or any UI it's not possible by default.
Hopefully Postgresql have that sweet feature named Logical Replication, which stream the change made into the database over a replication slot. We can use a multitude of plugins to format the output of this stream, but for Speculare-PGCDC we've chosen to use wal2json.
This project create a replication slot on the targeted postgres instance and then stream the change from this slot to all the websockets connected.
Project Status
This project is still under development and the documentation is constantly changing. You are welcome to try it, but expect some changes with future updates. TAGs are used to mark a certain version in all Speculare repositories as compatible with each others.
Server setup / Dev setup
- Install all deps
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
$ sudo apt-get install libssl-dev libpq-dev pkg-config build-essential
There pretty much only one step in this setup (other than Docker (see below) and is optional)
- Create a Pgcdc.toml file based on Example.toml
⚠ WARNING: Check the docs !
Usage
$ wss://server/ws?query=change_type:table:col.eq.val
will get change_type event from table where col is equals to val.
The change_type and table parameters are mandatory, if you're missing them you'll get a 400 error.
change_type can be any of those: *, insert, update, delete.
table must be a valid table of your database.
I decided to restrict the API in such way that a single websocket can only listen to one table. This might change in the future if needed, but as of now and in the current shape of Speculare, it's not needed.
Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
