Design Notes
Design notes explain why PIG behaves the way it does. Each note identifies the decision date, the implementation and release boundary, alternatives that were rejected, and the current user documentation.
These articles are historical and architectural context. For current command syntax and behavior, use the linked PIG documentation; for delivery history, use the release notes.
Bootstrapping a Pigsty Controller as a Recoverable Transaction
Why pig sty boot resolves sources before elevation, separates hard failures from finishing warnings, and restores repositories after failed setup.
Catalog v2 Proposal: Immutable Typed Snapshots Instead of Bigger CSV
A proposed verifiable Catalog model with typed targets, content-addressed snapshots, explicit activation, project pins, and offline import.
PIG 2.0 Product Direction: A Proposal, Not a Release Contract
The proposed PIG 2.0 boundary: a stable Pigsty onboarding front door, verifiable Catalog client, and thin orchestrator that keeps deployment explicit.
Let Patronictl Speak for Itself
Why pig pt stopped mirroring Patronictl's command tree and became a transparent launcher with only a few PIG-owned local helpers.
A Bounded Grafana Client Instead of Dashboard Shell Scripts
Why pig sty grafana owns a small HTTP contract for dashboard lifecycle, preferences, and safe cleanup without becoming a general Grafana administration client.
Use the CMDB Pigsty Already Has
Why PIG retired a new revision-store design and became a thin, guarded adapter to Pigsty's existing PostgreSQL CMDB.
Edit the Declaration, Preserve the Document: Lossless Pigsty Inventory
Why pig inventory separates YAML semantics from source bytes so scoped edits can preserve comments, ordering, anchors, and formatting.
One Grammar for Dangerous Work: PIG's Operations CLI Safety Contract
How PIG separates primitives from orchestrators, makes destructive intent explicit, and prevents aliases or structured output from changing operational meaning.
Why PIG Keeps the Cobra Command Layer Flat
The source-layout decision that keeps one top-level command in one cmd file and moves concrete behavior into cli and internal packages.
The 70% Tuner: Defining the Boundary of pig pg tune
Why pig pg tune produces deterministic hardware-based core settings while refusing to present itself as complete production PostgreSQL tuning.
Compile, Validate, Then Commit: The Native sty conf Pipeline
Why pig sty conf treats Inventory generation as a bounded compiler pipeline with path safety, structural mutations, secret discipline, and atomic output.
From Human-Friendly to Agent-Native: PIG's CLI Contract
Why PIG separates human text, structured results, execution plans, and environment context instead of treating JSON as a formatting afterthought.
-
Bootstrapping a Pigsty Controller as a Recoverable Transaction
Decision date: 2026-08-14 Status: Implemented and released in pig v1.8.0. Current reference: pig sty boot Scope: Preparing a Pigsty controller and its package sources; not deploying a database cluster. Decision pig sty boot should be one native, …
Decision date: 2026-08-14 Status: Implemented and released in pig v1.8.0. Current reference: pig sty boot Scope: Preparing a Pigsty controller and its package sources; not deploying a database cluster. Decision pig sty boot should be one native, …
-
Catalog v2 Proposal: Immutable Typed Snapshots Instead of Bigger CSV
Decision date: 2026-08-13 Status: Pre-implementation proposal; security mechanism, overlay scope, packaging, and path ADRs remain open. Current reference: pig ext and pig repo describe the v1 Catalog behavior. Scope: A candidate PIG 2.0 publication …
Decision date: 2026-08-13 Status: Pre-implementation proposal; security mechanism, overlay scope, packaging, and path ADRs remain open. Current reference: pig ext and pig repo describe the v1 Catalog behavior. Scope: A candidate PIG 2.0 publication …
-
PIG 2.0 Product Direction: A Proposal, Not a Release Contract
Decision date: 2026-08-13 Status: Proposal for owner review; it is not implemented and is not a PIG 2.0 release commitment. Current reference: PIG documentation and the current v1.8.1 release Scope: Candidate product boundaries and verification …
Decision date: 2026-08-13 Status: Proposal for owner review; it is not implemented and is not a PIG 2.0 release commitment. Current reference: PIG documentation and the current v1.8.1 release Scope: Candidate product boundaries and verification …
-
Let Patronictl Speak for Itself
Decision date: 2026-07-21 Status: Implemented and released in pig v1.6.0. Current reference: pig pt Scope: Patronictl-backed cluster commands plus PIG-owned configuration selection, settings sugar, service, status, and log helpers. Decision pig pt …
Decision date: 2026-07-21 Status: Implemented and released in pig v1.6.0. Current reference: pig pt Scope: Patronictl-backed cluster commands plus PIG-owned configuration selection, settings sugar, service, status, and log helpers. Decision pig pt …
-
A Bounded Grafana Client Instead of Dashboard Shell Scripts
Decision date: 2026-07-18 Status: Implemented in v1.6.0; Grafana dashboard schema v2 support followed in v1.6.2. Current reference: pig sty grafana Scope: Pigsty-owned dashboard folders, dashboards, and UI preferences; not general Grafana …
Decision date: 2026-07-18 Status: Implemented in v1.6.0; Grafana dashboard schema v2 support followed in v1.6.2. Current reference: pig sty grafana Scope: Pigsty-owned dashboard folders, dashboards, and UI preferences; not general Grafana …
-
Use the CMDB Pigsty Already Has
Decision date: 2026-07-18 Status: The greenfield revision store is superseded; the thin existing-CMDB adapter is implemented and remains experimental. Current reference: pig inventory cmdb Scope: Exchanging declarations with Pigsty’s existing CMDB, …
Decision date: 2026-07-18 Status: The greenfield revision store is superseded; the thin existing-CMDB adapter is implemented and remains experimental. Current reference: pig inventory cmdb Scope: Exchanging declarations with Pigsty’s existing CMDB, …
-
Edit the Declaration, Preserve the Document: Lossless Pigsty Inventory
Decision date: 2026-07-18 Status: Implemented and released in pig v1.6.0. Current reference: pig inventory Scope: Static Pigsty Inventory inspection, scoped editing, validation, comparison, and safe writes. Decision PIG treats pigsty.yml as both a …
Decision date: 2026-07-18 Status: Implemented and released in pig v1.6.0. Current reference: pig inventory Scope: Static Pigsty Inventory inspection, scoped editing, validation, comparison, and safe writes. Decision PIG treats pigsty.yml as both a …
-
One Grammar for Dangerous Work: PIG's Operations CLI Safety Contract
Decision date: 2026-07-02 Status: Released for pg, pb, pt, and pitr by v1.5.0; the 2026-08-29 do and build proxy refinements were released in v1.8.1. Current reference: pig pg, pig pb, pig pitr, pig do, and pig build Scope: PIG-owned operational …
Decision date: 2026-07-02 Status: Released for pg, pb, pt, and pitr by v1.5.0; the 2026-08-29 do and build proxy refinements were released in v1.8.1. Current reference: pig pg, pig pb, pig pitr, pig do, and pig build Scope: PIG-owned operational …
-
Why PIG Keeps the Cobra Command Layer Flat
Decision date: 2026-06-30 Status: Active repository architecture. Current reference: pig command overview and the source repository Scope: Go source ownership and command registration, not the public command taxonomy itself. Decision The cmd package …
Decision date: 2026-06-30 Status: Active repository architecture. Current reference: pig command overview and the source repository Scope: Go source ownership and command registration, not the public command taxonomy itself. Decision The cmd package …
-
The 70% Tuner: Defining the Boundary of pig pg tune
Decision date: 2026-03-21 Status: Implemented on 2026-03-23 and released in pig v1.3.2. Current reference: pig pg tune Scope: A deterministic first-pass configuration for one local PostgreSQL instance, not a complete production design service. …
Decision date: 2026-03-21 Status: Implemented on 2026-03-23 and released in pig v1.3.2. Current reference: pig pg tune Scope: A deterministic first-pass configuration for one local PostgreSQL instance, not a complete production design service. …
-
Compile, Validate, Then Commit: The Native sty conf Pipeline
Decision date: 2026-02-18; the production contract was finalized on 2026-08-14. Status: Implemented and released in pig v1.8.0. Current reference: pig sty conf Scope: Generating one validated static Inventory from a trusted Pigsty template; not …
Decision date: 2026-02-18; the production contract was finalized on 2026-08-14. Status: Implemented and released in pig v1.8.0. Current reference: pig sty conf Scope: Generating one validated static Inventory from a trusted Pigsty template; not …
-
From Human-Friendly to Agent-Native: PIG's CLI Contract
Decision date: 2026-02-12 Status: Implemented in pig v1.1.0 and refined by later command-layer work. Current reference: pig command overview Scope: PIG-owned commands and their machine-consumption contract; opaque passthrough commands keep their …
Decision date: 2026-02-12 Status: Implemented in pig v1.1.0 and refined by later command-layer work. Current reference: pig command overview Scope: PIG-owned commands and their machine-consumption contract; opaque passthrough commands keep their …