New to KubeDB? Please start here.

Running PostgreSQL Branch Post-Actions

Post-actions prepare cloned PostgreSQL data for the people and applications that will use a branch. Define containers in spec.postActions, and Courier runs them as Kubernetes Jobs against the target database. For example, you can:

  • Mask names, email addresses, and other personal information before giving developers or AI agents access.
  • Drop tables containing sensitive information that the branch does not need.
  • Delete confidential rows or data outside the scope of a test.
  • Insert test fixtures or application-specific seed data.

These changes run against the branch database and leave the source data unchanged.

This tutorial runs one PostgreSQL post-action Job that anonymizes five customer records, then drops a table containing sensitive tokens. You will deploy and seed the source, create the Branch, inspect the Job, and compare the source and branch data. No database from another tutorial is required.

Execution and readiness

Courier runs the actions in list order, creating a separate Kubernetes Job for each action in the target namespace. The next action starts only after the preceding Job succeeds. Actions start after the target database is ready and requested credential isolation is complete. The Branch stays in ActionsRunning until all actions succeed, then becomes Ready.

The target database Service can exist before the actions finish. Applications and automation consuming prepared data should wait for the Branch to become Ready. Branch readiness provides a completion signal; it does not restrict connections to the Service while data preparation is running.

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 with 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 below against the same Kubernetes context. Your account must be able to create databases and Branches, inspect Jobs and pods, and open a shell in the database pods.

The examples use the StorageClass name ceph-rbd. Substitute your Ceph RBD class consistently in the source and Branch manifests. The namespaces are demo for the source and dev for the target; use the database names below for this tutorial only.

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 post-actions-source.yaml. It creates a three-replica PostgreSQL source named pa-source:

apiVersion: kubedb.com/v1
kind: Postgres
metadata:
  name: pa-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 the manifest:

kubectl apply -f post-actions-source.yaml

Once the source is ready, find its primary pod:

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

Example output:

pa-source-0

Use the returned pod name in the commands below; this example uses pa-source-0.

Seed and inspect the source data

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

kubectl -n demo exec -it pa-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 and a table of sample sensitive tokens:

CREATE TABLE customers (
    id integer PRIMARY KEY,
    full_name text NOT NULL,
    email text NOT NULL,
    phone text NOT NULL
);
INSERT INTO customers (id, full_name, email, phone) VALUES
    (1, 'Customer 1', '[email protected]', '+1-555-0001'),
    (2, 'Customer 2', '[email protected]', '+1-555-0002'),
    (3, 'Customer 3', '[email protected]', '+1-555-0003'),
    (4, 'Customer 4', '[email protected]', '+1-555-0004'),
    (5, 'Customer 5', '[email protected]', '+1-555-0005');

CREATE TABLE sensitive_tokens (
    id integer PRIMARY KEY,
    token text NOT NULL
);
INSERT INTO sensitive_tokens (id, token) VALUES
    (1, 'sample-token-1'),
    (2, 'sample-token-2');

In the same psql session, inspect the original data:

SELECT * FROM customers ORDER BY id;
SELECT * FROM sensitive_tokens ORDER BY id;

Expected results:

 id | full_name  |         email         |    phone
----+------------+-----------------------+-------------
  1 | Customer 1 | [email protected] | +1-555-0001
  2 | Customer 2 | [email protected] | +1-555-0002
  3 | Customer 3 | [email protected] | +1-555-0003
  4 | Customer 4 | [email protected] | +1-555-0004
  5 | Customer 5 | [email protected] | +1-555-0005
(5 rows)

 id |     token
----+----------------
  1 | sample-token-1
  2 | sample-token-2
(2 rows)

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

Create a Branch with post-actions

Save the following as branch-post-actions.yaml. The Branch lives in demo and creates the target database dev/pa-branch:

apiVersion: courier.kubedb.com/v1alpha1
kind: Branch
metadata:
  name: pa-branch
  namespace: demo
spec:
  source:
    databaseRef:
      apiGroup: kubedb.com
      kind: Postgres
      name: pa-source
    namespace: demo
  target:
    namespace: dev
    name: pa-branch
    storageClassName: ceph-rbd
    resources:
      requests:
        cpu: 500m
        memory: 1Gi
  postActions:
    - image: postgres:18.3-alpine
      jobDefaults:
        imagePullPolicy: IfNotPresent
        backoffLimit: 3
        activeDeadlineSeconds: 900
        ttlSecondsAfterFinished: 3600
      jobTemplate:
        metadata:
          labels:
            branch-action: pa-anonymize
        spec:
          # First -c: anonymize customer data.
          # Second -c: drop the sensitive table only if anonymization succeeds.
          args: [psql, -w, -v, ON_ERROR_STOP=1, -d, postgres,
                 -c, "UPDATE customers SET full_name = 'Masked Customer', email = 'user' || id || '@example.invalid', phone = '+1-555-0000';",
                 -c, "DROP TABLE IF EXISTS sensitive_tokens;"]
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
  deletionPolicy: Delete

