chore(clickhouse): rename aux golden/sql files off a reserved name

[tpgilmore]

Problem

aux is a Windows-reserved device name. Git refuses to check out a path whose basename is aux (core.protectNTFS, on by default on Windows), and NTFS rejects the name regardless of extension. So posthog/clickhouse/hcl/golden/*/aux.hcl and sql/*/aux.sql cannot land on a Windows working tree. This fails the build-local-artifacts (x86_64-pc-windows-msvc) job in the Release CLI workflow at checkout time, and it breaks any Windows clone of the repo. The files became reserved when #71133 restructured the flat local-aux.hcl (safe stem) into local-multi/aux.hcl (bare reserved stem).

Changes

These files are generated, and their names derive from the role name (golden/<env>/<role>.hcl, sql/<env>/<role>.sql). Renaming the aux role would be a load-bearing change: the role name chains to NodeRole.AUX, the aux remote_servers cluster, and the hostClusterRole macro on live hosts. So this aliases only the filename for the reserved word and leaves the role identity fully intact.

• New golden_name() helper in lib.sh, mirrored in codegen/gen_migration.py, maps the aux role's files to auxiliary (matching the existing roles/auxiliary/ layer dir). Every other role passes through unchanged.
• Every committed-file write and read site uses it: gen-golden.sh, gen-sql.sh, check.sh, check-live.sh, and gen_migration.py's golden reader.
• Renamed the six committed files: golden/{local-multi,prod-us,prod-eu}/aux.hcl to auxiliary.hcl, and sql/{...}/aux.sql to auxiliary.sql. Content is byte-identical. The role name never appears inside the files, only cluster_name = "aux" does, and that stays.
• check.sh gains a guard that fails if any committed golden or sql basename is a Windows-reserved device name, so a future reserved-name role fails loudly on the Linux gate instead of silently shipping a Windows-broken tree.

Note

The aux cluster name and NodeRole.AUX are deliberately unchanged. Only the on-disk golden/sql filenames move. No migration, no production code, no schema change.

How did you test this code?

All local and automated. I (Claude) ran these. No Windows machine was involved, so the Windows checkout behavior is argued from protectNTFS and NTFS semantics, not verified on a real Windows runner.

• check.sh against the pinned chschema image: exit 0, every (env, role) diff reports "no differences" including the three renamed aux nodes, sql freshness is clean, and the new filename guard prints "no reserved filenames".
• Fault injection: dropped a nul.hcl into golden/local-multi/, confirmed check.sh fails with the reserved-name error and names the file, then removed it.
• Unit-tested is_reserved_basename (aux, nul, com1, lpt9, con reserved; auxiliary, com0, data, ops clean; case-insensitive).
• gen_migration.py --ref HEAD: reaches "No DDL generated" cleanly, confirming the dump/plan pipeline still resolves the aux role. hclexp plan matches dumps to roles by their hostClusterRole macro, not by filename, so the scratch dump keeps the raw role name.
• ruff check and ruff format: clean. hogli ci:preflight: ruff lint and format pass, mypy advisory only.

Automatic notifications

• Publish to changelog?
• Alert Sales and Marketing teams?

Docs update

Updated posthog/clickhouse/hcl/migration.md (the end-state layout list) to auxiliary.hcl.

🤖 Agent context

Autonomy: Human-driven by @tpgilmore (agent-assisted)

I diagnosed and implemented this with Claude (Claude Code) at the author's direction. The main decision was scope. The tempting "rename the role" fix looks small but ripples into NodeRole.AUX, the live hostClusterRole host tags, and the aux remote_servers cluster, which is a cross-repo, production-infra change. I rejected that and aliased only the generated filename instead. A /code-review medium pass then flagged that the first cut special-cased aux without preventing recurrence, which is why check.sh now enforces the reserved-name invariant for the whole device-name class. Skills invoked: /code-review (medium).

[trunk-io]

😎 Merged manually by @tpgilmore - details.

[greptile-apps]

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
posthog/clickhouse/hcl/gen-golden.sh:42-46
**Reserved Name Is Written First**

On a Windows host where Docker's bind mount enforces NTFS naming rules, `hclexp` still tries to create `aux.hcl` before this loop renames it. That write fails, so the command exits before `mv` runs and Windows users still cannot regenerate the goldens.

### Issue 2 of 2
posthog/clickhouse/hcl/codegen/gen_migration.py:122
**Dump Name No Longer Matches Role**

This changes the temporary dump for role `aux` from `aux.hcl` to `auxiliary.hcl`. If `hclexp plan -dump` resolves files by the manifest role, it will not find the aux dump and can fail migration generation or plan against a missing aux schema; temporary dump files are not committed, so they can retain the raw role name.

_{Reviews (1): Last reviewed commit: "chore(clickhouse): rename aux golden/sql..." | Re-trigger Greptile}

[github-actions]

🤖 CI report

✅ Playwright — all passed

All tests passed.

View test results →

⚠️ Backend snapshots — 11 updated (11 modified, 0 added, 0 deleted)

Query snapshots: Backend query snapshots updated

Changes: 11 snapshots (11 modified, 0 added, 0 deleted)

What this means:

• Query snapshots have been automatically updated to match current output
• These changes reflect modifications to database queries or schema

Next steps:

• Review the query changes to ensure they're intentional
• If unexpected, investigate what caused the query to change

Review snapshot changes →

[deployment-status-posthog]

Deploy status

Environment	Status	Deployed At	Workflow
dev	✅ Deployed	2026-07-23 02:47 UTC	Run
prod-us	✅ Deployed	2026-07-23 03:01 UTC	Run
prod-eu	✅ Deployed	2026-07-23 03:01 UTC	Run