@wazir-dev/cli 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +111 -0
- package/CHANGELOG.md +14 -0
- package/CONTRIBUTING.md +101 -0
- package/LICENSE +21 -0
- package/README.md +314 -0
- package/assets/composition-engine.mmd +34 -0
- package/assets/demo-script.sh +17 -0
- package/assets/logo-dark.svg +14 -0
- package/assets/logo.svg +14 -0
- package/assets/pipeline.mmd +39 -0
- package/assets/record-demo.sh +51 -0
- package/docs/README.md +51 -0
- package/docs/adapters/context-mode.md +60 -0
- package/docs/concepts/architecture.md +87 -0
- package/docs/concepts/artifact-model.md +60 -0
- package/docs/concepts/composition-engine.md +36 -0
- package/docs/concepts/indexing-and-recall.md +160 -0
- package/docs/concepts/observability.md +41 -0
- package/docs/concepts/roles-and-workflows.md +59 -0
- package/docs/concepts/terminology-policy.md +27 -0
- package/docs/getting-started/01-installation.md +78 -0
- package/docs/getting-started/02-first-run.md +102 -0
- package/docs/getting-started/03-adding-to-project.md +15 -0
- package/docs/getting-started/04-host-setup.md +15 -0
- package/docs/guides/ci-integration.md +15 -0
- package/docs/guides/creating-skills.md +15 -0
- package/docs/guides/expertise-module-authoring.md +15 -0
- package/docs/guides/hook-development.md +15 -0
- package/docs/guides/memory-and-learnings.md +34 -0
- package/docs/guides/multi-host-export.md +15 -0
- package/docs/guides/troubleshooting.md +101 -0
- package/docs/guides/writing-custom-roles.md +15 -0
- package/docs/plans/2026-03-15-cli-pipeline-integration-design.md +592 -0
- package/docs/plans/2026-03-15-cli-pipeline-integration-plan.md +598 -0
- package/docs/plans/2026-03-15-docs-enforcement-plan.md +238 -0
- package/docs/readmes/INDEX.md +99 -0
- package/docs/readmes/features/expertise/README.md +171 -0
- package/docs/readmes/features/exports/README.md +222 -0
- package/docs/readmes/features/hooks/README.md +103 -0
- package/docs/readmes/features/hooks/loop-cap-guard.md +133 -0
- package/docs/readmes/features/hooks/post-tool-capture.md +121 -0
- package/docs/readmes/features/hooks/post-tool-lint.md +130 -0
- package/docs/readmes/features/hooks/pre-compact-summary.md +122 -0
- package/docs/readmes/features/hooks/pre-tool-capture-route.md +100 -0
- package/docs/readmes/features/hooks/protected-path-write-guard.md +128 -0
- package/docs/readmes/features/hooks/session-start.md +119 -0
- package/docs/readmes/features/hooks/stop-handoff-harvest.md +125 -0
- package/docs/readmes/features/roles/README.md +157 -0
- package/docs/readmes/features/roles/clarifier.md +152 -0
- package/docs/readmes/features/roles/content-author.md +190 -0
- package/docs/readmes/features/roles/designer.md +193 -0
- package/docs/readmes/features/roles/executor.md +184 -0
- package/docs/readmes/features/roles/learner.md +210 -0
- package/docs/readmes/features/roles/planner.md +182 -0
- package/docs/readmes/features/roles/researcher.md +164 -0
- package/docs/readmes/features/roles/reviewer.md +184 -0
- package/docs/readmes/features/roles/specifier.md +162 -0
- package/docs/readmes/features/roles/verifier.md +215 -0
- package/docs/readmes/features/schemas/README.md +178 -0
- package/docs/readmes/features/skills/README.md +63 -0
- package/docs/readmes/features/skills/brainstorming.md +96 -0
- package/docs/readmes/features/skills/debugging.md +148 -0
- package/docs/readmes/features/skills/design.md +120 -0
- package/docs/readmes/features/skills/prepare-next.md +109 -0
- package/docs/readmes/features/skills/run-audit.md +159 -0
- package/docs/readmes/features/skills/scan-project.md +109 -0
- package/docs/readmes/features/skills/self-audit.md +176 -0
- package/docs/readmes/features/skills/tdd.md +137 -0
- package/docs/readmes/features/skills/using-skills.md +92 -0
- package/docs/readmes/features/skills/verification.md +120 -0
- package/docs/readmes/features/skills/writing-plans.md +104 -0
- package/docs/readmes/features/tooling/README.md +320 -0
- package/docs/readmes/features/workflows/README.md +186 -0
- package/docs/readmes/features/workflows/author.md +181 -0
- package/docs/readmes/features/workflows/clarify.md +154 -0
- package/docs/readmes/features/workflows/design-review.md +171 -0
- package/docs/readmes/features/workflows/design.md +169 -0
- package/docs/readmes/features/workflows/discover.md +162 -0
- package/docs/readmes/features/workflows/execute.md +173 -0
- package/docs/readmes/features/workflows/learn.md +167 -0
- package/docs/readmes/features/workflows/plan-review.md +165 -0
- package/docs/readmes/features/workflows/plan.md +170 -0
- package/docs/readmes/features/workflows/prepare-next.md +167 -0
- package/docs/readmes/features/workflows/review.md +169 -0
- package/docs/readmes/features/workflows/run-audit.md +191 -0
- package/docs/readmes/features/workflows/spec-challenge.md +159 -0
- package/docs/readmes/features/workflows/specify.md +160 -0
- package/docs/readmes/features/workflows/verify.md +177 -0
- package/docs/readmes/packages/README.md +50 -0
- package/docs/readmes/packages/ajv.md +117 -0
- package/docs/readmes/packages/context-mode.md +118 -0
- package/docs/readmes/packages/gray-matter.md +116 -0
- package/docs/readmes/packages/node-test.md +137 -0
- package/docs/readmes/packages/yaml.md +112 -0
- package/docs/reference/configuration-reference.md +159 -0
- package/docs/reference/expertise-index.md +52 -0
- package/docs/reference/git-flow.md +43 -0
- package/docs/reference/hooks.md +87 -0
- package/docs/reference/host-exports.md +50 -0
- package/docs/reference/launch-checklist.md +172 -0
- package/docs/reference/marketplace-listings.md +76 -0
- package/docs/reference/release-process.md +34 -0
- package/docs/reference/roles-reference.md +77 -0
- package/docs/reference/skills.md +33 -0
- package/docs/reference/templates.md +29 -0
- package/docs/reference/tooling-cli.md +94 -0
- package/docs/truth-claims.yaml +222 -0
- package/expertise/PROGRESS.md +63 -0
- package/expertise/README.md +18 -0
- package/expertise/antipatterns/PROGRESS.md +56 -0
- package/expertise/antipatterns/backend/api-design-antipatterns.md +1271 -0
- package/expertise/antipatterns/backend/auth-antipatterns.md +1195 -0
- package/expertise/antipatterns/backend/caching-antipatterns.md +622 -0
- package/expertise/antipatterns/backend/database-antipatterns.md +1038 -0
- package/expertise/antipatterns/backend/index.md +24 -0
- package/expertise/antipatterns/backend/microservices-antipatterns.md +850 -0
- package/expertise/antipatterns/code/architecture-antipatterns.md +919 -0
- package/expertise/antipatterns/code/async-antipatterns.md +622 -0
- package/expertise/antipatterns/code/code-smells.md +1186 -0
- package/expertise/antipatterns/code/dependency-antipatterns.md +1209 -0
- package/expertise/antipatterns/code/error-handling-antipatterns.md +1360 -0
- package/expertise/antipatterns/code/index.md +27 -0
- package/expertise/antipatterns/code/naming-and-abstraction.md +1118 -0
- package/expertise/antipatterns/code/state-management-antipatterns.md +1076 -0
- package/expertise/antipatterns/code/testing-antipatterns.md +1053 -0
- package/expertise/antipatterns/design/accessibility-antipatterns.md +1136 -0
- package/expertise/antipatterns/design/dark-patterns.md +1121 -0
- package/expertise/antipatterns/design/index.md +22 -0
- package/expertise/antipatterns/design/ui-antipatterns.md +1202 -0
- package/expertise/antipatterns/design/ux-antipatterns.md +680 -0
- package/expertise/antipatterns/frontend/css-layout-antipatterns.md +691 -0
- package/expertise/antipatterns/frontend/flutter-antipatterns.md +1827 -0
- package/expertise/antipatterns/frontend/index.md +23 -0
- package/expertise/antipatterns/frontend/mobile-antipatterns.md +573 -0
- package/expertise/antipatterns/frontend/react-antipatterns.md +1128 -0
- package/expertise/antipatterns/frontend/spa-antipatterns.md +1235 -0
- package/expertise/antipatterns/index.md +31 -0
- package/expertise/antipatterns/performance/index.md +20 -0
- package/expertise/antipatterns/performance/performance-antipatterns.md +1013 -0
- package/expertise/antipatterns/performance/premature-optimization.md +623 -0
- package/expertise/antipatterns/performance/scaling-antipatterns.md +785 -0
- package/expertise/antipatterns/process/ai-coding-antipatterns.md +853 -0
- package/expertise/antipatterns/process/code-review-antipatterns.md +656 -0
- package/expertise/antipatterns/process/deployment-antipatterns.md +920 -0
- package/expertise/antipatterns/process/index.md +23 -0
- package/expertise/antipatterns/process/technical-debt-antipatterns.md +647 -0
- package/expertise/antipatterns/security/index.md +20 -0
- package/expertise/antipatterns/security/secrets-antipatterns.md +849 -0
- package/expertise/antipatterns/security/security-theater.md +843 -0
- package/expertise/antipatterns/security/vulnerability-patterns.md +801 -0
- package/expertise/architecture/PROGRESS.md +70 -0
- package/expertise/architecture/data/caching-architecture.md +671 -0
- package/expertise/architecture/data/data-consistency.md +574 -0
- package/expertise/architecture/data/data-modeling.md +536 -0
- package/expertise/architecture/data/event-streams-and-queues.md +634 -0
- package/expertise/architecture/data/index.md +25 -0
- package/expertise/architecture/data/search-architecture.md +663 -0
- package/expertise/architecture/data/sql-vs-nosql.md +708 -0
- package/expertise/architecture/decisions/architecture-decision-records.md +640 -0
- package/expertise/architecture/decisions/build-vs-buy.md +616 -0
- package/expertise/architecture/decisions/index.md +23 -0
- package/expertise/architecture/decisions/monolith-to-microservices.md +790 -0
- package/expertise/architecture/decisions/technology-selection.md +616 -0
- package/expertise/architecture/distributed/cap-theorem-and-tradeoffs.md +800 -0
- package/expertise/architecture/distributed/circuit-breaker-bulkhead.md +741 -0
- package/expertise/architecture/distributed/consensus-and-coordination.md +796 -0
- package/expertise/architecture/distributed/distributed-systems-fundamentals.md +564 -0
- package/expertise/architecture/distributed/idempotency-and-retry.md +796 -0
- package/expertise/architecture/distributed/index.md +25 -0
- package/expertise/architecture/distributed/saga-pattern.md +797 -0
- package/expertise/architecture/foundations/architectural-thinking.md +460 -0
- package/expertise/architecture/foundations/coupling-and-cohesion.md +770 -0
- package/expertise/architecture/foundations/design-principles-solid.md +649 -0
- package/expertise/architecture/foundations/domain-driven-design.md +719 -0
- package/expertise/architecture/foundations/index.md +25 -0
- package/expertise/architecture/foundations/separation-of-concerns.md +472 -0
- package/expertise/architecture/foundations/twelve-factor-app.md +797 -0
- package/expertise/architecture/index.md +34 -0
- package/expertise/architecture/integration/api-design-graphql.md +638 -0
- package/expertise/architecture/integration/api-design-grpc.md +804 -0
- package/expertise/architecture/integration/api-design-rest.md +892 -0
- package/expertise/architecture/integration/index.md +25 -0
- package/expertise/architecture/integration/third-party-integration.md +795 -0
- package/expertise/architecture/integration/webhooks-and-callbacks.md +1152 -0
- package/expertise/architecture/integration/websockets-realtime.md +791 -0
- package/expertise/architecture/mobile-architecture/index.md +22 -0
- package/expertise/architecture/mobile-architecture/mobile-app-architecture.md +780 -0
- package/expertise/architecture/mobile-architecture/mobile-backend-for-frontend.md +670 -0
- package/expertise/architecture/mobile-architecture/offline-first.md +719 -0
- package/expertise/architecture/mobile-architecture/push-and-sync.md +782 -0
- package/expertise/architecture/patterns/cqrs-event-sourcing.md +717 -0
- package/expertise/architecture/patterns/event-driven.md +797 -0
- package/expertise/architecture/patterns/hexagonal-clean-architecture.md +870 -0
- package/expertise/architecture/patterns/index.md +27 -0
- package/expertise/architecture/patterns/layered-architecture.md +736 -0
- package/expertise/architecture/patterns/microservices.md +753 -0
- package/expertise/architecture/patterns/modular-monolith.md +692 -0
- package/expertise/architecture/patterns/monolith.md +626 -0
- package/expertise/architecture/patterns/plugin-architecture.md +735 -0
- package/expertise/architecture/patterns/serverless.md +780 -0
- package/expertise/architecture/scaling/database-scaling.md +615 -0
- package/expertise/architecture/scaling/feature-flags-and-rollouts.md +757 -0
- package/expertise/architecture/scaling/horizontal-vs-vertical.md +606 -0
- package/expertise/architecture/scaling/index.md +24 -0
- package/expertise/architecture/scaling/multi-tenancy.md +800 -0
- package/expertise/architecture/scaling/stateless-design.md +787 -0
- package/expertise/backend/embedded-firmware.md +625 -0
- package/expertise/backend/go.md +853 -0
- package/expertise/backend/index.md +24 -0
- package/expertise/backend/java-spring.md +448 -0
- package/expertise/backend/node-typescript.md +625 -0
- package/expertise/backend/python-fastapi.md +724 -0
- package/expertise/backend/rust.md +458 -0
- package/expertise/backend/solidity.md +711 -0
- package/expertise/composition-map.yaml +443 -0
- package/expertise/content/foundations/content-modeling.md +395 -0
- package/expertise/content/foundations/editorial-standards.md +449 -0
- package/expertise/content/foundations/index.md +24 -0
- package/expertise/content/foundations/microcopy.md +455 -0
- package/expertise/content/foundations/terminology-governance.md +509 -0
- package/expertise/content/index.md +34 -0
- package/expertise/content/patterns/accessibility-copy.md +518 -0
- package/expertise/content/patterns/index.md +24 -0
- package/expertise/content/patterns/notification-content.md +433 -0
- package/expertise/content/patterns/sample-content.md +486 -0
- package/expertise/content/patterns/state-copy.md +439 -0
- package/expertise/design/PROGRESS.md +58 -0
- package/expertise/design/disciplines/dark-mode-theming.md +577 -0
- package/expertise/design/disciplines/design-systems.md +595 -0
- package/expertise/design/disciplines/index.md +25 -0
- package/expertise/design/disciplines/information-architecture.md +800 -0
- package/expertise/design/disciplines/interaction-design.md +788 -0
- package/expertise/design/disciplines/responsive-design.md +552 -0
- package/expertise/design/disciplines/usability-testing.md +516 -0
- package/expertise/design/disciplines/user-research.md +792 -0
- package/expertise/design/foundations/accessibility-design.md +796 -0
- package/expertise/design/foundations/color-theory.md +797 -0
- package/expertise/design/foundations/iconography.md +795 -0
- package/expertise/design/foundations/index.md +26 -0
- package/expertise/design/foundations/motion-and-animation.md +653 -0
- package/expertise/design/foundations/rtl-design.md +585 -0
- package/expertise/design/foundations/spacing-and-layout.md +607 -0
- package/expertise/design/foundations/typography.md +800 -0
- package/expertise/design/foundations/visual-hierarchy.md +761 -0
- package/expertise/design/index.md +32 -0
- package/expertise/design/patterns/authentication-flows.md +474 -0
- package/expertise/design/patterns/content-consumption.md +789 -0
- package/expertise/design/patterns/data-display.md +618 -0
- package/expertise/design/patterns/e-commerce.md +1494 -0
- package/expertise/design/patterns/feedback-and-states.md +642 -0
- package/expertise/design/patterns/forms-and-input.md +819 -0
- package/expertise/design/patterns/gamification.md +801 -0
- package/expertise/design/patterns/index.md +31 -0
- package/expertise/design/patterns/microinteractions.md +449 -0
- package/expertise/design/patterns/navigation.md +800 -0
- package/expertise/design/patterns/notifications.md +705 -0
- package/expertise/design/patterns/onboarding.md +700 -0
- package/expertise/design/patterns/search-and-filter.md +601 -0
- package/expertise/design/patterns/settings-and-preferences.md +768 -0
- package/expertise/design/patterns/social-and-community.md +748 -0
- package/expertise/design/platforms/desktop-native.md +612 -0
- package/expertise/design/platforms/index.md +25 -0
- package/expertise/design/platforms/mobile-android.md +825 -0
- package/expertise/design/platforms/mobile-cross-platform.md +983 -0
- package/expertise/design/platforms/mobile-ios.md +699 -0
- package/expertise/design/platforms/tablet.md +794 -0
- package/expertise/design/platforms/web-dashboard.md +790 -0
- package/expertise/design/platforms/web-responsive.md +550 -0
- package/expertise/design/psychology/behavioral-nudges.md +449 -0
- package/expertise/design/psychology/cognitive-load.md +1191 -0
- package/expertise/design/psychology/error-psychology.md +778 -0
- package/expertise/design/psychology/index.md +22 -0
- package/expertise/design/psychology/persuasive-design.md +736 -0
- package/expertise/design/psychology/user-mental-models.md +623 -0
- package/expertise/design/tooling/open-pencil.md +266 -0
- package/expertise/frontend/angular.md +1073 -0
- package/expertise/frontend/desktop-electron.md +546 -0
- package/expertise/frontend/flutter.md +782 -0
- package/expertise/frontend/index.md +27 -0
- package/expertise/frontend/native-android.md +409 -0
- package/expertise/frontend/native-ios.md +490 -0
- package/expertise/frontend/react-native.md +1160 -0
- package/expertise/frontend/react.md +808 -0
- package/expertise/frontend/vue.md +1089 -0
- package/expertise/humanize/domain-rules-code.md +79 -0
- package/expertise/humanize/domain-rules-content.md +67 -0
- package/expertise/humanize/domain-rules-technical-docs.md +56 -0
- package/expertise/humanize/index.md +35 -0
- package/expertise/humanize/self-audit-checklist.md +87 -0
- package/expertise/humanize/sentence-patterns.md +218 -0
- package/expertise/humanize/vocabulary-blacklist.md +105 -0
- package/expertise/i18n/PROGRESS.md +65 -0
- package/expertise/i18n/advanced/accessibility-and-i18n.md +28 -0
- package/expertise/i18n/advanced/bidirectional-text-algorithm.md +38 -0
- package/expertise/i18n/advanced/complex-scripts.md +30 -0
- package/expertise/i18n/advanced/performance-and-i18n.md +27 -0
- package/expertise/i18n/advanced/testing-i18n.md +28 -0
- package/expertise/i18n/content/content-adaptation.md +23 -0
- package/expertise/i18n/content/locale-specific-formatting.md +23 -0
- package/expertise/i18n/content/machine-translation-integration.md +28 -0
- package/expertise/i18n/content/translation-management.md +29 -0
- package/expertise/i18n/foundations/date-time-calendars.md +67 -0
- package/expertise/i18n/foundations/i18n-architecture.md +272 -0
- package/expertise/i18n/foundations/locale-and-language-tags.md +79 -0
- package/expertise/i18n/foundations/numbers-currency-units.md +61 -0
- package/expertise/i18n/foundations/pluralization-and-gender.md +109 -0
- package/expertise/i18n/foundations/string-externalization.md +236 -0
- package/expertise/i18n/foundations/text-direction-bidi.md +241 -0
- package/expertise/i18n/foundations/unicode-and-encoding.md +86 -0
- package/expertise/i18n/index.md +38 -0
- package/expertise/i18n/platform/backend-i18n.md +31 -0
- package/expertise/i18n/platform/flutter-i18n.md +148 -0
- package/expertise/i18n/platform/native-android-i18n.md +36 -0
- package/expertise/i18n/platform/native-ios-i18n.md +36 -0
- package/expertise/i18n/platform/react-i18n.md +103 -0
- package/expertise/i18n/platform/web-css-i18n.md +81 -0
- package/expertise/i18n/rtl/arabic-specific.md +175 -0
- package/expertise/i18n/rtl/hebrew-specific.md +149 -0
- package/expertise/i18n/rtl/rtl-animations-and-transitions.md +111 -0
- package/expertise/i18n/rtl/rtl-forms-and-input.md +161 -0
- package/expertise/i18n/rtl/rtl-fundamentals.md +211 -0
- package/expertise/i18n/rtl/rtl-icons-and-images.md +181 -0
- package/expertise/i18n/rtl/rtl-layout-mirroring.md +252 -0
- package/expertise/i18n/rtl/rtl-navigation-and-gestures.md +107 -0
- package/expertise/i18n/rtl/rtl-testing-and-qa.md +147 -0
- package/expertise/i18n/rtl/rtl-typography.md +160 -0
- package/expertise/index.md +113 -0
- package/expertise/index.yaml +216 -0
- package/expertise/infrastructure/cloud-aws.md +597 -0
- package/expertise/infrastructure/cloud-gcp.md +599 -0
- package/expertise/infrastructure/cybersecurity.md +816 -0
- package/expertise/infrastructure/database-mongodb.md +447 -0
- package/expertise/infrastructure/database-postgres.md +400 -0
- package/expertise/infrastructure/devops-cicd.md +787 -0
- package/expertise/infrastructure/index.md +27 -0
- package/expertise/performance/PROGRESS.md +50 -0
- package/expertise/performance/backend/api-latency.md +1204 -0
- package/expertise/performance/backend/background-jobs.md +506 -0
- package/expertise/performance/backend/connection-pooling.md +1209 -0
- package/expertise/performance/backend/database-query-optimization.md +515 -0
- package/expertise/performance/backend/index.md +23 -0
- package/expertise/performance/backend/rate-limiting-and-throttling.md +971 -0
- package/expertise/performance/foundations/algorithmic-complexity.md +954 -0
- package/expertise/performance/foundations/caching-strategies.md +489 -0
- package/expertise/performance/foundations/concurrency-and-parallelism.md +847 -0
- package/expertise/performance/foundations/index.md +24 -0
- package/expertise/performance/foundations/measuring-and-profiling.md +440 -0
- package/expertise/performance/foundations/memory-management.md +964 -0
- package/expertise/performance/foundations/performance-budgets.md +1314 -0
- package/expertise/performance/index.md +31 -0
- package/expertise/performance/infrastructure/auto-scaling.md +1059 -0
- package/expertise/performance/infrastructure/cdn-and-edge.md +1081 -0
- package/expertise/performance/infrastructure/index.md +22 -0
- package/expertise/performance/infrastructure/load-balancing.md +1081 -0
- package/expertise/performance/infrastructure/observability.md +1079 -0
- package/expertise/performance/mobile/index.md +23 -0
- package/expertise/performance/mobile/mobile-animations.md +544 -0
- package/expertise/performance/mobile/mobile-memory-battery.md +416 -0
- package/expertise/performance/mobile/mobile-network.md +452 -0
- package/expertise/performance/mobile/mobile-rendering.md +599 -0
- package/expertise/performance/mobile/mobile-startup-time.md +505 -0
- package/expertise/performance/platform-specific/flutter-performance.md +647 -0
- package/expertise/performance/platform-specific/index.md +22 -0
- package/expertise/performance/platform-specific/node-performance.md +1307 -0
- package/expertise/performance/platform-specific/postgres-performance.md +1366 -0
- package/expertise/performance/platform-specific/react-performance.md +1403 -0
- package/expertise/performance/web/bundle-optimization.md +1239 -0
- package/expertise/performance/web/image-and-media.md +636 -0
- package/expertise/performance/web/index.md +24 -0
- package/expertise/performance/web/network-optimization.md +1133 -0
- package/expertise/performance/web/rendering-performance.md +1098 -0
- package/expertise/performance/web/ssr-and-hydration.md +918 -0
- package/expertise/performance/web/web-vitals.md +1374 -0
- package/expertise/quality/accessibility.md +985 -0
- package/expertise/quality/evidence-based-verification.md +499 -0
- package/expertise/quality/index.md +24 -0
- package/expertise/quality/ml-model-audit.md +614 -0
- package/expertise/quality/performance.md +600 -0
- package/expertise/quality/testing-api.md +891 -0
- package/expertise/quality/testing-mobile.md +496 -0
- package/expertise/quality/testing-web.md +849 -0
- package/expertise/security/PROGRESS.md +54 -0
- package/expertise/security/agentic-identity.md +540 -0
- package/expertise/security/compliance-frameworks.md +601 -0
- package/expertise/security/data/data-encryption.md +364 -0
- package/expertise/security/data/data-privacy-gdpr.md +692 -0
- package/expertise/security/data/database-security.md +1171 -0
- package/expertise/security/data/index.md +22 -0
- package/expertise/security/data/pii-handling.md +531 -0
- package/expertise/security/foundations/authentication.md +1041 -0
- package/expertise/security/foundations/authorization.md +603 -0
- package/expertise/security/foundations/cryptography.md +1001 -0
- package/expertise/security/foundations/index.md +25 -0
- package/expertise/security/foundations/owasp-top-10.md +1354 -0
- package/expertise/security/foundations/secrets-management.md +1217 -0
- package/expertise/security/foundations/secure-sdlc.md +700 -0
- package/expertise/security/foundations/supply-chain-security.md +698 -0
- package/expertise/security/index.md +31 -0
- package/expertise/security/infrastructure/cloud-security-aws.md +1296 -0
- package/expertise/security/infrastructure/cloud-security-gcp.md +1376 -0
- package/expertise/security/infrastructure/container-security.md +721 -0
- package/expertise/security/infrastructure/incident-response.md +1295 -0
- package/expertise/security/infrastructure/index.md +24 -0
- package/expertise/security/infrastructure/logging-and-monitoring.md +1618 -0
- package/expertise/security/infrastructure/network-security.md +1337 -0
- package/expertise/security/mobile/index.md +23 -0
- package/expertise/security/mobile/mobile-android-security.md +1218 -0
- package/expertise/security/mobile/mobile-binary-protection.md +1229 -0
- package/expertise/security/mobile/mobile-data-storage.md +1265 -0
- package/expertise/security/mobile/mobile-ios-security.md +1401 -0
- package/expertise/security/mobile/mobile-network-security.md +1520 -0
- package/expertise/security/smart-contract-security.md +594 -0
- package/expertise/security/testing/index.md +22 -0
- package/expertise/security/testing/penetration-testing.md +1258 -0
- package/expertise/security/testing/security-code-review.md +1765 -0
- package/expertise/security/testing/threat-modeling.md +1074 -0
- package/expertise/security/testing/vulnerability-scanning.md +1062 -0
- package/expertise/security/web/api-security.md +586 -0
- package/expertise/security/web/cors-and-headers.md +433 -0
- package/expertise/security/web/csrf.md +562 -0
- package/expertise/security/web/file-upload.md +1477 -0
- package/expertise/security/web/index.md +25 -0
- package/expertise/security/web/injection.md +1375 -0
- package/expertise/security/web/session-management.md +1101 -0
- package/expertise/security/web/xss.md +1158 -0
- package/exports/README.md +17 -0
- package/exports/hosts/claude/.claude/agents/clarifier.md +42 -0
- package/exports/hosts/claude/.claude/agents/content-author.md +63 -0
- package/exports/hosts/claude/.claude/agents/designer.md +55 -0
- package/exports/hosts/claude/.claude/agents/executor.md +55 -0
- package/exports/hosts/claude/.claude/agents/learner.md +51 -0
- package/exports/hosts/claude/.claude/agents/planner.md +53 -0
- package/exports/hosts/claude/.claude/agents/researcher.md +43 -0
- package/exports/hosts/claude/.claude/agents/reviewer.md +54 -0
- package/exports/hosts/claude/.claude/agents/specifier.md +47 -0
- package/exports/hosts/claude/.claude/agents/verifier.md +71 -0
- package/exports/hosts/claude/.claude/commands/author.md +42 -0
- package/exports/hosts/claude/.claude/commands/clarify.md +38 -0
- package/exports/hosts/claude/.claude/commands/design-review.md +46 -0
- package/exports/hosts/claude/.claude/commands/design.md +44 -0
- package/exports/hosts/claude/.claude/commands/discover.md +37 -0
- package/exports/hosts/claude/.claude/commands/execute.md +48 -0
- package/exports/hosts/claude/.claude/commands/learn.md +38 -0
- package/exports/hosts/claude/.claude/commands/plan-review.md +42 -0
- package/exports/hosts/claude/.claude/commands/plan.md +39 -0
- package/exports/hosts/claude/.claude/commands/prepare-next.md +37 -0
- package/exports/hosts/claude/.claude/commands/review.md +40 -0
- package/exports/hosts/claude/.claude/commands/run-audit.md +41 -0
- package/exports/hosts/claude/.claude/commands/spec-challenge.md +41 -0
- package/exports/hosts/claude/.claude/commands/specify.md +38 -0
- package/exports/hosts/claude/.claude/commands/verify.md +37 -0
- package/exports/hosts/claude/.claude/settings.json +34 -0
- package/exports/hosts/claude/CLAUDE.md +19 -0
- package/exports/hosts/claude/export.manifest.json +38 -0
- package/exports/hosts/claude/host-package.json +67 -0
- package/exports/hosts/codex/AGENTS.md +19 -0
- package/exports/hosts/codex/export.manifest.json +38 -0
- package/exports/hosts/codex/host-package.json +41 -0
- package/exports/hosts/cursor/.cursor/hooks.json +16 -0
- package/exports/hosts/cursor/.cursor/rules/wazir-core.mdc +19 -0
- package/exports/hosts/cursor/export.manifest.json +38 -0
- package/exports/hosts/cursor/host-package.json +42 -0
- package/exports/hosts/gemini/GEMINI.md +19 -0
- package/exports/hosts/gemini/export.manifest.json +38 -0
- package/exports/hosts/gemini/host-package.json +41 -0
- package/hooks/README.md +18 -0
- package/hooks/definitions/loop_cap_guard.yaml +21 -0
- package/hooks/definitions/post_tool_capture.yaml +24 -0
- package/hooks/definitions/pre_compact_summary.yaml +19 -0
- package/hooks/definitions/pre_tool_capture_route.yaml +19 -0
- package/hooks/definitions/protected_path_write_guard.yaml +19 -0
- package/hooks/definitions/session_start.yaml +19 -0
- package/hooks/definitions/stop_handoff_harvest.yaml +20 -0
- package/hooks/loop-cap-guard +17 -0
- package/hooks/post-tool-lint +36 -0
- package/hooks/protected-path-write-guard +17 -0
- package/hooks/session-start +41 -0
- package/llms-full.txt +2355 -0
- package/llms.txt +43 -0
- package/package.json +79 -0
- package/roles/README.md +20 -0
- package/roles/clarifier.md +42 -0
- package/roles/content-author.md +63 -0
- package/roles/designer.md +55 -0
- package/roles/executor.md +55 -0
- package/roles/learner.md +51 -0
- package/roles/planner.md +53 -0
- package/roles/researcher.md +43 -0
- package/roles/reviewer.md +54 -0
- package/roles/specifier.md +47 -0
- package/roles/verifier.md +71 -0
- package/schemas/README.md +24 -0
- package/schemas/accepted-learning.schema.json +20 -0
- package/schemas/author-artifact.schema.json +156 -0
- package/schemas/clarification.schema.json +19 -0
- package/schemas/design-artifact.schema.json +80 -0
- package/schemas/docs-claim.schema.json +18 -0
- package/schemas/export-manifest.schema.json +20 -0
- package/schemas/hook.schema.json +67 -0
- package/schemas/host-export-package.schema.json +18 -0
- package/schemas/implementation-plan.schema.json +19 -0
- package/schemas/proposed-learning.schema.json +19 -0
- package/schemas/research.schema.json +18 -0
- package/schemas/review.schema.json +29 -0
- package/schemas/run-manifest.schema.json +18 -0
- package/schemas/spec-challenge.schema.json +18 -0
- package/schemas/spec.schema.json +20 -0
- package/schemas/usage.schema.json +102 -0
- package/schemas/verification-proof.schema.json +29 -0
- package/schemas/wazir-manifest.schema.json +173 -0
- package/skills/README.md +40 -0
- package/skills/brainstorming/SKILL.md +77 -0
- package/skills/debugging/SKILL.md +50 -0
- package/skills/design/SKILL.md +61 -0
- package/skills/dispatching-parallel-agents/SKILL.md +128 -0
- package/skills/executing-plans/SKILL.md +70 -0
- package/skills/finishing-a-development-branch/SKILL.md +169 -0
- package/skills/humanize/SKILL.md +123 -0
- package/skills/init-pipeline/SKILL.md +124 -0
- package/skills/prepare-next/SKILL.md +20 -0
- package/skills/receiving-code-review/SKILL.md +123 -0
- package/skills/requesting-code-review/SKILL.md +105 -0
- package/skills/requesting-code-review/code-reviewer.md +108 -0
- package/skills/run-audit/SKILL.md +197 -0
- package/skills/scan-project/SKILL.md +41 -0
- package/skills/self-audit/SKILL.md +153 -0
- package/skills/subagent-driven-development/SKILL.md +154 -0
- package/skills/subagent-driven-development/code-quality-reviewer-prompt.md +26 -0
- package/skills/subagent-driven-development/implementer-prompt.md +102 -0
- package/skills/subagent-driven-development/spec-reviewer-prompt.md +61 -0
- package/skills/tdd/SKILL.md +23 -0
- package/skills/using-git-worktrees/SKILL.md +163 -0
- package/skills/using-skills/SKILL.md +95 -0
- package/skills/verification/SKILL.md +22 -0
- package/skills/wazir/SKILL.md +463 -0
- package/skills/writing-plans/SKILL.md +30 -0
- package/skills/writing-skills/SKILL.md +157 -0
- package/skills/writing-skills/anthropic-best-practices.md +122 -0
- package/skills/writing-skills/persuasion-principles.md +50 -0
- package/templates/README.md +20 -0
- package/templates/artifacts/README.md +10 -0
- package/templates/artifacts/accepted-learning.md +19 -0
- package/templates/artifacts/accepted-learning.template.json +12 -0
- package/templates/artifacts/author.md +74 -0
- package/templates/artifacts/author.template.json +19 -0
- package/templates/artifacts/clarification.md +21 -0
- package/templates/artifacts/clarification.template.json +12 -0
- package/templates/artifacts/execute-notes.md +19 -0
- package/templates/artifacts/implementation-plan.md +21 -0
- package/templates/artifacts/implementation-plan.template.json +11 -0
- package/templates/artifacts/learning-proposal.md +19 -0
- package/templates/artifacts/next-run-handoff.md +21 -0
- package/templates/artifacts/plan-review.md +19 -0
- package/templates/artifacts/proposed-learning.template.json +12 -0
- package/templates/artifacts/research.md +21 -0
- package/templates/artifacts/research.template.json +12 -0
- package/templates/artifacts/review-findings.md +19 -0
- package/templates/artifacts/review.template.json +11 -0
- package/templates/artifacts/run-manifest.template.json +8 -0
- package/templates/artifacts/spec-challenge.md +19 -0
- package/templates/artifacts/spec-challenge.template.json +11 -0
- package/templates/artifacts/spec.md +21 -0
- package/templates/artifacts/spec.template.json +12 -0
- package/templates/artifacts/verification-proof.md +19 -0
- package/templates/artifacts/verification-proof.template.json +11 -0
- package/templates/examples/accepted-learning.example.json +14 -0
- package/templates/examples/author.example.json +152 -0
- package/templates/examples/clarification.example.json +15 -0
- package/templates/examples/docs-claim.example.json +8 -0
- package/templates/examples/export-manifest.example.json +7 -0
- package/templates/examples/host-export-package.example.json +11 -0
- package/templates/examples/implementation-plan.example.json +17 -0
- package/templates/examples/proposed-learning.example.json +13 -0
- package/templates/examples/research.example.json +15 -0
- package/templates/examples/research.example.md +6 -0
- package/templates/examples/review.example.json +17 -0
- package/templates/examples/run-manifest.example.json +9 -0
- package/templates/examples/spec-challenge.example.json +14 -0
- package/templates/examples/spec.example.json +21 -0
- package/templates/examples/verification-proof.example.json +21 -0
- package/templates/examples/wazir-manifest.example.yaml +65 -0
- package/templates/task-definition-schema.md +99 -0
- package/tooling/README.md +20 -0
- package/tooling/src/adapters/context-mode.js +50 -0
- package/tooling/src/capture/command.js +376 -0
- package/tooling/src/capture/store.js +99 -0
- package/tooling/src/capture/usage.js +270 -0
- package/tooling/src/checks/branches.js +50 -0
- package/tooling/src/checks/brand-truth.js +110 -0
- package/tooling/src/checks/changelog.js +231 -0
- package/tooling/src/checks/command-registry.js +36 -0
- package/tooling/src/checks/commits.js +102 -0
- package/tooling/src/checks/docs-drift.js +103 -0
- package/tooling/src/checks/docs-truth.js +201 -0
- package/tooling/src/checks/runtime-surface.js +156 -0
- package/tooling/src/cli.js +116 -0
- package/tooling/src/command-options.js +56 -0
- package/tooling/src/commands/validate.js +320 -0
- package/tooling/src/doctor/command.js +91 -0
- package/tooling/src/export/command.js +77 -0
- package/tooling/src/export/compiler.js +498 -0
- package/tooling/src/guards/loop-cap-guard.js +52 -0
- package/tooling/src/guards/protected-path-write-guard.js +67 -0
- package/tooling/src/index/command.js +152 -0
- package/tooling/src/index/storage.js +1061 -0
- package/tooling/src/index/summarizers.js +261 -0
- package/tooling/src/loaders.js +18 -0
- package/tooling/src/project-root.js +22 -0
- package/tooling/src/recall/command.js +225 -0
- package/tooling/src/schema-validator.js +30 -0
- package/tooling/src/state-root.js +40 -0
- package/tooling/src/status/command.js +71 -0
- package/wazir.manifest.yaml +135 -0
- package/workflows/README.md +19 -0
- package/workflows/author.md +42 -0
- package/workflows/clarify.md +38 -0
- package/workflows/design-review.md +46 -0
- package/workflows/design.md +44 -0
- package/workflows/discover.md +37 -0
- package/workflows/execute.md +48 -0
- package/workflows/learn.md +38 -0
- package/workflows/plan-review.md +42 -0
- package/workflows/plan.md +39 -0
- package/workflows/prepare-next.md +37 -0
- package/workflows/review.md +40 -0
- package/workflows/run-audit.md +41 -0
- package/workflows/spec-challenge.md +41 -0
- package/workflows/specify.md +38 -0
- package/workflows/verify.md +37 -0
|
@@ -0,0 +1,400 @@
|
|
|
1
|
+
# PostgreSQL -- Expertise Module
|
|
2
|
+
|
|
3
|
+
> PostgreSQL specialist responsible for designing, optimizing, and administering relational databases.
|
|
4
|
+
> Scope covers schema design, query optimization, replication, security hardening, backup/recovery,
|
|
5
|
+
> and operational excellence for PostgreSQL 16+ in both self-hosted and managed environments.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Core Patterns & Conventions
|
|
10
|
+
|
|
11
|
+
### Schema Design Conventions
|
|
12
|
+
|
|
13
|
+
**Naming:** Tables: plural `snake_case` (`order_items`). Columns: singular `snake_case` (`created_at`). PKs: `id` as `BIGINT GENERATED ALWAYS AS IDENTITY`. FKs: `<table_singular>_id`. Indexes: `idx_<table>_<cols>`. Constraints: `chk_`/`uq_` prefix. Booleans: `is_`/`has_` prefix.
|
|
14
|
+
|
|
15
|
+
**Data Types:**
|
|
16
|
+
- `BIGINT GENERATED ALWAYS AS IDENTITY` over `SERIAL` (SQL-standard, PG 10+)
|
|
17
|
+
- `timestamptz` always; never bare `timestamp` (ambiguous across timezones)
|
|
18
|
+
- `text` over `varchar(n)` unless a hard DB-enforced length limit is needed
|
|
19
|
+
- `numeric`/`integer` for money; never `float`/`double precision`
|
|
20
|
+
- `uuid` for external IDs; `bigint` for internal PKs
|
|
21
|
+
- `inet`/`cidr` for IPs; `daterange`/`tstzrange` for temporal ranges
|
|
22
|
+
|
|
23
|
+
**Constraints:** Default to `NOT NULL`. Use `CHECK` for domain rules (`CHECK (price >= 0)`). Prefer DB-level `UNIQUE` over app-level checks. Use `EXCLUDE` for range overlaps. Define FKs with explicit `ON DELETE` behavior.
|
|
24
|
+
|
|
25
|
+
### Indexing Strategies
|
|
26
|
+
|
|
27
|
+
| Type | Use Case | Notes |
|
|
28
|
+
|------|----------|-------|
|
|
29
|
+
| **B-tree** | Equality, range, ORDER BY | Default; covers 95% of cases; supports index-only scans |
|
|
30
|
+
| **GIN** | Full-text search, JSONB `@>`, arrays | Use `jsonb_path_ops` for containment-only queries (smaller, faster) |
|
|
31
|
+
| **GiST** | PostGIS geometry, range types, FTS (write-heavy) | Lossy; faster builds than GIN; proximity/nearest-neighbor |
|
|
32
|
+
| **BRIN** | Naturally-ordered append-only data (timestamps) | Up to 1000x smaller than B-tree; requires correlated physical order |
|
|
33
|
+
| **Hash** | Equality-only `=` lookups | WAL-logged since PG 10; rarely beats B-tree |
|
|
34
|
+
|
|
35
|
+
**Partial indexes:** `CREATE INDEX idx_orders_pending ON orders(created_at) WHERE status = 'pending'` -- dramatically smaller and cheaper to maintain.
|
|
36
|
+
**Covering indexes:** `CREATE INDEX ... ON orders(user_id) INCLUDE (total, status)` -- enables index-only scans for extra columns.
|
|
37
|
+
**Expression indexes:** `CREATE INDEX ... ON users(lower(email))` -- must match the exact expression in queries.
|
|
38
|
+
|
|
39
|
+
### Migration Patterns and Tools
|
|
40
|
+
|
|
41
|
+
| Tool | Approach | Best For |
|
|
42
|
+
|------|----------|----------|
|
|
43
|
+
| **Flyway** | Versioned SQL scripts | Java/JVM teams, CI/CD pipelines |
|
|
44
|
+
| **Liquibase** | Changelog (XML/YAML/SQL) | Enterprise teams needing rollback plans |
|
|
45
|
+
| **Prisma Migrate** | Declarative schema DSL | TypeScript full-stack teams |
|
|
46
|
+
| **Atlas** | Declarative HCL/SQL | "Terraform for databases" approach |
|
|
47
|
+
| **dbmate** | Plain SQL up/down files | Lightweight, language-agnostic |
|
|
48
|
+
| **Alembic** | Python migration scripts | SQLAlchemy / Python teams |
|
|
49
|
+
|
|
50
|
+
**Rules:** Migrations must be idempotent (`IF NOT EXISTS`). Never modify applied migrations. Include `up`+`down` scripts. Use `CREATE INDEX CONCURRENTLY`. Separate DDL from DML. Lint with `squawk` or `pgspot` in CI.
|
|
51
|
+
|
|
52
|
+
### Query Patterns
|
|
53
|
+
|
|
54
|
+
**CTEs:** PG 12+ auto-inlines CTEs when beneficial. Use `MATERIALIZED`/`NOT MATERIALIZED` to override.
|
|
55
|
+
**Window functions:** `RANK()`, `LAG()`, `LEAD()` with `PARTITION BY` + `ORDER BY` for analytics without self-joins.
|
|
56
|
+
**LATERAL joins:** Row-by-row correlated subqueries -- ideal for "top-N per group" patterns.
|
|
57
|
+
**Bulk operations:** Use `COPY` or multi-row `INSERT` (up to 100x faster than row-by-row).
|
|
58
|
+
|
|
59
|
+
### Connection Management
|
|
60
|
+
|
|
61
|
+
pgBouncer is the standard pooler. Use `transaction` mode (connection returned after each transaction) for most workloads. Use `session` mode only when you need prepared statements, LISTEN/NOTIFY, or temp tables. Sizing: `(num_pools x default_pool_size) < max_connections - 15`. For CPU-bound OLTP, set `max_connections` to 2-4x vCPU count. Deploy multiple pgBouncer instances behind HAProxy for HA.
|
|
62
|
+
|
|
63
|
+
### Transaction Isolation Levels
|
|
64
|
+
|
|
65
|
+
| Level | When to Use | Trade-off |
|
|
66
|
+
|-------|-------------|-----------|
|
|
67
|
+
| **Read Committed** (default) | 90% of OLTP workloads | Non-repeatable reads between statements |
|
|
68
|
+
| **Repeatable Read** | Reporting, analytics, consistent multi-statement reads | Must retry on serialization failure |
|
|
69
|
+
| **Serializable** | Financial ops, inventory, double-booking prevention | Highest retry rate; always implement retry logic |
|
|
70
|
+
|
|
71
|
+
PG silently upgrades `Read Uncommitted` to `Read Committed`.
|
|
72
|
+
|
|
73
|
+
### JSONB Usage Patterns
|
|
74
|
+
|
|
75
|
+
**Use for:** variable-schema metadata, event payloads, sparse attributes, user preferences.
|
|
76
|
+
**Avoid for:** fixed schemas (use columns), frequently filtered/joined data, deeply nested docs (5+ levels), large documents (>2KB triggers TOAST overhead).
|
|
77
|
+
**Best practice:** Hybrid -- typed columns for fixed attributes, `metadata JSONB` for variable data. Index with GIN (`jsonb_path_ops` for `@>` only). **Caveat:** PG cannot collect statistics inside JSONB -- planner uses hardcoded 0.1% selectivity estimate, leading to poor plans. Extract hot keys to typed columns.
|
|
78
|
+
|
|
79
|
+
### Partitioning Strategies
|
|
80
|
+
|
|
81
|
+
**Range:** Time-series data (partition by month/week). **List:** Categorical data (tenant, region). **Hash:** No natural key; even distribution.
|
|
82
|
+
**When:** Table exceeds server RAM or >50-100M rows; queries consistently filter on partition key; need fast bulk deletes (DROP PARTITION). **Limits:** Keep to a few dozen to a few hundred partitions; avoid <10K rows per partition. Automate creation with cron or `pg_partman`.
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## Anti-Patterns & Pitfalls
|
|
87
|
+
|
|
88
|
+
### 1. Using `SELECT *` in Production Queries
|
|
89
|
+
Forces heap fetches for every row, defeating index-only scans. Breaks app code when columns change. Always specify exact columns needed.
|
|
90
|
+
|
|
91
|
+
### 2. Missing Indexes on Foreign Keys
|
|
92
|
+
PG does NOT auto-index FK columns. JOINs and cascading DELETE/UPDATE degrade to sequential scans -- O(n) per operation on the referenced table.
|
|
93
|
+
|
|
94
|
+
### 3. Using `timestamp` Without Time Zone
|
|
95
|
+
Stores wall-clock time with no timezone context. Values become ambiguous when servers/clients operate in different timezones. Always use `timestamptz` (stores UTC, converts on display).
|
|
96
|
+
|
|
97
|
+
### 4. Long-Running Transactions
|
|
98
|
+
MVCC keeps old row versions for any open transaction. Hours-long transactions prevent autovacuum from reclaiming dead tuples across ALL tables, causing persistent bloat. Monitor `pg_stat_activity` for `idle in transaction`.
|
|
99
|
+
|
|
100
|
+
### 5. Not Tuning Autovacuum for High-Churn Tables
|
|
101
|
+
Default `scale_factor = 0.2` means vacuum waits for 20% dead rows. For a 100M-row table, that is 20M dead rows. Set per-table: `ALTER TABLE hot_table SET (autovacuum_vacuum_scale_factor = 0.01)`.
|
|
102
|
+
|
|
103
|
+
### 6. Using `OFFSET` for Pagination
|
|
104
|
+
`OFFSET N` scans and discards N rows. Page 1000 scans 1000 x page_size rows. Use keyset pagination: `WHERE (created_at, id) < (:last_created_at, :last_id) ORDER BY created_at DESC, id DESC LIMIT 20`.
|
|
105
|
+
|
|
106
|
+
### 7. Read-Modify-Write Without Proper Locking
|
|
107
|
+
Read, modify in app, write back = race condition. Concurrent sessions cause lost updates. Use atomic SQL (`SET balance = balance - 100`), `SELECT ... FOR UPDATE`, or Serializable isolation.
|
|
108
|
+
|
|
109
|
+
### 8. Using `SERIAL` Instead of Identity Columns
|
|
110
|
+
`SERIAL` has loose coupling -- values can be manually set, `pg_dump`/restore causes sequence drift. `GENERATED ALWAYS AS IDENTITY` enforces DB control (SQL-standard, PG 10+).
|
|
111
|
+
|
|
112
|
+
### 9. Storing ENUMs as Text Strings
|
|
113
|
+
`'pending'`/`'active'` wastes storage per row, inflates indexes. Use PG `ENUM` types for small stable sets, or a lookup table with integer FK for mutable sets.
|
|
114
|
+
|
|
115
|
+
### 10. Using `NOT IN` with Nullable Columns
|
|
116
|
+
`NOT IN (subquery)` returns zero rows if any subquery value is NULL (three-valued logic). Use `NOT EXISTS` instead -- handles NULLs correctly and often yields better anti-join plans.
|
|
117
|
+
|
|
118
|
+
### 11. Over-Indexing Write-Heavy Tables
|
|
119
|
+
Each index adds maintenance cost to every INSERT/UPDATE/DELETE (5-10x write slowdown with 10+ indexes). Increases WAL volume and replication lag. Audit with `pg_stat_user_indexes`; drop indexes with `idx_scan = 0`.
|
|
120
|
+
|
|
121
|
+
### 12. UUIDv4 as Primary Key
|
|
122
|
+
Random UUIDs destroy B-tree locality -- index page splits, fragmentation, cache misses. Inserts drop from ~72K/s (BIGINT) to ~13K/s. Use UUIDv7 (time-sorted, `pg_uuidv7` extension) or BIGINT PK + UUID column for external exposure.
|
|
123
|
+
|
|
124
|
+
### 13. `CREATE INDEX` Without `CONCURRENTLY`
|
|
125
|
+
Standard `CREATE INDEX` acquires SHARE lock, blocking all writes. Hours of downtime on large tables. Always use `CONCURRENTLY` in production (cannot run inside a transaction).
|
|
126
|
+
|
|
127
|
+
### 14. ORM `synchronize: true` in Production
|
|
128
|
+
TypeORM's `synchronize` / Prisma's `db push` can drop columns, alter types, remove constraints without warning. Use migration files in all non-dev environments.
|
|
129
|
+
|
|
130
|
+
### 15. No `statement_timeout` on Application Connections
|
|
131
|
+
Without timeout, bad queries run for hours, holding locks, blocking autovacuum. Set `statement_timeout = '30s'` per role. Use longer timeouts for batch/admin connections.
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## Testing Strategy
|
|
136
|
+
|
|
137
|
+
**Approaches:** Unit-test functions/triggers/constraints with pgTAP. Integration-test queries against real PG (never SQLite). Run migration up/down/up in CI. Property-test constraint enforcement with random data.
|
|
138
|
+
|
|
139
|
+
**Test data:** Use factories (`factory_bot`, `fishery`, `faker.js`) over static fixtures. Use `TRUNCATE ... CASCADE` (not DELETE) for fast cleanup. Snapshot with `pg_dump` for known-good states.
|
|
140
|
+
|
|
141
|
+
**pgTAP example:**
|
|
142
|
+
```sql
|
|
143
|
+
BEGIN;
|
|
144
|
+
SELECT plan(3);
|
|
145
|
+
SELECT has_table('users');
|
|
146
|
+
SELECT has_column('users', 'email');
|
|
147
|
+
SELECT col_is_unique('users', 'email');
|
|
148
|
+
SELECT * FROM finish();
|
|
149
|
+
ROLLBACK;
|
|
150
|
+
```
|
|
151
|
+
Run with `pg_prove -d mydb tests/*.sql`. `runtests()` auto-rolls back each test.
|
|
152
|
+
|
|
153
|
+
**Migration testing:** Validate reversibility (up/down/up). Compare schema with `pg_dump --schema-only`. Test against anonymized production data. Lint with `squawk`/`pgspot`.
|
|
154
|
+
|
|
155
|
+
**Isolation:** Each test in its own `BEGIN`/`ROLLBACK`. For committed data, use template databases (`CREATE DATABASE test_x TEMPLATE test_base`). `pgtestdb` (Go) creates ephemeral DBs from cached templates in milliseconds.
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## Performance Considerations
|
|
160
|
+
|
|
161
|
+
### EXPLAIN ANALYZE Interpretation
|
|
162
|
+
```sql
|
|
163
|
+
EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) SELECT ...;
|
|
164
|
+
```
|
|
165
|
+
- **Seq Scan:** OK for <10K rows or >5-10% selectivity; investigate otherwise
|
|
166
|
+
- **Index Scan → heap fetch:** Good for selective queries
|
|
167
|
+
- **Index Only Scan:** Best case; requires up-to-date visibility map (VACUUM)
|
|
168
|
+
- **Buffers shared hit/read:** `hit` = cache; `read` = disk I/O. High `read` = cache miss
|
|
169
|
+
- **rows vs actual rows mismatch:** Stale statistics; run `ANALYZE`
|
|
170
|
+
|
|
171
|
+
### Query Optimization
|
|
172
|
+
Run `ANALYZE` after bulk loads. Rewrite `NOT IN` as `NOT EXISTS`. Use keyset pagination. Avoid bare functions in WHERE (or create expression indexes). Use `EXISTS` not `COUNT(*) > 0`. Use `COPY` for bulk inserts. Use `ANY(ARRAY[...])` over long `IN (...)` lists.
|
|
173
|
+
|
|
174
|
+
### Autovacuum Tuning (PostgreSQL 16+)
|
|
175
|
+
```ini
|
|
176
|
+
autovacuum_max_workers = 4 # default 3
|
|
177
|
+
autovacuum_vacuum_scale_factor = 0.05 # default 0.2
|
|
178
|
+
autovacuum_analyze_scale_factor = 0.02 # default 0.1
|
|
179
|
+
autovacuum_vacuum_cost_delay = 2ms # default 2ms (PG12+)
|
|
180
|
+
autovacuum_vacuum_cost_limit = 1000 # default 200
|
|
181
|
+
autovacuum_naptime = 15s # default 60s
|
|
182
|
+
```
|
|
183
|
+
Monitor: `SELECT relname, n_dead_tup, last_autovacuum FROM pg_stat_user_tables ORDER BY n_dead_tup DESC;`
|
|
184
|
+
|
|
185
|
+
### Memory Tuning
|
|
186
|
+
|
|
187
|
+
| Parameter | Setting | Notes |
|
|
188
|
+
|-----------|---------|-------|
|
|
189
|
+
| `shared_buffers` | 25% RAM (max 40%) | PG internal cache; OS handles the rest |
|
|
190
|
+
| `effective_cache_size` | 50-75% RAM | Not an allocation; tells planner expected cache |
|
|
191
|
+
| `work_mem` | 32-256 MB | Per-operation (sorts, hashes); multiply by connections for worst case |
|
|
192
|
+
| `maintenance_work_mem` | 512 MB - 2 GB | VACUUM, CREATE INDEX |
|
|
193
|
+
| `random_page_cost` | 1.1 (SSD) | Default 4.0 assumes HDD |
|
|
194
|
+
| `effective_io_concurrency` | 200 (SSD) | Default 1 assumes HDD |
|
|
195
|
+
|
|
196
|
+
**Rule:** `shared_buffers + effective_cache_size <= 0.97 * total_RAM`
|
|
197
|
+
|
|
198
|
+
### Monitoring
|
|
199
|
+
- **pg_stat_statements:** Query execution stats (essential; enable in `shared_preload_libraries`)
|
|
200
|
+
- **pg_stat_user_tables/indexes:** Dead tuples, unused indexes (`idx_scan = 0`)
|
|
201
|
+
- **pg_stat_activity:** Active queries, idle-in-transaction, wait events
|
|
202
|
+
- **auto_explain:** Logs plans for slow queries (`log_min_duration = 3s`)
|
|
203
|
+
- **pgBadger:** Log analysis into HTML reports
|
|
204
|
+
- **Datadog/Grafana:** Real-time dashboards from pg_stat_statements
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
## Security Considerations
|
|
209
|
+
|
|
210
|
+
### Role-Based Access Control
|
|
211
|
+
Create per-responsibility roles: `app_readonly`, `app_readwrite`, `app_admin`, `migration_runner`. Grant minimum privileges. Never use `postgres` superuser for app connections. Revoke `CREATE ON SCHEMA public FROM PUBLIC`. Use `ALTER DEFAULT PRIVILEGES` for future objects.
|
|
212
|
+
|
|
213
|
+
### Row-Level Security (RLS)
|
|
214
|
+
```sql
|
|
215
|
+
ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
|
|
216
|
+
ALTER TABLE orders FORCE ROW LEVEL SECURITY;
|
|
217
|
+
CREATE POLICY tenant_isolation ON orders
|
|
218
|
+
USING (tenant_id = current_setting('app.tenant_id')::bigint)
|
|
219
|
+
WITH CHECK (tenant_id = current_setting('app.tenant_id')::bigint);
|
|
220
|
+
```
|
|
221
|
+
Always `FORCE` RLS (owners bypass otherwise). Index policy columns. Test with non-superuser accounts. Avoid non-`LEAKPROOF` functions (prevent index usage). Set session vars at connection time, never from user input.
|
|
222
|
+
|
|
223
|
+
### SSL/TLS and Authentication
|
|
224
|
+
Set `ssl = on`, `ssl_min_protocol_version = 'TLSv1.3'` in postgresql.conf. Use `hostssl` in pg_hba.conf with `scram-sha-256` (never `md5` or `trust` over TCP). Client-side: `sslmode=verify-full`.
|
|
225
|
+
|
|
226
|
+
### SQL Injection Prevention
|
|
227
|
+
Always use parameterized queries. Never interpolate user input. Set `statement_timeout` to limit blast radius.
|
|
228
|
+
|
|
229
|
+
### Audit Logging
|
|
230
|
+
Use `pgaudit` extension: `pgaudit.log = 'write, ddl'` logs all data modifications and schema changes.
|
|
231
|
+
|
|
232
|
+
### Encryption
|
|
233
|
+
**In transit:** SSL/TLS. **At rest:** OS/cloud-level (LUKS, dm-crypt, RDS default encryption). **Column-level:** `pgcrypto` (`pgp_sym_encrypt`). **Keys:** Store outside DB (AWS KMS, Vault). PG has no native TDE.
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
## Integration Patterns
|
|
238
|
+
|
|
239
|
+
### ORM Best Practices
|
|
240
|
+
- **Prisma:** Type-safe; use `prisma migrate` not `db push` in prod; vendor lock-in via proprietary DSL
|
|
241
|
+
- **Drizzle:** Generates single optimized SQL; up to 14x lower latency than N+1-prone ORMs
|
|
242
|
+
- **TypeORM:** Never `synchronize: true` in prod; validate generated migration SQL
|
|
243
|
+
- **SQLAlchemy:** Prefer `Core` over `ORM` for complex queries; use scoped sessions
|
|
244
|
+
- **General:** Review generated SQL in dev. Eager-load to avoid N+1. Use raw SQL for CTEs/window functions/LATERAL. Match ORM pool size to pgBouncer's `default_pool_size`.
|
|
245
|
+
|
|
246
|
+
### Replication
|
|
247
|
+
**Streaming (physical):** Byte-for-byte replica. HA failover + read scaling. Sync mode for zero data loss.
|
|
248
|
+
**Logical (PG 10+):** Publish/subscribe. Replicate specific tables or filtered rows (PG 15+ WHERE). Use for cross-version upgrades. Does NOT replicate DDL or sequences.
|
|
249
|
+
|
|
250
|
+
### LISTEN/NOTIFY for Real-Time
|
|
251
|
+
```sql
|
|
252
|
+
CREATE OR REPLACE FUNCTION notify_change() RETURNS TRIGGER AS $$
|
|
253
|
+
BEGIN
|
|
254
|
+
PERFORM pg_notify('order_changes', json_build_object('op', TG_OP, 'id', NEW.id)::text);
|
|
255
|
+
RETURN NEW;
|
|
256
|
+
END; $$ LANGUAGE plpgsql;
|
|
257
|
+
```
|
|
258
|
+
Ideal for low-medium rates (hundreds/sec). Payload max 8KB. Transactional (delivered on COMMIT). Use `pg_eventserv` for WebSocket bridging. For high throughput, pair with Redis/Kafka.
|
|
259
|
+
|
|
260
|
+
### Full-Text Search
|
|
261
|
+
```sql
|
|
262
|
+
ALTER TABLE articles ADD COLUMN search_vector tsvector GENERATED ALWAYS AS (
|
|
263
|
+
setweight(to_tsvector('english', coalesce(title,'')), 'A') ||
|
|
264
|
+
setweight(to_tsvector('english', coalesce(body,'')), 'B')
|
|
265
|
+
) STORED;
|
|
266
|
+
CREATE INDEX idx_articles_search ON articles USING GIN (search_vector);
|
|
267
|
+
```
|
|
268
|
+
Good for small-to-medium datasets. Use `pg_trgm` for `LIKE '%pattern%'`. For faceting/fuzzy/synonyms, consider Elasticsearch or ParadeDB.
|
|
269
|
+
|
|
270
|
+
### PostGIS
|
|
271
|
+
Use `geography` for lat/lon; `geometry` for projected coordinates. GiST indexes for spatial queries (`ST_DWithin`, `ST_Distance`, `ST_Contains`).
|
|
272
|
+
|
|
273
|
+
---
|
|
274
|
+
|
|
275
|
+
## DevOps & Deployment
|
|
276
|
+
|
|
277
|
+
### Backup Strategies
|
|
278
|
+
|
|
279
|
+
| Method | Type | RPO |
|
|
280
|
+
|--------|------|-----|
|
|
281
|
+
| `pg_dump`/`pg_dumpall` | Logical | Point-in-time of dump |
|
|
282
|
+
| `pg_basebackup` + WAL | Physical | Seconds (PITR) |
|
|
283
|
+
| **pgBackRest** | Physical + WAL | Seconds; incremental, parallel, encrypted, S3/GCS |
|
|
284
|
+
| **Barman** | Physical + WAL | Seconds; strong Patroni integration |
|
|
285
|
+
|
|
286
|
+
Test restores monthly. Store backups in a different region/account. Retain 7+ days PITR (30 for compliance).
|
|
287
|
+
|
|
288
|
+
### High Availability
|
|
289
|
+
**Patroni** (recommended): Cluster orchestration with auto-failover via etcd/Consul/ZooKeeper. Deploy across 3+ AZs. Pair with pgBackRest. Architecture: `etcd (3 nodes) -> Patroni (primary + replicas) -> HAProxy/pgBouncer -> App`.
|
|
290
|
+
**repmgr:** Lighter alternative; less automation, simpler setup.
|
|
291
|
+
|
|
292
|
+
### Docker
|
|
293
|
+
Use `postgres:16-alpine` or `postgres:17-alpine`. Named volumes for data. Enable `--data-checksums`. Health check: `pg_isready`. Docker is excellent for dev/CI; prefer VMs or managed for production.
|
|
294
|
+
|
|
295
|
+
### Managed vs Self-Hosted
|
|
296
|
+
Managed (RDS/Cloud SQL/Supabase): low ops, limited extensions, higher cost at scale. Self-hosted (Patroni): full control, any extension, lower cost but requires DBA expertise. Supabase for instant APIs + auth. Neon for serverless scale-to-zero.
|
|
297
|
+
|
|
298
|
+
### Alerting
|
|
299
|
+
**Page immediately:** replication lag >30s, disk >85%, connections >80% of max, queries >5min, failed autovacuum.
|
|
300
|
+
**Warning:** dead tuples growing, cache hit ratio <99%, checkpoint storms, lock waits increasing.
|
|
301
|
+
|
|
302
|
+
---
|
|
303
|
+
|
|
304
|
+
## Decision Trees
|
|
305
|
+
|
|
306
|
+
### Which Index Type?
|
|
307
|
+
```
|
|
308
|
+
Equality (=)? --> B-tree
|
|
309
|
+
Range (<, >, BETWEEN, ORDER BY)? --> B-tree
|
|
310
|
+
Full-text (tsvector @@ tsquery)? --> GIN (read-heavy) or GiST (write-heavy)
|
|
311
|
+
JSONB containment (@>), arrays? --> GIN (jsonb_path_ops for @> only)
|
|
312
|
+
Geospatial (PostGIS)? --> GiST
|
|
313
|
+
Append-only, naturally ordered? --> BRIN (large tables only)
|
|
314
|
+
Subset of rows? --> Add WHERE clause (partial index)
|
|
315
|
+
Need index-only scan extras? --> Add INCLUDE clause (covering index)
|
|
316
|
+
Function in WHERE? --> Expression index
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
### Managed vs Self-Hosted?
|
|
320
|
+
```
|
|
321
|
+
Team < 5 engineers? --> Managed
|
|
322
|
+
Need extensions not on managed platforms? --> Self-host (Patroni)
|
|
323
|
+
DB spend > $5K/mo + have DBA expertise? --> Self-host (cost savings)
|
|
324
|
+
DB spend > $5K/mo but no DBA? --> Managed (ops cost offsets)
|
|
325
|
+
Serverless / bursty? --> Neon
|
|
326
|
+
Need instant APIs + auth + realtime? --> Supabase
|
|
327
|
+
Multi-region active-active? --> Aurora or CockroachDB
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
### When to Partition?
|
|
331
|
+
```
|
|
332
|
+
Table > 50-100M rows or exceeds server RAM? --> Yes
|
|
333
|
+
Queries filter on partition key consistently? --> Range (dates) or List (categories)
|
|
334
|
+
No natural key? --> Hash partitioning
|
|
335
|
+
Need fast bulk deletes of old data? --> Range + DROP PARTITION
|
|
336
|
+
Otherwise? --> Do not partition (overhead not justified)
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
---
|
|
340
|
+
|
|
341
|
+
## Code Examples
|
|
342
|
+
|
|
343
|
+
### 1. Safe Migration: Add Column + Concurrent Index
|
|
344
|
+
```sql
|
|
345
|
+
-- PG 11+ does NOT rewrite table for non-volatile defaults. Fast on billion-row tables.
|
|
346
|
+
ALTER TABLE users ADD COLUMN is_verified BOOLEAN NOT NULL DEFAULT false;
|
|
347
|
+
CREATE INDEX CONCURRENTLY idx_users_unverified ON users (is_verified) WHERE is_verified = false;
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
### 2. Keyset Pagination
|
|
351
|
+
```sql
|
|
352
|
+
-- First page
|
|
353
|
+
SELECT id, title, created_at FROM articles
|
|
354
|
+
WHERE published = true ORDER BY created_at DESC, id DESC LIMIT 20;
|
|
355
|
+
-- Next page (pass last row's values)
|
|
356
|
+
SELECT id, title, created_at FROM articles
|
|
357
|
+
WHERE published = true AND (created_at, id) < (:last_created_at, :last_id)
|
|
358
|
+
ORDER BY created_at DESC, id DESC LIMIT 20;
|
|
359
|
+
```
|
|
360
|
+
Constant performance at any depth -- unlike OFFSET which degrades linearly.
|
|
361
|
+
|
|
362
|
+
### 3. Upsert with Conflict Handling
|
|
363
|
+
```sql
|
|
364
|
+
INSERT INTO product_inventory (product_id, warehouse_id, quantity)
|
|
365
|
+
VALUES (:product_id, :warehouse_id, :quantity)
|
|
366
|
+
ON CONFLICT (product_id, warehouse_id) DO UPDATE SET
|
|
367
|
+
quantity = product_inventory.quantity + EXCLUDED.quantity,
|
|
368
|
+
updated_at = NOW()
|
|
369
|
+
RETURNING *;
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
### 4. Advisory Locks for Job Coordination
|
|
373
|
+
```sql
|
|
374
|
+
SELECT pg_try_advisory_lock(hashtext('process_batch_42')); -- non-blocking acquire
|
|
375
|
+
-- ... exclusive work ...
|
|
376
|
+
SELECT pg_advisory_unlock(hashtext('process_batch_42'));
|
|
377
|
+
```
|
|
378
|
+
Lightweight, never conflict with row/table locks. Ideal for preventing duplicate background job processing.
|
|
379
|
+
|
|
380
|
+
### 5. Production postgresql.conf (32 GB RAM, 8 vCPU, SSD)
|
|
381
|
+
```ini
|
|
382
|
+
max_connections = 200
|
|
383
|
+
shared_buffers = 8GB
|
|
384
|
+
effective_cache_size = 24GB
|
|
385
|
+
work_mem = 64MB
|
|
386
|
+
maintenance_work_mem = 2GB
|
|
387
|
+
random_page_cost = 1.1
|
|
388
|
+
effective_io_concurrency = 200
|
|
389
|
+
max_wal_size = 4GB
|
|
390
|
+
checkpoint_completion_target = 0.9
|
|
391
|
+
autovacuum_max_workers = 4
|
|
392
|
+
autovacuum_vacuum_scale_factor = 0.05
|
|
393
|
+
autovacuum_vacuum_cost_limit = 1000
|
|
394
|
+
log_min_duration_statement = 1000
|
|
395
|
+
shared_preload_libraries = 'pg_stat_statements, auto_explain, pgaudit'
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
---
|
|
399
|
+
|
|
400
|
+
*Researched: 2026-03-07 | Sources: [PostgreSQL Official Docs v18](https://www.postgresql.org/docs/current/), [Instaclustr Best Practices 2025](https://www.instaclustr.com/education/postgresql/top-10-postgresql-best-practices-for-2025/), [PostgreSQL Wiki - Don't Do This](https://wiki.postgresql.org/wiki/Don't_Do_This), [Percona Index Guide](https://www.percona.com/blog/a-practical-guide-to-postgresql-indexes/), [Sachith Indexing Playbook 2026](https://www.sachith.co.uk/postgresql-indexing-playbook-practical-guide-feb-12-2026/), [MyDBOps Tuning 2025](https://www.mydbops.com/blog/postgresql-parameter-tuning-best-practices), [AWS JSONB Patterns](https://aws.amazon.com/blogs/database/postgresql-as-a-json-database-advanced-patterns-and-best-practices/), [Bytebase Flyway vs Liquibase 2026](https://www.bytebase.com/blog/flyway-vs-liquibase/), [Permit.io RLS Guide](https://www.permit.io/blog/postgres-rls-implementation-guide), [Bytebase RLS Footguns](https://www.bytebase.com/blog/postgres-row-level-security-footguns/), [CYBERTEC Autovacuum](https://www.cybertec-postgresql.com/en/tuning-autovacuum-postgresql/), [pgTAP](https://pgtap.org/), [Brandur Notifier Pattern](https://brandur.org/notifier), [OneUpTime PG Tuning 2026](https://oneuptime.com/blog/post/2026-02-20-postgresql-performance-tuning/view), [SQLFlash Managed PG 2026](https://sqlflash.ai/article/20260114_aws-azure-gcp-supabase-postgresql-2026/), [EDB Security Hardening](https://www.enterprisedb.com/blog/how-to-secure-postgresql-security-hardening-best-practices-checklist-tips-encryption-authentication-vulnerabilities)*
|