Skip to content

pg_hardstorage_repo_init.md

Latest commit

 

History

History
97 lines (73 loc) · 4.96 KB

pg_hardstorage_repo_init.md

File metadata and controls

97 lines (73 loc) · 4.96 KB
Raw
title pg hardstorage repo init
description CLI reference for the pg hardstorage repo init command.
tags
cli
reference

pg_hardstorage repo init

Create a new repository at the given URL

Synopsis

Initialise a new pg_hardstorage repository at the given URL.

Supported schemes: file://, s3:///

The operation is atomic and race-safe: if two processes init the same URL concurrently, exactly one wins and the other receives a conflict error.

WORM (write-once-read-many):

--worm-mode {compliance|governance} \
--worm-retention <duration>     # 7y, 30d, 8760h

Records a retention policy in HSREPO that propagates to every committed object's PUT (chunks, manifests, replicas, audit events). Compliance mode is the regulatory-grade posture (even root credentials cannot delete before the deadline). Governance mode allows IAM principals with the BypassGovernance permission to delete. WORM is set at init time only — flipping it on later would produce a mixed-fleet situation operators can't reason about.

Retention units: y (365-day years), d (days), h (hours), m (minutes).

Compression:

--compression {fast|balanced|max}

Picks the zstd encoder level for new chunks. Profiling under a write-heavy workload (10 GB pgbench seed + sustained UPDATE load) showed the v0.1..default ("balanced", ~zstd level 7) burned ~40% of pg_hardstorage CPU.

fast ~zstd level 3. Halves zstd CPU; ~10-15% larger on disk. Recommended for write-heavy clusters where wal-stream CPU matters more than disk bytes. balanced ~zstd level 7. v0.1..default. Sweet spot for the median operator. max ~zstd level 11. 2-3x more CPU than balanced; ~5% smaller on disk. Archive-tier backups read rarely.

Set at init time and not changed after. A repo holding a mix of levels still reads back fine — the decoder handles every level — but the operator's "what does my CPU/disk trade-off look like?" answer is more legible when the level is stable across the repo.

pg_hardstorage repo init <url> [flags]

Options

      --compression string      zstd encoder level: fast | balanced | max (default: balanced)
  -h, --help                    help for init
      --worm-mode string        WORM retention mode: compliance | governance (set with --worm-retention)
      --worm-retention string   WORM retention duration: e.g. 7y, 30d, 8760h (required with --worm-mode)

Options inherited from parent commands

      --airgapped airgapped: strict                                                       refuse outbound endpoints (LLM providers, sinks, OTLP collectors) outside loopback / RFC1918 / explicit airgap.allowlist. Also enabled by PG_HARDSTORAGE_AIRGAPPED=1 or airgapped: strict in the config file.
  -c, --config string                                                                     path to config file (default: XDG/FHS lookup)
      --cpu-profile go tool pprof <path>                                                  write a pprof CPU profile to this path for the duration of the command (go tool pprof <path> to analyse). Off when empty.
      --mem-profile string                                                                write a pprof heap profile to this path at command exit. Off when empty.
      --no-color                                                                          disable ANSI color in text output
      --on-error-llm                                                                      on a structured-error failure, drop into the matching LLM helper skill (auto_on_error trigger). Also enabled by PG_HARDSTORAGE_ON_ERROR_LLM=1.
      --otel-endpoint string                                                              OpenTelemetry OTLP/HTTP endpoint (e.g. http://otel-collector:4318); empty disables tracing
      --otel-stdout                                                                       also export OpenTelemetry traces to stderr (useful for dev)
  -o, --output string                                                                     output format: text|json|ndjson|yaml|template|csv|markdown|html|tap|junit|pdf (default: text on TTY, json off-TTY)
      --profile-port go tool pprof http://127.0.0.1:6060/debug/pprof/profile?seconds=30   if non-zero, expose net/http/pprof on 127.0.0.1:<port> for live profiling of long-running commands (e.g. go tool pprof http://127.0.0.1:6060/debug/pprof/profile?seconds=30). Off when zero.
  -q, --quiet                                                                             suppress non-essential output
      --template string                                                                   Go text/template applied when --output template (or implied if --template is set without --output)

SEE ALSO