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 PGCDC 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.
1
# Install Rust
2
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
3
4
# Install APT dependencies
5
sudo apt-get install libssl-dev libpq-dev pkg-config build-essential
Copied!

Setup an env file

The server config depends on a Pgcdc.toml file located at the root of the working dir.
This does not mean you will have to keep the source code after compilation, this just mean the Pgcdc.toml must be present at in the workdir from where you will execute the binary.
You can create your Pgcdc.toml from the Example.toml given in the source code or using the following template:
1
POSTGRES_HOST = "127.0.0.1"
2
POSTGRES_USER = "postgres"
3
POSTGRES_PASSWORD = "azertyuiop"
4
POSTGRES_DATABASE = "speculare"
5
POSTGRES_TLS = false # default = true
6
7
BINDING = "0.0.0.0:8080"
8
9
KEY_PRIV = "key.pem" # (optional)
10
KEY_CERT = "cert.pem" # (optional)
11
HTTPS = true # (optional [default = false])
12
13
RUST_LOG = "warn,speculare_pgcdc=info,warp=info" # (optional [default = "error,wrap=info"])
Copied!
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:
1
[Unit]
2
Description=Speculare Cdc Process
3
After=network.target postgresql.service
4
StartLimitIntervalSec=600
5
StartLimitBurst=10
6
7
[Service]
8
Restart=on-failure
9
RestartSec=60s
10
Group=www-data
11
WorkingDirectory=/root/speculare-pgcdc
12
ExecStart=/root/speculare-pgcdc/target/release/speculare-pgcdc
13
14
[Install]
15
WantedBy=multi-user.target
Copied!
The above service will start after postgres, this is important. The pgcdc cannot start before postgresql.
Last modified 2mo ago
Copy link
Contents
Setup