Getting started

Speculare PGCDC is used to stream change from the Postgres database over WebSocket to active clients.

Setup

As of now Speculare PGCDC does not provide easy setup solution such as a one-line installer (but it's planned). The current recommanded way to install Speculare PGCDC is to build it from source. But don't be afraid, it's easy and straightforwards.

Install dependencies

Speculare Alerts is a Rust project that rely on some dependencies to be able to be built correctly. Much of them are default deps in most servers.

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install APT dependencies
sudo apt-get install libssl-dev libpq-dev pkg-config build-essential cmake

Configuration files

The server binary depends on a pgcdc.config file whose path will be passed as arguments to the binary.

You can create your pgcdc.config from the pgcdc.example.config given in the source code.

PGCDC will get a list of available tables at startup time. In case of update of the database you might need to restart PGCDC to refetch new tables.

Example of usage

Use this base request:

https://cdc.speculare.cloud/ws?query=change_type:table:col.eq.val

Will get change_type event from table where col is equals to val. The change_table and table parameters are mandatory, if you're missing them you'll get a 400 error.

• change_table: can be either of those: *, insert, update, delete

• table: must be a real table from your database

• col.eq.val: is optional but col is the column name and val is the expected value (String)

Install as a service

Here is a sample speculare-pgcdc.service for systemd:

[Unit]
Description=Speculare Cdc Process
After=network.target postgresql.service
StartLimitIntervalSec=600
StartLimitBurst=10

[Service]
Restart=on-failure
RestartSec=60s
Group=www-data
ExecStart=/root/speculare-pgcdc/target/release/speculare-pgcdc -c "/path/to/Config.toml"

[Install]
WantedBy=multi-user.target

The above service will start after postgres, this is important. The pgcdc cannot start before postgresql.