
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 instances.
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-postgresqlGood to know
One instance of Hermes PostgreSQL, identified by the consumerName and partitionKey parameters, equals one replication slot.
It means that the instance of your app which created the consumer will receive all messages related to this consumer and its partition.
When you try to start another consumer of the same name and with the same partition's name, you get the HermesConsumerAlreadyTakenError 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 instance executes this code.
Next, see the basic usage.
