docs: document the in-place primary/replica role switch

documentation/changelog.mdx

@@ -21,6 +21,8 @@ This page tracks significant updates to the QuestDB documentation.
 
 ### New
 
+- [SWITCH ROLE](/docs/query/sql/switch-role/) - New reference page for switching a QuestDB Enterprise node between the primary and replica roles in place, with `SWITCH STATUS`, the timeout semantics, the statement errors, and the `SWITCH ROLE` permission
+- [Failover and role switch](/docs/high-availability/failover/) - Operator guide for planned switchovers and promotions without a restart: prerequisites, the timeout budget, refusals and the `UNKNOWN` state, what each client protocol sees during a demote, the restart hazard, and the `GET /lifecycle` and `POST /lifecycle/switch` endpoints
 - [Cold storage](/docs/concepts/cold-storage/) - Historical partitions move to S3, Google Cloud Storage, Azure Blob Storage, or a filesystem store as Parquet and stay queryable with normal SQL, covering the partition lifecycle, the range-read path, the immutability boundary at `DROP LOCAL`, and the manager and refresher roles
 - [Operating cold storage](/docs/operations/cold-storage/) - Setup guide and runbook: preparing the object store prefix, configuring the cluster, the two-step manager handoff, remote garbage collection, cold-read metrics, backup interaction, and a troubleshooting table
 - [Cold storage configuration](/docs/configuration/cold-storage/) - Every `cold.storage.*` setting, covering the store connection, roles, upload, read path, garbage collection, and request timeouts
@@ -45,6 +47,11 @@ This page tracks significant updates to the QuestDB documentation.
 
 ### Reference
 