The single postActions entry creates one Job. Its psql process executes the two -c commands in order: anonymize the customer data, then drop the sensitive table. Both operations are safe to repeat: the update produces the same values on each run, and the drop allows the table to be absent.

The image contains psql, which reads the connection environment supplied by Courier. -d postgres selects the database, -w prevents an interactive password prompt, and ON_ERROR_STOP=1 stops execution on a SQL error. If the update fails, the drop command does not run and the container exits unsuccessfully.

Apply the Branch and wait for all preparation to finish:

kubectl apply -f branch-post-actions.yaml
kubectl -n demo wait branch/pa-branch \
  --for=condition=Ready --timeout=20m
kubectl -n demo get branch pa-branch

Representative output after successful completion:

NAME        PHASE   MODE    TARGET      FRESHNESS   AGE
pa-branch   Ready   Local   pa-branch   2s          5m

The Branch passes through ActionsRunning while the Job executes. It may finish too quickly for you to see that phase in an interactive watch. Names and data results below follow the manifests; ages, durations, and pod names vary between runs.

Inspect the action Job

Courier labels its Jobs with the Branch name and source namespace. List this Branch’s Jobs in the target namespace:

kubectl -n dev get jobs \
  -l courier.kubedb.com/branch=pa-branch,courier.kubedb.com/branch-namespace=demo

Representative output:

NAME                    STATUS     COMPLETIONS   DURATION   AGE
pa-branch-post-action   Complete   1/1           13s         30s

The Job contains one container named actions. Inspect its logs:

kubectl -n dev logs job/pa-branch-post-action -c actions

The same Job logs both SQL results:

UPDATE 5
DROP TABLE

The custom label in jobTemplate.metadata identifies the action pod:

kubectl -n dev get pods -l branch-action=pa-anonymize

Check the Branch’s conditions:

kubectl -n demo get branch pa-branch \
  -o jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\n"}{end}'

Successful completion includes these conditions; their display order may vary:

SnapshotReady           True
TargetCreated           True
TargetReady             True
PostActionsCompleted    True
Ready                   True

Inspect the resource references recorded by Courier:

kubectl -n demo get branch pa-branch -o jsonpath='{.status.resources}{"\n"}'

The authSecret and clonedPVCs fields identify target resources. postActionJob identifies pa-branch-post-action here. For Branches with multiple postActions entries, this field references the first Job; use the Job labels to find all of them.

Verify that only the branch was changed

From your terminal, find the branch primary:

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

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

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

Inside the pod, start psql:

psql -U postgres -d postgres -v ON_ERROR_STOP=1

At the postgres=# prompt, inspect all five customers and check that the sensitive table was removed:

SELECT * FROM customers ORDER BY id;
SELECT to_regclass('public.sensitive_tokens') IS NULL AS sensitive_table_removed;

Expected results:

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

 sensitive_table_removed
-------------------------
 t
(1 row)

The five customer records are preserved with anonymized values, and the sensitive table no longer exists on the branch. Leave psql with \q, then run exit in the pod shell to return to your terminal.

Find the source primary again in case a failover occurred:

kubectl -n demo get pods -l app.kubernetes.io/instance=pa-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 pa-source-0 -c postgres -- bash

Inside the pod, start psql:

psql -U postgres -d postgres -v ON_ERROR_STOP=1

Query the original tables:

SELECT * FROM customers ORDER BY id;
SELECT * FROM sensitive_tokens ORDER BY id;

The source returns the same five original customer records and two sample tokens shown in Seed and inspect the source data. This verifies both that anonymization was limited to the branch and that dropping its sensitive table did not remove the source table.

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

For action fields, template configuration, and Job defaults, see the common post-action field reference.

Connection environment

Courier injects the following PostgreSQL connection variables into each action container:

VariableValue or sourceUse
PGHOSTTarget Service name, pa-branch.Connects to the branch in the Job’s target namespace.
PGPORT5432.PostgreSQL Service port.
PGUSERusername key of the target auth Secret.Authenticates as the branch’s database user.
PGPASSWORDpassword key of the target auth Secret.Supplies the branch’s current password through a Secret reference.

PGDATABASE is not injected. This tutorial passes -d postgres explicitly. Keep passwords out of image layers, SQL text, and logs.

Using post-actions with refresh or another cluster

A scheduled refresh replaces branch data from a fresh source snapshot and reruns the full action list before the Branch returns to Ready. Write actions that can be repeated against freshly cloned data and retried without producing unwanted changes. The deterministic update and DROP TABLE IF EXISTS in this tutorial meet that requirement.

Refresh generations have separate Jobs. For example, generation 1 uses pa-branch-post-action-gen1 to run both commands. Inspect the current generation rather than assuming the initial Job name remains current. Courier removes older action Jobs after successful replacement.

The same feature applies to cross-cluster branching. Apply the original Branch on the source cluster; action Jobs execute in the target namespace on the target cluster, where the target Service, auth Secret, and any referenced ServiceAccounts or image pull Secrets must be available. Inspect Jobs and logs using the target cluster context. The source Branch reports readiness after target-side preparation completes.

Cleanup

Delete this tutorial’s Branch and wait for Courier to finish cleanup:

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

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

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

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

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