Document managed database naming, URLs, and region flags

[parteeksingh24]

Summary

The managed database docs leave out three behaviors that matter when a user creates or operates a database:

• what scope DB names must be unique within
• when credentials and DATABASE_URL are actually available
• when --region is needed for CLI database commands

Observed facts

Docs/source review shows:

• docs/src/web/content/services/database/*.mdx has no mention of naming rules or uniqueness scope for database names (the only unique is a Drizzle schema snippet).
• docs/src/web/content/services/database/index.mdx says, "Creating a database from a project, or linking an existing database to a project, writes DATABASE_URL to your local .env." The platform path can omit the URL for several minutes while credential enrichment catches up, and the CLI silently skips the .env write when the create response has no env values.
• --region is not documented anywhere under the database docs, even though some DB commands need it explicitly when the DB is outside the default region.

Verification update (2026-07-07)

All three gaps confirmed on main (73cf43d4e):

• Naming rules: the only unique matches under docs/src/web/content/services/database/ are Drizzle .unique() snippets (index.mdx:74, drizzle.mdx:22). Nothing documents naming rules or uniqueness scope.
• The .env sentence is at index.mdx:23. The silent skip is specific to db create (packages/cli/src/cmd/cloud/db/create.ts:80-85, no else branch when the response has no env values). The project linking flow does warn when there is nothing to write (packages/cli/src/cmd/project/add/database.ts:187), so the docs mainly need to set expectations for create. History shows the divergence is drift: the warning was added to the linking flow later and never back-ported to create.
• --region appears nowhere under the database docs. From source: db create and db sql require a region; db get, db list, db delete, db wal, db logs, and db stats take none (get, delete, logs, and wal resolve the DB's stored region; stats reports org-wide).

Potential cause

Potential cause: the docs describe the happy path for managed databases, but not the edge cases from current platform and CLI behavior.

Suggested docs updates

Consider adding a checklist item for each gap:

• Document database naming rules and the real uniqueness scope.
• Set realistic expectations for credential and DATABASE_URL availability after creation. If URL enrichment can lag, say that plainly and tell users what to retry. Note that db create writes .env only when the create response includes env values.
• Document per-command --region behavior for database commands: which commands resolve a DB's region themselves and which ones require or benefit from an explicit region.

Related drafts

• db sql and db stats use the wrong region #1610 tracks the db sql and db stats region behavior; the docs here only need to match whatever ships there.
• Name-uniqueness behavior has operational consequences tracked internally; this docs task only asks that the documented rules match actual behavior.

Notes

No state was mutated by this investigation.

[linear]

AGENT-1619

[coderabbitai]

🔗 Related PRs

#1569 - CLI: add project add keyvalue command [merged]
#1599 - Add Postgres WAL connection API to SDK and CLI [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!