New to KubeDB? Please start here.

Refreshing a PostgreSQL Branch

A PostgreSQL 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.

This tutorial demonstrates a same-cluster PostgreSQL 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

  • Read the branching overview to understand how branches work.
  • 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.

For field definitions, defaults, and cron syntax, see the common schedule and history reference. The refresh status reference explains the fields reported by Courier.

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.