docs: add Multigres Public Alpha documentation — MERGE ON SEP 14, 2026 (#49020)

## I have read the CONTRIBUTING.md file. YES ## What kind of change does this PR introduce? This PR adds Public Alpha documentation for Multigres, Supabase's multi-node Postgres high-availability integration. It introduces an overview guide, a compatibility stub, Database sidebar navigation, a Features table row, and a "What you get" card grid. ContentListings items can now omit `href` so those cards are not forced to be links. Linear: MUL-452. ~~🚨 **DO NOT MERGE UNTIL THE PUBLIC ALPHA GOES LIVE** 🚨~~ [@jhydra12 OK'ed merging, FYI] ## What is the current behavior? - Linear item: Documentation for Multigres - Production has no Multigres guides. `https://supabase.com/docs/guides/database/multigres` and `https://supabase.com/docs/guides/database/multigres/compatibility` return 404 - The Database sidebar has no Multigres section - The Features status table does not list Multigres - ContentListings items required a link (`href` was mandatory) ## What is the new behavior? - Overview guide at `/docs/guides/database/multigres` covering alpha status, eligibility, enablement, and what is not included - Compatibility stub at `/docs/guides/database/multigres/compatibility` - Database sidebar: Multigres → Overview, Compatibility (after OrioleDB) - Features table: Database / Multigres / `public alpha` - "What you get" renders as three non-link ContentListings cards - `href` is optional on ContentListings items; markdown export renders unlinked entries when it is omitted ## Additional context - Worktree: ~/GitHub/supabase/supabase-worktrees/nikrichers/mul-452-documentation-for-multigres-ready - Branch commits: Initial Multigres docs draft; Edits (cards, copy, MDX comments); merge master; spelling allow-list for Multigres, Vitess, and sharding - Verification: | Check | Result | | --------------------------------------- | --------------- | | Preview overview | 200 | | Preview compatibility | 200 | | Production overview | 404 (expected) | | Production compatibility | 404 (expected) | | `supa-mdx-lint` on changed MDX | pass | | `vitest` `lib/content-listings.test.ts` | pass (21 tests) | ### Proof: Multigres docs pages render, including non-link What you get cards **Verified:** production 404 · Vercel docs preview 200 #### Overview [(PR preview)](https://docs-git-nikrichers-mul-452-documentation-for-m-6f8a59-supabase.vercel.app/docs/guides/database/multigres) <img width="1388" height="2272" alt="image" src="https://github.com/user-attachments/assets/2780f728-07c0-4320-9826-8f6e68df21e6" /> #### Compatibility [(PR preview)](https://docs-git-nikrichers-mul-452-documentation-for-m-6f8a59-supabase.vercel.app/docs/guides/database/multigres/compatibility) <img width="1388" height="852" alt="image" src="https://github.com/user-attachments/assets/1f8f7181-5b7d-4d01-b376-a2eac923626b" /> ### Test plan - [ ] [Production overview](https://supabase.com/docs/guides/database/multigres) (404) vs [preview overview](https://docs-git-nikrichers-mul-452-documentation-for-m-6f8a59-supabase.vercel.app/docs/guides/database/multigres) - [ ] [Production compatibility](https://supabase.com/docs/guides/database/multigres/compatibility) (404) vs [preview compatibility](https://docs-git-nikrichers-mul-452-documentation-for-m-6f8a59-supabase.vercel.app/docs/guides/database/multigres/compatibility) - [ ] Database sidebar shows Multigres → Overview and Compatibility after OrioleDB - [ ] Overview shows Public Alpha caution, three What you get cards (not links), eligibility, and one-way-migration caution - [ ] Compatibility page is a placeholder that links back to the overview - [ ] Features table lists Database / Multigres / `public alpha` - [ ] `supa-mdx-lint` on `apps/docs/content/guides/database/multigres.mdx`, `apps/docs/content/guides/database/multigres/compatibility.mdx`, and `apps/docs/content/guides/getting-started/features.mdx`  ## Summary by CodeRabbit * **New Features** * Added Multigres documentation covering availability, setup, compatibility, limitations, migration behavior, and external resources. * Added Multigres to database navigation and feature-status listings. * Added an overview of Multigres benefits, including automatic failover, unchanged connection strings, and consensus-backed write durability. * **Improvements** * Content listings now support informational items without links across layouts. * Improved listing rendering and click tracking for linked and non-linked items. * **Documentation** * Added spelling support for Multigres, Vitess, and sharding terminology.  --------- Co-authored-by: Nik Richers <nik@validmind.ai> Co-authored-by: Cursor Agent <cursoragent@cursor.com>
2026-10-05 01:15:03 +03:00 · 2026-09-15 09:48:39 +10:00
1 parent 5979218c97
commit 74c116de74
@@ -517,6 +517,10 @@ Use _might_ for possibility or an uncertain outcome.

 Use _must_ or _need to_ for a requirement. Don't use _must_ for a recommendation.

+### Multigres
+
+Use _Multigres_ for the product name. Don't write _multi-gres_ or _MultiGres_.
+
 ## N

 ### native
@@ -652,6 +656,11 @@ Use _setup_ as a noun or adjective and _set up_ as a verb.
 - Recommended: Complete the setup to set up authentication.
 - Not recommended: Setup authentication.

+### shard
+
+Use _shard_ as a noun and _sharding_ for the practice of splitting data across
+nodes.
+
 ### sign in and sign-in

 Use _sign in_, _sign out_, and _sign up_ as verbs. Use the hyphenated forms
@@ -788,6 +797,10 @@ actual operation.
 Write _versus_ in prose, not _vs._ Use `vs` only when it is part of a literal name
 or when space is constrained.

+### Vitess
+
+Use _Vitess_ for the product name.
+
 ## W

 ### web
@@ -29,6 +29,8 @@ function useContentListingClickHandler(group: ContentListingGroup) {

  const trackClick = useCallback(
    (item: ContentListingItem) => {
+      if (!item.href) return
+
      sendTelemetryEvent({
        action: 'docs_content_listing_clicked',
        properties: {
@@ -73,8 +75,45 @@ function ContentListingsGroup({ group }: { group: ContentListingGroup }) {
        )}
        <ul className={listClassName}>
          {items.map((item) => {
+            const key = `${group.id}-${item.href ?? item.title}`
+            const panel = (
+              <GlassPanel
+                title={item.title}
+                icon={resolveContentListingIcon(item.icon)}
+                hasLightIcon={item.hasLightIcon ?? typeof item.icon === 'string'}
+                className={item.href ? undefined : 'cursor-default'}
+                badge={
+                  item.badge && item.badgePosition !== 'below' ? (
+                    <Badge variant="success">{item.badge}</Badge>
+                  ) : undefined
+                }
+              >
+                {item.badge && item.badgePosition === 'below' && (
+                  <Badge variant="success" className="mb-3 block w-fit">
+                    {item.badge}
+                  </Badge>
+                )}
+                {item.subtitle && (
+                  <span className="mb-2 block text-tertiary-foreground">{item.subtitle}</span>
+                )}
+                {item.description}
+              </GlassPanel>
+            )
+            const listContent = (
+              <>
+                <strong>{item.title}</strong>: {item.description}
+              </>
+            )
+
+            if (!item.href) {
+              return (
+                <li key={key} className={gridItemClassName}>
+                  {isGrid ? panel : listContent}
+                </li>
+              )
+            }
+
            const external = isExternalContentListingHref(item.href)
-            const key = `${group.id}-${item.href}`

            if (isGrid) {
              return (
@@ -87,26 +126,7 @@ function ContentListingsGroup({ group }: { group: ContentListingGroup }) {
                    target={external ? '_blank' : undefined}
                    rel={external ? 'noopener noreferrer' : undefined}
                  >
-                    <GlassPanel
-                      title={item.title}
-                      icon={resolveContentListingIcon(item.icon)}
-                      hasLightIcon={item.hasLightIcon ?? typeof item.icon === 'string'}
-                      badge={
-                        item.badge && item.badgePosition !== 'below' ? (
-                          <Badge variant="success">{item.badge}</Badge>
-                        ) : undefined
-                      }
-                    >
-                      {item.badge && item.badgePosition === 'below' && (
-                        <Badge variant="success" className="mb-3 block w-fit">
-                          {item.badge}
-                        </Badge>
-                      )}
-                      {item.subtitle && (
-                        <span className="mb-2 block text-tertiary-foreground">{item.subtitle}</span>
-                      )}
-                      {item.description}
-                    </GlassPanel>
+                    {panel}
                  </Link>
                </li>
              )
@@ -120,7 +140,7 @@ function ContentListingsGroup({ group }: { group: ContentListingGroup }) {
                  target={external ? '_blank' : undefined}
                  rel={external ? 'noopener noreferrer' : undefined}
                >
-                  <strong>{item.title}</strong>: {item.description}
+                  {listContent}
                </Link>
              </li>
            )
@@ -1139,6 +1139,20 @@ export const database: NavMenuConstant = {
        },
      ],
    },
+    {
+      name: 'Multigres',
+      url: undefined,
+      items: [
+        {
+          name: 'Overview',
+          url: '/guides/database/multigres' as `/${string}`,
+        },
+        {
+          name: 'Compatibility',
+          url: '/guides/database/multigres/compatibility' as `/${string}`,
+        },
+      ],
+    },
    {
      name: 'Access and security',
      url: undefined,
@@ -0,0 +1,60 @@
+---
+id: 'multigres'
+title: 'Multigres'
+subtitle: 'Horizontally scalable Postgres for high availability'
+description: 'Run high availability Postgres across multiple nodes with automatic failover, using Multigres.'
+---
+
+<Admonition type="caution">
+
+Multigres is in [Public Alpha](/docs/guides/getting-started/features#feature-status). It's free during the Alpha for organizations on a paid plan, for up to two projects, but pricing may change once it leaves Alpha. It isn't covered by the [uptime SLA](/sla), and Supabase isn't targeting production or mission-critical workloads with it during this stage.
+
+</Admonition>
+
+Multigres gives your project high availability by running Postgres across multiple nodes instead of one, so reads and writes continue if a node fails. It is Supabase's integration of [Multigres](https://multigres.com), an open-source project that brings the same distributed-systems approach Vitess brought to MySQL to Postgres.
+
+<ContentListings id="database-multigres-what-you-get" />
+
+## Eligibility
+
+During the Public Alpha:
+
+- Multigres is available to organizations on a paid plan. It isn't available on the Free plan.
+- Availability is being rolled out gradually, so the option to enable it may not yet appear for every eligible organization.
+- Up to two projects per eligible organization can use Multigres for free during the Alpha.
+
+## Enabling Multigres
+
+In the Dashboard, Multigres appears as **High availability** during project creation:
+
+1. Open [Create a new project](/dashboard/new/_) in the Dashboard.
+2. Under **High availability**, turn on **Enable high availability**.
+3. Finish the remaining fields such as database password, region, and compute size, if shown.
+4. Click **Create new project**.
+
+If your organization isn't eligible or hasn't been rolled out yet, **High availability** won't appear.
+
+## What's not included in the alpha
+
+Some Supabase features and project operations aren't yet available on Multigres-backed projects:
+
+- **Realtime.** Multigres doesn't yet support the logical replication that Realtime depends on, so Realtime is unavailable.
+- **Point-in-Time Recovery.** Only the standard daily backups are available.
+- **Cross-region read replicas.** Multigres projects run in a single region during the Alpha.
+- **OrioleDB.** A project can use Multigres or [OrioleDB](/docs/guides/database/orioledb), not both.
+- **Resizing after creation.** Compute size, disk, and the number of replicas can't be changed after a Multigres project is created.
+- **Sharding and custom durability policies.** These are on the longer-term roadmap but aren't part of the Alpha.
+
+<Admonition type="caution">
+
+Enabling Multigres migrates your project's database to run on Multigres. There's currently no managed path to move it back to a standard Postgres project.
+
+</Admonition>
+
+## Compatibility
+
+Multigres aims for full compatibility with standard Postgres, but there are some differences to be aware of. See [Multigres compatibility](/docs/guides/database/multigres/compatibility) for details.
+
+## Resources
+
+[Multigres documentation](https://multigres.com/docs) — architecture, self-hosted deployment, and other technical depth that goes beyond the hosted Supabase integration covered on this page.
@@ -0,0 +1,6 @@
+---
+title: 'Multigres compatibility'
+description: 'Where Multigres-backed Postgres projects differ from standard Postgres.'
+---
+
+Multigres targets full compatibility with standard Postgres, verified against the [`pg_regress`](https://www.postgresql.org/docs/current/regress.html) test suite. See the [Multigres documentation](https://multigres.com/docs) for lower-level architecture and compatibility details, and the [Multigres overview](/docs/guides/database/multigres#whats-not-included-in-the-alpha) for what's not yet supported during the Public Alpha.
@@ -176,7 +176,7 @@ Manage your projects programmatically. [Docs](/docs/reference/api).

 ## Client libraries

-Official client libraries for [JavaScript](/docs/reference/javascript/start), [Flutter](/docs/reference/dart/initializing) and [Swift](/docs/reference/swift/introduction).
+Official client libraries for [JavaScript](/docs/reference/javascript/introduction), [Flutter](/docs/reference/dart/initializing) and [Swift](/docs/reference/swift/introduction).
 Unofficial libraries are supported by the community.

 ## Feature status
@@ -208,6 +208,7 @@ In addition to the Beta requirements, features in GA are covered by the [uptime
 | Database       | Webhooks                   | `beta`         | ✅                                          |
 | Database       | Vault                      | `public alpha` | ✅                                          |
 | Database       | Supabase Pipelines         | `public alpha` | N/A                                         |
+| Database       | Multigres                  | `public alpha` | N/A                                         |
 | Platform       |                            | `GA`           | ✅                                          |
 | Platform       | Point-in-Time Recovery     | `GA`           | 🚧 [wal-g](https://github.com/wal-g/wal-g)  |
 | Platform       | Custom Domains             | `GA`           | N/A                                         |
@@ -94,3 +94,27 @@ export const databaseNextSteps: ContentListingGroup = {
    },
  ],
 }
+
+export const databaseMultigresWhatYouGet: ContentListingGroup = {
+  id: 'database-multigres-what-you-get',
+  heading: 'What you get',
+  description:
+    'When you enable Multigres on a project, your database runs as a small cluster instead of a single instance:',
+  type: 'grid',
+  items: [
+    {
+      title: 'Automatic failover',
+      description:
+        'If a node fails, another in the cluster is promoted within seconds, without you having to intervene.',
+    },
+    {
+      title: 'No connection changes',
+      description:
+        'Use the same connection string. Coordination is transparent to your application.',
+    },
+    {
+      title: 'Consensus-backed durability',
+      description: 'Writes are acknowledged only after the cluster agrees they are durable.',
+    },
+  ],
+}
@@ -2,7 +2,7 @@ import type { ContentListingGroup } from '~/lib/content-listings.schema'

 import { aiToolsBuildingIntoApp, aiToolsSupportedAgents } from './ai-tools.data'
 import { authGetStarted, authNextSteps, authPricing } from './auth.data'
-import { databaseGetStarted, databaseNextSteps } from './database.data'
+import { databaseGetStarted, databaseMultigresWhatYouGet, databaseNextSteps } from './database.data'
 import {
  functionsExamplesAiMedia,
  functionsExamplesMessaging,
@@ -42,6 +42,7 @@ const ALL_GROUPS: readonly ContentListingGroup[] = [
  authPricing,
  authNextSteps,
  databaseGetStarted,
+  databaseMultigresWhatYouGet,
  databaseNextSteps,
  functionsGetStarted,
  functionsExamplesSupabase,
@@ -34,6 +34,11 @@ export function serializeContentListingGroupToMarkdown(
  }

  for (const item of items) {
+    if (!item.href) {
+      lines.push(`- **${item.title}:** ${item.description}`)
+      continue
+    }
+
    const href = isExternalContentListingHref(item.href)
      ? item.href
      : `${linkBaseUrl}${withDocsBasePath(item.href)}`
@@ -147,6 +147,27 @@ describe('serializeContentListingGroupToMarkdown', () => {
    )
  })

+  it('renders items without href as unlinked list entries', () => {
+    const markdown = serializeContentListingGroupToMarkdown(
+      {
+        id: 'what-you-get',
+        heading: 'What you get',
+        items: [
+          {
+            title: 'Automatic failover',
+            description: 'Another node is promoted if a node goes down.',
+          },
+        ],
+      },
+      'https://supabase.com'
+    )
+
+    expect(markdown).toContain(
+      '- **Automatic failover:** Another node is promoted if a node goes down.'
+    )
+    expect(markdown).not.toContain('](')
+  })
+
  it('omits heading line when heading is not set', () => {
    const markdown = serializeContentListingGroupToMarkdown(
      {
@@ -260,9 +281,11 @@ describe('dashboard content listing hrefs', () => {
  // Root-relative /dashboard hrefs get the docs basePath and 404; use absolute URLs.
  it('uses absolute https://supabase.com dashboard URLs', () => {
    const dashboardLinks = Object.values(CONTENT_LISTINGS).flatMap((group) =>
-      group.items
-        .filter((item) => isDashboardHref(item.href))
-        .map((item) => ({ listingId: group.id, title: item.title, href: item.href }))
+      group.items.flatMap((item) =>
+        item.href && isDashboardHref(item.href)
+          ? [{ listingId: group.id, title: item.title, href: item.href }]
+          : []
+      )
    )

    expect(dashboardLinks.length).toBeGreaterThan(0)
@@ -275,6 +298,16 @@ describe('dashboard content listing hrefs', () => {
  })
 })

+describe('contentListingItemSchema href', () => {
+  it('accepts an item without href', () => {
+    const result = contentListingItemSchema.safeParse({
+      title: 'Automatic failover',
+      description: 'Another node is promoted if a node goes down.',
+    })
+    expect(result.success).toBe(true)
+  })
+})
+
 describe('contentListingItemSchema icon', () => {
  const baseItem = {
    title: 'Datadog',
@@ -22,7 +22,7 @@ export const contentListingIconSchema = z.union([z.string().min(1), contentListi

 export const contentListingItemSchema = z.object({
  title: z.string().min(1),
-  href: z.string().min(1),
+  href: z.string().min(1).optional(),
  description: z.string().min(1),
  /** Shown under the title on grid cards, before the description. */
  subtitle: z.string().min(1).optional(),
@@ -37,7 +37,7 @@ export function HighAvailabilityBadge({ size = 'default' }: HighAvailabilityBadg
            globally distributed deployments.
          </p>
          <Link
-            href={`${DOCS_URL}/guides/deployment/high-availability`}
+            href={`${DOCS_URL}/guides/database/multigres`}
            target="_blank"
            rel="noopener noreferrer"
            className="mt-1 inline-flex items-center gap-1 text-xs text-foreground-lighter transition-colors hover:text-foreground"
@@ -153,6 +153,7 @@ may_uppercase = [
    "Mixpeek",
    "Mixpeek Embed",
    "Model Context Protocol",
+    "Multigres",
    "MySQL",
    "Navigable Small World",
    "Neon",
@@ -145,6 +145,7 @@ allow_list = [
    "[Ss]anitization",
    "[Ss]erverless",
    "[Ss]erverside",
+    "[Ss]harding",
    "[Ss]itekeys?",
    "[Ss]tateful",
    "[Ss]treamable",
@@ -319,6 +320,7 @@ allow_list = [
    "[Mm]itigations",
    "Mixpeek",
    "Multiplatform",
+    "Multigres",
    "MySQL",
    "Nix",
    "[Nn]amespaces?",
@@ -442,6 +444,7 @@ allow_list = [
    "Vercel",
    "VictoriaMetrics",
    "Vite",
+    "Vitess",
    "Vonage",
    "Vue",
    "Wasm",