Omar SobhandClaude Opus 4.7
7b23f61632
Hand-authored skill catalog anchored to real 2026-07 versions:
- Rust 1.97.1 (stable), edition 2024
- React 19.2.7, Server Components + Actions
- TailwindCSS 4.3.3 (CSS-first config, Oxide engine)
- three.js r185 (WebGPURenderer stable, BatchedMesh matured)
- React Native 0.86 / Expo SDK 54+ (New Architecture default)
- cargo-nextest 0.9.140, gitleaks 8.20+, cargo-audit 0.21+
- Postgres 17 (18 in beta, don't rely on)
- CUDA Blackwell, Metal Apple7+, ROCm CDNA3
Ships 15 skills across the categories:
foundation/ workspace-repo-commit-protocol
small-focused-commits
tdd-red-green-refactor
code-review-checklist
int-xx-marker-protocol
decompose-int-items
rust/ write-rust-current-edition
rust-error-handling
cargo-test-driven-development
rust-async-tokio-idioms
backend/ postgres-migrations-forward-only
postgres-index-selection
api-pagination-day-1
frontend/ react-19-server-components
tailwind-v4-idioms
component-4-state-model
mobile/ expo-managed-vs-bare
rn-flashlist-perf
gpu/ gpu-coalescing-and-occupancy
roofline-model
threejs/ threejs-perf-and-teardown
security/ cargo-audit-workflow
secret-scanning-gitleaks
skills_loader.rs walks skills/**/*.md, parses YAML frontmatter
(name, description, when_to_use, tags), upserts via
skills_catalog::upsert_builtin. Idempotent per boot — bumps version
+ appends skill_versions row ONLY when body changes. Deterministic
sha256-derived ids so builtins are stable across boots.
Dockerfile copies skills/ to /etc/clawmates/skills. Server boot
task spawns loader alongside team_template_loader.
Follow-ups (Slice 3.5c continuation, future PRs):
- 20-30 more skills (duckdb, shadcn composition, a11y, WebGPU
migration, metal frame capture, rocprof, deep gitea forge
integration, semgrep rulepacks)
- Bind skills to team template roles (add [role.skills] refs to
templates/teams/*.toml + wire template_role_skills population
in team_template_loader)
Co-Authored-By: Claude Opus 4.7 <[email protected]>
65 lines
3.0 KiB
Markdown
65 lines
3.0 KiB
Markdown
---
|
|
name: postgres-migrations-forward-only
|
|
description: Forward-only, reversible-by-new-migration policy for Postgres 17. No `--rollback`, no ALTER TABLE without concurrent-safe patterns on hot tables.
|
|
when_to_use: You are the db_engineer role or any coder authoring a `migrations/NNNN_*.sql` file.
|
|
tags: [backend, postgres, migrations, versioned]
|
|
---
|
|
|
|
# Postgres migrations (17-safe)
|
|
|
|
Anchored to **Postgres 17** (latest stable as of 2026-07). Postgres 18 is in beta at time of writing — don't rely on 18-only syntax without a version guard.
|
|
|
|
## Cardinal rule: forward-only
|
|
|
|
- Every migration file is applied once and never rolled back. If you need to undo, ship a NEW migration that undoes.
|
|
- `sqlx-cli` reads `migrations/NNNN_*.sql` in ascending order; each is wrapped in a txn where possible.
|
|
- The migration is part of the commit that introduces the code depending on it. Split ONLY when a two-step deploy is required (see below).
|
|
|
|
## Two-step deploys (for column drops + renames)
|
|
|
|
- **Adding a column**: single migration, always safe.
|
|
- **Removing a column**:
|
|
1. **Migration N** stops writing the column (code change first).
|
|
2. **Migration N+1** (weeks later) drops the column, after every replica has caught up.
|
|
- **Renaming a column**: don't. Add new, dual-write, backfill, stop-writing-old, drop-old.
|
|
|
|
## Concurrent-safe patterns on hot tables
|
|
|
|
Anything > 1M rows or in the request path needs concurrent-safe DDL:
|
|
|
|
```sql
|
|
-- Index adds
|
|
CREATE INDEX CONCURRENTLY foo_bar_idx ON foo(bar);
|
|
-- (CONCURRENTLY can't run in a txn — omit sqlx's txn wrap by prefixing
|
|
-- the migration file with `-- fx-no-tx`; sqlx-cli honors it.)
|
|
|
|
-- Adding NOT NULL to an existing column
|
|
ALTER TABLE foo ADD CONSTRAINT foo_bar_nn CHECK (bar IS NOT NULL) NOT VALID;
|
|
ALTER TABLE foo VALIDATE CONSTRAINT foo_bar_nn;
|
|
-- Later: drop the CHECK, add NOT NULL to the column — cheap now.
|
|
|
|
-- Backfill in batches
|
|
UPDATE foo SET bar = new_value
|
|
WHERE id IN (SELECT id FROM foo WHERE bar IS NULL LIMIT 10000);
|
|
-- Loop until 0 rows.
|
|
```
|
|
|
|
## Foreign keys
|
|
|
|
- Every FK gets an index UNLESS the table is small (< 100k rows expected long-term).
|
|
- `ON DELETE CASCADE` for owned child rows; `ON DELETE SET NULL` for weak references; explicit `NO ACTION` for anything else.
|
|
- Deferring: `DEFERRABLE INITIALLY IMMEDIATE` on tables where cross-table batch writes need to defer FK checks.
|
|
|
|
## Naming
|
|
|
|
- Migration filename: `NNNN_snake_case_description.sql` — 4-digit prefix, no gaps.
|
|
- Table names: singular is fine, plural is fine — pick one per crate and never mix.
|
|
- Index name: `<table>_<cols>_idx` for unique; `<table>_<cols>_uniq` for UNIQUE.
|
|
- Constraint name: `<table>_<cols>_ck` for CHECK, `_fk` for FK.
|
|
|
|
## What NOT to put in a migration
|
|
|
|
- Data seeding beyond a handful of rows — that's a boot-time loader (see [[team_template_loader]] pattern).
|
|
- `SET search_path` or `SET timezone` — belongs in role config or session, not migration.
|
|
- Anything requiring a specific extension without `CREATE EXTENSION IF NOT EXISTS pgcrypto` (or whichever) first.
|