Design Notes
Design notes explain the decisions and proposals behind PIG. Each note gives its date, status, scope, alternatives, and supporting evidence. Proposals describe directions under discussion; implemented and released records explain work that has reached those stages.
For command syntax and usage, use the PIG documentation. For changes in each version, use the release notes.
One Catalog Entry Count for the Website and CLI
Count every catalog record consistently across the website, extension lists, availability summaries, and catalog refresh results.
One-command Xray Clients and Servers
One-command VLESS, REALITY, and Vision client/server setup, stable server credentials, and verified proxy connectivity.
Install the Pigsty Repository Key Automatically
Prepare the Pigsty key best-effort, reuse existing files, and fall back with a warning unless repository metadata explicitly names a key.
Why PIG Builds Debug Packages by Default
The build-policy decision that makes RPM debuginfo/debugsource and DEB dbgsym output opt-out rather than opt-in.
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
A proposed verifiable Catalog model with typed targets, content-addressed snapshots, explicit activation, project pins, and offline import.
PIG 2.0 Product Direction
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
How pig sty grafana manages dashboards and preferences through a native HTTP 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
How pig pg tune calculates initial PostgreSQL parameters from hardware and workload inputs.
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
How PIG separates terminal text, structured results, execution plans, and environment context.
-
One Catalog Entry Count for the Website and CLI
Decision date: 2026-10-16 Status: Implemented in the v1.10.0 candidate, not yet released. Current reference: pig ext catalog count Scope: Catalog totals and default listing membership; package installation and SQL activation rules remain defined by …
Decision date: 2026-10-16 Status: Implemented in the v1.10.0 candidate, not yet released. Current reference: pig ext catalog count Scope: Catalog totals and default listing membership; package installation and SQL activation rules remain defined by …
-
One-command Xray Clients and Servers
Decision date: 2026-10-05 Status: Released in v1.9.0. The 2026-10-16 refinements below are Implemented in the v1.10.0 candidate, not yet released. Current reference: pig build, operations safety, and release history Scope: One-command Xray client …
Decision date: 2026-10-05 Status: Released in v1.9.0. The 2026-10-16 refinements below are Implemented in the v1.10.0 candidate, not yet released. Current reference: pig build, operations safety, and release history Scope: One-command Xray client …
-
Install the Pigsty Repository Key Automatically
Decision date: 2026-10-04 Status: Released in v1.9.0. Current reference: pig repo Scope: Installing the existing embedded Pigsty public key during repository configuration. Decision When a selected module contains an available pigsty-infra or …
Decision date: 2026-10-04 Status: Released in v1.9.0. Current reference: pig repo Scope: Installing the existing embedded Pigsty public key during repository configuration. Decision When a selected module contains an available pigsty-infra or …
-
Why PIG Builds Debug Packages by Default
Decision date: 2026-09-03 Status: Released in v1.8.1. Current reference: pig build Scope: Debug-package policy for pig build ext and pig build pkg; individual package recipes remain authoritative for their payload. Decision pig build ext and pig …
Decision date: 2026-09-03 Status: Released in v1.8.1. Current reference: pig build Scope: Debug-package policy for pig build ext and pig build pkg; individual package recipes remain authoritative for their payload. Decision pig build ext and pig …
-
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
Decision date: 2026-08-13 Status: Proposal; security mechanism, overlays, packaging, and path layout remain open. Current reference: pig ext and pig repo describe the v1 Catalog behavior. Scope: A candidate PIG 2.0 publication and consumption model …
Decision date: 2026-08-13 Status: Proposal; security mechanism, overlays, packaging, and path layout remain open. Current reference: pig ext and pig repo describe the v1 Catalog behavior. Scope: A candidate PIG 2.0 publication and consumption model …
-
PIG 2.0 Product Direction
Decision date: 2026-08-13 Status: Proposal for review; not implemented. Current reference: PIG documentation and release history Scope: Candidate product boundaries and verification gates for a future PIG 2.0 / Pigsty 5.0 line. Decision The proposed …
Decision date: 2026-08-13 Status: Proposal for review; not implemented. Current reference: PIG documentation and release history Scope: Candidate product boundaries and verification gates for a future PIG 2.0 / Pigsty 5.0 line. Decision The proposed …
-
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: Released in v1.6.0; dashboard schema v2 support followed in v1.6.2. Current reference: pig sty grafana Scope: Dashboard import, export, cleanup, and selected organization and user preferences. Decision PIG uses a …
Decision date: 2026-07-18 Status: Released in v1.6.0; dashboard schema v2 support followed in v1.6.2. Current reference: pig sty grafana Scope: Dashboard import, export, cleanup, and selected organization and user preferences. Decision PIG uses a …
-
Use the CMDB Pigsty Already Has
Decision date: 2026-07-18 Status: Released in v1.6.0 as an experimental adapter. The earlier revision-store design is superseded. Current reference: pig inventory cmdb Scope: Exchanging declarations with Pigsty’s existing CMDB, not designing another …
Decision date: 2026-07-18 Status: Released in v1.6.0 as an experimental adapter. The earlier revision-store design is superseded. Current reference: pig inventory cmdb Scope: Exchanging declarations with Pigsty’s existing CMDB, not designing another …
-
Edit the Declaration, Preserve the Document: Lossless Pigsty Inventory
Decision date: 2026-07-18 Status: Implemented and released in pig v1.6.0. The 2026-10-16 to 2026-10-17 refinements below are Implemented in the v1.10.0 candidate, not yet released. Current reference: pig inventory Scope: Static Pigsty Inventory …
Decision date: 2026-07-18 Status: Implemented and released in pig v1.6.0. The 2026-10-16 to 2026-10-17 refinements below are Implemented in the v1.10.0 candidate, not yet released. Current reference: pig inventory Scope: Static Pigsty Inventory …
-
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. The acceptance refinements below are Implemented for v1.10.0; source evidence is listed under …
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. The acceptance refinements below are Implemented for v1.10.0; source evidence is listed under …
-
Why PIG Keeps the Cobra Command Layer Flat
Decision date: 2026-06-30 Status: Implemented; the repository uses this layout for new commands. Current reference: pig command overview and the source repository Scope: Go source ownership and command registration, not the public command taxonomy …
Decision date: 2026-06-30 Status: Implemented; the repository uses this layout for new commands. Current reference: pig command overview and the source repository Scope: Go source ownership and command registration, not the public command taxonomy …
-
The 70% Tuner: Defining the Boundary of pig pg tune
Decision date: 2026-03-21 Status: Released in pig v1.3.2, following implementation on 2026-03-23. Current reference: pig pg tune Scope: Generate a starting configuration from hardware, PostgreSQL version, and workload profile. Decision pig pg tune …
Decision date: 2026-03-21 Status: Released in pig v1.3.2, following implementation on 2026-03-23. Current reference: pig pg tune Scope: Generate a starting configuration from hardware, PostgreSQL version, and workload profile. Decision pig pg tune …
-
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: Released in pig v1.1.0 and refined by later command-layer work. The 2026-10-16 refinements below are Implemented in the v1.10.0 candidate, not yet released. Current reference: pig command overview Scope: PIG-owned …
Decision date: 2026-02-12 Status: Released in pig v1.1.0 and refined by later command-layer work. The 2026-10-16 refinements below are Implemented in the v1.10.0 candidate, not yet released. Current reference: pig command overview Scope: PIG-owned …