Skip to content

(MODULES-11816) Add CLAUDE.md for Claude Code guidance #1676

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
SugatD wants to merge 4 commits into
base: main
Choose a base branch
from
+19 −0
Draft

(MODULES-11816) Add CLAUDE.md for Claude Code guidance #1676

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
91222bb
(MODULES-11816) Add CLAUDE.md for Claude Code guidance
SugatD May 28, 2026
03230a8
(MODULES-11816) Update branch-name convention in CLAUDE.md
SugatD May 28, 2026
baa872a
(MODULES-11816) Refactor CLAUDE.md to avoid duplicating authoritative…
SugatD May 28, 2026
bdd9a01
(MODULES-11816) Narrow CLAUDE.md to postgresql-specific content
SugatD May 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

For generic Puppet module workflow (validate, lint, unit/acceptance tests, Litmus, branch/commit conventions, CI matrix mechanics), see the PDK docs and the README's Tests section. The notes below cover only what is specific to `puppetlabs-postgresql` and not derivable from reading individual files.

## Architecture

The module has a three-layer composition that must be understood before changing anything in `manifests/`:

1. **`manifests/globals.pp`** — sole source of truth for version + OS detection. Resolves `$default_version` from `$facts['os']['family']`, `$facts['os']['name']`, and `$facts['os']['release']['major']` (a nested selector hash). Also resolves `$default_postgis_version`. Optionally configures the PGDG yum/apt repo via `postgresql::repo`, or enables `postgresql::dnfmodule` on EL8+/Fedora. **Must be included before `postgresql::server`** — `postgresql::server` reads `$postgresql::globals::default_version` to decide package names. Adding a new OS or version means editing the selector here.

2. **`manifests/params.pp`** — translates the resolved version into package/service/path names per OS. Has a critical branch: if `$version == $default_version` (and not Amazon Linux), it uses unversioned package names (`postgresql`, `postgresql-server`) from the OS base repo; otherwise it constructs versioned names (`postgresql16-server`) for the PGDG repo. Changing default version mappings without understanding this branch will break either base-repo or PGDG installs.

3. **`manifests/server.pp` + `manifests/server/`** — the user-facing API. `server.pp` orchestrates `install` → `initdb` → `config` → `service` → `reload`. The defined types under `manifests/server/` are the public interface — each one ultimately fires a `postgresql_psql` custom resource. The manifests are mostly orchestration; the actual work happens in `lib/puppet/`.

**Multi-instance support** (`manifests/server_instance.pp` + `manifests/server/instance/`) is opt-in and currently tested only on RHEL 8 / CentOS Stream 8 — see the warning at `manifests/server_instance.pp:39`. Treat changes there as RHEL-8-specific unless explicitly broadening scope.

**Hiera-driven OS defaults**: `hiera.yaml` is keyed by `os.name`/`os.family` + `os.release.major`. Per-OS YAML lives in `data/os/<Family>/<major>.yaml` and `data/os/<Name>.yaml`. Prefer adding new-OS defaults here over hard-coding them in `params.pp`.
Loading