From d9772cf39dab3531e7b545d453ed0f0d48d66b4c Mon Sep 17 00:00:00 2001
From: Bobby DeSimone <bobbydesimone@gmail.com>
Date: Wed, 29 Oct 2025 09:08:14 -0700
Subject: [PATCH] docs(zero): clarify databroker storage type auto-inference
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add Zero-specific documentation tabs to databroker reference

Resolves ENG-3098

## Changes

Added "Zero" tabs to three sections in databroker.mdx:

1. **Databroker Storage Type section**
   - Explains that storage type is automatically inferred from connection string
   - Lists format patterns for all three backends (file, postgres, memory)
   - Links to connection string section for configuration details

2. **File Storage Configuration section**
   - Shows where to configure in Zero console (Settings → General)
   - Provides file:// URI example
   - Includes note about directory permissions and persistence

3. **Postgres Storage Configuration section**
   - Demonstrates both postgres:// and postgresql:// schemes
   - Clarifies both are auto-detected
   - Includes production tip about managed databases and replication

## Formatting

- Follows Docusaurus admonition guidelines with empty lines around content
- Prettier formatting validated
- CSpell check passes

## Impact

Eliminates documentation gap for Zero users who were confused about
the absence of a separate storage type field. Clarifies that the
inference is intentional and automatic.

🤖 AI assistance disclosure: Used Claude Code to generate the MDX
tab content following existing documentation patterns. Manually
verified MDX syntax, Docusaurus admonition formatting, and Prettier
compliance.
---
 content/docs/reference/databroker.mdx | 49 +++++++++++++++++++++++++++
 content/docs/reference/reference.json |  2 +-
 2 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/content/docs/reference/databroker.mdx b/content/docs/reference/databroker.mdx
index a51ff1628..5611e768b 100644
--- a/content/docs/reference/databroker.mdx
+++ b/content/docs/reference/databroker.mdx
@@ -50,6 +50,17 @@ DATABROKER_STORAGE_TYPE=postgres
 
 `databroker_storage_type` is a bootstrap configuration setting and is not configurable in the Console.
 
+</TabItem>
+<TabItem value="Zero" label="Zero">
+
+In Pomerium Zero, the storage type is **automatically inferred** from the connection string format and does not need to be configured separately:
+
+- `file:///path/to/directory` → file backend
+- `postgres://...` or `postgresql://...` → Postgres backend
+- Empty/unset → in-memory (default)
+
+See [Databroker Storage Connection String](#databroker-storage-connection-string) below for configuration details.
+
 </TabItem>
 <TabItem value="Kubernetes" label="Kubernetes">
 
@@ -84,6 +95,21 @@ DATABROKER_STORAGE_CONNECTION_STRING=file:///var/pomerium/databroker
 
 `databroker_storage_connection_string` is a bootstrap configuration setting and is not configurable in the Console.
 
+</TabItem>
+<TabItem value="Zero" label="Zero">
+
+In Pomerium Zero, configure the connection string in the **Settings → General** section of the Zero console. The storage type is automatically inferred from the connection string:
+
+```
+file:///var/lib/pomerium
+```
+
+:::note
+
+When using the file backend, ensure the specified directory exists and has appropriate permissions. The in-memory backend (when the field is left empty) does not persist data across restarts.
+
+:::
+
 </TabItem>
 <TabItem value="Kubernetes" label="Kubernetes">
 
@@ -132,6 +158,29 @@ DATABROKER_STORAGE_CONNECTION_STRING_FILE=/run/secrets/db_connection_string
 
 `databroker_storage_connection_string` is a bootstrap configuration setting and is not configurable in the Console.
 
+</TabItem>
+<TabItem value="Zero" label="Zero">
+
+In Pomerium Zero, configure the connection string in the **Settings → General** section of the Zero console. The storage type is automatically inferred from the connection string format:
+
+```
+postgres://user:password@host:5432/database?sslmode=require
+```
+
+or
+
+```
+postgresql://user:password@host:5432/database?sslmode=require
+```
+
+Both `postgres://` and `postgresql://` schemes are supported and automatically detected as Postgres storage.
+
+:::tip
+
+For production deployments, use a managed Postgres service or ensure your database has proper backups configured. Unlike the in-memory backend, Postgres provides persistent, replicated storage suitable for multi-replica deployments.
+
+:::
+
 </TabItem>
 <TabItem value="Kubernetes" label="Kubernetes">
 
diff --git a/content/docs/reference/reference.json b/content/docs/reference/reference.json
index 0388aed86..90ef8150f 100644
--- a/content/docs/reference/reference.json
+++ b/content/docs/reference/reference.json
@@ -271,7 +271,7 @@
     "type": "URL"
   },
   "data-broker-storage-connection-string": {
-    "description": "Sets the connection string for the Databroker storage backend.",
+    "description": "Sets the connection string for the Databroker storage backend. The storage type (memory, file, or Postgres) is automatically inferred from the connection string format: 'file:///' URIs use the file backend, 'postgres://' or 'postgresql://' URIs use the Postgres backend, and empty/unset defaults to in-memory storage (not persisted across restarts).",
     "id": "data-broker-storage-connection-string",
     "path": "/databroker#databroker-storage-connection-string",
     "services": [],