Quick start

PostgreSQL configuration

First, change your Write-Ahead Log mode to logical.

The aim is to set the wal_level parameter.

This is how this can be done with Docker Compose 👇

services:
  postgres:
    image: postgres:17-alpine
    restart: always
    ports:
      - "5434:5432"
    environment:
      - POSTGRES_DB=hermes
      - POSTGRES_USER=hermes
      - POSTGRES_PASSWORD=hermes
    command:
      - "postgres"
      - "-c"
      - "wal_level=logical"

You can also change the maximum number of replication slots when you will be working on many partitions or Hermes PostgreSQL instantions.

command:
  - "postgres"
  - "-c"
  - "wal_level=logical"
  - "max_replication_slots=20" 👈👈👈

When it comes e.g. to AWS RDS for PostgreSQL you can use AWS CDK and CloudFormation.

You have to use the logical_replication set to 1 👇

import * as cdk from 'aws-cdk-lib'
import { aws_ec2 as ec2, aws_rds as rds } from 'aws-cdk-lib'

const vpc = ec2.Vpc.fromLookup(this, 'DefaultVPC', { isDefault: true })
// Create a parameter group with logical replication enabled
const parameterGroup = new rds.ParameterGroup(this, 'PostgresParams', {
  engine: rds.DatabaseInstanceEngine.postgres({
    version: rds.PostgresEngineVersion.VER_14,
  }),
  parameters: {
    'rds.logical_replication': '1', // 👈👈👈
    max_replication_slots: '10', // 👈👈👈
  },
})

// Create the RDS PostgreSQL instance
new rds.DatabaseInstance(this, 'PostgresRDS', {
  engine: rds.DatabaseInstanceEngine.postgres({
    version: rds.PostgresEngineVersion.VER_14,
  }),
  instanceType: ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE3, ec2.InstanceSize.MICRO),
  vpc,
  multiAz: false,
  allocatedStorage: 20,
  storageType: rds.StorageType.GP2,
  publiclyAccessible: false,
  credentials: rds.Credentials.fromGeneratedSecret('postgres'),
  databaseName: 'mydb',
  parameterGroup: parameterGroup,
})

Installation

npm i @chassisjs/hermes @chassisjs/hermes-postgresql

# or

pnpm install @chassisjs/hermes @chassisjs/hermes-postgresql

# or

yarn add @chassisjs/hermes @chassisjs/hermes-postgresql

Good to know

One instnace of Hermes PostgreSQL, pointed by the consumerName parameter equals one replication slot.

It means that the instnace of your app which created the consumer will receive all messages related to this consumer and its partition.

When you try to create another consumer of the same name and with the same partition's name, you get an error rooted in PostgreSQL Logical Replication.

It's a beautiful native mechanism that does a job for you of taking care of instantiating of exactly one consumer of given name.

You can use it to take advantage of the fact that no other instnace executes this code.