From ecbc17354ba13af706711d4191e8b8918c9b1e82 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 8 Jun 2026 09:49:52 +0000 Subject: [PATCH 1/2] docs: port managed-postgres branching doc and Supabase migration link --- products/managed-postgres/branching.mdx | 108 ++++++++++++++++++ .../managed-postgres/migrations/overview.mdx | 4 + products/managed-postgres/navigation.json | 1 + 3 files changed, 113 insertions(+) create mode 100644 products/managed-postgres/branching.mdx diff --git a/products/managed-postgres/branching.mdx b/products/managed-postgres/branching.mdx new file mode 100644 index 000000000..a02140bff --- /dev/null +++ b/products/managed-postgres/branching.mdx @@ -0,0 +1,108 @@ +--- +slug: /cloud/managed-postgres/branching +sidebarTitle: 'Branching' +title: 'Branching' +description: 'Create isolated database branches from point-in-time snapshots for development, staging, testing, and recovery workflows' +keywords: ['managed postgres', 'branching', 'pitr', 'point-in-time recovery', 'staging', 'development', 'database branch'] +doc_type: 'guide' +--- + +import BetaBadge from "/snippets/components/BetaBadge/BetaBadge.jsx"; + + + +Managed Postgres supports creating isolated database branches using Point-in-Time Recovery (PITR). + +A branch is a fully independent PostgreSQL deployment created from a specific point in time of an existing database. Branches can be used for development, staging, testing, debugging, data validation, or recovery workflows — without impacting the source database. + +Unlike copy-on-write implementations that share storage with the primary database, Managed Postgres branches are restored from backups and operate as independent PostgreSQL deployments. + +## How branching works {#branching} + +Branch creation is built on the same backup and recovery infrastructure used for [Point-in-Time Recovery (PITR)](/products/managed-postgres/backup-and-restore). + +When you create a branch, Managed Postgres restores a base backup from object storage, replays the required WAL segments to reach the requested recovery point, and provisions a new PostgreSQL deployment from the recovered state. Once recovery completes, the branch operates independently of the source database. + +The resulting branch is a complete copy of the source database at the selected point in time. + +## Common use cases {#common-use-cases} + +### Development and testing {#dev-and-testing} + +Create a branch from a production or staging database to validate application changes, migrations, or new features against realistic data. + +### Staging environments {#staging-environments} + +Maintain a staging environment that closely mirrors production without affecting production workloads. + +### Data validation {#date-validation} + +Test schema changes, indexing strategies, and query optimizations before deploying them to production. + +### Recovery and investigation {#recovery-and-investigation} + +Recover a database to a specific point in time for troubleshooting, auditing, or validating application behavior. + +## Branch sizing {#branch-sizing} + +Branches are independent PostgreSQL deployments and can be sized separately from the source database. + +For example, a production deployment may run on a larger configuration while a development or staging branch can use a smaller compute profile to reduce costs. This lets teams create temporary environments without matching the compute resources of production. + +## Branch creation time {#branch-creation-time} + +Because Managed Postgres uses NVMe-backed PostgreSQL storage, branches are restored from backups rather than created through storage-level copy-on-write mechanisms. As a result, branch creation isn't instantaneous. + +Typical branch creation times range from several minutes to tens of minutes, depending on: + +- Database size +- Backup size +- Recovery point +- Amount of WAL that must be replayed +- Overall cluster configuration + +For most deployments, branches are available within a few minutes. Larger databases may require additional time. + +If branch creation time becomes a bottleneck for your workflow, contact the ClickHouse team. In many cases, branch recovery performance can be optimized based on workload characteristics and recovery requirements. + +## Branches vs local development {#branches-v-local-dev} + +A common question is whether every developer should use a production branch as their development environment. + +While branches are useful for testing, validation, and staging workflows, they're generally not the recommended approach for day-to-day application development. Each branch is a separate PostgreSQL deployment that must be restored from backups and maintained independently. Creating large numbers of branches can increase infrastructure costs and operational complexity. + +For most organizations, we recommend: + +- Using PostgreSQL branches for staging, testing, debugging, and validation workflows. +- Using local PostgreSQL environments for day-to-day development. +- Generating synthetic development datasets or using sanitized datasets where appropriate. +- Avoiding routine development directly against production-derived branches. + +This approach reduces load on production systems, improves development velocity, and helps ensure that production data remains appropriately protected. + +For guidance on creating local PostgreSQL development environments using Docker, see Local development environments. + +{/* TODO: link to /products/managed-postgres/local-development once the Mintlify port of docs/cloud/managed-postgres/local-development.md exists. */} + +## Recommended workflow {#recommended-workflow} + +A common workflow looks like: + +```text +Production Database + │ + ├─────────────► Branch + │ │ + │ ├── Staging + │ ├── Validation + │ ├── Migration Testing + │ └── Incident Investigation + │ + └─────────────► Local Development + │ + ├── Docker PostgreSQL + ├── Application Migrations + └── Synthetic Test Data +``` + +Branches are best suited for environments that need a production-like copy of a database. For routine development, local PostgreSQL environments typically provide a faster, lower-cost, and more scalable workflow. diff --git a/products/managed-postgres/migrations/overview.mdx b/products/managed-postgres/migrations/overview.mdx index df3913277..6506d4daa 100644 --- a/products/managed-postgres/migrations/overview.mdx +++ b/products/managed-postgres/migrations/overview.mdx @@ -65,3 +65,7 @@ Once data is moving, use [data validation](/products/managed-postgres/migrations to confirm row counts and content match between source and target before cutting over application traffic. The [migrations FAQ](/products/managed-postgres/migrations/faq) covers common errors and recovery steps. + +## Migrating from Supabase {#supabase} + +If you're migrating from Supabase, see the [Supabase to Managed Postgres migration guide](https://github.com/iskakaushik/supa-auth-migrate/blob/main/MIGRATION.md) for a step-by-step walkthrough. diff --git a/products/managed-postgres/navigation.json b/products/managed-postgres/navigation.json index 961c270df..114d2e98f 100644 --- a/products/managed-postgres/navigation.json +++ b/products/managed-postgres/navigation.json @@ -20,6 +20,7 @@ "products/managed-postgres/high-availability", "products/managed-postgres/read-replicas", "products/managed-postgres/backup-and-restore", + "products/managed-postgres/branching", "products/managed-postgres/extensions", { "group": "pg_clickhouse", From 8d2ec920d9fab437b86b8f5c44ab7cb471f49fc8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 8 Jun 2026 14:11:58 +0000 Subject: [PATCH 2/2] docs: resolve TODO - wire up local-development link in branching.mdx --- products/managed-postgres/branching.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/products/managed-postgres/branching.mdx b/products/managed-postgres/branching.mdx index a02140bff..50e1bf7e4 100644 --- a/products/managed-postgres/branching.mdx +++ b/products/managed-postgres/branching.mdx @@ -80,9 +80,7 @@ For most organizations, we recommend: This approach reduces load on production systems, improves development velocity, and helps ensure that production data remains appropriately protected. -For guidance on creating local PostgreSQL development environments using Docker, see Local development environments. - -{/* TODO: link to /products/managed-postgres/local-development once the Mintlify port of docs/cloud/managed-postgres/local-development.md exists. */} +For guidance on creating local PostgreSQL development environments using Docker, see [Local development environments](/products/managed-postgres/local-development). ## Recommended workflow {#recommended-workflow}