New to KubeDB? Please start here.

PostgreSQL Branching Overview

KubeDB Courier creates PostgreSQL branches from CSI snapshots on CoW storage such as Ceph RBD. Each branch has its own database resource, Service, storage, and auth Secret. Use a branch for development, testing, or data preparation, and optionally refresh it from its source.

Start with Courier setup or Courier cross-cluster setup. The tutorials demonstrate:

The Branch resource

A Branch is a namespaced courier.kubedb.com/v1alpha1 resource created on the source cluster. This example copies demo/prod-pg to dev/pg-dev:

apiVersion: courier.kubedb.com/v1alpha1
kind: Branch
metadata:
  name: pg-dev
  namespace: demo
spec:
  source:
    databaseRef:
      apiGroup: kubedb.com
      kind: Postgres
      name: prod-pg
    namespace: demo
  target:
    namespace: dev
    name: pg-dev
    storageClassName: ceph-rbd
    resources:
      requests:
        cpu: 500m
        memory: 1Gi
  deletionPolicy: Delete

Source

FieldMeaning
spec.source.databaseRef.apiGroupkubedb.com for a KubeDB PostgreSQL database.
spec.source.databaseRef.kindPostgres.
spec.source.databaseRef.nameName of the source database.
spec.source.namespaceSource namespace; defaults to the Branch’s namespace when omitted.

The source must be a ready, durable KubeDB PostgreSQL database with snapshot-capable Ceph storage. Put the Branch in the source namespace, as the tutorials do, to keep requests and source status together.

Target

FieldMeaning
spec.target.nameName of the new PostgreSQL database. Choose an unused name in the target namespace.
spec.target.namespaceNamespace of the branch database.
spec.target.clusterNameOCM managed-cluster name for cross-cluster branching. Omit for same-cluster branching.
spec.target.storageClassNameStorageClass on the target cluster; the examples use ceph-rbd. It must resolve compatible snapshot handles.
spec.target.resourcesPostgreSQL container CPU/memory requests and limits for the target.
spec.target.issuerRefTarget cert-manager Issuer or ClusterIssuer required when the source has TLS enabled.

Courier prepares target configuration and copies applicable source configuration Secrets. An external ServiceAccount, Secret, or other dependency referenced by your configuration must also be available in the target environment. See PostgreSQL branch configuration for TLS and overrides.

Optional behavior

FieldMeaning
spec.resetRootPasswordGenerate an independent branch root credential; defaults to false.
spec.postActionsOrdered list of action images and Job settings to run against the target before the Branch becomes Ready.
spec.schedule.cronStandard five-field cron expression for periodic refresh. Omit for a one-time branch.
spec.historyLimit.successSuccessful status-history entries to retain; defaults to 3.
spec.historyLimit.failedFailed status-history entries to retain; defaults to 2.
spec.volumeSnapshotClassNameExplicit VolumeSnapshotClass selection for source and importing snapshots.
spec.deletionPolicyDelete removes the branch database and managed resources; Orphan retains the database, its PVCs, and required Secrets. Defaults to Delete.

Post-action entries support image, jobDefaults, and jobTemplate. The post-action tutorial explains this shape with runnable SQL. Deletion policies and TLS examples are covered in configuration.

Status and readiness

Wait for the Branch to become Ready, even if the PostgreSQL resource becomes ready earlier. Credential isolation and post-actions must finish first.

kubectl -n demo wait branch/pg-dev \
  --for=jsonpath='{.status.phase}'=Ready --timeout=15m
kubectl -n demo get branch pg-dev -o yaml
Status fieldMeaning
phaseCurrent step, including Snapshotting, Cloning, Provisioning, ActionsRunning, Ready, Refreshing, Failed, or Deleting.
modeLocal for same-cluster execution, Initiator on a cross-cluster source, or Creator on its target.
conditionsReadiness and failure details for individual steps.
resourcesManaged object names, such as cloned PVCs, auth Secret, and post-action Job.
snapshotSnapshot strategy, readiness, and source-volume provenance.
refreshGenerationCurrent refresh generation.
lastRefreshTime, lastSuccessfulRefreshTime, nextRefreshTimeAttempt, completion, and scheduling timestamps.
historyBounded run history.

For cross-cluster branches, inspect the requested Branch on the source cluster and database resources on the target. The target also has a delivered Branch used by Courier; manage the lifecycle through the original source Branch.