Skip to content

feat: Add treplica helper for PostgreSQL streaming read replicas - #404

Open
O1eq wants to merge 3 commits into
totara:masterfrom
O1eq:feat-add-treplica
Open

O1eq wants to merge 3 commits into
totara:masterfrom
O1eq:feat-add-treplica

Conversation

@O1eq

@O1eq O1eq commented Aug 7, 2026

Copy link
Copy Markdown

Description

Adds a new bin/treplica command that creates and manages a PostgreSQL streaming read replica of any totara pgsql container. Its purpose is testing Totara's database read/write splitting feature ($CFG->dboptions['readonly']), which routes read queries to a read-only replica.

  • treplica up [pgsqlNN] - clones the running primary with pg_basebackup into a new volume and starts it as a hot standby (default service: pgsql16). Image, PGDATA and resource settings (max_connections, max_locks_per_transaction, ...) are derived from the running primary, so it works with any pgsql version/config without hardcoded values. Idempotent: re-running shows status, a stopped replica is restarted, a stale volume is refused with a hint. Ends by printing the ready-to-paste config.php block (including a warning that it must be placed after the config-after.phpinclude, which reassigns $CFG->dboptions).
  • treplica status - recovery check, pg_stat_replication, replication lag.
  • treplica logs - follows the standby's statement log.
  • treplica down - removes container + volume after confirmation and drop the replication slot if one was created.
  • Options: --port (publish on a host port), --slot (physical replication slot for bulk-load safety), --quiet-logs.

Testing Instructions

  1. Check out this pull request
  2. Have any Totara site running on a pgsql container (e.g. pgsql16)
  3. Run treplica up - it should finish with state: streaming / Replica lag: in sync and print a config.php snippet
  4. Run treplica status - same healthy output; run treplica up again - it should no-op politely
  5. (Optional, needs a t21/TL-36188 site) paste the printed readonly block at the end of your config.php, set $CFG->perfdebug = 15;, reload any page and check the footer shows "DB reads from replica" counting up, while treplica logs shows only SELECT statements
  6. Run treplica down, confirm - container, volume (and slot, if --slot was used) are removed; treplica status now reports there is no replica

Checklist

  • Does what the author says it will do
  • Testing instructions are provided
  • Commit messages make sense and follow the conventional commit standard
  • No identified security issues
  • No identified maintenance issues
  • Any third-party libraries/dependencies use the MIT or Apache 2.0 license
  • Changes made are backwards compatible and will not break existing setups
  • Changes to scripts in the bin/ directory run correctly on both MacOS and WSL
  • Changes to containers can be built locally sucessfully (e.g. via tbuild container && tup container)
  • Containers/images are compatible with both AMD64 (Windows) and ARM64 (MacOS)
  • Changes made to config.php are compatible with our oldest supported Totara version, our newest Totara version, and Moodle

Comment thread bin/treplica
@O1eq O1eq changed the title Add treplica helper for PostgreSQL streaming read replicas feat: add treplica helper for PostgreSQL streaming read replicas Aug 17, 2026
@O1eq O1eq changed the title feat: add treplica helper for PostgreSQL streaming read replicas Add treplica helper for PostgreSQL streaming read replicas Aug 17, 2026
@O1eq
O1eq force-pushed the feat-add-treplica branch from d1b7036 to 2acbb24 Compare August 17, 2026 03:33
@O1eq O1eq changed the title Add treplica helper for PostgreSQL streaming read replicas feat: Add treplica helper for PostgreSQL streaming read replicas Aug 17, 2026
Oleg Demeshev and others added 2 commits August 28, 2026 11:15
@O1eq
O1eq force-pushed the feat-add-treplica branch from 2acbb24 to 5eb79fb Compare August 27, 2026 23:15
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants