New to KubeDB? Please start here.

Running Neo4j Branch Post-Actions

Post-actions prepare branch data before the Branch becomes ready. They can mask personal information, remove sensitive data, or create test fixtures. This example masks five customer nodes and deletes sensitive token nodes, leaving the source unchanged.

Execution and readiness

Each postActions entry creates a Job in the target namespace. This tutorial uses one entry and one Job, running masking first and sensitive-data removal second. Courier waits for target readiness and any configured credential reset before running the action; the Branch becomes Ready only after the Job succeeds.

Before You Begin

  • Read the branching overview.
  • Complete Courier setup, including KubeDB and the Branch CRD. Use branching-capable Courier, provisioner, and database images.
  • Ensure Neo4jVersion 2025.12.1 is available in your installed catalog.
  • Use Ceph RBD storage with copy-on-write cloning, compatible VolumeSnapshot and VolumeGroupSnapshot classes, and the corresponding CSI APIs, controllers, and driver support.
  • Review the snapshot requirements. Your account must be able to create databases and Branches, read auth Secrets, inspect snapshots and Jobs, and open pod shells.
  • Allow capacity for three source and three target database pods, each requesting 2Gi of memory, plus operators and action Jobs.

The source uses demo; the target uses dev. Replace ceph-rbd consistently if your Ceph StorageClass has another name. Reserve the tutorial names and create namespaces if they do not already exist:

kubectl create namespace demo
kubectl create namespace dev

Deploy the source database

Save the following as neo4j-pa-source.yaml. It creates a three-server cluster:

apiVersion: kubedb.com/v1alpha2
kind: Neo4j
metadata:
  name: neo4j-pa-source
  namespace: demo
spec:
  version: 2025.12.1
  replicas: 3
  podTemplate:
    spec:
      containers:
      - name: neo4j
        resources:
          requests:
            cpu: 500m
            memory: 2Gi
          limits:
            memory: 2Gi
  storageType: Durable
  storage:
    storageClassName: ceph-rbd
    accessModes:
    - ReadWriteOnce
    resources:
      requests:
        storage: 4Gi
  deletionPolicy: WipeOut
kubectl -n demo apply -f neo4j-pa-source.yaml
kubectl -n demo wait neo4j/neo4j-pa-source --for=jsonpath='{.status.phase}'=Ready --timeout=30m

Use the Enterprise server catalog entry for this cluster. The client examples select database neo4j and use routing so writes reach its leader.

Seed and inspect the source data

Discover the auth Secret referenced by neo4j-pa-source:

kubectl -n demo get neo4j neo4j-pa-source -o jsonpath='{.spec.authSecret.name}{"\n"}'
neo4j-pa-source-auth

Use the returned name below if it differs. Read its password:

kubectl -n demo get secret neo4j-pa-source-auth -o jsonpath='{.data.password}' | base64 -d

Enter this password when the client prompts.

From your terminal, open a pod shell:

kubectl -n demo exec -it neo4j-pa-source-0 -c neo4j -- bash

Inside the pod, start the client through the writable database Service:

cypher-shell -a neo4j://neo4j-pa-source.demo.svc:7687 -u neo4j -d neo4j --format plain

Enter Cypher at the client prompt. neo4j:// discovers the cluster’s writer; a direct bolt:// connection to an arbitrary member can reject writes.

Create five customers. Expected results below omit connection banners and are formatted for readability.

CREATE (c1:Customer {id: 1, full_name: "Customer 1", email: "[email protected]", phone: "+1-555-0001"}),
       (c2:Customer {id: 2, full_name: "Customer 2", email: "[email protected]", phone: "+1-555-0002"}),
       (c3:Customer {id: 3, full_name: "Customer 3", email: "[email protected]", phone: "+1-555-0003"}),
       (c4:Customer {id: 4, full_name: "Customer 4", email: "[email protected]", phone: "+1-555-0004"}),
       (c5:Customer {id: 5, full_name: "Customer 5", email: "[email protected]", phone: "+1-555-0005"});
CREATE (:SensitiveToken {id: 1, token: 'sample-token-1'}),
       (:SensitiveToken {id: 2, token: 'sample-token-2'});
CALL db.checkpoint();

db.checkpoint() is provided by the Enterprise server used here. Committed transaction logs still support recovery when the cloned database starts.

MATCH (c:Customer) RETURN c.id AS id, c.full_name AS full_name, c.email AS email, c.phone AS phone ORDER BY id;
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"
MATCH (t:SensitiveToken) RETURN count(t) AS tokens;
tokens
2

Run :exit to leave cypher-shell, then exit to leave the pod shell.

Create a Branch with post-actions

Save the following as neo4j-pa-branch.yaml:

apiVersion: courier.kubedb.com/v1alpha1
kind: Branch
metadata:
  name: neo4j-pa-branch
  namespace: demo
