@ahmedbanihani/ahmed-rivet

Zero Cache with binary protocol support (MessagePack + Gzip compression) and optimized performance for real-time data synchronization.

Features

• Binary Protocol: MessagePack encoding with Gzip compression
• Smart Compression: Only compresses payloads larger than 1KB
• Fast Compression: Level 1 Gzip for optimal speed
• Database Separation: Supports Supabase + Neon architecture
• Connection Pooling: Neon pooler support for CVR/CHANGE databases
• Production Ready: Stable deployment with persistent replica storage

Docker Image

docker pull awsahmedbanihani/ahmed-rivet:latest

Configuration

Environment Variables

# Database Configuration
ZERO_UPSTREAM_DB=postgresql://...
ZERO_CVR_DB=postgresql://...  # Supports Neon pooler
ZERO_CHANGE_DB=postgresql://... # Supports Neon pooler

# Connection Limits
ZERO_UPSTREAM_MAX_CONNS=5
ZERO_CVR_MAX_CONNS=5
ZERO_CHANGE_MAX_CONNS=2

# Worker Configuration
ZERO_NUM_SYNC_WORKERS=5

# Stability Settings
ZERO_AUTO_RESET=false
ZERO_REPLICA_FILE=/data/replica.db

# Core Settings
ZERO_APP_ID=your-app-id
ZERO_PORT=4848

Docker Deployment

# Create persistent volume
mkdir -p /data/zero-replica

# Run container
docker run -d \
  --name zero-cache \
  -p 4848:4848 \
  -v /data/zero-replica:/data \
  --env-file .env \
  -e ZERO_LOG_FORMAT=text \
  -e ZERO_REPLICA_FILE=/data/replica.db \
  -e ZERO_UPSTREAM_MAX_CONNS=5 \
  -e ZERO_CVR_MAX_CONNS=5 \
  -e ZERO_CHANGE_MAX_CONNS=2 \
  -e ZERO_NUM_SYNC_WORKERS=5 \
  --health-cmd='curl -f http://localhost:4848/ || exit 1' \
  --health-interval=30s \
  --health-timeout=5s \
  --health-retries=3 \
  --health-start-period=15s \
  --restart unless-stopped \
  awsahmedbanihani/ahmed-rivet:latest

Performance

Binary Protocol Compression

• MessagePack: 60-70% size reduction vs JSON
• MessagePack + Gzip: 85-95% size reduction vs JSON
• Compression Level: 1 (fastest)
• Compression Threshold: 1KB (smart compression)

Database Latency

• Supabase: ~193-198ms average ping
• Neon Pooler: ~192-202ms average ping

Architecture

Database Separation

• Upstream DB: Supabase Direct (port 5432) - application data
• CVR DB: Neon Pooler - client view records metadata
• CHANGE DB: Neon Pooler - change tracking metadata

Why Neon Pooler?

Supabase's transaction pooler (port 6543) does NOT support statement_timeout parameter. Neon's pooler supports full PostgreSQL compatibility including statement_timeout.

Health Check

curl http://localhost:4848/
# Response: OK

Monitoring

# Check restart count
docker inspect zero-cache --format='Restarts: {{.RestartCount}}'

# Monitor query performance
docker logs zero-cache -f | grep "processing queries"

# Check worker count
docker logs zero-cache | grep "worker=syncer.*telemetry" | wc -l

Troubleshooting

Container Restarts

If container restarts frequently:

1. Check ZERO_AUTO_RESET is set to false
2. Verify persistent volume is mounted
3. Check Supabase replication slots:

   SELECT * FROM pg_replication_slots WHERE slot_name LIKE 'your-app%';

Connection Issues

If experiencing connection errors:

1. Increase connection limits:

   ZERO_UPSTREAM_MAX_CONNS=20
   ZERO_CVR_MAX_CONNS=20

2. Reduce worker count:

   ZERO_NUM_SYNC_WORKERS=2

License

MIT

Author

Ahmed Banihani

Version

0.2.7-optimized