VoltroDocumentation

Voltro + AWS RDS / Aurora

Run Voltro on AWS RDS or Aurora — Postgres and MySQL connection strings, RDS Proxy and the session-mode requirement for LISTEN/NOTIFY, SSL, and read replicas.

AWS RDS and Aurora offer managed Postgres, MySQL, and MariaDB, mapping to Voltro's postgres, mysql, and mariadb dialects. RDS/Aurora Postgres is the production-grade home for Voltro's full reactive surface — LISTEN/NOTIFY CDC, advisory-lock cluster workflows, streaming-replication read replicas, JSONB.

Connect

# RDS / Aurora Postgres
DB_DIALECT=postgres
DB_URL=postgresql://[USER]:[PASSWORD]@[INSTANCE].[ID].[REGION].rds.amazonaws.com:5432/[DB]?sslmode=require
# RDS / Aurora MySQL
DB_DIALECT=mysql
DB_URL=mysql://[USER]:[PASSWORD]@[INSTANCE].[ID].[REGION].rds.amazonaws.com:3306/[DB]?ssl-mode=REQUIRED
# RDS MariaDB
DB_DIALECT=mariadb
DB_URL=mysql://[USER]:[PASSWORD]@[INSTANCE].[ID].[REGION].rds.amazonaws.com:3306/[DB]?ssl-mode=REQUIRED

For the MySQL dialect, the framework handles the cross-dialect gaps for you (no RETURNING, inline CDC, 0/1 booleans) — see the MySQL dialect page. The MariaDB dialect adds binlog-based CDC; for cross-instance reactivity on MySQL, add @voltro/plugin-broadcast. See the CDC section below.

Enabling CDC

How you enable change-data-capture depends on the dialect:

  • Postgres — CDC is LISTEN/NOTIFY, on by default (CDC=1), no extension or flag. The only requirement is that the framework's listener runs over a session-mode connection: point DB_URL (or at least the listener) at the direct RDS instance/cluster endpoint, not RDS Proxy in its default transaction-multiplexing mode (which breaks it — see below).
  • MySQL — inline CDC by default (single-instance reactivity). No binlog path in Voltro's mysql dialect. For cross-instance reactivity add @voltro/plugin-broadcast (Redis / NATS) — it fans out app-mutation change events to every replica. (For native, binlog-driven CDC on RDS MySQL-family, use the MariaDB dialect instead.)
  • MariaDB — CDC is binlog-based (ROW format), giving cross-instance change events. RDS MariaDB needs a binlog-friendly parameter group: binlog_format=ROW, binlog_row_image=FULL, gtid_strict_mode=ON, a replication user granted REPLICATION SLAVE, REPLICATION CLIENT, and a unique server_id per instance. Note that some managed tiers restrict direct binlog access — confirm your RDS configuration exposes it before relying on cross-instance reactivity. See the MariaDB dialect page.

RDS Proxy + the LISTEN/NOTIFY gotcha (Postgres)

RDS Proxy multiplexes connections, which is great for connection-churn-heavy workloads — but its default behavior reuses backend connections across clients (transaction-level multiplexing). On Postgres that breaks LISTEN/NOTIFY: the framework's dedicated listener registers on a connection the proxy may hand to someone else, so change events never arrive.

  • App queries through RDS Proxy → fine, as long as you don't depend on the listener on that connection.
  • CDC listener → must use a direct RDS endpoint (the instance/cluster endpoint, not the proxy) so the LISTEN connection is pinned. RDS Proxy "pinning" can also keep a session sticky, but the simplest robust setup is: direct endpoint for the framework process.
  • Serverless (Lambda) → a per-request lifecycle is the wrong shape for a push-reactive Voltro process. Prefer a long-running ECS/EC2 service for the API.

SSL

RDS requires TLS for most parameter groups. Append sslmode=require (Postgres) / ssl-mode=REQUIRED (MySQL). For full chain verification, download the AWS RDS CA bundle and point the driver at it via sslmode=verify-full + the cert path; require (encrypt, don't verify hostname) is the common baseline.

Read replicas

RDS/Aurora Postgres read replicas plug straight into Voltro's replica routing — set DB_REPLICA_URLS to the reader endpoints. Aurora's single reader endpoint load-balances for you; with RDS you list each replica. Add DB_REPLICA_REGIONS + AWS_REGION for cross-region locality. See read replicas.

Verify

[voltro:dev] sql dialect resolved: postgres — CDC: LISTEN/NOTIFY, RETURNING: native
[voltro:dev] read replicas: 0 configured (DB_REPLICA_URLS empty) — all queries → primary
[voltro:dev] workflow engine: cluster-sql, dialect=postgres

Confirm with voltro logs --tail 50.

See also