@sysnee/pgs 0.1.6 → 0.1.7-rc.10

package/docs/PROJECT.md

@@ -4,7 +4,7 @@
 
 ### What It Is
 
-A **dynamic PostgreSQL multi-tenant management system** that provides complete database isolation by creating dedicated PostgreSQL instances per tenant. The system uses HAProxy with custom PostgreSQL protocol parsing to route connections intelligently while maintaining complete tenant isolation at the database server level.
+A **dynamic PostgreSQL multi-tenant management system** that provides complete database isolation by creating dedicated PostgreSQL instances per tenant. The system uses **Traefik v3** with native PostgreSQL STARTTLS support to route connections based on SNI (Server Name Indication), enabling hostname-based tenant routing with TLS security.
 
 ### Core Concept
 
@@ -22,15 +22,16 @@ Instead of sharing a single PostgreSQL instance with multiple databases (shared
    - Automatic volume and network configuration
    - Custom initialization scripts per tenant
 
-2. **Intelligent Routing**
-   - HAProxy parses PostgreSQL protocol to extract username
-   - Routes connections to correct tenant backend automatically
+2. **SNI-Based Routing**
+   - Traefik v3 handles PostgreSQL STARTTLS protocol
+   - Routes connections based on hostname (SNI)
    - Single external port (5432) for all tenants
+   - TLS/SSL encryption required
 
 3. **Access Control**
    - Per-tenant external access enable/disable
-   - Secure by default (access disabled on creation)
    - Runtime access control without service restart
+   - Dynamic Traefik configuration updates
 
 4. **Complete Isolation**
    - Separate Docker containers per tenant
@@ -39,49 +40,50 @@ Instead of sharing a single PostgreSQL instance with multiple databases (shared
    - No shared processes or memory
 
 5. **Zero-Downtime Operations**
-   - Graceful HAProxy reloads
+   - Traefik dynamic configuration (no restarts needed)
    - Independent tenant management
    - No impact on other tenants during operations
 
 ## Architecture
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│                    External Access                       │
-│                  (localhost:5432)                        │
-└──────────────────────┬──────────────────────────────────┘
-                       │
-                       ▼
-┌─────────────────────────────────────────────────────────┐
-│                    HAProxy Proxy                         │
-│  ┌──────────────────────────────────────────────────┐   │
-│  │  Frontend: postgres_frontend                     │   │
-│  │  - Listens on port 5432                          │   │
-│  │  - Parses PostgreSQL protocol (Lua script)       │   │
-│  │  - Extracts username from startup packet         │   │
-│  │  - Checks tenant-access.json for permissions     │   │
-│  └──────────────────────────────────────────────────┘   │
-└──────────────────────┬──────────────────────────────────┘
-                       │
-        ┌──────────────┼──────────────┐
-        │              │              │
-        ▼              ▼              ▼
-┌──────────────┐ ┌──────────────┐ ┌──────────────┐
-│  Backend     │ │  Backend     │ │  Backend     │
-│ pgs_tenant1  │ │ pgs_tenant2  │ │ pgs_tenant3  │
-└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
-       │                │                │
-       ▼                ▼                ▼
-┌──────────────┐ ┌──────────────┐ ┌──────────────┐
-│ PostgreSQL   │ │ PostgreSQL   │ │ PostgreSQL   │
-│ Container 1  │ │ Container 2  │ │ Container 3  │
-│              │ │              │ │              │
-│ Port: 5432   │ │ Port: 5432   │ │ Port: 5432   │
-│ (internal)   │ │ (internal)   │ │ (internal)   │
-│              │ │              │ │              │
-│ Volume:      │ │ Volume:      │ │ Volume:      │
-│ pgdata_1     │ │ pgdata_2     │ │ pgdata_3     │
-└──────────────┘ └──────────────┘ └──────────────┘
+┌─────────────────────────────────────────────────────────────────┐
+│                       External Access                            │
+│           (tenant-id.pgs.domain.com:5432 + TLS/SNI)             │
+└───────────────────────────┬─────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      Traefik v3 Proxy                            │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │  EntryPoint: postgres (port 5432)                         │  │
+│  │  - TLS termination with wildcard certificate              │  │
+│  │  - PostgreSQL STARTTLS protocol support                   │  │
+│  │  - SNI-based routing (HostSNI rule)                       │  │
+│  │  - Dynamic configuration via dynamic.yml                  │  │
+│  └───────────────────────────────────────────────────────────┘  │
+└───────────────────────────┬─────────────────────────────────────┘
+                            │
+         ┌──────────────────┼──────────────────┐
+         │                  │                  │
+         ▼                  ▼                  ▼
+┌──────────────┐   ┌──────────────┐   ┌──────────────┐
+│  TCP Router  │   │  TCP Router  │   │  TCP Router  │
+│  tenant1     │   │  tenant2     │   │  tenant3     │
+│  HostSNI()   │   │  HostSNI()   │   │  HostSNI()   │
+└──────┬───────┘   └──────┬───────┘   └──────┬───────┘
+       │                  │                  │
+       ▼                  ▼                  ▼
+┌──────────────┐   ┌──────────────┐   ┌──────────────┐
+│ PostgreSQL   │   │ PostgreSQL   │   │ PostgreSQL   │
+│ Container 1  │   │ Container 2  │   │ Container 3  │
+│              │   │              │   │              │
+│ Port: 5432   │   │ Port: 5432   │   │ Port: 5432   │
+│ (internal)   │   │ (internal)   │   │ (internal)   │
+│              │   │              │   │              │
+│ Volume:      │   │ Volume:      │   │ Volume:      │
+│ pgdata_1     │   │ pgdata_2     │   │ pgdata_3     │
+└──────────────┘   └──────────────┘   └──────────────┘
 ```
 
 ## Technical Implementation
@@ -91,37 +93,88 @@ Instead of sharing a single PostgreSQL instance with multiple databases (shared
 1. **Manager Script (manager.js)**
    - Node.js CLI tool for tenant lifecycle management
    - Dynamically generates docker-compose.yml entries
-   - Manages HAProxy configuration
+   - Manages Traefik dynamic configuration (dynamic.yml)
    - Controls tenant access permissions
 
-2. **HAProxy Reverse Proxy**
-   - TCP-level load balancer and router
-   - Custom Lua script for PostgreSQL protocol parsing
-   - Routes based on extracted username
-   - Per-tenant access control
+2. **Traefik v3 Reverse Proxy**
+   - TCP-level routing with TLS termination
+   - Native PostgreSQL STARTTLS protocol support
+   - SNI-based routing via HostSNI() rule
+   - Dynamic configuration without restarts
 
-3. **PostgreSQL Protocol Parser (pg-route.lua)**
-   - Parses binary PostgreSQL startup packet
-   - Extracts username and connection parameters
-   - Handles SSL negotiation
-   - Enforces access control policies
-
-4. **Docker Infrastructure**
+3. **Docker Infrastructure**
    - Separate container per tenant
    - Bridge network for internal communication
    - Persistent volumes for data
    - Isolated execution environments
 
+### Why Traefik v3 for PostgreSQL?
+
+PostgreSQL uses a non-standard TLS negotiation called STARTTLS:
+
+```
+Standard TLS (HTTPS):
+  Client → TLS ClientHello (with SNI) → Server
+  
+PostgreSQL STARTTLS:
+  Client → SSLRequest (PG protocol) → Server
+  Server → 'S' (SSL supported) → Client
+  Client → TLS ClientHello (with SNI) → Server
+```
+
+Most SNI proxies expect TLS ClientHello as the first packet. PostgreSQL sends its own protocol first, then TLS.
+
+**Traefik v3** is one of the few proxies that natively understands this PostgreSQL-specific flow:
+- Detects PostgreSQL SSLRequest
+- Responds with 'S'
+- Captures TLS ClientHello with SNI
+- Routes based on hostname
+
 ### Connection Flow
 
-1. Client connects to `localhost:5432` with username `tenant_id`
-2. HAProxy receives connection and invokes Lua script
-3. Script parses PostgreSQL startup packet and extracts username
-4. Script checks `tenant-access.json` for permission
-5. If allowed, routes to backend `pgs_{tenant_id}`
-6. Backend forwards to PostgreSQL container on internal network
+1. Client connects to `tenant-id.pgs.domain.com:5432` with `sslmode=require`
+2. Traefik receives connection and detects PostgreSQL SSLRequest
+3. Traefik responds 'S' (SSL supported)
+4. Client sends TLS ClientHello with SNI (hostname)
+5. Traefik extracts SNI and matches against configured routers in dynamic.yml
+6. If tenant has access enabled, routes to backend `pgs_{tenant_id}:5432`
 7. Connection established with complete isolation
 
+### Configuration Files
+
+**traefik.yml** (Static Configuration):
+```yaml
+entryPoints:
+  postgres:
+    address: ":5432"
+
+providers:
+  file:
+    filename: /etc/traefik/dynamic.yml
+    watch: true
+```
+
+**dynamic.yml** (Dynamic Configuration - Auto-generated):
+```yaml
+tcp:
+  routers:
+    router_tenant1:
+      entryPoints:
+        - postgres
+      rule: "HostSNI(`tenant1-abc123.pgs.domain.com`)"
+      service: svc_tenant1
+      tls: {}
+  services:
+    svc_tenant1:
+      loadBalancer:
+        servers:
+          - address: "pgs_tenant1-abc123:5432"
+tls:
+  certificates:
+    - certFile: /etc/traefik/certs/fullchain.pem
+      keyFile: /etc/traefik/certs/privkey.pem
+```
+
 ## Comparison with Similar Solutions
 
 ### Shared Database Architecture
@@ -152,7 +205,7 @@ Instead of sharing a single PostgreSQL instance with multiple databases (shared
 - **Difference**: Shards data across nodes; this creates separate instances per tenant
 - **Use Case**: Horizontal scaling vs. tenant isolation
 
-#### 3. **Patroni + HAProxy**
+#### 3. **Patroni + Traefik/HAProxy**
 - **Purpose**: High availability and load balancing
 - **Difference**: Replicates single database; this creates isolated instances
 - **Use Case**: HA for single database vs. multi-tenant isolation
@@ -173,18 +226,18 @@ Instead of sharing a single PostgreSQL instance with multiple databases (shared
    - Not just database or schema separation
    - Complete process and memory isolation
 
-2. **Dynamic provisioning with single external port**
+2. **SNI-based routing with single external port**
    - No need for port management
-   - Automatic routing based on connection parameters
+   - Automatic routing based on hostname
+   - TLS/SSL security by default
 
-3. **Protocol-aware routing**
-   - Parses PostgreSQL binary protocol
-   - Routes before connection completion
-   - Handles SSL negotiation
+3. **PostgreSQL STARTTLS support**
+   - Traefik v3 handles non-standard PG protocol
+   - Proper SNI extraction after PG handshake
 
 4. **Runtime access control**
    - Enable/disable tenant access without restart
-   - No downtime for access changes
+   - Dynamic Traefik configuration
 
 5. **Docker-native architecture**
    - Leverages container isolation
@@ -211,9 +264,9 @@ Instead of sharing a single PostgreSQL instance with multiple databases (shared
 ## Advantages
 
 ✅ **Maximum Isolation**: Complete process and data separation
-✅ **Security**: Zero risk of cross-tenant data access
+✅ **Security**: Zero risk of cross-tenant data access + TLS encryption
 ✅ **Flexibility**: Independent scaling and management per tenant
-✅ **Simplicity**: Single external port, automatic routing
+✅ **Simplicity**: Single external port, automatic SNI routing
 ✅ **Compliance**: Easier to meet regulatory requirements
 ✅ **Debugging**: Isolated environments simplify troubleshooting
 
@@ -223,15 +276,16 @@ Instead of sharing a single PostgreSQL instance with multiple databases (shared
 ⚠️ **Management Overhead**: More containers to manage
 ⚠️ **Scaling Limits**: Practical limit on number of tenants per host
 ⚠️ **Backup Complexity**: Need to backup multiple instances
+⚠️ **SSL Required**: Clients must support TLS with SNI
 
 ## Technology Stack
 
 - **Runtime**: Node.js (ES Modules)
 - **Container Orchestration**: Docker Compose
-- **Reverse Proxy**: HAProxy with Lua scripting
+- **Reverse Proxy**: Traefik v3 (PostgreSQL STARTTLS + SNI routing)
 - **Database**: PostgreSQL 18+
-- **Protocol Parsing**: Custom Lua script
-- **Configuration**: YAML (docker-compose.yml), JSON (tenant-access.json)
+- **TLS**: Wildcard SSL certificate
+- **Configuration**: YAML (docker-compose.yml, traefik.yml, dynamic.yml), JSON (tenant-access.json)
 
 ## Future Enhancements
 
@@ -242,9 +296,8 @@ Instead of sharing a single PostgreSQL instance with multiple databases (shared
 - [ ] Tenant migration tools
 - [ ] Kubernetes support
 - [ ] Connection pooling per tenant
-- [ ] SSL/TLS termination
+- [ ] Web dashboard
 
 ## License & Status
 
-This is a custom solution built for specific multi-tenant requirements. It combines open-source tools (HAProxy, PostgreSQL, Docker) with custom routing logic to achieve instance-per-tenant isolation with intelligent connection routing.
-
+This is a custom solution built for specific multi-tenant requirements. It combines open-source tools (Traefik v3, PostgreSQL, Docker) with SNI-based routing to achieve instance-per-tenant isolation with intelligent connection routing.