PG-SOCKET

Runs a socket.io server with events for changes from configured postgres database

Supported ENV Variables

Database Configuration (Required)

DB_DATABASE - Database Name
DB_HOST - Database Host
DB_PORT - Database Port
DB_USER - Database User
DB_PASSWORD - Database Password

or

DATABASE_URL - Postgres Connection String (ex: postgres://user:password@host:port/database?schema=public)

Optional Configs

WHITELISTED_TABLES - Comma Separated List of Tables to watch, if not set, all tables will be watched
BLACKLISTED_TABLES - Comma Separated List of Tables to ignore. Ignored in case WHITELISTED_TABLES is set
SOCKET_PORT - Port to run socket.io server on, defaults to 4000. Can be overridden by -p flag

Example Usage

CLI

npx pg-socket #-p 4001

package.json

Additionally env-cmd can be used to load the environment variables

yarn add -D pg-socket env-cmd

{
  "scripts": {
    "pg:socket": "env-cmd --silent pg-socket"
  }
}

Docker

docker run -p 4000:4000 -e DB_DATABASE=postgres -e DB_HOST=localhost -e DB_PORT=5432 -e DB_USER=postgres -e DB_PASSWORD=postgres -e WHITELISTED_TABLES=users,posts -e SOCKET_PORT=4000 -d pg-socket

Docker Compose

version: "3"

services:
  app:
    build:
      context: .
    image: my-app-backend-img
    container_name: my-app-backend
    restart: unless-stopped
  redis:
    image: redis
    container_name: my-app-redis
    restart: unless-stopped
  pg-socket:
    image: ashrhmn/pg-socket
    container_name: my-app-pg-socket
    restart: unless-stopped
    # Set ENV Variables in .env file
    env_file:
      - .env
    # Or set ENV Variables here
    environment:
      - DATABASE_URL=postgres://user:password@host:port/database?schema=public
      - WHITELISTED_TABLES=users,items
      - SOCKET_PORT=4000

Client Side Usage

Socket will emit events for each table that is watched. The event name will be the table name. The event payload will be empty.

Global watch event will be emitted on the all event. The payload will be the table name.

// Client Side
import { io } from "socket.io-client";

export const socket = io(
  process.env.NEXT_PUBLIC_SOCKET_URL
);

socket.on("products", ()=>{
    // Do something
});


socket.on("all", (tableName)=>{
  if(tableName === "products"){
    // Do something
  }
});