New to KubeDB? Please start here.

Refreshing Database Branches

A branch starts as a point-in-time copy of its source. It does not continuously receive source changes. Set spec.schedule.cron to periodically replace the target data with a fresh source snapshot, keeping development or test environments current.

Refresh applies to all supported database engines. This tutorial uses PostgreSQL to demonstrate a same-cluster branch in a different namespace. You will deploy and seed a source, create a scheduled Branch, change data on both databases, and verify what the next refresh preserves and replaces. No database from another tutorial is required.

What happens during refresh

  1. At the scheduled time, Courier advances the refresh generation and takes fresh source snapshots. It keeps the existing target running until the new snapshots are ready.
  2. For a target in another namespace, Courier imports the snapshot references into that namespace.
  3. Courier pauses the target, removes its old cloned volumes, and creates new volumes from the fresh snapshots.
  4. Courier unpauses the target, and KubeDB brings the database back up using the new volumes.
  5. After the target and any configured preparation steps complete, the Branch returns to Ready. Courier releases the previous generation’s snapshots.

If configured, root password reset and post-actions run again on every refresh before the Branch returns to Ready.

Refresh discards branch-only writes and makes the target temporarily unavailable while its storage is replaced and the database restarts. It replaces the branch’s data; it does not merge changes back into the source. The source continues to serve its own workload. Choose a schedule that fits the target application’s maintenance requirements.

Before You Begin

  • Complete the single-cluster Courier installation, including KubeDB and the Branch CRD.
  • Have a working Ceph RBD StorageClass supporting copy-on-write cloning and a compatible snapshot class. See snapshot configuration.
  • Ensure PostgreSQL version 18.3 is available in the installed KubeDB catalog, and use branching-capable KubeDB and database images.
  • Run the commands against the same Kubernetes context. Your account must be able to create databases and Branches, inspect their status and pods, and open a shell in database pods.

The manifests use the StorageClass name ceph-rbd. Substitute your Ceph RBD class consistently in both manifests. The source lives in demo and the target in dev; reserve the database names below for this tutorial.

Create the namespaces if they do not already exist:

kubectl create namespace demo
kubectl create namespace dev

Deploy the source database

Save the following as refresh-source.yaml. It creates a three-replica PostgreSQL source named refresh-source:

apiVersion: kubedb.com/v1
kind: Postgres
metadata:
  name: refresh-source
  namespace: demo
spec:
  version: "18.3"
  replicas: 3
  standbyMode: Hot
  storageType: Durable
  storage:
    storageClassName: ceph-rbd
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 2Gi
  deletionPolicy: WipeOut

Apply it and wait for the source to become ready:

kubectl apply -f refresh-source.yaml
kubectl -n demo wait postgres/refresh-source \
  --for=jsonpath='{.status.phase}'=Ready --timeout=15m

Find the source primary:

kubectl -n demo get pods -l app.kubernetes.io/instance=refresh-source,kubedb.com/role=primary -o jsonpath='{.items[0].metadata.name}{"\n"}'

Example output:

refresh-source-0

Use the returned pod name in the following commands; this example uses refresh-source-0.

Seed and inspect the source data

From your terminal, open a shell in the source primary:

kubectl -n demo exec -it refresh-source-0 -c postgres -- bash

Inside the pod, connect to database postgres. Local socket connections in this setup use trust authentication, so no password is required:

psql -U postgres -d postgres

At the postgres=# prompt, create five customer records:

CREATE TABLE customers (
    id integer PRIMARY KEY,
    full_name text NOT NULL,
    email text NOT NULL
);
INSERT INTO customers (id, full_name, email) VALUES
    (1, 'Customer 1', '[email protected]'),
    (2, 'Customer 2', '[email protected]'),
    (3, 'Customer 3', '[email protected]'),
    (4, 'Customer 4', '[email protected]'),
    (5, 'Customer 5', '[email protected]');

Inspect the source data:

SELECT * FROM customers ORDER BY id;

Expected result:

 id | full_name  |         email
----+------------+-----------------------
  1 | Customer 1 | [email protected]
  2 | Customer 2 | [email protected]
  3 | Customer 3 | [email protected]
  4 | Customer 4 | [email protected]
  5 | Customer 5 | [email protected]
(5 rows)

Leave psql with \q, then run exit in the pod shell to return to your terminal.

Create a scheduled Branch

Save the following as branch-refresh.yaml. The Branch lives in demo and creates dev/refresh-branch:

apiVersion: courier.kubedb.com/v1alpha1
kind: Branch
metadata:
  name: refresh-branch
  namespace: demo
