Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed on your system:

Bun Runtime

Install from bun.sh

Docker

Required for running PostgreSQL

​
Installation

1

Clone the repository

First, clone the PostgreSQL Realtime Monitor repository:
git clone <your-repository-url>
cd listen-postgres
2

Install dependencies

Use Bun to install all required dependencies:
bun install
This will install the following key dependencies:
  • postgres - PostgreSQL client with logical replication support
  • react & react-dom - Frontend UI framework
  • typescript - Type-safe development
3

Start PostgreSQL with Docker

The project includes a pre-configured Docker setup for PostgreSQL:
docker-compose up -d
This command will:
  • Pull the postgres:16-alpine image
  • Create a container named postgres-realtime
  • Enable logical replication with the following settings:
    • wal_level=logical
    • max_wal_senders=10
    • max_replication_slots=10
  • Expose PostgreSQL on port 5432
  • Create the alltables publication for change tracking
The database credentials are:
  • Database: appdb
  • User: appuser
  • Password: secret
4

Start the application

Run the development server:
bun run dev
This starts the Bun server on port 3000 with:
  • WebSocket server at ws://localhost:3000/ws
  • HTTP server at http://localhost:3000
  • Hot Module Reloading (HMR) enabled
  • PostgreSQL subscription active
5

Open in browser

Navigate to http://localhost:3000 to access the monitoring dashboard.

​
Docker Configuration

The docker-compose.yml file configures PostgreSQL with logical replication enabled:
docker-compose.yml
version: "3.9"

services:
  db:
    image: postgres:16-alpine
    container_name: postgres-realtime
    restart: unless-stopped
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: secret
    ports:
      - "5432:5432"
    command: >
      postgres
        -c wal_level=logical
        -c max_wal_senders=10
        -c max_replication_slots=10
        -c max_connections=100
    volumes:
      - db-data:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro

volumes:
  db-data:

​
Understanding the Configuration

  • wal_level=logical: Enables logical decoding required for change data capture
  • max_wal_senders=10: Allows up to 10 concurrent replication connections
  • max_replication_slots=10: Maximum number of replication slots
The init.sql file runs on first startup and creates the publication:
init.sql
CREATE PUBLICATION alltables FOR ALL TABLES;
This publication allows the application to subscribe to changes on all tables.
The db-data volume ensures your database persists between container restarts:
# To reset the database, remove the volume
docker-compose down -v

​
Testing Your Setup

Verify that everything is working by creating a test table and inserting data:
1

Connect to PostgreSQL

docker exec -it postgres-realtime psql -U appuser -d appdb
2

Create a test table

CREATE TABLE todos (
  id SERIAL PRIMARY KEY,
  title TEXT NOT NULL,
  done BOOLEAN NOT NULL DEFAULT false,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
3

Insert test data

INSERT INTO todos (title) VALUES ('Test task 1');
INSERT INTO todos (title) VALUES ('Test task 2');
You should see these changes appear in real-time in your browser!
4

Test updates and deletes

UPDATE todos SET done = true WHERE id = 1;
DELETE FROM todos WHERE id = 2;
All operations will be captured and displayed live.
Changes are stored in memory and will be lost when the server restarts. This is intentional for the monitoring use case.

​
Troubleshooting

If you have another PostgreSQL instance running, either:
  1. Stop the existing instance
  2. Modify the port mapping in docker-compose.yml:
ports:
  - "5433:5432"  # Use port 5433 on host
Then update db.ts to match:
const DB_PORT = 5433
Ensure the server is running on port 3000 and check the browser console for errors. The frontend automatically attempts to reconnect if the connection is lost.
Verify that:
  1. The alltables publication exists: \dRp+ in psql
  2. Logical replication is enabled: SHOW wal_level; should return logical
  3. The server console shows ”✅ Realtime subscription ready”

​
Next Steps

Configuration

Learn how to customize database settings and server options

Usage

Explore real-time monitoring features and workflows

Build docs developers (and LLMs) love

Get started for freeTalk to us