cable-postgres

A PostgreSQL backend for Cable using PostgreSQL's LISTEN/NOTIFY functionality for pub/sub operations.

About

This shard provides a PostgreSQL backend for Cable, implementing real-time WebSocket communication using PostgreSQL's built-in LISTEN/NOTIFY commands. It offers a robust alternative to Redis for applications already using PostgreSQL as their primary database.

Why Choose PostgreSQL Backend?

1. Reduced Infrastructure: No need for a separate Redis server if you're already using PostgreSQL
2. Simplified Deployment: One less service to manage, monitor, and maintain
3. Built-in Reliability: Leverages PostgreSQL's proven stability and ACID compliance
4. Cost Effective: Eliminates the need for additional Redis hosting/resources

Features

• Full compatibility with Cable framework
• Automatic connection management
• Connection health monitoring via ping/pong
• Support for both postgres:// and postgresql:// URL schemes
• Concurrent publish/subscribe operations
• Proper connection pooling through Crystal's DB module

Installation

1. Add the dependency to your shard.yml:

   dependencies:
     cable-postgres:
       github: cable-cr/cable-postgres
   

2. Run shards install

Usage

require "cable"
require "cable-postgres"

Cable.configure do |settings|
  settings.url = ENV.fetch("CABLE_BACKEND_URL", "postgresql://localhost:5432/myapp")
  settings.backend_class = Cable::PostgresBackend
  
  # Optional settings
  settings.restart_error_allowance = 20
  settings.backend_ping_interval = 15.seconds
end

Environment Variables

• CABLE_BACKEND_URL: PostgreSQL connection URL (default: postgresql://localhost:5432/myapp)
• DATABASE_URL: Alternative environment variable for PostgreSQL connection

Connection URL Format

The backend supports standard PostgreSQL connection URLs:

postgresql://[user[:password]@][host][:port][/dbname][?param1=value1&...]
postgres://[user[:password]@][host][:port][/dbname][?param1=value1&...]

How It Works

The PostgreSQL backend uses two separate database connections:

1. Listen Connection: Dedicated to receiving notifications via LISTEN commands
2. Notify Connection: Used for publishing messages via NOTIFY commands

This separation ensures that publishing operations don't interfere with the listening state and provides better concurrency.

PostgreSQL LISTEN/NOTIFY

PostgreSQL's LISTEN/NOTIFY mechanism provides a lightweight pub/sub system:

• LISTEN channel: Subscribe to a notification channel
• NOTIFY channel, 'payload': Send a notification to all listeners
• Notifications are delivered asynchronously
• Payload size is limited to 8000 bytes

Development

Running Tests

Using Docker (Recommended)

1. Start PostgreSQL using Docker Compose:

   docker-compose up -d
   

2. Run tests:

   DATABASE_URL="postgresql://postgres:postgres@localhost:5432/cable_test" crystal spec
   

3. Stop PostgreSQL:

   docker-compose down
   

Or use the provided test script:

./test.sh

Using Local PostgreSQL

1. Ensure PostgreSQL is installed and running
2. Create a test database:

   createdb cable_test
   

3. Run tests:

   crystal spec
   

Contributing

1. Fork it (https://github.com/cable-cr/cable-postgres/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Performance Considerations

• PostgreSQL NOTIFY has a maximum payload size of 8000 bytes
• For high-throughput applications, Redis might still be preferred
• Connection pooling is handled by Crystal's DB module
• Consider PostgreSQL connection limits when scaling

Contributors

• Cable Contributors - maintainers