spec:
  source:
    databaseRef:
      apiGroup: kubedb.com
      kind: Postgres
      name: refresh-source
    namespace: demo
  target:
    namespace: dev
    name: refresh-branch
    storageClassName: ceph-rbd
    resources:
      requests:
        cpu: 500m
        memory: 1Gi
  schedule:
    cron: "*/10 * * * *"
  historyLimit:
    success: 3
    failed: 2
  deletionPolicy: Delete

The initial copy starts when you create the Branch. After it becomes ready, */10 * * * * schedules refreshes at ten-minute clock boundaries: :00, :10, :20, and so on. It does not mean ten minutes after creation. For example, a branch ready at 10:02 has its next refresh scheduled for 10:10 in the Courier controller’s timezone.

Apply the manifest and wait for the initial copy:

kubectl apply -f branch-refresh.yaml
kubectl -n demo wait branch/refresh-branch \
  --for=jsonpath='{.status.phase}'=Ready --timeout=20m
kubectl -n demo get branch refresh-branch

Illustrative output:

NAME             PHASE   MODE    TARGET           FRESHNESS   AGE
refresh-branch   Ready   Local   refresh-branch   2s          3m

Outputs below illustrate successful runs; pod names, timestamps, ages, and durations vary between environments.

Check the initial copy

Find the target primary from your terminal:

kubectl -n dev get pods -l app.kubernetes.io/instance=refresh-branch,kubedb.com/role=primary -o jsonpath='{.items[0].metadata.name}{"\n"}'

Use the returned name below; this example uses refresh-branch-0:

kubectl -n dev exec -it refresh-branch-0 -c postgres -- bash

Inside the pod, start psql:

psql -U postgres -d postgres

Query the branch:

SELECT * FROM customers ORDER BY id;

It should contain the same five rows:

 id | full_name  |         email
----+------------+-----------------------
  1 | Customer 1 | [email protected]
  2 | Customer 2 | [email protected]
  3 | Customer 3 | [email protected]
  4 | Customer 4 | [email protected]
  5 | Customer 5 | [email protected]
(5 rows)

Leave psql with \q, then run exit to return to your terminal.

Check the next refresh time

Before changing either database, inspect the current generation and schedule:

kubectl -n demo get branch refresh-branch \
  -o custom-columns='PHASE:.status.phase,GENERATION:.status.refreshGeneration,LAST-SUCCESS:.status.lastSuccessfulRefreshTime,NEXT-REFRESH:.status.nextRefreshTime'

For an initial copy completed at 10:02 UTC, with Courier using UTC:

PHASE   GENERATION   LAST-SUCCESS           NEXT-REFRESH
Ready   <none>       2026-11-10T10:02:00Z   2026-11-10T10:10:00Z

The initial generation is 0; it may appear as <none> because the API omits zero values. Record the generation and successful completion time. If the next deadline is close, let that cycle finish before starting the following steps, then record the new values. Make both edits and inspect the data before the next refresh starts.

Change source and branch data

Update the source

From your terminal, find the source primary again in case a failover occurred:

kubectl -n demo get pods -l app.kubernetes.io/instance=refresh-source,kubedb.com/role=primary -o jsonpath='{.items[0].metadata.name}{"\n"}'

Open a shell in that pod, substituting its name if different:

kubectl -n demo exec -it refresh-source-0 -c postgres -- bash

Inside the pod, start psql:

psql -U postgres -d postgres

Change customer 1 on the source and inspect all five rows:

UPDATE customers SET full_name = 'Updated Customer 1' WHERE id = 1;
SELECT * FROM customers ORDER BY id;

Expected result:

UPDATE 1
 id |     full_name      |         email
----+--------------------+-----------------------
  1 | Updated Customer 1 | [email protected]
  2 | Customer 2         | [email protected]
  3 | Customer 3         | [email protected]
  4 | Customer 4         | [email protected]
  5 | Customer 5         | [email protected]
(5 rows)

Leave psql with \q, then run exit to return to your terminal.

Make a branch-only edit

Find the target primary again:

kubectl -n dev get pods -l app.kubernetes.io/instance=refresh-branch,kubedb.com/role=primary -o jsonpath='{.items[0].metadata.name}{"\n"}'

Open its pod shell, using the returned name:

kubectl -n dev exec -it refresh-branch-0 -c postgres -- bash

Inside the pod, start psql:

psql -U postgres -d postgres

Change customer 5 on the branch, then inspect the data:

UPDATE customers SET full_name = 'Branch-only Customer 5' WHERE id = 5;
SELECT * FROM customers ORDER BY id;