+- Added the [`node_role()`](/docs/query/functions/meta/#node_role) function, which reports the replication role of the instance to any authenticated session
+- [RBAC](/docs/security/rbac/#failover-operator) - Added the `SWITCH ROLE` permission to the permissions table, a failover operator scenario, and the built-in admin's break-glass role in a replicated cluster
+- [Minimal HTTP server](/docs/operations/logging-metrics/#lifecycle-endpoint) - Documented the `GET /lifecycle` component snapshot and the [`http.health.check.authentication.required`](/docs/configuration/http-min-server/#httphealthcheckauthenticationrequired) setting
+- [Replication metrics](/docs/operations/logging-metrics/#replication-metrics) - Added `questdb_replication_pending_upload_txn` and `questdb_backup_active_at_last_demote`
+- [Replication configuration](/docs/configuration/database-replication/#replicationrole) - Documented that `replication.role` is the boot role, the `primary-catchup-uploads` value, and the restart hazard after an in-place switch
 - [Storage Policy](/docs/concepts/storage-policy/) - The `TO REMOTE` and `DROP REMOTE` stages are now enforced. Documented what each does, the requirement for a WAL table with cold storage enabled, and the warning that `DROP LOCAL` makes a partition read-only for good
 - Added the [`table_cold_partitions()`](/docs/query/functions/meta/#table_cold_partitions) function, which returns the remote state of every partition in a table's manifest as it walks `pending`, `live`, `sealed`, and `deleting`
 - [SHOW PARTITIONS](/docs/query/sql/show/#show-partitions) - Two trailing columns, `seqTxn` and `isRemotelyServed`, are appended to the result set. Tools binding columns by position must be updated
@@ -80,6 +87,8 @@ This page tracks significant updates to the QuestDB documentation.
 
 ### Updated
 
+- [Replication setup guide](/docs/high-availability/setup/#migration-procedures) - Planned primary migration now points at the in-place switch; the restart-based flow is kept for older versions and the emergency migration is marked as the lossy path
+- [Error codes](/docs/troubleshooting/error-codes/#er005) - ER005 now covers the refusal of an in-place promotion, and ER006 the restart of a demoted node with a stale `replication.role`
 - Client libraries rewritten for the QWP binary protocol, unifying ingestion and streaming SQL queries under one handle: [Java](/docs/connect/clients/java/), [Python](/docs/connect/clients/python/), [Go](/docs/connect/clients/go/), [C & C++](/docs/connect/clients/c-and-cpp/), [Rust](/docs/connect/clients/rust/), and [.NET](/docs/connect/clients/dotnet/)
 - [Web Console](/docs/getting-started/web-console/overview/) - Documented query sharing by link and tab import/export in the [code editor](/docs/getting-started/web-console/code-editor/), custom AI providers and per-provider permission levels in [QuestDB AI](/docs/getting-started/web-console/questdb-ai/), automatic column sizing in the [result grid](/docs/getting-started/web-console/result-grid/), and the storage policy section in [table details](/docs/getting-started/web-console/table-details/)
 - [AI coding agents](/docs/getting-started/ai-coding-agents/) - Repositioned around the agent skill and the Web Console MCP bridge together

documentation/configuration/database-replication.md

@@ -55,7 +55,28 @@ accepts the `ca_cert_file` and `ca_builtin_roots` TLS parameters. See
 - **Reloadable**: no
 
 Defaults to `none` for stand-alone instances. To enable replication, set to
-one of: `primary`, `replica`.
+one of: `primary`, `replica`. Values are case-insensitive.
+
+This is the role the instance boots into. Since QuestDB Enterprise 3.3.3 the
+role can also be switched at runtime with
+[`SWITCH ROLE`](/docs/query/sql/switch-role/), which does not update this
+setting.
+
+:::danger
+
+After a runtime switch, set `replication.role` to the new role on both nodes
+before either of them restarts. A demoted node that restarts with
+`replication.role=primary` can come back as a second primary on the same object
+store, and a promoted node that restarts with `replication.role=replica`
+silently demotes itself. See
+[Restarts](/docs/high-availability/failover/#restarts).
+
+:::
+
+`primary-catchup-uploads` is a one-shot maintenance value: the instance starts
+as a primary, uploads every pending transaction, and exits. It is used by the
+restart-based
+[planned primary migration](/docs/high-availability/setup/#planned-primary-migration).
 
 ### replication.summary.interval
 

documentation/configuration/http-min-server.md

@@ -3,10 +3,29 @@ title: Minimal HTTP server
 description: Configuration settings for the minimal HTTP server in QuestDB.
 ---
 
-The minimal HTTP server provides the health check and Prometheus metrics
-endpoints, running on a separate port (default 9003) from the main HTTP server.
-This lightweight server remains responsive even when the main server is under
-heavy load.
+The minimal HTTP server provides the health check, Prometheus metrics, and
+lifecycle endpoints, running on a separate port (default 9003) from the main
+HTTP server. This lightweight server remains responsive even when the main
+server is under heavy load.
+
+It serves `GET /status` (any unbound path answers the same health check),
+`GET /metrics` when metrics are enabled, `GET /lifecycle`, and in QuestDB
+Enterprise `POST /lifecycle/switch`. See the
+[minimal HTTP server](/docs/operations/logging-metrics/#minimal-http-server)
+section for the health check and lifecycle endpoints, and
+[Failover and role switch](/docs/high-availability/failover/#lifecycle-api) for
+the switch endpoint. TLS for this port is configured with the `http.min.tls.*`
+settings on the [TLS](/docs/configuration/tls/) page.
+
+## http.health.check.authentication.required
+
+- **Default**: `true`
+- **Reloadable**: no
+
+Whether `GET /status`, `GET /metrics`, and `GET /lifecycle` require
+authentication when the HTTP server does. Set to `false` to let a load balancer
+or a Kubernetes probe call them without credentials. `POST /lifecycle/switch`
+always requires credentials, regardless of this setting.
 
 ## http.min.bind.to
 

documentation/configuration/http-server.md

@@ -320,6 +320,11 @@ Limit the number of response rows over HTTP.
 Forces HTTP read-only mode when `true`, disabling commands which modify data
 or data structure (e.g. INSERT, UPDATE, CREATE TABLE).
 
+Read-only mode is a data boundary, not an administrative lockdown. With access
+control disabled, functions such as `reload_config()` and, in QuestDB
+Enterprise, the [role switch](/docs/high-availability/failover/) statements and
+endpoint stay available on a read-only interface.
+
 ## Query cache
 
 ### http.query.cache.block.count

documentation/enterprise-kubernetes-operator/high-availability.md

@@ -45,6 +45,17 @@ until an explicit promotion; fencing is not automatic failover.
 
 ## Promotion and failover
 
+:::note
+
+The operator performs a cutover by changing configuration and re-rolling pods.
+It does not use the database's in-place
+[role switch](/docs/high-availability/failover/) (`SWITCH ROLE`,
+`POST /lifecycle/switch`). Do not run those against instances managed by the
+operator: `status.currentPrimary` and the PVC role labels would no longer
+describe the cluster.
+
+:::
+
 | Mode        | Use                                                                | Data effect                                                                                                                                                                                                                                       |
 | ----------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `Planned`   | Healthy primary and live replica                                   | Drains the old primary and verifies the target before promotion. Fails rather than becoming lossy.                                                                                                                                                |

documentation/high-availability/client-failover/concepts.md

@@ -16,7 +16,8 @@ import { EnterpriseNote } from "@site/src/components/EnterpriseNote"
 </EnterpriseNote>
 
 When a QuestDB cluster fails over from one primary to another — whether through
-a planned promotion, a rolling upgrade, or an unplanned outage — clients with a
+a planned [in-place promotion](/docs/high-availability/failover/), a rolling
+upgrade, or an unplanned outage — clients with a
 single hard-coded address must be reconfigured and restarted. A failover-aware
 client instead carries the full list of peers and walks that list automatically
 when the current connection breaks.