spec:
  source:
    databaseRef:
      apiGroup: kubedb.com
      kind: Neo4j
      name: neo4j-pa-source
    namespace: demo
  target:
    namespace: dev
    name: neo4j-pa-branch
    storageClassName: ceph-rbd
    resources:
      requests:
        cpu: 500m
        memory: 2Gi
      limits:
        memory: 2Gi
  postActions:
  - image: neo4j:2025.12.1
    jobDefaults:
      imagePullPolicy: IfNotPresent
      backoffLimit: 3
      activeDeadlineSeconds: 900
      ttlSecondsAfterFinished: 3600
    jobTemplate:
      metadata:
        labels:
          branch-action: neo4j-pa-branch-prepare
      spec:
        args:
        - bash
        - -ec
        - |
          # First operation: mask the five customer nodes through leader routing.
          cypher-shell -a "neo4j://${NEO4J_HOST}:${NEO4J_PORT}" \
            -u "$NEO4J_USERNAME" -p "$NEO4J_PASSWORD" --format plain --fail-fast \
            "MATCH (c:Customer) SET c.full_name = 'Masked Customer', c.email = '[email protected]', c.phone = '+1-555-0000' RETURN count(c) AS masked;"
          # Second operation: remove sensitive nodes after masking succeeds.
          cypher-shell -a "neo4j://${NEO4J_HOST}:${NEO4J_PORT}" \
            -u "$NEO4J_USERNAME" -p "$NEO4J_PASSWORD" --format plain --fail-fast \
            "MATCH (t:SensitiveToken) DETACH DELETE t;"          
        resources:
          requests:
            cpu: 100m
            memory: 256Mi
  deletionPolicy: Delete
kubectl -n demo apply -f neo4j-pa-branch.yaml
kubectl -n demo wait branch/neo4j-pa-branch --for=condition=Ready --timeout=60m
kubectl -n demo get branch neo4j-pa-branch

Courier creates neo4j/neo4j-pa-branch and its cloned PVCs in dev; KubeDB provisions the target database.

The image executes the Bash arguments and uses cypher-shell only as a client. Both commands use neo4j:// routing to reach the writer. --fail-fast and bash -ec stop the Job on an error, so sensitive-node removal follows successful masking. Repeating the fixed update and deleting already-absent nodes are harmless.

Inspect the action Job

The Branch passes through ActionsRunning; the phase may finish before you see it. Find the Job and inspect its logs:

kubectl -n dev get jobs -l courier.kubedb.com/branch=neo4j-pa-branch,courier.kubedb.com/branch-namespace=demo
kubectl -n dev logs job/neo4j-pa-branch-post-action -c actions
kubectl -n dev get pods -l branch-action=neo4j-pa-branch-prepare

Expect Job status Complete with 1/1 completions. The first query reports masked as 5.

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

Expect PostActionsCompleted=True and Ready=True. Resource references identify the target auth Secret, cloned PVCs, and action Job.

Verify that only the branch was changed

Inspect the branch

Discover the auth Secret referenced by neo4j-pa-branch:

kubectl -n dev get neo4j neo4j-pa-branch -o jsonpath='{.spec.authSecret.name}{"\n"}'
neo4j-pa-branch-auth

Use the returned name below if it differs. Read its password:

kubectl -n dev get secret neo4j-pa-branch-auth -o jsonpath='{.data.password}' | base64 -d

Enter this password when the client prompts.

From your terminal, open a pod shell:

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

Inside the pod, start the client through the writable database Service:

cypher-shell -a neo4j://neo4j-pa-branch.dev.svc:7687 -u neo4j -d neo4j --format plain

Enter Cypher at the client prompt. neo4j:// discovers the cluster’s writer; a direct bolt:// connection to an arbitrary member can reject writes.

MATCH (c:Customer) RETURN c.id AS id, c.full_name AS full_name, c.email AS email, c.phone AS phone ORDER BY id;
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"
MATCH (t:SensitiveToken) RETURN count(t) AS tokens;
tokens
0

Run :exit to leave cypher-shell, then exit to leave the pod shell.

Inspect the source

Discover the auth Secret referenced by neo4j-pa-source:

kubectl -n demo get neo4j neo4j-pa-source -o jsonpath='{.spec.authSecret.name}{"\n"}'
neo4j-pa-source-auth

Use the returned name below if it differs. Read its password:

kubectl -n demo get secret neo4j-pa-source-auth -o jsonpath='{.data.password}' | base64 -d

Enter this password when the client prompts.

From your terminal, open a pod shell:

kubectl -n demo exec -it neo4j-pa-source-0 -c neo4j -- bash

Inside the pod, start the client through the writable database Service:

cypher-shell -a neo4j://neo4j-pa-source.demo.svc:7687 -u neo4j -d neo4j --format plain

Enter Cypher at the client prompt. neo4j:// discovers the cluster’s writer; a direct bolt:// connection to an arbitrary member can reject writes.

MATCH (c:Customer) RETURN c.id AS id, c.full_name AS full_name, c.email AS email, c.phone AS phone ORDER BY id;
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"
MATCH (t:SensitiveToken) RETURN count(t) AS tokens;
tokens
2

Run :exit to leave cypher-shell, then exit to leave the pod shell.

The source keeps all five original customer records and both sensitive tokens.

Connection environment

VariableValue used by the action
NEO4J_HOSTTarget Service
NEO4J_PORT7687
NEO4J_USERNAMEUsername from the target auth Secret
NEO4J_PASSWORDPassword from the target auth Secret

See the common action fields and Job defaults. The action image must execute its supplied arguments; the Branch template does not expose a container command override.

Use post-actions with refresh or another cluster

Refresh runs the action against every new copy before readiness. Inspect each generation’s Job using the Courier labels above; older Jobs can be removed during cleanup. For cross-cluster branching, the Job runs on the target cluster and receives the target’s credentials.

Cleanup

Delete the Branch on the source cluster first. Let Courier remove its target and snapshots before deleting the source:

kubectl -n demo delete branch neo4j-pa-branch --wait=true --timeout=30m
kubectl -n demo delete neo4j neo4j-pa-source --wait=true --timeout=30m

Keep Courier, CSI, the shared backend, and OCM when used available until cleanup completes. These commands leave the namespaces in place.