Before refresh, the branch should return:

UPDATE 1
 id |       full_name        |         email
----+------------------------+-----------------------
  1 | Customer 1             | [email protected]
  2 | Customer 2             | [email protected]
  3 | Customer 3             | [email protected]
  4 | Customer 4             | [email protected]
  5 | Branch-only Customer 5 | [email protected]
(5 rows)

Customer 1 still has its original name: the source update has not reached the branch. Customer 5 contains the branch-only edit that the next refresh will discard.

Leave psql with \q, then run exit to return to your terminal.

Wait for the next completed refresh

Watch the Branch from your terminal:

kubectl -n demo get branch refresh-branch \
  -o custom-columns='NAME:.metadata.name,PHASE:.status.phase,GENERATION:.status.refreshGeneration,LAST-SUCCESS:.status.lastSuccessfulRefreshTime' \
  --watch

An initial generation 0 followed by a successful refresh might look like:

NAME             PHASE        GENERATION   LAST-SUCCESS
refresh-branch   Ready        <none>       2026-11-10T10:02:00Z
refresh-branch   Refreshing   1            2026-11-10T10:02:00Z
refresh-branch   Ready        1            2026-11-10T10:11:30Z

Wait until the generation is later than the one you recorded, the phase is Ready, and LAST-SUCCESS has advanced. Then press Ctrl+C to stop watching. Intermediate events may repeat or pass too quickly to observe. Do not treat the initial Ready row or a generation increase alone as a completed refresh.

Inspect the full status:

kubectl -n demo get branch refresh-branch -o yaml

For the example above, the refresh-related status would include:

status:
  history:
    - at: "2026-11-10T10:02:00Z"
      result: Succeeded
    - at: "2026-11-10T10:11:30Z"
      result: Succeeded
  lastRefreshTime: "2026-11-10T10:11:30Z"
  lastSuccessfulRefreshTime: "2026-11-10T10:11:30Z"
  mode: Local
  nextRefreshTime: "2026-11-10T10:20:00Z"
  phase: Ready
  refreshGeneration: 1
  snapshot:
    generation: 1
    ready: true
    strategy: VolumeSnapshot

The two history entries represent the initial copy and one successful refresh. The current snapshot generation matches the refreshed branch. The snapshot strategy may differ with your storage configuration; this excerpt omits the snapshot members and other status fields.

The FRESHNESS column in the default kubectl get branch output measures time since lastSuccessfulRefreshTime. It increases between successful runs and resets when another run completes. It is a completion-age indicator; use status.snapshot.members[].creationTime, when supplied by the CSI driver, to inspect when source snapshots were actually taken.

Verify the refreshed data

Check the branch

Refresh replaces storage and restarts the target. From your terminal, discover the current target primary rather than reusing an existing pod session:

kubectl -n dev get pods -l app.kubernetes.io/instance=refresh-branch,kubedb.com/role=primary -o jsonpath='{.items[0].metadata.name}{"\n"}'

Open its pod shell, substituting the returned name:

kubectl -n dev exec -it refresh-branch-0 -c postgres -- bash

Inside the pod, start psql:

psql -U postgres -d postgres

Inspect all five customers:

SELECT * FROM customers ORDER BY id;

Expected result:

 id |     full_name      |         email
----+--------------------+-----------------------
  1 | Updated Customer 1 | [email protected]
  2 | Customer 2         | [email protected]
  3 | Customer 3         | [email protected]
  4 | Customer 4         | [email protected]
  5 | Customer 5         | [email protected]
(5 rows)

The source update to customer 1 is now present. The branch-only edit to customer 5 is gone, and the table still contains five rows.

Leave psql with \q, then run exit to return to your terminal.

Confirm the source was not changed by refresh

Find the source primary again:

kubectl -n demo get pods -l app.kubernetes.io/instance=refresh-source,kubedb.com/role=primary -o jsonpath='{.items[0].metadata.name}{"\n"}'

Open its pod shell, using the returned name:

kubectl -n demo exec -it refresh-source-0 -c postgres -- bash

Inside the pod, start psql:

psql -U postgres -d postgres

Query the source:

SELECT * FROM customers ORDER BY id;

It should still contain the source-side update and no branch-only edit:

 id |     full_name      |         email
----+--------------------+-----------------------
  1 | Updated Customer 1 | [email protected]
  2 | Customer 2         | [email protected]
  3 | Customer 3         | [email protected]
  4 | Customer 4         | [email protected]
  5 | Customer 5         | [email protected]
(5 rows)

