From f4984eeb31fed7d3166badd2491b143ec1654f93 Mon Sep 17 00:00:00 2001 From: Bob Ward Date: Sat, 24 Oct 2026 11:17:53 -0500 Subject: [PATCH] docs: clarify Hyperscale geo-replica initial seeding Explain snapshot-based seeding before log-service replication and link the supplement from the Chapter 9 overview. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- examples/ch09-ha-resiliency/README.md | 8 ++++++ examples/ch09-ha-resiliency/geo/README.md | 34 +++++++++++++++++++++-- 2 files changed, 40 insertions(+), 2 deletions(-) diff --git a/examples/ch09-ha-resiliency/README.md b/examples/ch09-ha-resiliency/README.md index e876224..fa2e219 100644 --- a/examples/ch09-ha-resiliency/README.md +++ b/examples/ch09-ha-resiliency/README.md @@ -26,6 +26,14 @@ The matching skills are `test-hyperscale-failover`, `recover-wardgeneral-pitr`, and `deploy-wardgeneral-geo-replica`. They drive the same commands and approval gates as the READMEs. +> **Beyond the book: geo-replicas need an initial seed.** Azure first seeds the +> new geo-replica from snapshots of the primary's physical storage into the +> target's own storage and page servers. Only then can it pull changes from the +> primary's log service to catch up and continue asynchronous replication. +> Azure does this automatically, but the cross-region copy is a size-of-data +> operation, not an instant compute-only addition. See +> [initial seeding comes before log replication](geo/README.md#supplement-initial-seeding-comes-before-log-replication). + The chapter explains HA replica count, continuous priming, failover groups, zone redundancy, backup policy, replica lag, maintenance windows, and RPO/RTO commitments without packaging each topic as another guided example. Chapter 7 diff --git a/examples/ch09-ha-resiliency/geo/README.md b/examples/ch09-ha-resiliency/geo/README.md index dbc843b..998a18a 100644 --- a/examples/ch09-ha-resiliency/geo/README.md +++ b/examples/ch09-ha-resiliency/geo/README.md @@ -107,8 +107,8 @@ have a hot local HA standby or availability-zone distribution there. If its compute fails, Azure must create replacement compute before the geo-secondary is available again, so local recovery can take longer. -Geo-replica creation is asynchronous. Wait until Azure reports the database -online, then verify it: +Geo-replica creation is asynchronous and includes the initial seeding described +below. Wait until Azure reports the database online, then verify it: ```powershell ./examples/ch09-ha-resiliency/geo/verify-geo-replica.ps1 ` @@ -120,6 +120,36 @@ geo-failover promotes it. Replication is asynchronous with respect to commit, so the primary does not wait for the geo-secondary before acknowledging a transaction. +## Supplement: initial seeding comes before log replication + +This repository supplement makes explicit a setup step not covered in the +book's geo-replication discussion: **a new Hyperscale geo-replica must first be +seeded from snapshots of the primary database's physical storage before it can +start pulling changes from the log service.** The log stream alone does not +provide the existing database contents. + +1. **Seed the data.** Azure uses storage snapshots to establish the initial + database contents in the target's own storage, served by its own page + servers. +2. **Catch up and keep up.** After seeding, the geo-replica pulls changes from + the primary's log service to catch up, then continues asynchronous log + replication as the primary accepts new transactions. + +**Azure performs this seeding automatically as part of geo-replica creation.** +There is no separate reader-run backup, restore, or synthetic-data seed script. +The primary remains online and writable during setup. + +Unlike HA and named replicas, a geo-replica **does not share the primary's page +servers or storage**, even when it is in the same region. This example creates +it in another region, so the initial data must be copied there. Allow for a +size-of-data operation, not just the time to start another compute replica; +snapshot-based seeding does not make a cross-region data copy instantaneous. +Do not treat a submitted creation request as an already protected database: +wait for creation to finish and run the verification above. + +See [Microsoft Learn: Hyperscale geo-replicas](https://learn.microsoft.com/azure/azure-sql/database/service-tier-hyperscale-replicas#geo-replica) +for the separate page-server architecture and initial data-copy requirement. + ## Supplement: a planned geo-failover, step by step This diagram is a repository supplement to the book's *The Failover Process*