Skip to content

feat(postgresql): graceful primary switchover #99

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
renecannao merged 12 commits into from
Apr 18, 2026
Merged

feat(postgresql): graceful primary switchover #99

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
a8d8e00
docs: add design spec for PostgreSQL graceful primary switchover
renecannao Apr 18, 2026
31ffa1b
docs: add implementation plan for PostgreSQL graceful primary switchover
renecannao Apr 18, 2026
44c12e9
feat(postgresql): add PostgreSQLSetReadOnly for graceful switchover
renecannao Apr 18, 2026
51ce741
feat(postgresql): add PostgreSQLGetCurrentWALLSN for graceful switchover
renecannao Apr 18, 2026
d6c4a9f
feat(postgresql): add PostgreSQLWaitForStandbyLSN for graceful switch…
renecannao Apr 18, 2026
1dfea47
feat(postgresql): add PostgreSQLRepositionAsStandby for graceful swit…
renecannao Apr 18, 2026
19b510b
feat(postgresql): add PostgreSQLGracefulPrimarySwitchover orchestration
renecannao Apr 18, 2026
ae749c7
feat(postgresql): dispatch graceful-master-takeover to PostgreSQL swi…
renecannao Apr 18, 2026
2ea800e
test(postgresql): add functional test for graceful primary switchover
renecannao Apr 18, 2026
a7c0456
docs: update PostgreSQL docs to reflect graceful switchover support
renecannao Apr 18, 2026
dcafd12
fix(postgresql): address code review findings for graceful switchover
renecannao Apr 18, 2026
a594961
test(postgresql): expand graceful switchover coverage and enforce in CI
renecannao Apr 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .github/workflows/functional.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -278,7 +278,6 @@ jobs:

- name: Run PostgreSQL tests
run: bash tests/functional/test-postgresql.sh
continue-on-error: true # PG support is new — iterating on CI stability

- name: Collect orchestrator logs
if: always()
Expand Down
10 changes: 8 additions & 2 deletions docs/database-providers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,8 +180,14 @@ GRANT pg_monitor TO orchestrator;
- **`client_port` from `pg_stat_replication`** is an ephemeral port, not the
PostgreSQL listen port. Orchestrator uses `DefaultInstancePort` for standby
discovery, so all instances must listen on the same port.
- **Graceful master takeover** (planned switchover) is not yet implemented for
PostgreSQL. Only unplanned failover (dead primary) is supported.
- **Graceful master takeover** (planned switchover) is supported for PostgreSQL.
The same CLI commands and API endpoints (`graceful-master-takeover`,
`graceful-master-takeover-auto`) work for PostgreSQL clusters. The switchover
sets the primary read-only, waits for the designated standby to catch up via
WAL LSN, promotes the standby, reconfigures remaining standbys, and configures
the demoted primary's `primary_conninfo`. The demoted primary requires an
operator-managed restart with `standby.signal` — use
`PostGracefulTakeoverProcesses` hooks to automate this step.
Comment on lines +183 to +190
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

PostgreSQL privileges required for ALTER SYSTEM pg_reload_conf pg_terminate_backend pg_signal_backend

💡 Result:

PostgreSQL privileges required: - ALTER SYSTEM: Superuser or users granted the ALTER SYSTEM privilege on the specific configuration parameter (via GRANT ALTER SYSTEM ON PARAMETER ...). {value: Superuser or ALTER SYSTEM privilege on parameter, citations: [1,2,4], confidence: high} - pg_reload_conf: Superuser or EXECUTE privilege granted on the pg_catalog.pg_reload_conf function (via GRANT EXECUTE ON FUNCTION pg_catalog.pg_reload_conf TO role;). These signaling functions are restricted to superusers by default but access may be granted using GRANT. {value: Superuser or EXECUTE on pg_reload_conf, citations: [6,8,11], confidence: high} - pg_terminate_backend(pid): Superuser, or the calling role is a member of the target backend's role, or has privileges of the pg_signal_backend role. Only superusers can terminate superuser backends. {value: Superuser, member of target role, or pg_signal_backend role, citations: [6,7,11], confidence: high} - pg_signal_backend(pid): This appears to refer to the pg_signal_backend predefined role (not a function). Membership in pg_signal_backend role allows signaling (cancel/terminate) other backends (via pg_cancel_backend/pg_terminate_backend). Superusers bypass this. {value: pg_signal_backend role membership, citations: [6,7,13], confidence: high}

Citations:

🏁 Script executed:

# First, let's read the specific documentation section mentioned
head -200 docs/database-providers.md | tail -50

Repository: ProxySQL/orchestrator

Length of output: 2911

🏁 Script executed:

# Search for pg_monitor mentions in the documentation
rg "pg_monitor" docs/database-providers.md -B 5 -A 5

Repository: ProxySQL/orchestrator

Length of output: 688

🏁 Script executed:

# Find the PostgreSQL instance topology implementation
fd "instance_topology_postgresql" --type f

Repository: ProxySQL/orchestrator

Length of output: 149

🏁 Script executed:

# Search for ALTER SYSTEM, pg_reload_conf, pg_terminate_backend in codebase
rg "ALTER SYSTEM|pg_reload_conf|pg_terminate_backend" --type go -B 2 -A 2

Repository: ProxySQL/orchestrator

Length of output: 5706

🏁 Script executed:

# Check the exact context around the pg_monitor requirement to see where prerequisites are documented
rg -B 10 "pg_monitor role:" docs/database-providers.md

Repository: ProxySQL/orchestrator

Length of output: 47

🏁 Script executed:

# Verify if there are any existing privilege requirements documented for graceful takeover nearby
rg -A 20 "Graceful master takeover" docs/database-providers.md | head -40

Repository: ProxySQL/orchestrator

Length of output: 1039

Add privilege requirements to PostgreSQL graceful takeover documentation.

The graceful takeover implementation requires additional PostgreSQL privileges beyond pg_monitor. The operations (ALTER SYSTEM, pg_reload_conf(), pg_terminate_backend()) require superuser access or equivalent role-based privileges. Update the documentation to specify these requirements so operators can configure the orchestrator user with the necessary permissions before attempting graceful takeover.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/database-providers.md` around lines 183 - 190, Update the PostgreSQL
graceful takeover docs to state that in addition to the pg_monitor role, the
orchestrator user must have superuser privileges or equivalent role-based
permissions to run ALTER SYSTEM, call pg_reload_conf(), and execute
pg_terminate_backend(); mention these specific operations and recommend granting
either superuser or targeted role-based privileges (or extension of pg_monitor)
before using the CLI/API endpoints (`graceful-master-takeover`,
`graceful-master-takeover-auto`), and add a note explaining that an
operator-managed restart (triggered via `PostGracefulTakeoverProcesses`) is
still required for the demoted primary.


## Implementing a New Provider

Expand Down
Loading
Loading