Leave psql with \q, then run exit to return to your terminal.

Schedule and history field reference

FieldTypeDefault or omitted behaviorPurpose
spec.scheduleObjectOmitted: create a one-time branch without scheduled refreshes.Enables periodic replacement of branch data.
spec.schedule.cronStringRequired when schedule is present; no default expression.Sets the refresh cadence. The example uses */10 * * * *.
spec.historyLimitObjectOmitted: keep the last 3 successful and 2 failed run records.Bounds entries in status.history independently for each outcome.
spec.historyLimit.successInteger (int32)3 when omitted.Number of successful run records to keep, including initial creation. Set 0 to retain none.
spec.historyLimit.failedInteger (int32)2 when omitted.Number of failed run records to keep. Set 0 to retain none.

History limits retain outcome records, not database copies or snapshots for rollback. With the example limits, status can hold up to five entries: three successful and two failed. A fourth success removes the oldest success without consuming the failed-run allowance. Snapshot cleanup follows the refresh lifecycle independently of these limits.

Cron syntax and timezone

Use five fields separated by spaces:

minute hour day-of-month month day-of-week
ExpressionSchedule
*/10 * * * *Every ten minutes, at minutes 0, 10, 20, 30, 40, and 50.
0 2 * * *Every day at 02:00.
0 2 * * 1Every Monday at 02:00.

Without an explicit timezone prefix, expressions use the Courier controller process’s local timezone, which may differ from your workstation. The parser also accepts a prefix such as CRON_TZ=Etc/UTC 0 2 * * * to specify a timezone. There is no separate spec.schedule.timeZone field.

After a run completes, Courier computes the next future cron deadline. Refreshes run sequentially for a Branch; a short interval does not make an in-progress replacement complete sooner or start a second replacement concurrently.

Refresh status reference

These fields are written by Courier; do not set them in your manifest.

FieldTypeWhen absent or initialMeaning
status.phaseStringMay be absent before reconciliation.Current lifecycle phase. A scheduled local replacement uses Refreshing, then returns to Ready on success.
status.refreshGenerationInteger (int64)Initial generation is 0, which may be omitted from output.Advances when a scheduled refresh begins. It identifies an attempt, not proof of successful completion.
status.lastRefreshTimeTimestampAbsent until a run outcome is recorded.Time the latest attempt’s outcome was recorded, whether successful or failed. It is not the refresh start time.
status.lastSuccessfulRefreshTimeTimestampAbsent until the first successful copy completes.Latest successful completion time, including initial creation. Drives FRESHNESS; a failed attempt does not advance it.
status.nextRefreshTimeTimestampAbsent for a one-time branch or before the next deadline is computed.Next scheduled refresh deadline. It does not predict when replacement will finish.
status.historyArray of run recordsEmpty before recorded outcomes, or when both limits are 0.Bounded successful and failed outcomes, ordered oldest to newest.
status.history[].atTimestampRecorded with the outcome.Time that run finished successfully or was recorded as failed.
status.history[].resultStringRecorded with the outcome.Succeeded or Failed.
status.history[].messageStringOptional; normally absent on success.Human-readable detail about a failed attempt.
status.snapshot.generationInteger (int64)Generation 0 may be omitted.Generation of the source snapshot set recorded for the branch. Compare it with the refresh generation and completion status.

Apply the same strategy across clusters

The same schedule and history settings apply to a cross-cluster Branch. After completing cross-cluster Courier setup, use spec.target.clusterName to select the registered target cluster and apply the original Branch on the source cluster. See the PostgreSQL cross-cluster walkthrough for the complete configuration.

The source Courier agent owns the schedule and takes the next generation’s snapshots. OCM delivers the new generation through the hub, the target agent performs replacement, and completion is reported back to the source Branch. Inspect scheduling and freshness on the source cluster and target pods and data on the target cluster. Both agents and the hub delivery path must remain available.

Both clusters must use the same Ceph backend, reachable over the network, with compatible CSI configuration and snapshot support. Matching StorageClass names alone are insufficient; the target must be able to resolve the source snapshot handles. See cross-cluster backend compatibility.

Cleanup

Delete the scheduled Branch first and wait for Courier to finish cleanup:

kubectl -n demo delete branch refresh-branch --wait=true --timeout=15m

With deletionPolicy: Delete, Courier removes the target database, cloned volumes, auth Secret, and managed snapshots. The source remains available.

Remove the tutorial source when finished. Its WipeOut policy deletes its data:

kubectl -n demo delete postgres refresh-source --wait=true --timeout=15m

These commands leave the demo and dev namespaces available for other resources.