cow

package

v0.3.0 Latest Latest Go to latest Published: Jun 11, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/abd-ulbasit/pgbranch

Links

Open Source Insights

Documentation ¶

Overview ¶

Package cow plans copy-on-write layer layouts for branch containers. The overlay mount itself is performed inside the branch container by EntrypointScript; host code only decides volume names and mount paths.

Index ¶

Constants
Variables
func BranchRWVolumeName(branch string) string
func BranchRWVolumeNameGen(branch string, gen int) string
func LowerMountTarget(i int) string
func SourceVolumeName(source string, gen int) string
type Backend
- func ParseBackend(s string) (Backend, error)
type Plan
- func PlanBranch(rwVolume, sourceVolume string, layerVolumes []string) Plan
- func (p Plan) LowerEnv() string
type Planner

Constants ¶

View Source

const (
	MergedPath = "/pgbranch/merged" // PGDATA inside branch container (overlay)
	RWPath     = "/pgbranch/rw"     // branch rw layer mountpoint
	// DirectDataPath is PGDATA in the direct (zfs/csi) modes: the writable
	// clone (dataset mountpoint or PVC) is mounted at RWPath and seeding put
	// the cluster in its data/ subdir.
	DirectDataPath = RWPath + "/data"
)

Variables ¶

View Source

var EntrypointScript string

View Source

var EntrypointScriptDirect string

EntrypointScriptDirect runs postgres straight on a writable copy-on-write view of the data dir — zfs clones and csi PVC clones; no overlay assembly.

Functions ¶

func BranchRWVolumeName ¶

func BranchRWVolumeName(branch string) string

func BranchRWVolumeNameGen ¶

func BranchRWVolumeNameGen(branch string, gen int) string

BranchRWVolumeNameGen names a branch's writable volume after gen-1 freezes: every freeze turns the current rw volume into an immutable layer (keeping its name) and moves the branch onto a fresh volume. Gen 1 is the original (legacy) name.

func LowerMountTarget ¶

func LowerMountTarget(i int) string

LowerMountTarget is the in-container mount point of lower layer i (0 = the source volume, 1..N = frozen layer volumes, newest first).

func SourceVolumeName ¶

func SourceVolumeName(source string, gen int) string

SourceVolumeName names a source's seed volume for a given generation. Generation 1 keeps the legacy Phase 1 name so existing volumes keep working.

Types ¶

type Backend ¶

type Backend string

Backend selects the copy-on-write mechanism branches are built on.

const (
	BackendOverlay Backend = "overlay" // OverlayFS assembled inside the branch container (default)
	BackendZFS     Backend = "zfs"     // ZFS snapshot+clone datasets (experimental)
	BackendCSI     Backend = "csi"     // Kubernetes PVC clones (--runtime kube --kube-storage csi only)
)

func ParseBackend ¶

func ParseBackend(s string) (Backend, error)

ParseBackend validates a backend name from configuration (branchd --cow).

type Plan ¶

type Plan struct {
	SourceVolume string   // mounted ro at /pgbranch/lower0
	RWVolume     string   // upper+work live here
	LayerVolumes []string // frozen layer volumes, NEWEST first, mounted ro at /pgbranch/lower1..N
	Lowers       []string // in overlay order, topmost (newest) first, source last
}

func PlanBranch ¶

func PlanBranch(rwVolume, sourceVolume string, layerVolumes []string) Plan

PlanBranch lays out a branch's overlay: rwVolume holds upper/work, layerVolumes are the branch's frozen layer chain (NEWEST first, possibly empty), and the overlay lowerdir stacks newest layer first with the source volume last.

func (Plan) LowerEnv ¶

func (p Plan) LowerEnv() string

LowerEnv renders PGBRANCH_LOWERS for the entrypoint (colon-separated).

type Planner ¶

type Planner struct {
	Backend Backend
	Dataset string // zfs only: dataset prefix all pgbranch datasets live under, e.g. "tank/pgbranch"
}

Planner yields backend-specific layer names, entrypoints, and (zfs) the exact zfs argv the engine runs through privileged helpers. Pure — no I/O.

func (Planner) BranchLayerName ¶

func (p Planner) BranchLayerName(branch string) string

BranchLayerName names a branch's writable layer: the rw volume (overlay) or the clone dataset (zfs).

func (Planner) Entrypoint ¶

func (p Planner) Entrypoint() string

Entrypoint returns the branch container entrypoint script for the backend. zfs and csi branches run directly on their writable clone; only overlay branches assemble a mount in-container.

func (Planner) Mountpoint ¶

func (p Planner) Mountpoint(dataset string) string

Mountpoint maps a dataset to its default zfs mountpoint (/<dataset>). The zfs backend requires default mountpoints (no altroot/mountpoint=).

func (Planner) SnapshotName ¶

func (p Planner) SnapshotName(sourceDataset, branch string) string

SnapshotName names the per-branch snapshot on the source dataset.

func (Planner) SourceLayerName ¶

func (p Planner) SourceLayerName(source string, gen int) string

SourceLayerName names the layer a source generation is seeded into: a docker/kube volume (overlay) or a zfs dataset (zfs).

func (Planner) ZFSClone ¶

func (p Planner) ZFSClone(sourceDataset, branch string) []string

func (Planner) ZFSCreate ¶

func (p Planner) ZFSCreate(dataset string) []string

func (Planner) ZFSDestroyClone ¶

func (p Planner) ZFSDestroyClone(branch string) []string

func (Planner) ZFSDestroyDataset ¶

func (p Planner) ZFSDestroyDataset(dataset string) []string

func (Planner) ZFSDestroySnapshot ¶

func (p Planner) ZFSDestroySnapshot(sourceDataset, branch string) []string

func (Planner) ZFSSnapshot ¶

func (p Planner) ZFSSnapshot(sourceDataset, branch string) []string

func (Planner) ZFSUsed ¶

func (p Planner) ZFSUsed(dataset string) []string

Source Files ¶

View all Source files

plan.go

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL