From 0a96774998b7d7cf7212d57073cfc7bf8f558631 Mon Sep 17 00:00:00 2001 From: viragtripathi <15679776+viragtripathi@users.noreply.github.com> Date: Mon, 18 May 2026 10:34:05 +0000 Subject: [PATCH] chore: update cockroachdb-skills submodule --- .cursor-plugin/plugin.json | 66 +++---- .../SKILL.md | 2 +- .../SKILL.md | 9 +- .../monitoring-and-concurrency-testing.md | 0 .../SKILL.md | 10 +- .../.gitkeep | 0 .../.gitkeep | 0 .../.gitkeep | 0 .../analyzing-range-distribution/SKILL.md | 26 +-- .../references/permissions.md | 0 .../references/sql-queries.md | 0 .../SKILL.md | 21 ++- .../references/permissions.md | 0 .../auditing-table-statistics/SKILL.md | 0 .../references/create-statistics-examples.md | 0 .../references/statistics-thresholds.md | 0 .../monitoring-background-jobs/SKILL.md | 0 .../references/job-states.md | 0 .../references/job-types.md | 0 .../references/permissions.md | 0 .../references/sql-query-variations.md | 0 .../profiling-statement-fingerprints/SKILL.md | 6 +- .../references/json-field-reference.md | 0 .../references/metrics-and-units.md | 0 .../references/sql-query-variations.md | 0 .../SKILL.md | 6 +- .../references/json-field-reference.md | 0 .../references/metrics-and-units.md | 0 .../references/sql-query-variations.md | 0 .../triaging-live-sql-activity/SKILL.md | 2 +- .../references/permissions.md | 0 .../references/sql-queries.md | 0 .../.gitkeep | 0 .../molt-fetch/SKILL.md | 16 +- .../molt-fetch/references/flags.md | 0 .../molt-replicator/SKILL.md | 6 +- .../molt-replicator/references/flags.md | 0 .../molt-verify/SKILL.md | 9 +- .../molt-verify/references/flags.md | 0 .../setting-up-local-cluster/SKILL.md | 41 +++-- .../SKILL.md | 18 +- .../references/cmek-procedures.md | 0 .../references/kubernetes-certs.md | 0 .../references/rotation-procedures.md | 0 .../references/safety-guide.md | 0 .../managing-cluster-capacity/SKILL.md | 78 +++----- .../references/replacing-failed-nodes.md | 0 .../references/storage-management.md | 0 .../managing-cluster-settings/SKILL.md | 6 +- .../references/cloud-restricted-settings.md | 0 .../references/node-level-settings.md | 0 .../references/recommended-values.md | 0 .../references/safety-guide.md | 0 .../references/sql-queries.md | 0 .../performing-cluster-maintenance/SKILL.md | 67 ++++--- .../references/drain-details.md | 0 .../references/maintenance-prechecks.md | 0 .../references/safety-guide.md | 0 .../SKILL.md | 6 +- .../references/hardware-and-infrastructure.md | 0 .../production-deployment-checklist.md | 0 .../reviewing-cluster-health/SKILL.md | 172 +++++++----------- .../references/production-readiness.md | 0 .../upgrading-cluster-version/SKILL.md | 41 ++--- .../.gitkeep | 0 .../.gitkeep | 0 .../cockroachdb-sql/SKILL.md | 0 .../cockroachdb-sql/references/EXAMPLES.md | 0 .../00-fundamental-principles.md | 0 .../cockroachdb-rules/01-schema-design.md | 0 .../cockroachdb-rules/02-dml-operations.md | 0 .../cockroachdb-rules/03-query-patterns.md | 0 .../cockroachdb-rules/04-optimization.md | 0 .../cockroachdb-rules/05-operational.md | 0 .../.gitkeep | 0 .../.gitkeep | 0 .../auditing-cloud-cluster-security/SKILL.md | 18 +- .../references/ccloud-commands.md | 0 .../references/permissions.md | 0 .../references/sample-report.md | 0 .../references/sql-queries.md | 0 .../configuring-audit-logging/SKILL.md | 0 .../references/sql-queries.md | 0 .../configuring-ip-allowlists/SKILL.md | 0 .../references/ccloud-commands.md | 0 .../configuring-log-export/SKILL.md | 0 .../references/cloud-provider-setup.md | 0 .../configuring-private-connectivity/SKILL.md | 0 .../references/ccloud-commands.md | 0 .../references/cloud-provider-setup.md | 0 .../configuring-sso-and-scim/SKILL.md | 0 .../references/configuration-steps.md | 0 .../enabling-cmek-encryption/SKILL.md | 7 +- .../references/ccloud-commands.md | 0 .../enforcing-password-policies/SKILL.md | 45 +---- .../references/sql-queries.md | 0 .../hardening-user-privileges/SKILL.md | 28 ++- .../references/sql-queries.md | 0 .../managing-tls-certificates/SKILL.md | 0 .../references/connection-examples.md | 0 .../references/troubleshooting.md | 0 .../SKILL.md | 0 .../references/compliance-matrix.md | 0 submodules/cockroachdb-skills | 2 +- 104 files changed, 315 insertions(+), 393 deletions(-) rename skills/{application-development => cockroachdb-application-development}/benchmarking-transaction-patterns/SKILL.md (99%) rename skills/{application-development => cockroachdb-application-development}/designing-application-transactions/SKILL.md (97%) rename skills/{application-development => cockroachdb-application-development}/designing-application-transactions/references/monitoring-and-concurrency-testing.md (100%) rename skills/{application-development => cockroachdb-application-development}/designing-multi-region-applications/SKILL.md (93%) rename skills/{cost-and-usage-management => cockroachdb-cost-and-usage-management}/.gitkeep (100%) rename skills/{integrations-and-ecosystem => cockroachdb-integrations-and-ecosystem}/.gitkeep (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/.gitkeep (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/analyzing-range-distribution/SKILL.md (89%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/analyzing-range-distribution/references/permissions.md (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/analyzing-range-distribution/references/sql-queries.md (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/analyzing-schema-change-storage-risk/SKILL.md (92%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/analyzing-schema-change-storage-risk/references/permissions.md (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/auditing-table-statistics/SKILL.md (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/auditing-table-statistics/references/create-statistics-examples.md (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/auditing-table-statistics/references/statistics-thresholds.md (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/monitoring-background-jobs/SKILL.md (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/monitoring-background-jobs/references/job-states.md (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/monitoring-background-jobs/references/job-types.md (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/monitoring-background-jobs/references/permissions.md (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/monitoring-background-jobs/references/sql-query-variations.md (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/profiling-statement-fingerprints/SKILL.md (96%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/profiling-statement-fingerprints/references/json-field-reference.md (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/profiling-statement-fingerprints/references/metrics-and-units.md (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/profiling-statement-fingerprints/references/sql-query-variations.md (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/profiling-transaction-fingerprints/SKILL.md (97%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/profiling-transaction-fingerprints/references/json-field-reference.md (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/profiling-transaction-fingerprints/references/metrics-and-units.md (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/profiling-transaction-fingerprints/references/sql-query-variations.md (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/triaging-live-sql-activity/SKILL.md (99%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/triaging-live-sql-activity/references/permissions.md (100%) rename skills/{observability-and-diagnostics => cockroachdb-observability-and-diagnostics}/triaging-live-sql-activity/references/sql-queries.md (100%) rename skills/{onboarding-and-migrations => cockroachdb-onboarding-and-migrations}/.gitkeep (100%) rename skills/{onboarding-and-migrations => cockroachdb-onboarding-and-migrations}/molt-fetch/SKILL.md (90%) rename skills/{onboarding-and-migrations => cockroachdb-onboarding-and-migrations}/molt-fetch/references/flags.md (100%) rename skills/{onboarding-and-migrations => cockroachdb-onboarding-and-migrations}/molt-replicator/SKILL.md (92%) rename skills/{onboarding-and-migrations => cockroachdb-onboarding-and-migrations}/molt-replicator/references/flags.md (100%) rename skills/{onboarding-and-migrations => cockroachdb-onboarding-and-migrations}/molt-verify/SKILL.md (94%) rename skills/{onboarding-and-migrations => cockroachdb-onboarding-and-migrations}/molt-verify/references/flags.md (100%) rename skills/{onboarding-and-migrations => cockroachdb-onboarding-and-migrations}/setting-up-local-cluster/SKILL.md (80%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/managing-certificates-and-encryption/SKILL.md (95%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/managing-certificates-and-encryption/references/cmek-procedures.md (100%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/managing-certificates-and-encryption/references/kubernetes-certs.md (100%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/managing-certificates-and-encryption/references/rotation-procedures.md (100%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/managing-certificates-and-encryption/references/safety-guide.md (100%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/managing-cluster-capacity/SKILL.md (86%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/managing-cluster-capacity/references/replacing-failed-nodes.md (100%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/managing-cluster-capacity/references/storage-management.md (100%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/managing-cluster-settings/SKILL.md (97%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/managing-cluster-settings/references/cloud-restricted-settings.md (100%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/managing-cluster-settings/references/node-level-settings.md (100%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/managing-cluster-settings/references/recommended-values.md (100%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/managing-cluster-settings/references/safety-guide.md (100%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/managing-cluster-settings/references/sql-queries.md (100%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/performing-cluster-maintenance/SKILL.md (88%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/performing-cluster-maintenance/references/drain-details.md (100%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/performing-cluster-maintenance/references/maintenance-prechecks.md (100%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/performing-cluster-maintenance/references/safety-guide.md (100%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/provisioning-cluster-for-production/SKILL.md (98%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/provisioning-cluster-for-production/references/hardware-and-infrastructure.md (100%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/provisioning-cluster-for-production/references/production-deployment-checklist.md (100%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/reviewing-cluster-health/SKILL.md (66%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/reviewing-cluster-health/references/production-readiness.md (100%) rename skills/{operations-and-lifecycle => cockroachdb-operations-and-lifecycle}/upgrading-cluster-version/SKILL.md (91%) rename skills/{performance-and-scaling => cockroachdb-performance-and-scaling}/.gitkeep (100%) rename skills/{query-and-schema-design => cockroachdb-query-and-schema-design}/.gitkeep (100%) rename skills/{query-and-schema-design => cockroachdb-query-and-schema-design}/cockroachdb-sql/SKILL.md (100%) rename skills/{query-and-schema-design => cockroachdb-query-and-schema-design}/cockroachdb-sql/references/EXAMPLES.md (100%) rename skills/{query-and-schema-design => cockroachdb-query-and-schema-design}/cockroachdb-sql/references/cockroachdb-rules/00-fundamental-principles.md (100%) rename skills/{query-and-schema-design => cockroachdb-query-and-schema-design}/cockroachdb-sql/references/cockroachdb-rules/01-schema-design.md (100%) rename skills/{query-and-schema-design => cockroachdb-query-and-schema-design}/cockroachdb-sql/references/cockroachdb-rules/02-dml-operations.md (100%) rename skills/{query-and-schema-design => cockroachdb-query-and-schema-design}/cockroachdb-sql/references/cockroachdb-rules/03-query-patterns.md (100%) rename skills/{query-and-schema-design => cockroachdb-query-and-schema-design}/cockroachdb-sql/references/cockroachdb-rules/04-optimization.md (100%) rename skills/{query-and-schema-design => cockroachdb-query-and-schema-design}/cockroachdb-sql/references/cockroachdb-rules/05-operational.md (100%) rename skills/{resilience-and-disaster-recovery => cockroachdb-resilience-and-disaster-recovery}/.gitkeep (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/.gitkeep (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/auditing-cloud-cluster-security/SKILL.md (97%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/auditing-cloud-cluster-security/references/ccloud-commands.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/auditing-cloud-cluster-security/references/permissions.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/auditing-cloud-cluster-security/references/sample-report.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/auditing-cloud-cluster-security/references/sql-queries.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/configuring-audit-logging/SKILL.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/configuring-audit-logging/references/sql-queries.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/configuring-ip-allowlists/SKILL.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/configuring-ip-allowlists/references/ccloud-commands.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/configuring-log-export/SKILL.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/configuring-log-export/references/cloud-provider-setup.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/configuring-private-connectivity/SKILL.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/configuring-private-connectivity/references/ccloud-commands.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/configuring-private-connectivity/references/cloud-provider-setup.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/configuring-sso-and-scim/SKILL.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/configuring-sso-and-scim/references/configuration-steps.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/enabling-cmek-encryption/SKILL.md (97%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/enabling-cmek-encryption/references/ccloud-commands.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/enforcing-password-policies/SKILL.md (82%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/enforcing-password-policies/references/sql-queries.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/hardening-user-privileges/SKILL.md (83%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/hardening-user-privileges/references/sql-queries.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/managing-tls-certificates/SKILL.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/managing-tls-certificates/references/connection-examples.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/managing-tls-certificates/references/troubleshooting.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/preparing-compliance-documentation/SKILL.md (100%) rename skills/{security-and-governance => cockroachdb-security-and-governance}/preparing-compliance-documentation/references/compliance-matrix.md (100%) diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 3902514..160591e 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -22,38 +22,38 @@ "multi-region" ], "skills": [ - "./skills/application-development/benchmarking-transaction-patterns", - "./skills/application-development/designing-application-transactions", - "./skills/application-development/designing-multi-region-applications", - "./skills/observability-and-diagnostics/analyzing-range-distribution", - "./skills/observability-and-diagnostics/analyzing-schema-change-storage-risk", - "./skills/observability-and-diagnostics/auditing-table-statistics", - "./skills/observability-and-diagnostics/monitoring-background-jobs", - "./skills/observability-and-diagnostics/profiling-statement-fingerprints", - "./skills/observability-and-diagnostics/profiling-transaction-fingerprints", - "./skills/observability-and-diagnostics/triaging-live-sql-activity", - "./skills/onboarding-and-migrations/molt-fetch", - "./skills/onboarding-and-migrations/molt-replicator", - "./skills/onboarding-and-migrations/molt-verify", - "./skills/onboarding-and-migrations/setting-up-local-cluster", - "./skills/operations-and-lifecycle/managing-certificates-and-encryption", - "./skills/operations-and-lifecycle/managing-cluster-capacity", - "./skills/operations-and-lifecycle/managing-cluster-settings", - "./skills/operations-and-lifecycle/performing-cluster-maintenance", - "./skills/operations-and-lifecycle/provisioning-cluster-for-production", - "./skills/operations-and-lifecycle/reviewing-cluster-health", - "./skills/operations-and-lifecycle/upgrading-cluster-version", - "./skills/query-and-schema-design/cockroachdb-sql", - "./skills/security-and-governance/auditing-cloud-cluster-security", - "./skills/security-and-governance/configuring-audit-logging", - "./skills/security-and-governance/configuring-ip-allowlists", - "./skills/security-and-governance/configuring-log-export", - "./skills/security-and-governance/configuring-private-connectivity", - "./skills/security-and-governance/configuring-sso-and-scim", - "./skills/security-and-governance/enabling-cmek-encryption", - "./skills/security-and-governance/enforcing-password-policies", - "./skills/security-and-governance/hardening-user-privileges", - "./skills/security-and-governance/managing-tls-certificates", - "./skills/security-and-governance/preparing-compliance-documentation" + "./skills/cockroachdb-application-development/benchmarking-transaction-patterns", + "./skills/cockroachdb-application-development/designing-application-transactions", + "./skills/cockroachdb-application-development/designing-multi-region-applications", + "./skills/cockroachdb-observability-and-diagnostics/analyzing-range-distribution", + "./skills/cockroachdb-observability-and-diagnostics/analyzing-schema-change-storage-risk", + "./skills/cockroachdb-observability-and-diagnostics/auditing-table-statistics", + "./skills/cockroachdb-observability-and-diagnostics/monitoring-background-jobs", + "./skills/cockroachdb-observability-and-diagnostics/profiling-statement-fingerprints", + "./skills/cockroachdb-observability-and-diagnostics/profiling-transaction-fingerprints", + "./skills/cockroachdb-observability-and-diagnostics/triaging-live-sql-activity", + "./skills/cockroachdb-onboarding-and-migrations/molt-fetch", + "./skills/cockroachdb-onboarding-and-migrations/molt-replicator", + "./skills/cockroachdb-onboarding-and-migrations/molt-verify", + "./skills/cockroachdb-onboarding-and-migrations/setting-up-local-cluster", + "./skills/cockroachdb-operations-and-lifecycle/managing-certificates-and-encryption", + "./skills/cockroachdb-operations-and-lifecycle/managing-cluster-capacity", + "./skills/cockroachdb-operations-and-lifecycle/managing-cluster-settings", + "./skills/cockroachdb-operations-and-lifecycle/performing-cluster-maintenance", + "./skills/cockroachdb-operations-and-lifecycle/provisioning-cluster-for-production", + "./skills/cockroachdb-operations-and-lifecycle/reviewing-cluster-health", + "./skills/cockroachdb-operations-and-lifecycle/upgrading-cluster-version", + "./skills/cockroachdb-query-and-schema-design/cockroachdb-sql", + "./skills/cockroachdb-security-and-governance/auditing-cloud-cluster-security", + "./skills/cockroachdb-security-and-governance/configuring-audit-logging", + "./skills/cockroachdb-security-and-governance/configuring-ip-allowlists", + "./skills/cockroachdb-security-and-governance/configuring-log-export", + "./skills/cockroachdb-security-and-governance/configuring-private-connectivity", + "./skills/cockroachdb-security-and-governance/configuring-sso-and-scim", + "./skills/cockroachdb-security-and-governance/enabling-cmek-encryption", + "./skills/cockroachdb-security-and-governance/enforcing-password-policies", + "./skills/cockroachdb-security-and-governance/hardening-user-privileges", + "./skills/cockroachdb-security-and-governance/managing-tls-certificates", + "./skills/cockroachdb-security-and-governance/preparing-compliance-documentation" ] } diff --git a/skills/application-development/benchmarking-transaction-patterns/SKILL.md b/skills/cockroachdb-application-development/benchmarking-transaction-patterns/SKILL.md similarity index 99% rename from skills/application-development/benchmarking-transaction-patterns/SKILL.md rename to skills/cockroachdb-application-development/benchmarking-transaction-patterns/SKILL.md index a653f32..7a72189 100644 --- a/skills/application-development/benchmarking-transaction-patterns/SKILL.md +++ b/skills/cockroachdb-application-development/benchmarking-transaction-patterns/SKILL.md @@ -11,7 +11,7 @@ metadata: Guides users through benchmarking, explaining, and comparing two formulations of the same transactional business workflow in CockroachDB: explicit multi-statement transactions versus single-statement CTE transactions. Focuses on performance under contention, fair test methodology, and result interpretation. -**Complement to design skills:** For general transaction design principles, see [designing-application-transactions](../designing-application-transactions/SKILL.md). For SQL syntax and query patterns, see [cockroachdb-sql](../../query-and-schema-design/cockroachdb-sql/SKILL.md). +**Complement to design skills:** For general transaction design principles, see [designing-application-transactions](../designing-application-transactions/SKILL.md). For SQL syntax and query patterns, see [cockroachdb-sql](../../cockroachdb-query-and-schema-design/cockroachdb-sql/SKILL.md). ## Core Concept diff --git a/skills/application-development/designing-application-transactions/SKILL.md b/skills/cockroachdb-application-development/designing-application-transactions/SKILL.md similarity index 97% rename from skills/application-development/designing-application-transactions/SKILL.md rename to skills/cockroachdb-application-development/designing-application-transactions/SKILL.md index 3e9e11f..b0ed237 100644 --- a/skills/application-development/designing-application-transactions/SKILL.md +++ b/skills/cockroachdb-application-development/designing-application-transactions/SKILL.md @@ -11,7 +11,7 @@ metadata: Guides application developers through the design principles and implementation patterns needed to build correct, performant, and resilient applications on CockroachDB. Covers the full spectrum from transaction scoping and retry logic to connection pooling and observability. -**Complement to SQL skills:** For SQL syntax, schema design, and query optimization, see [cockroachdb-sql](../../query-and-schema-design/cockroachdb-sql/SKILL.md). For benchmarking transaction formulations under contention, see [benchmarking-transaction-patterns](../benchmarking-transaction-patterns/SKILL.md). +**Complement to SQL skills:** For SQL syntax, schema design, and query optimization, see [cockroachdb-sql](../../cockroachdb-query-and-schema-design/cockroachdb-sql/SKILL.md). For benchmarking transaction formulations under contention, see [benchmarking-transaction-patterns](../benchmarking-transaction-patterns/SKILL.md). ## When to Use This Skill @@ -292,16 +292,21 @@ WHERE u.id = incoming.id; ```sql DELETE FROM sessions WHERE expires_at < now() +ORDER BY expires_at LIMIT 10000; ``` +`ORDER BY` keeps the batch deterministic so successive runs make forward progress; without it, CockroachDB may pick a different subset each iteration. + **JDBC batching (Java):** Use `addBatch`/`executeBatch` instead of per-row `executeUpdate`. This sends all rows in a single network round trip rather than N individual round trips, eliminating idle time that can account for ~50% of transaction latency in chatty workloads. **Declarative TTL:** ```sql +-- created_at must be TIMESTAMPTZ; the expression's result type must also be TIMESTAMPTZ. +-- Cast if the source column is plain TIMESTAMP. ALTER TABLE events -SET (ttl_expiration_expression = 'created_at + INTERVAL ''7 DAY'''); +SET (ttl_expiration_expression = '(created_at + INTERVAL ''7 DAY'')::TIMESTAMPTZ'); ``` ### 8. Use Follower Reads for Non-Critical Queries diff --git a/skills/application-development/designing-application-transactions/references/monitoring-and-concurrency-testing.md b/skills/cockroachdb-application-development/designing-application-transactions/references/monitoring-and-concurrency-testing.md similarity index 100% rename from skills/application-development/designing-application-transactions/references/monitoring-and-concurrency-testing.md rename to skills/cockroachdb-application-development/designing-application-transactions/references/monitoring-and-concurrency-testing.md diff --git a/skills/application-development/designing-multi-region-applications/SKILL.md b/skills/cockroachdb-application-development/designing-multi-region-applications/SKILL.md similarity index 93% rename from skills/application-development/designing-multi-region-applications/SKILL.md rename to skills/cockroachdb-application-development/designing-multi-region-applications/SKILL.md index ddac074..b28072d 100644 --- a/skills/application-development/designing-multi-region-applications/SKILL.md +++ b/skills/cockroachdb-application-development/designing-multi-region-applications/SKILL.md @@ -11,7 +11,7 @@ metadata: Guides developers through selecting the right multi-region pattern for their CockroachDB application and implementing it with proper validation. Covers the decision model for choosing between regular regional tables, `REGIONAL BY ROW`, `GLOBAL` tables, and manual geo-partitioning, plus a hands-on demo framework for comparing approaches. -**Complement to other skills:** For transaction design patterns, see [designing-application-transactions](../designing-application-transactions/SKILL.md). For SQL syntax and schema design, see [cockroachdb-sql](../../query-and-schema-design/cockroachdb-sql/SKILL.md). +**Complement to other skills:** For transaction design patterns, see [designing-application-transactions](../designing-application-transactions/SKILL.md). For SQL syntax and schema design, see [cockroachdb-sql](../../cockroachdb-query-and-schema-design/cockroachdb-sql/SKILL.md). ## When to Use This Skill @@ -29,7 +29,13 @@ Guides developers through selecting the right multi-region pattern for their Coc ## Prerequisites - Understanding of CockroachDB range architecture and leaseholder concepts -- Multi-region cluster or `cockroach demo` with locality flags for testing +- A **multi-region cluster** with nodes started using `--locality=region=...,zone=...` matching the regions used in the examples below. Without matching localities the DDL errors with `region "..." does not exist` and constraints like `+region=...` match no nodes. Quickest path locally: + ```bash + # 9-node demo with three regions, three AZs each — note --no-example-database + cockroach demo --no-example-database --nodes=9 \ + --demo-locality=region=NA-NE,az=1:region=NA-NE,az=2:region=NA-NE,az=3:region=NA-MW,az=1:region=NA-MW,az=2:region=NA-MW,az=3:region=EU-DE,az=1:region=EU-DE,az=2:region=EU-DE,az=3 + ``` + For long-running clusters, see [setting-up-local-cluster](../../cockroachdb-onboarding-and-migrations/setting-up-local-cluster/SKILL.md) and add `--locality=region=...,zone=...` to each `cockroach start` invocation. - Knowledge of application write patterns (single-region vs multi-region) ## Pattern Selection diff --git a/skills/cost-and-usage-management/.gitkeep b/skills/cockroachdb-cost-and-usage-management/.gitkeep similarity index 100% rename from skills/cost-and-usage-management/.gitkeep rename to skills/cockroachdb-cost-and-usage-management/.gitkeep diff --git a/skills/integrations-and-ecosystem/.gitkeep b/skills/cockroachdb-integrations-and-ecosystem/.gitkeep similarity index 100% rename from skills/integrations-and-ecosystem/.gitkeep rename to skills/cockroachdb-integrations-and-ecosystem/.gitkeep diff --git a/skills/observability-and-diagnostics/.gitkeep b/skills/cockroachdb-observability-and-diagnostics/.gitkeep similarity index 100% rename from skills/observability-and-diagnostics/.gitkeep rename to skills/cockroachdb-observability-and-diagnostics/.gitkeep diff --git a/skills/observability-and-diagnostics/analyzing-range-distribution/SKILL.md b/skills/cockroachdb-observability-and-diagnostics/analyzing-range-distribution/SKILL.md similarity index 89% rename from skills/observability-and-diagnostics/analyzing-range-distribution/SKILL.md rename to skills/cockroachdb-observability-and-diagnostics/analyzing-range-distribution/SKILL.md index 9fce789..a00de62 100644 --- a/skills/observability-and-diagnostics/analyzing-range-distribution/SKILL.md +++ b/skills/cockroachdb-observability-and-diagnostics/analyzing-range-distribution/SKILL.md @@ -29,12 +29,12 @@ Analyzes CockroachDB range distribution, leaseholder placement, and zone configu - SQL connection to CockroachDB cluster - Admin role OR `ZONECONFIG` system privilege -- Understanding of CockroachDB range architecture (64MB default max size) +- Understanding of CockroachDB range architecture (default 512MB max size; verify with `SHOW ZONE CONFIGURATION FOR RANGE default`) - Knowledge of cluster topology (node IDs, regions, availability zones) **Check your privileges:** ```sql -SHOW GRANTS ON SYSTEM FOR current_user; -- Should show admin or ZONECONFIG +SHOW SYSTEM GRANTS FOR ; -- Should show admin or ZONECONFIG ``` See [permissions reference](references/permissions.md) for RBAC setup. @@ -43,11 +43,11 @@ See [permissions reference](references/permissions.md) for RBAC setup. ### Ranges: Units of Data Distribution -**Range:** Contiguous key space segment (default 64MB max size, configurable via zone config `range_max_bytes`) +**Range:** Contiguous key space segment (default 512MB max size, configurable via zone config `range_max_bytes`) **Raft group:** Each range replicated across nodes (default 3 replicas) **Leaseholder:** Single replica handling reads and coordinating writes for a range -**Critical:** Ranges split automatically at 64MB by default, but can fragment further due to load-based splitting during high write traffic. +**Critical:** Ranges split automatically at `range_max_bytes` (default 512MB), but can fragment further due to load-based splitting during high write traffic. ### Leaseholders and Hotspots @@ -61,7 +61,7 @@ See [permissions reference](references/permissions.md) for RBAC setup. **Causes:** High write throughput, sequential inserts (timestamp-based primary keys), load-based splitting **Symptoms:** High range count relative to data size, increased latency from Raft overhead -**Fragmentation metric:** Ranges per GB (healthy: 1-15, fragmented: 50+) +**Fragmentation metric:** Ranges per GB. With the 512MB default `range_max_bytes`, a fully-grown range covers 0.5 GB — so ~2 ranges/GB is the natural floor. Anything well above that (e.g., 10+ ranges/GB) suggests load-based splits or many small ranges; tune to your workload. ### Zone Configurations @@ -113,7 +113,7 @@ ORDER BY (span_stats->>'approximate_disk_bytes')::INT DESC LIMIT 50; ``` -**Interpretation:** Large ranges (>64MB) indicate split lag; many small ranges (<10MB) indicate fragmentation. +**Interpretation:** Ranges close to or above `range_max_bytes` (default 512MB) indicate split lag; many small ranges (<10MB) indicate fragmentation. **CRITICAL:** Always include `LIMIT` and target specific tables. Never run `SHOW RANGES WITH DETAILS` on entire database. @@ -239,7 +239,7 @@ ALTER TABLE hot_table CONFIGURE ZONE USING lease_preferences = '[[+region=us-wes **Steps:** 1. **Review intended configs:** Run Query 5 (SHOW ZONE CONFIGURATIONS) 2. **Check actual replica placement:** Run Query 4 on critical tables, inspect `replicas` array for node IDs -3. **Map node IDs to regions:** Cross-reference with `SHOW REGIONS` or `crdb_internal.gossip_nodes` +3. **Map node IDs to regions:** Use `SHOW REGIONS` (cluster-wide) or read the `locality` column of `cockroach node status` 4. **Identify mismatches:** Ranges not matching constraints indicate rebalancing in progress or misconfiguration **Example:** @@ -250,8 +250,10 @@ SHOW ZONE CONFIGURATION FOR TABLE multi_region_table; -- Check replica placement SELECT range_id, replicas FROM [SHOW RANGES FROM TABLE multi_region_table] LIMIT 20; --- Map node IDs to regions -SELECT node_id, locality FROM crdb_internal.gossip_nodes; +-- Map node IDs to regions (cluster-level view) +SHOW REGIONS; +-- For per-node locality strings, use the CLI: +-- cockroach node status --certs-dir= --host= ``` ### Workflow 3: Fragmentation Diagnosis @@ -264,7 +266,7 @@ SELECT node_id, locality FROM crdb_internal.gossip_nodes; 3. **Determine if expected:** Fragmentation may be intentional for load distribution 4. **Remediate if excessive:** Increase `range_max_bytes` (with caution - larger ranges = slower splits), or investigate reducing write hotspots -**CRITICAL:** Never increase `range_max_bytes` above 512MB without understanding impact on split/rebalance performance. +**CRITICAL:** `range_max_bytes` defaults to 512MB. Raising it further without understanding the impact on split/rebalance performance is risky. ## Safety Considerations @@ -320,10 +322,10 @@ See [permissions reference](references/permissions.md) for granting minimal priv - **DETAILS option:** Expensive operation - always use with LIMIT and targeted scope - **Fragmentation is sometimes intentional:** Load-based splitting improves concurrency - **Leaseholder concentration:** Check zone configs (lease_preferences) before assuming hotspot -- **Range size target:** Default 64MB max (not 512MB as in older versions) +- **Range size target:** Default `range_max_bytes` is 512MB (verify with `SHOW ZONE CONFIGURATION FOR RANGE default`) - **Replication lag:** Range placement may not immediately reflect zone config changes (rebalancing takes time) - **Cross-reference queries:** Combine range analysis with zone configs for complete picture -- **Node mapping:** Use `crdb_internal.gossip_nodes` to map node IDs to regions/zones +- **Node mapping:** Use `SHOW REGIONS` for cluster-level locality, or `cockroach node status` for per-node locality ## References diff --git a/skills/observability-and-diagnostics/analyzing-range-distribution/references/permissions.md b/skills/cockroachdb-observability-and-diagnostics/analyzing-range-distribution/references/permissions.md similarity index 100% rename from skills/observability-and-diagnostics/analyzing-range-distribution/references/permissions.md rename to skills/cockroachdb-observability-and-diagnostics/analyzing-range-distribution/references/permissions.md diff --git a/skills/observability-and-diagnostics/analyzing-range-distribution/references/sql-queries.md b/skills/cockroachdb-observability-and-diagnostics/analyzing-range-distribution/references/sql-queries.md similarity index 100% rename from skills/observability-and-diagnostics/analyzing-range-distribution/references/sql-queries.md rename to skills/cockroachdb-observability-and-diagnostics/analyzing-range-distribution/references/sql-queries.md diff --git a/skills/observability-and-diagnostics/analyzing-schema-change-storage-risk/SKILL.md b/skills/cockroachdb-observability-and-diagnostics/analyzing-schema-change-storage-risk/SKILL.md similarity index 92% rename from skills/observability-and-diagnostics/analyzing-schema-change-storage-risk/SKILL.md rename to skills/cockroachdb-observability-and-diagnostics/analyzing-schema-change-storage-risk/SKILL.md index feed1f2..ae0efdc 100644 --- a/skills/observability-and-diagnostics/analyzing-schema-change-storage-risk/SKILL.md +++ b/skills/cockroachdb-observability-and-diagnostics/analyzing-schema-change-storage-risk/SKILL.md @@ -76,14 +76,12 @@ foreground writes on the affected store may already be unhealthy. The minimum free space across stores is what bounds the schema change, not the total cluster free space (replicas are spread across nodes). -```sql -SELECT - node_id, - store_id, - ROUND((capacity - used) / 1073741824.0, 2) AS free_gb, - ROUND((used::FLOAT / capacity) * 100, 2) AS used_pct -FROM crdb_internal.kv_store_status -ORDER BY free_gb ASC; +No production-safe SQL view exposes per-store capacity. Use the DB Console +**Overview** → **Storage** page (sorts per-store usage), or scrape the +per-node Prometheus endpoint and look at the smallest `capacity_available`: + +```bash +curl -ks https://:8080/_status/vars | grep -E '^capacity( |_used|_available)' ``` ### Step 2 — Estimate the affected table/index size @@ -134,13 +132,16 @@ indexes, expand storage) before issuing the DDL. `InsufficientSpaceError`, free disk on the affected store and resume the paused schema change job. Check with: ```sql + WITH j AS (SHOW JOBS) SELECT job_id, status, error - FROM crdb_internal.jobs + FROM j WHERE job_type = 'SCHEMA CHANGE' AND status = 'paused'; ``` - **Drop unused indexes first.** Often the cheapest way to free headroom before a large backfill is to drop indexes that - `crdb_internal.index_usage_statistics` shows are unused. + `crdb_internal.index_usage_statistics` shows are unused (this is one of the + 12 production-safe `crdb_internal` views, per the + [docs](https://www.cockroachlabs.com/docs/stable/crdb-internal)). - **Statistics lag.** `range_size_mb` is approximate and can lag actual disk usage; treat estimates as conservative ballparks, not exact figures. diff --git a/skills/observability-and-diagnostics/analyzing-schema-change-storage-risk/references/permissions.md b/skills/cockroachdb-observability-and-diagnostics/analyzing-schema-change-storage-risk/references/permissions.md similarity index 100% rename from skills/observability-and-diagnostics/analyzing-schema-change-storage-risk/references/permissions.md rename to skills/cockroachdb-observability-and-diagnostics/analyzing-schema-change-storage-risk/references/permissions.md diff --git a/skills/observability-and-diagnostics/auditing-table-statistics/SKILL.md b/skills/cockroachdb-observability-and-diagnostics/auditing-table-statistics/SKILL.md similarity index 100% rename from skills/observability-and-diagnostics/auditing-table-statistics/SKILL.md rename to skills/cockroachdb-observability-and-diagnostics/auditing-table-statistics/SKILL.md diff --git a/skills/observability-and-diagnostics/auditing-table-statistics/references/create-statistics-examples.md b/skills/cockroachdb-observability-and-diagnostics/auditing-table-statistics/references/create-statistics-examples.md similarity index 100% rename from skills/observability-and-diagnostics/auditing-table-statistics/references/create-statistics-examples.md rename to skills/cockroachdb-observability-and-diagnostics/auditing-table-statistics/references/create-statistics-examples.md diff --git a/skills/observability-and-diagnostics/auditing-table-statistics/references/statistics-thresholds.md b/skills/cockroachdb-observability-and-diagnostics/auditing-table-statistics/references/statistics-thresholds.md similarity index 100% rename from skills/observability-and-diagnostics/auditing-table-statistics/references/statistics-thresholds.md rename to skills/cockroachdb-observability-and-diagnostics/auditing-table-statistics/references/statistics-thresholds.md diff --git a/skills/observability-and-diagnostics/monitoring-background-jobs/SKILL.md b/skills/cockroachdb-observability-and-diagnostics/monitoring-background-jobs/SKILL.md similarity index 100% rename from skills/observability-and-diagnostics/monitoring-background-jobs/SKILL.md rename to skills/cockroachdb-observability-and-diagnostics/monitoring-background-jobs/SKILL.md diff --git a/skills/observability-and-diagnostics/monitoring-background-jobs/references/job-states.md b/skills/cockroachdb-observability-and-diagnostics/monitoring-background-jobs/references/job-states.md similarity index 100% rename from skills/observability-and-diagnostics/monitoring-background-jobs/references/job-states.md rename to skills/cockroachdb-observability-and-diagnostics/monitoring-background-jobs/references/job-states.md diff --git a/skills/observability-and-diagnostics/monitoring-background-jobs/references/job-types.md b/skills/cockroachdb-observability-and-diagnostics/monitoring-background-jobs/references/job-types.md similarity index 100% rename from skills/observability-and-diagnostics/monitoring-background-jobs/references/job-types.md rename to skills/cockroachdb-observability-and-diagnostics/monitoring-background-jobs/references/job-types.md diff --git a/skills/observability-and-diagnostics/monitoring-background-jobs/references/permissions.md b/skills/cockroachdb-observability-and-diagnostics/monitoring-background-jobs/references/permissions.md similarity index 100% rename from skills/observability-and-diagnostics/monitoring-background-jobs/references/permissions.md rename to skills/cockroachdb-observability-and-diagnostics/monitoring-background-jobs/references/permissions.md diff --git a/skills/observability-and-diagnostics/monitoring-background-jobs/references/sql-query-variations.md b/skills/cockroachdb-observability-and-diagnostics/monitoring-background-jobs/references/sql-query-variations.md similarity index 100% rename from skills/observability-and-diagnostics/monitoring-background-jobs/references/sql-query-variations.md rename to skills/cockroachdb-observability-and-diagnostics/monitoring-background-jobs/references/sql-query-variations.md diff --git a/skills/observability-and-diagnostics/profiling-statement-fingerprints/SKILL.md b/skills/cockroachdb-observability-and-diagnostics/profiling-statement-fingerprints/SKILL.md similarity index 96% rename from skills/observability-and-diagnostics/profiling-statement-fingerprints/SKILL.md rename to skills/cockroachdb-observability-and-diagnostics/profiling-statement-fingerprints/SKILL.md index 5c93848..9c55541 100644 --- a/skills/observability-and-diagnostics/profiling-statement-fingerprints/SKILL.md +++ b/skills/cockroachdb-observability-and-diagnostics/profiling-statement-fingerprints/SKILL.md @@ -52,7 +52,7 @@ See [triaging-live-sql-activity permissions reference](../triaging-live-sql-acti ### Time-Series Bucketing **aggregated_ts:** Hourly UTC buckets (e.g., `2026-02-21 14:00:00` = 14:00-14:59 executions) -**Data retention:** Default ~7 days (check `sql.stats.persisted_rows.max`) +**Data retention:** Capped by row count, not time. `sql.stats.persisted_rows.max` (default 1,000,000) bounds the persisted statement+transaction rows; older buckets are compacted once the cap is reached. Effective wall-clock window depends on workload diversity. **Best practice:** Always filter by time window: `WHERE aggregated_ts > now() - INTERVAL '24 hours'` ### Aggregated vs Sampled Metrics @@ -60,7 +60,7 @@ See [triaging-live-sql-activity permissions reference](../triaging-live-sql-acti | Metric Category | JSON Path | Scope | Use Case | |-----------------|-----------|-------|----------| | **Aggregated** | `statistics.statistics.*` | All executions | Latency, row counts, execution counts | -| **Sampled** | `statistics.execution_statistics.*` | ~10% sample | CPU, contention, admission wait, memory/disk | +| **Sampled** | `statistics.execution_statistics.*` | Probabilistic sample governed by `sql.txn_stats.sample_rate` (default 0.01) | CPU, contention, admission wait, memory/disk | **Critical:** Always check sampled metrics presence: `WHERE (statistics->'execution_statistics'->>'cnt') IS NOT NULL` @@ -307,7 +307,7 @@ LIMIT 20; - **Privacy:** Use VIEWACTIVITYREDACTED in production - **Performance:** Always include time filters and LIMIT - **Complement to live triage:** Use together for complete coverage (historical + real-time) -- **Data retention:** Default ~7 days; verify with `sql.stats.persisted_rows.max` +- **Data retention:** Bounded by the row-count cap `sql.stats.persisted_rows.max` (default 1,000,000), not a TTL; effective time window varies with workload diversity - **Plan instability:** Multiple plan hashes indicate optimizer/schema changes ## References diff --git a/skills/observability-and-diagnostics/profiling-statement-fingerprints/references/json-field-reference.md b/skills/cockroachdb-observability-and-diagnostics/profiling-statement-fingerprints/references/json-field-reference.md similarity index 100% rename from skills/observability-and-diagnostics/profiling-statement-fingerprints/references/json-field-reference.md rename to skills/cockroachdb-observability-and-diagnostics/profiling-statement-fingerprints/references/json-field-reference.md diff --git a/skills/observability-and-diagnostics/profiling-statement-fingerprints/references/metrics-and-units.md b/skills/cockroachdb-observability-and-diagnostics/profiling-statement-fingerprints/references/metrics-and-units.md similarity index 100% rename from skills/observability-and-diagnostics/profiling-statement-fingerprints/references/metrics-and-units.md rename to skills/cockroachdb-observability-and-diagnostics/profiling-statement-fingerprints/references/metrics-and-units.md diff --git a/skills/observability-and-diagnostics/profiling-statement-fingerprints/references/sql-query-variations.md b/skills/cockroachdb-observability-and-diagnostics/profiling-statement-fingerprints/references/sql-query-variations.md similarity index 100% rename from skills/observability-and-diagnostics/profiling-statement-fingerprints/references/sql-query-variations.md rename to skills/cockroachdb-observability-and-diagnostics/profiling-statement-fingerprints/references/sql-query-variations.md diff --git a/skills/observability-and-diagnostics/profiling-transaction-fingerprints/SKILL.md b/skills/cockroachdb-observability-and-diagnostics/profiling-transaction-fingerprints/SKILL.md similarity index 97% rename from skills/observability-and-diagnostics/profiling-transaction-fingerprints/SKILL.md rename to skills/cockroachdb-observability-and-diagnostics/profiling-transaction-fingerprints/SKILL.md index 0fcc47a..0c4b5b6 100644 --- a/skills/observability-and-diagnostics/profiling-transaction-fingerprints/SKILL.md +++ b/skills/cockroachdb-observability-and-diagnostics/profiling-transaction-fingerprints/SKILL.md @@ -57,7 +57,7 @@ See [triaging-live-sql-activity permissions reference](../triaging-live-sql-acti ### Time-Series Bucketing **aggregated_ts:** Hourly UTC buckets (e.g., `2026-02-21 14:00:00` = 14:00-14:59 executions) -**Data retention:** Default ~7 days (check `sql.stats.persisted_rows.max`) +**Data retention:** Capped by row count, not time. `sql.stats.persisted_rows.max` (default 1,000,000) bounds the persisted statement+transaction rows; older buckets are compacted once the cap is reached. Effective wall-clock window depends on workload diversity. **Best practice:** Always filter by time window: `WHERE aggregated_ts > now() - INTERVAL '24 hours'` ### Aggregated vs Sampled Metrics @@ -65,7 +65,7 @@ See [triaging-live-sql-activity permissions reference](../triaging-live-sql-acti | Metric Category | JSON Path | Scope | Use Case | |-----------------|-----------|-------|----------| | **Aggregated** | `statistics.statistics.*` | All executions | Retries, commit latency, execution counts | -| **Sampled** | `statistics.execution_statistics.*` | Probabilistic sample (~10%) | Contention, network, memory/disk | +| **Sampled** | `statistics.execution_statistics.*` | Probabilistic sample governed by `sql.txn_stats.sample_rate` (default 0.01) | Contention, network, memory/disk | **Critical:** Sampled metrics have `cnt` field showing sample size. Always check: ```sql @@ -371,7 +371,7 @@ All queries are `SELECT` statements against `crdb_internal.transaction_statistic - **Performance:** Always include time filters and LIMIT clauses - **Complement to statement profiling:** Use together for complete coverage (transaction + statement) - **Complement to live triage:** Historical patterns vs real-time (use both) -- **Data retention:** Default ~7 days; verify with `sql.stats.persisted_rows.max` +- **Data retention:** Bounded by the row-count cap `sql.stats.persisted_rows.max` (default 1,000,000), not a TTL; effective time window varies with workload diversity - **Retry semantics:** `maxRetries` is maximum across all executions in bucket, not average - **Fingerprint encoding:** Use `encode(fingerprint_id, 'hex')` for human-readable IDs diff --git a/skills/observability-and-diagnostics/profiling-transaction-fingerprints/references/json-field-reference.md b/skills/cockroachdb-observability-and-diagnostics/profiling-transaction-fingerprints/references/json-field-reference.md similarity index 100% rename from skills/observability-and-diagnostics/profiling-transaction-fingerprints/references/json-field-reference.md rename to skills/cockroachdb-observability-and-diagnostics/profiling-transaction-fingerprints/references/json-field-reference.md diff --git a/skills/observability-and-diagnostics/profiling-transaction-fingerprints/references/metrics-and-units.md b/skills/cockroachdb-observability-and-diagnostics/profiling-transaction-fingerprints/references/metrics-and-units.md similarity index 100% rename from skills/observability-and-diagnostics/profiling-transaction-fingerprints/references/metrics-and-units.md rename to skills/cockroachdb-observability-and-diagnostics/profiling-transaction-fingerprints/references/metrics-and-units.md diff --git a/skills/observability-and-diagnostics/profiling-transaction-fingerprints/references/sql-query-variations.md b/skills/cockroachdb-observability-and-diagnostics/profiling-transaction-fingerprints/references/sql-query-variations.md similarity index 100% rename from skills/observability-and-diagnostics/profiling-transaction-fingerprints/references/sql-query-variations.md rename to skills/cockroachdb-observability-and-diagnostics/profiling-transaction-fingerprints/references/sql-query-variations.md diff --git a/skills/observability-and-diagnostics/triaging-live-sql-activity/SKILL.md b/skills/cockroachdb-observability-and-diagnostics/triaging-live-sql-activity/SKILL.md similarity index 99% rename from skills/observability-and-diagnostics/triaging-live-sql-activity/SKILL.md rename to skills/cockroachdb-observability-and-diagnostics/triaging-live-sql-activity/SKILL.md index 540a308..9af9fb0 100644 --- a/skills/observability-and-diagnostics/triaging-live-sql-activity/SKILL.md +++ b/skills/cockroachdb-observability-and-diagnostics/triaging-live-sql-activity/SKILL.md @@ -37,7 +37,7 @@ Diagnoses live cluster performance issues by identifying currently active long-r **Check your privileges:** ```sql -SHOW GRANTS ON ROLE ; +SHOW SYSTEM GRANTS FOR ; ``` See [permissions reference](references/permissions.md) for detailed RBAC setup. diff --git a/skills/observability-and-diagnostics/triaging-live-sql-activity/references/permissions.md b/skills/cockroachdb-observability-and-diagnostics/triaging-live-sql-activity/references/permissions.md similarity index 100% rename from skills/observability-and-diagnostics/triaging-live-sql-activity/references/permissions.md rename to skills/cockroachdb-observability-and-diagnostics/triaging-live-sql-activity/references/permissions.md diff --git a/skills/observability-and-diagnostics/triaging-live-sql-activity/references/sql-queries.md b/skills/cockroachdb-observability-and-diagnostics/triaging-live-sql-activity/references/sql-queries.md similarity index 100% rename from skills/observability-and-diagnostics/triaging-live-sql-activity/references/sql-queries.md rename to skills/cockroachdb-observability-and-diagnostics/triaging-live-sql-activity/references/sql-queries.md diff --git a/skills/onboarding-and-migrations/.gitkeep b/skills/cockroachdb-onboarding-and-migrations/.gitkeep similarity index 100% rename from skills/onboarding-and-migrations/.gitkeep rename to skills/cockroachdb-onboarding-and-migrations/.gitkeep diff --git a/skills/onboarding-and-migrations/molt-fetch/SKILL.md b/skills/cockroachdb-onboarding-and-migrations/molt-fetch/SKILL.md similarity index 90% rename from skills/onboarding-and-migrations/molt-fetch/SKILL.md rename to skills/cockroachdb-onboarding-and-migrations/molt-fetch/SKILL.md index 32c767f..988bc69 100644 --- a/skills/onboarding-and-migrations/molt-fetch/SKILL.md +++ b/skills/cockroachdb-onboarding-and-migrations/molt-fetch/SKILL.md @@ -83,13 +83,7 @@ molt fetch --source "..." --target "..." --direct-copy --use-copy ## Common Workflows -### 1. Validate before migrating -```bash -molt fetch --dry-run --source "..." --target "..." --bucket-path "s3://..." -# Exports 1 row, imports, verifies, cleans up. Returns immediately. -``` - -### 2. Full migration with schema creation +### 1. Full migration with schema creation ```bash molt fetch \ --source "postgresql://user:pass@pg:5432/db" \ @@ -100,7 +94,7 @@ molt fetch \ --log-file migration.log ``` -### 3. Resume after failure +### 2. Resume after failure ```bash # List available continuation tokens molt fetch tokens --fetch-id "abc-123" --target "postgresql://root@crdb:26257/db" @@ -113,12 +107,6 @@ molt fetch \ --non-interactive ``` -### 4. Validate flag syntax without connecting -```bash -molt fetch --compile-only --source "..." --target "..." --bucket-path "..." -# Returns JSON: {"status":"ok","message":"arguments parsed successfully"} -``` - ## Error Recovery | Error | Cause | Fix | diff --git a/skills/onboarding-and-migrations/molt-fetch/references/flags.md b/skills/cockroachdb-onboarding-and-migrations/molt-fetch/references/flags.md similarity index 100% rename from skills/onboarding-and-migrations/molt-fetch/references/flags.md rename to skills/cockroachdb-onboarding-and-migrations/molt-fetch/references/flags.md diff --git a/skills/onboarding-and-migrations/molt-replicator/SKILL.md b/skills/cockroachdb-onboarding-and-migrations/molt-replicator/SKILL.md similarity index 92% rename from skills/onboarding-and-migrations/molt-replicator/SKILL.md rename to skills/cockroachdb-onboarding-and-migrations/molt-replicator/SKILL.md index 88b321d..11355b9 100644 --- a/skills/onboarding-and-migrations/molt-replicator/SKILL.md +++ b/skills/cockroachdb-onboarding-and-migrations/molt-replicator/SKILL.md @@ -66,8 +66,10 @@ CREATE DATABASE _replicator; ### Step 4: Test connectivity ```bash +# preflight only takes --stagingConn and --targetConn (always required for the +# target; stagingConn required if the target is not CRDB) replicator preflight \ - --sourceConn "postgresql://user:pass@source:5432/db" \ + --stagingConn "postgresql://root@crdb:26257/_replicator" \ --targetConn "postgresql://root@crdb:26257/db" ``` @@ -190,7 +192,7 @@ replicator oraclelogminer \ ## Gotchas - Staging schema (`_replicator.public`) is auto-created by replicator, but the **database** (`_replicator`) must exist first -- `--publicationName` and `--slotName` must match what `molt fetch` created (default: `molt_fetch` / `molt_slot`) +- `--publicationName` and `--slotName` must match what `molt fetch` created. `molt fetch`'s `--pglogical-publication-name` defaults to `molt_fetch` and its `--pglogical-replication-slot-name` has no default; on the replicator side, `--publicationName` has no default and `--slotName` defaults to `replicator`. If the names don't line up, set both explicitly on both sides. - DLQ table grows over time — monitor and purge failed rows periodically - Replicator holds an open replication slot on the source — this blocks WAL cleanup; monitor source disk usage - Graceful shutdown respects `--gracePeriod` (default: 30s); don't SIGKILL without it diff --git a/skills/onboarding-and-migrations/molt-replicator/references/flags.md b/skills/cockroachdb-onboarding-and-migrations/molt-replicator/references/flags.md similarity index 100% rename from skills/onboarding-and-migrations/molt-replicator/references/flags.md rename to skills/cockroachdb-onboarding-and-migrations/molt-replicator/references/flags.md diff --git a/skills/onboarding-and-migrations/molt-verify/SKILL.md b/skills/cockroachdb-onboarding-and-migrations/molt-verify/SKILL.md similarity index 94% rename from skills/onboarding-and-migrations/molt-verify/SKILL.md rename to skills/cockroachdb-onboarding-and-migrations/molt-verify/SKILL.md index fb23d8a..4e4f1f9 100644 --- a/skills/onboarding-and-migrations/molt-verify/SKILL.md +++ b/skills/cockroachdb-onboarding-and-migrations/molt-verify/SKILL.md @@ -32,7 +32,6 @@ molt verify \ |------|---------|----------| | Full (default) | `molt verify --source "..." --target "..."` | Post-migration integrity check | | Schema-only | `molt verify ... --rows=false` | Fast DDL check; no data I/O | -| Compile-only | `molt verify ... --compile-only` | Validate flag syntax without connecting | ## Concurrency & Sharding @@ -82,12 +81,6 @@ molt verify \ --transformations-file transformations.json ``` -### 5. Validate flags without connecting -```bash -molt verify --source "..." --target "..." --compile-only -# Returns: {"status":"ok","message":"arguments parsed successfully"} -``` - ## Source-Specific Prerequisites **PostgreSQL**: No special requirements. Partition tables (child partitions) are not supported — remove them before verifying. @@ -109,7 +102,7 @@ truth rows seen: 10000, success: 9950, missing: 5, mismatch: 45, extraneous: 0 Schema issues (missing/extra tables or columns, type mismatches, PK differences) are logged as warnings and do not stop row verification. -Prometheus metrics available at `--metrics-listen-addr` (default `localhost:8888`). +Prometheus metrics available at `--metrics-listen-addr` (default `127.0.0.1:3030`). ## Error Recovery diff --git a/skills/onboarding-and-migrations/molt-verify/references/flags.md b/skills/cockroachdb-onboarding-and-migrations/molt-verify/references/flags.md similarity index 100% rename from skills/onboarding-and-migrations/molt-verify/references/flags.md rename to skills/cockroachdb-onboarding-and-migrations/molt-verify/references/flags.md diff --git a/skills/onboarding-and-migrations/setting-up-local-cluster/SKILL.md b/skills/cockroachdb-onboarding-and-migrations/setting-up-local-cluster/SKILL.md similarity index 80% rename from skills/onboarding-and-migrations/setting-up-local-cluster/SKILL.md rename to skills/cockroachdb-onboarding-and-migrations/setting-up-local-cluster/SKILL.md index 5d353db..4465e11 100644 --- a/skills/onboarding-and-migrations/setting-up-local-cluster/SKILL.md +++ b/skills/cockroachdb-onboarding-and-migrations/setting-up-local-cluster/SKILL.md @@ -58,20 +58,25 @@ A 3-node cluster is recommended for development because it exercises replication ### 3-Node Cluster (Recommended) ```bash -# Start 3 nodes with separate SQL, RPC, and HTTP ports +# Start 3 nodes with separate SQL, RPC, and HTTP ports. +# Use $HOME instead of ~ in --store / --log-dir / --pid-file: tilde does not +# expand inside --flag=~/... in bash or zsh. cockroach start --insecure --listen-addr=localhost:26357 --sql-addr=localhost:26257 \ - --http-addr=localhost:8080 --store=~/.cockroachdb/data/node1 \ - --log-dir=~/.cockroachdb/logs/node1 \ + --http-addr=localhost:8080 --store=$HOME/.cockroachdb/data/node1 \ + --log-dir=$HOME/.cockroachdb/logs/node1 \ + --pid-file=$HOME/.cockroachdb/data/node1/cockroach.pid \ --join=localhost:26357,localhost:26358,localhost:26359 --background cockroach start --insecure --listen-addr=localhost:26358 --sql-addr=localhost:26258 \ - --http-addr=localhost:8081 --store=~/.cockroachdb/data/node2 \ - --log-dir=~/.cockroachdb/logs/node2 \ + --http-addr=localhost:8081 --store=$HOME/.cockroachdb/data/node2 \ + --log-dir=$HOME/.cockroachdb/logs/node2 \ + --pid-file=$HOME/.cockroachdb/data/node2/cockroach.pid \ --join=localhost:26357,localhost:26358,localhost:26359 --background cockroach start --insecure --listen-addr=localhost:26359 --sql-addr=localhost:26259 \ - --http-addr=localhost:8082 --store=~/.cockroachdb/data/node3 \ - --log-dir=~/.cockroachdb/logs/node3 \ + --http-addr=localhost:8082 --store=$HOME/.cockroachdb/data/node3 \ + --log-dir=$HOME/.cockroachdb/logs/node3 \ + --pid-file=$HOME/.cockroachdb/data/node3/cockroach.pid \ --join=localhost:26357,localhost:26358,localhost:26359 --background # Initialize the cluster (only needed on first start) @@ -84,8 +89,9 @@ For minimal resource usage when full cluster capabilities are not needed: ```bash cockroach start-single-node --insecure --listen-addr=localhost:26257 \ - --http-addr=localhost:8080 --store=~/.cockroachdb/data/node1 \ - --log-dir=~/.cockroachdb/logs/node1 --background + --http-addr=localhost:8080 --store=$HOME/.cockroachdb/data/node1 \ + --log-dir=$HOME/.cockroachdb/logs/node1 \ + --pid-file=$HOME/.cockroachdb/data/node1/cockroach.pid --background ``` ## Step 3: Verify the Cluster @@ -95,12 +101,11 @@ cockroach start-single-node --insecure --listen-addr=localhost:26257 \ cockroach sql --insecure --host=localhost:26257 -e "SELECT version();" # Verify all nodes joined (3-node cluster) -cockroach sql --insecure --host=localhost:26257 \ - -e "SELECT node_id, address, is_live FROM crdb_internal.gossip_nodes;" +cockroach node status --insecure --host=localhost:26257 -# Check replication (should show num_replicas=3) +# Check replication factor (should show num_replicas = 3) cockroach sql --insecure --host=localhost:26257 \ - -e "SHOW RANGES FROM DATABASE defaultdb;" + -e "SHOW ZONE CONFIGURATION FOR RANGE default;" ``` ## Connection Details @@ -127,15 +132,15 @@ export COCKROACHDB_SSLMODE=disable ```bash # Graceful shutdown via PID files -kill $(cat ~/.cockroachdb/data/node1/cockroach.pid) 2>/dev/null -kill $(cat ~/.cockroachdb/data/node2/cockroach.pid) 2>/dev/null -kill $(cat ~/.cockroachdb/data/node3/cockroach.pid) 2>/dev/null +kill $(cat $HOME/.cockroachdb/data/node1/cockroach.pid) 2>/dev/null +kill $(cat $HOME/.cockroachdb/data/node2/cockroach.pid) 2>/dev/null +kill $(cat $HOME/.cockroachdb/data/node3/cockroach.pid) 2>/dev/null ``` ## Destroying All Data ```bash -rm -rf ~/.cockroachdb/data ~/.cockroachdb/logs +rm -rf $HOME/.cockroachdb/data $HOME/.cockroachdb/logs ``` ## Air-Gapped / Restricted Environments @@ -162,7 +167,7 @@ For environments without internet access: ## Safety Considerations - The cluster runs in **insecure mode** (no TLS, no authentication) -- suitable for local development only. -- Data persists in `~/.cockroachdb/data` across restarts. +- Data persists in `$HOME/.cockroachdb/data` across restarts. - The binary and data are user-local (`~/.cockroachdb/`) -- no `sudo` or system modifications. - A 3-node cluster uses approximately 750 MB of RAM total. diff --git a/skills/operations-and-lifecycle/managing-certificates-and-encryption/SKILL.md b/skills/cockroachdb-operations-and-lifecycle/managing-certificates-and-encryption/SKILL.md similarity index 95% rename from skills/operations-and-lifecycle/managing-certificates-and-encryption/SKILL.md rename to skills/cockroachdb-operations-and-lifecycle/managing-certificates-and-encryption/SKILL.md index 91593ba..baa3d0f 100644 --- a/skills/operations-and-lifecycle/managing-certificates-and-encryption/SKILL.md +++ b/skills/cockroachdb-operations-and-lifecycle/managing-certificates-and-encryption/SKILL.md @@ -72,13 +72,17 @@ Manages TLS certificate and encryption key lifecycle across all deployment tiers ### Monitor Certificate Expiry -```sql -SELECT node_id, - to_timestamp((metrics->>'security.certificate.expiration.ca')::FLOAT)::TIMESTAMPTZ AS ca_expires, - to_timestamp((metrics->>'security.certificate.expiration.node')::FLOAT)::TIMESTAMPTZ AS node_cert_expires, - CASE WHEN to_timestamp((metrics->>'security.certificate.expiration.node')::FLOAT)::TIMESTAMPTZ - < now() + INTERVAL '90 days' THEN 'EXPIRING_SOON' ELSE 'OK' END AS status -FROM crdb_internal.kv_node_status ORDER BY node_cert_expires; +No production-safe SQL view exposes certificate expiration. Use one of: + +```bash +# Inspect certs locally on each node +cockroach cert list --certs-dir= + +# Or read a specific cert file +openssl x509 -in /node.crt -noout -enddate + +# Or scrape the per-node Prometheus endpoint (UNIX seconds for ca, node, client_ca, ui_ca) +curl -ks https://:8080/_status/vars | grep '^security_certificate_expiration_' ``` Alert thresholds: CA < 1 year = plan rotation. Node < 90 days = schedule rotation. Node < 30 days = rotate immediately. diff --git a/skills/operations-and-lifecycle/managing-certificates-and-encryption/references/cmek-procedures.md b/skills/cockroachdb-operations-and-lifecycle/managing-certificates-and-encryption/references/cmek-procedures.md similarity index 100% rename from skills/operations-and-lifecycle/managing-certificates-and-encryption/references/cmek-procedures.md rename to skills/cockroachdb-operations-and-lifecycle/managing-certificates-and-encryption/references/cmek-procedures.md diff --git a/skills/operations-and-lifecycle/managing-certificates-and-encryption/references/kubernetes-certs.md b/skills/cockroachdb-operations-and-lifecycle/managing-certificates-and-encryption/references/kubernetes-certs.md similarity index 100% rename from skills/operations-and-lifecycle/managing-certificates-and-encryption/references/kubernetes-certs.md rename to skills/cockroachdb-operations-and-lifecycle/managing-certificates-and-encryption/references/kubernetes-certs.md diff --git a/skills/operations-and-lifecycle/managing-certificates-and-encryption/references/rotation-procedures.md b/skills/cockroachdb-operations-and-lifecycle/managing-certificates-and-encryption/references/rotation-procedures.md similarity index 100% rename from skills/operations-and-lifecycle/managing-certificates-and-encryption/references/rotation-procedures.md rename to skills/cockroachdb-operations-and-lifecycle/managing-certificates-and-encryption/references/rotation-procedures.md diff --git a/skills/operations-and-lifecycle/managing-certificates-and-encryption/references/safety-guide.md b/skills/cockroachdb-operations-and-lifecycle/managing-certificates-and-encryption/references/safety-guide.md similarity index 100% rename from skills/operations-and-lifecycle/managing-certificates-and-encryption/references/safety-guide.md rename to skills/cockroachdb-operations-and-lifecycle/managing-certificates-and-encryption/references/safety-guide.md diff --git a/skills/operations-and-lifecycle/managing-cluster-capacity/SKILL.md b/skills/cockroachdb-operations-and-lifecycle/managing-cluster-capacity/SKILL.md similarity index 86% rename from skills/operations-and-lifecycle/managing-cluster-capacity/SKILL.md rename to skills/cockroachdb-operations-and-lifecycle/managing-cluster-capacity/SKILL.md index 2be52a9..c5aa9b8 100644 --- a/skills/operations-and-lifecycle/managing-cluster-capacity/SKILL.md +++ b/skills/cockroachdb-operations-and-lifecycle/managing-cluster-capacity/SKILL.md @@ -87,29 +87,27 @@ Manages cluster capacity across all CockroachDB deployment tiers. What "capacity #### Pre-Decommission Validation +```bash +# All nodes live, version-consistent, with replication and per-node range counts +cockroach node status --decommission --certs-dir= --host= +``` + +Inspect the output for: +- `is_live = true` for every node +- `ranges_underreplicated` is `0` everywhere (all ranges fully replicated) + ```sql --- All nodes live -SELECT n.node_id, n.is_live, n.build_tag -FROM crdb_internal.gossip_nodes n -JOIN crdb_internal.gossip_liveness l USING (node_id) ORDER BY n.node_id; - --- Ranges fully replicated -SELECT CASE WHEN array_length(replicas, 1) >= 3 THEN 'fully_replicated' - ELSE 'under_replicated' END AS status, COUNT(*) -FROM crdb_internal.ranges_no_leases GROUP BY 1; - --- Remaining capacity check -SELECT node_id, store_id, - ROUND(capacity / 1073741824.0, 2) AS total_gb, - ROUND(available / 1073741824.0, 2) AS available_gb, - ROUND((1 - available::FLOAT / capacity::FLOAT) * 100, 2) AS utilization_pct -FROM crdb_internal.kv_store_status ORDER BY node_id; - --- Replication factor +-- Replication factor (and other zone-level settings) SHOW ZONE CONFIGURATION FOR RANGE default; ``` -Remaining nodes must stay < 60% utilization after absorbing data. Node count after decommission must be >= replication factor. +For per-store capacity (so you can verify remaining nodes won't exceed 60% utilization after absorbing the decommissioned node's data), use the DB Console **Overview** → **Storage** page or scrape the Prometheus metrics endpoint: + +```bash +curl -ks https://:8080/_status/vars | grep '^capacity' +``` + +Node count after decommission must be ≥ the zone's `num_replicas`. #### If Node Is Alive: Drain Then Decommission @@ -130,20 +128,13 @@ When a node has been dead longer than `server.time_until_store_dead` (default 5m **Step 1: Confirm the node is dead and data is safe** -```sql --- Confirm node is dead -SELECT node_id, is_live FROM crdb_internal.gossip_nodes WHERE node_id = ; - --- Verify all ranges are fully replicated (no under-replicated after re-replication) -SELECT CASE WHEN array_length(replicas, 1) >= 3 THEN 'fully_replicated' - ELSE 'under_replicated' END AS status, COUNT(*) -FROM crdb_internal.ranges_no_leases GROUP BY 1; - --- Check remaining capacity can handle the load -SELECT node_id, ROUND((1 - available::FLOAT / capacity::FLOAT) * 100, 2) AS utilization_pct -FROM crdb_internal.kv_store_status ORDER BY node_id; +```bash +# Confirm the dead node and verify replication has caught up +cockroach node status --decommission --certs-dir= --host= ``` +In the output: the dead node should show `is_live = false`, and every surviving node should show `ranges_underreplicated = 0`. For per-store capacity on the surviving nodes, use the DB Console **Overview** → **Storage** page. + If under-replicated ranges exist, wait for re-replication to complete before proceeding. **Step 2: Decommission the dead node (metadata cleanup)** @@ -184,29 +175,20 @@ Only works while still in `decommissioning` state. 1. Provision new hardware/VM with same specs as existing nodes 2. Install same CockroachDB version (`cockroach version` to confirm) 3. Start node with `--join` pointing to existing cluster nodes -4. Verify join: - ```sql - SELECT node_id, address, is_live FROM crdb_internal.gossip_nodes n - JOIN crdb_internal.gossip_liveness l USING (node_id) ORDER BY node_id; - ``` -5. Data rebalances automatically — monitor with: - ```sql - SELECT node_id, range_count, lease_count - FROM crdb_internal.kv_store_status ORDER BY node_id; +4. Verify join and monitor rebalancing: + ```bash + cockroach node status --certs-dir= --host= ``` + The new node should appear in the output with `is_live = true`. The `ranges` column climbs as data rebalances toward the new node. ### Post-Scaling Verification -```sql -SELECT CASE WHEN array_length(replicas, 1) >= 3 THEN 'fully_replicated' - ELSE 'under_replicated' END AS status, COUNT(*) -FROM crdb_internal.ranges_no_leases GROUP BY 1; - -SELECT node_id, range_count, lease_count, - ROUND((1 - available::FLOAT / capacity::FLOAT) * 100, 2) AS utilization_pct -FROM crdb_internal.kv_store_status ORDER BY node_id; +```bash +cockroach node status --decommission --certs-dir= --host= ``` +Expect `ranges_underreplicated = 0` on every node and a balanced `ranges` count across nodes. For per-store capacity utilization, use the DB Console **Overview** → **Storage** page. + --- ## Advanced Scaling diff --git a/skills/operations-and-lifecycle/managing-cluster-capacity/references/replacing-failed-nodes.md b/skills/cockroachdb-operations-and-lifecycle/managing-cluster-capacity/references/replacing-failed-nodes.md similarity index 100% rename from skills/operations-and-lifecycle/managing-cluster-capacity/references/replacing-failed-nodes.md rename to skills/cockroachdb-operations-and-lifecycle/managing-cluster-capacity/references/replacing-failed-nodes.md diff --git a/skills/operations-and-lifecycle/managing-cluster-capacity/references/storage-management.md b/skills/cockroachdb-operations-and-lifecycle/managing-cluster-capacity/references/storage-management.md similarity index 100% rename from skills/operations-and-lifecycle/managing-cluster-capacity/references/storage-management.md rename to skills/cockroachdb-operations-and-lifecycle/managing-cluster-capacity/references/storage-management.md diff --git a/skills/operations-and-lifecycle/managing-cluster-settings/SKILL.md b/skills/cockroachdb-operations-and-lifecycle/managing-cluster-settings/SKILL.md similarity index 97% rename from skills/operations-and-lifecycle/managing-cluster-settings/SKILL.md rename to skills/cockroachdb-operations-and-lifecycle/managing-cluster-settings/SKILL.md index 8721fe5..560e30e 100644 --- a/skills/operations-and-lifecycle/managing-cluster-settings/SKILL.md +++ b/skills/cockroachdb-operations-and-lifecycle/managing-cluster-settings/SKILL.md @@ -83,11 +83,13 @@ SELECT variable, value FROM [SHOW ALL CLUSTER SETTINGS] WHERE variable IN ( 'kv.rangefeed.enabled', 'sql.stats.automatic_collection.enabled', 'server.time_until_store_dead', 'admission.kv.enabled', - 'gc.ttlseconds', 'cluster.preserve_downgrade_option', + 'cluster.preserve_downgrade_option', 'sql.defaults.idle_in_transaction_session_timeout' ) ORDER BY variable; ``` +`gc.ttlseconds` is a zone-config parameter, not a cluster setting; check with `SHOW ZONE CONFIGURATION FOR ...` against the relevant table/database/range. + ### Search by Keyword ```sql @@ -253,7 +255,7 @@ All other configuration is managed by Cockroach Labs. If more control over setti **Risk levels:** - **Low:** `sql.defaults.statement_timeout`, `diagnostics.reporting.enabled` -- **Medium:** `gc.ttlseconds`, `kv.snapshot_rebalance.max_rate` +- **Medium:** `kv.snapshot_rebalance.max_rate`, `gc.ttlseconds` (zone-config parameter — same risk class) - **High:** `cluster.preserve_downgrade_option`, `admission.kv.enabled` **Critical:** Never change settings during a rolling upgrade. Cluster settings affect ALL workloads on the cluster — prefer session variables for narrower scope when possible. diff --git a/skills/operations-and-lifecycle/managing-cluster-settings/references/cloud-restricted-settings.md b/skills/cockroachdb-operations-and-lifecycle/managing-cluster-settings/references/cloud-restricted-settings.md similarity index 100% rename from skills/operations-and-lifecycle/managing-cluster-settings/references/cloud-restricted-settings.md rename to skills/cockroachdb-operations-and-lifecycle/managing-cluster-settings/references/cloud-restricted-settings.md diff --git a/skills/operations-and-lifecycle/managing-cluster-settings/references/node-level-settings.md b/skills/cockroachdb-operations-and-lifecycle/managing-cluster-settings/references/node-level-settings.md similarity index 100% rename from skills/operations-and-lifecycle/managing-cluster-settings/references/node-level-settings.md rename to skills/cockroachdb-operations-and-lifecycle/managing-cluster-settings/references/node-level-settings.md diff --git a/skills/operations-and-lifecycle/managing-cluster-settings/references/recommended-values.md b/skills/cockroachdb-operations-and-lifecycle/managing-cluster-settings/references/recommended-values.md similarity index 100% rename from skills/operations-and-lifecycle/managing-cluster-settings/references/recommended-values.md rename to skills/cockroachdb-operations-and-lifecycle/managing-cluster-settings/references/recommended-values.md diff --git a/skills/operations-and-lifecycle/managing-cluster-settings/references/safety-guide.md b/skills/cockroachdb-operations-and-lifecycle/managing-cluster-settings/references/safety-guide.md similarity index 100% rename from skills/operations-and-lifecycle/managing-cluster-settings/references/safety-guide.md rename to skills/cockroachdb-operations-and-lifecycle/managing-cluster-settings/references/safety-guide.md diff --git a/skills/operations-and-lifecycle/managing-cluster-settings/references/sql-queries.md b/skills/cockroachdb-operations-and-lifecycle/managing-cluster-settings/references/sql-queries.md similarity index 100% rename from skills/operations-and-lifecycle/managing-cluster-settings/references/sql-queries.md rename to skills/cockroachdb-operations-and-lifecycle/managing-cluster-settings/references/sql-queries.md diff --git a/skills/operations-and-lifecycle/performing-cluster-maintenance/SKILL.md b/skills/cockroachdb-operations-and-lifecycle/performing-cluster-maintenance/SKILL.md similarity index 88% rename from skills/operations-and-lifecycle/performing-cluster-maintenance/SKILL.md rename to skills/cockroachdb-operations-and-lifecycle/performing-cluster-maintenance/SKILL.md index 58a8c4b..9f80384 100644 --- a/skills/operations-and-lifecycle/performing-cluster-maintenance/SKILL.md +++ b/skills/cockroachdb-operations-and-lifecycle/performing-cluster-maintenance/SKILL.md @@ -80,33 +80,33 @@ Self-Hosted operators manage all maintenance directly. The core operation is dra Run all checks before any maintenance operation. **Stop if any check fails.** -```sql --- Check 1: All nodes live (STOP if any node is not live) -SELECT n.node_id, n.is_live -FROM crdb_internal.gossip_nodes n -JOIN crdb_internal.gossip_liveness l USING (node_id) ORDER BY n.node_id; +**Checks 1-3, 5 (node liveness, drain state, replication, version consistency):** --- Check 2: No other nodes currently draining (STOP if any draining) -SELECT node_id FROM crdb_internal.gossip_liveness WHERE draining = true; +```bash +cockroach node status --decommission --certs-dir= --host= +``` --- Check 3: Ranges fully replicated (STOP if under-replicated ranges exist) -SELECT CASE WHEN array_length(replicas, 1) >= 3 THEN 'fully_replicated' - ELSE 'under_replicated' END AS status, COUNT(*) -FROM crdb_internal.ranges_no_leases GROUP BY 1; +Stop conditions in the output: +- any `is_live = false` (Check 1) +- any `is_draining = true` (Check 2) +- any `ranges_underreplicated > 0` (Check 3) +- multiple distinct values in the `build` column (Check 5) --- Check 4: No disruptive jobs running (WAIT or pause before proceeding) +**Check 4: No disruptive jobs running (WAIT or pause before proceeding):** + +```sql WITH j AS (SHOW JOBS) SELECT job_id, job_type, status, now() - created AS running_for FROM j WHERE status IN ('running', 'paused') AND job_type IN ('SCHEMA CHANGE', 'BACKUP', 'RESTORE', 'IMPORT', 'NEW SCHEMA CHANGE'); +``` + +**Check 6: Storage utilization safe (WARNING if any node > 70%):** --- Check 5: Not mid-upgrade (STOP if versions differ) -SELECT DISTINCT build_tag FROM crdb_internal.gossip_nodes; +No production-safe SQL view exposes per-store capacity. Use the DB Console **Overview** → **Storage** page or scrape the per-node Prometheus endpoint: --- Check 6: Storage utilization safe (WARNING if any node > 70%) -SELECT node_id, - ROUND((1 - available::FLOAT / capacity::FLOAT) * 100, 2) AS utilization_pct -FROM crdb_internal.kv_store_status ORDER BY node_id; +```bash +curl -ks https://:8080/_status/vars | grep -E '^capacity( |_used|_available)' ``` **Stop conditions:** Do not proceed with maintenance if any node is not live, ranges are under-replicated, another node is draining, or a rolling upgrade is in progress. Wait for running jobs to complete or pause them. @@ -153,14 +153,12 @@ Never use `kill -9` unless the process is unresponsive to SIGTERM. ### Post-Restart Verification -```sql -SELECT node_id, is_live FROM crdb_internal.gossip_nodes WHERE node_id = ; --- is_live = true - -SELECT node_id, lease_count FROM crdb_internal.kv_store_status WHERE node_id = ; --- lease_count should increase over minutes as leases rebalance +```bash +cockroach node status --certs-dir= --host= ``` +The restarted node should show `is_live = true`. The `replicas_leaseholders` column for that node should increase over the next several minutes as leases rebalance back. + See [drain-details reference](references/drain-details.md) for drain phases, timeout configuration, and advanced monitoring. ### Storage Maintenance @@ -174,12 +172,11 @@ ls -lh /auxiliary/EMERGENCY_BALLAST ``` **Disk utilization check:** -```sql -SELECT node_id, - ROUND(capacity / 1073741824.0, 2) AS total_gb, - ROUND(available / 1073741824.0, 2) AS available_gb, - ROUND((1 - available::FLOAT / capacity::FLOAT) * 100, 2) AS utilization_pct -FROM crdb_internal.kv_store_status ORDER BY node_id; + +Use the DB Console **Overview** → **Storage** page or the per-node Prometheus endpoint: + +```bash +curl -ks https://:8080/_status/vars | grep -E '^capacity( |_used|_available)' ``` Nodes above 70% utilization should be addressed before maintenance — draining a node temporarily increases load on remaining nodes. @@ -237,12 +234,10 @@ Deferred patches still apply at the end of the deferral period. Deferral only de - Metrics page shows temporary dips in QPS and capacity - Alerts may fire for transient node unavailability -**SQL (during maintenance):** -```sql --- Check which nodes are currently live -SELECT node_id, build_tag, is_live -FROM crdb_internal.gossip_nodes n -JOIN crdb_internal.gossip_liveness l USING (node_id) ORDER BY node_id; +**During maintenance:** +```bash +# Check which nodes are currently live and what version they're on +cockroach node status --decommission --certs-dir= --host= ``` ### Best Practices diff --git a/skills/operations-and-lifecycle/performing-cluster-maintenance/references/drain-details.md b/skills/cockroachdb-operations-and-lifecycle/performing-cluster-maintenance/references/drain-details.md similarity index 100% rename from skills/operations-and-lifecycle/performing-cluster-maintenance/references/drain-details.md rename to skills/cockroachdb-operations-and-lifecycle/performing-cluster-maintenance/references/drain-details.md diff --git a/skills/operations-and-lifecycle/performing-cluster-maintenance/references/maintenance-prechecks.md b/skills/cockroachdb-operations-and-lifecycle/performing-cluster-maintenance/references/maintenance-prechecks.md similarity index 100% rename from skills/operations-and-lifecycle/performing-cluster-maintenance/references/maintenance-prechecks.md rename to skills/cockroachdb-operations-and-lifecycle/performing-cluster-maintenance/references/maintenance-prechecks.md diff --git a/skills/operations-and-lifecycle/performing-cluster-maintenance/references/safety-guide.md b/skills/cockroachdb-operations-and-lifecycle/performing-cluster-maintenance/references/safety-guide.md similarity index 100% rename from skills/operations-and-lifecycle/performing-cluster-maintenance/references/safety-guide.md rename to skills/cockroachdb-operations-and-lifecycle/performing-cluster-maintenance/references/safety-guide.md diff --git a/skills/operations-and-lifecycle/provisioning-cluster-for-production/SKILL.md b/skills/cockroachdb-operations-and-lifecycle/provisioning-cluster-for-production/SKILL.md similarity index 98% rename from skills/operations-and-lifecycle/provisioning-cluster-for-production/SKILL.md rename to skills/cockroachdb-operations-and-lifecycle/provisioning-cluster-for-production/SKILL.md index 91e623c..96f896e 100644 --- a/skills/operations-and-lifecycle/provisioning-cluster-for-production/SKILL.md +++ b/skills/cockroachdb-operations-and-lifecycle/provisioning-cluster-for-production/SKILL.md @@ -127,10 +127,10 @@ cockroach init --certs-dir=certs --host= ``` **Step 5: Verify** -```sql -SELECT node_id, address, locality, build_tag, is_live -FROM crdb_internal.gossip_nodes ORDER BY node_id; +```bash +cockroach node status --certs-dir=certs --host= ``` +Every node started in step 3 should appear with `is_live = true` and the expected `locality`. ### Deploy on Kubernetes diff --git a/skills/operations-and-lifecycle/provisioning-cluster-for-production/references/hardware-and-infrastructure.md b/skills/cockroachdb-operations-and-lifecycle/provisioning-cluster-for-production/references/hardware-and-infrastructure.md similarity index 100% rename from skills/operations-and-lifecycle/provisioning-cluster-for-production/references/hardware-and-infrastructure.md rename to skills/cockroachdb-operations-and-lifecycle/provisioning-cluster-for-production/references/hardware-and-infrastructure.md diff --git a/skills/operations-and-lifecycle/provisioning-cluster-for-production/references/production-deployment-checklist.md b/skills/cockroachdb-operations-and-lifecycle/provisioning-cluster-for-production/references/production-deployment-checklist.md similarity index 100% rename from skills/operations-and-lifecycle/provisioning-cluster-for-production/references/production-deployment-checklist.md rename to skills/cockroachdb-operations-and-lifecycle/provisioning-cluster-for-production/references/production-deployment-checklist.md diff --git a/skills/operations-and-lifecycle/reviewing-cluster-health/SKILL.md b/skills/cockroachdb-operations-and-lifecycle/reviewing-cluster-health/SKILL.md similarity index 66% rename from skills/operations-and-lifecycle/reviewing-cluster-health/SKILL.md rename to skills/cockroachdb-operations-and-lifecycle/reviewing-cluster-health/SKILL.md index a146ba7..397cbea 100644 --- a/skills/operations-and-lifecycle/reviewing-cluster-health/SKILL.md +++ b/skills/cockroachdb-operations-and-lifecycle/reviewing-cluster-health/SKILL.md @@ -19,9 +19,9 @@ Performs a comprehensive health check of a CockroachDB cluster. Before running d - Verifying production readiness - Monitoring capacity and performance -**For live query issues:** Use [triaging-live-sql-activity](../../observability-and-diagnostics/triaging-live-sql-activity/SKILL.md). -**For background jobs:** Use [monitoring-background-jobs](../../observability-and-diagnostics/monitoring-background-jobs/SKILL.md). -**For range analysis:** Use [analyzing-range-distribution](../../observability-and-diagnostics/analyzing-range-distribution/SKILL.md). +**For live query issues:** Use [triaging-live-sql-activity](../../cockroachdb-observability-and-diagnostics/triaging-live-sql-activity/SKILL.md). +**For background jobs:** Use [monitoring-background-jobs](../../cockroachdb-observability-and-diagnostics/monitoring-background-jobs/SKILL.md). +**For range analysis:** Use [analyzing-range-distribution](../../cockroachdb-observability-and-diagnostics/analyzing-range-distribution/SKILL.md). --- @@ -75,103 +75,63 @@ Performs a comprehensive health check of a CockroachDB cluster. Before running d **Applies when:** Tier = Self-Hosted -### Query 1: Node Liveness +Self-Hosted node-level health is read primarily through `cockroach node status` (CLI) and the DB Console. Cluster settings and jobs are read through public SQL (`SHOW ALL CLUSTER SETTINGS`, `SHOW JOBS`). The `crdb_internal` virtual tables for cluster topology, storage, and certificates are not for production use — see the [docs](https://www.cockroachlabs.com/docs/stable/crdb-internal) for the production-safe table list. -```sql -SELECT - n.node_id, n.address, n.build_tag AS version, n.locality, - n.is_live, l.epoch, - CASE WHEN n.is_live THEN 'HEALTHY' - WHEN n.is_live IS NULL THEN 'UNKNOWN' - ELSE 'DOWN' END AS health_status -FROM crdb_internal.gossip_nodes n -LEFT JOIN crdb_internal.gossip_liveness l ON n.node_id = l.node_id -ORDER BY n.node_id; -``` +### Check 1: Node Liveness, Version, and Replication -- Any `is_live = false` (from `gossip_nodes`) requires immediate investigation -- High `epoch` suggests repeated restarts (node flapping) - -**If CLI is available:** ```bash -cockroach node status --certs-dir= --host= +cockroach node status --decommission --certs-dir= --host= ``` -### Query 2: Version Consistency +Key columns: +- `is_live` — `false` requires immediate investigation +- `is_draining`, `is_decommissioning`, `membership` — flag in-progress lifecycle operations +- `started_at` — compare across runs to spot flapping (node restarts) +- `build` — version per node; should be a single value (or two during a rolling upgrade) +- `ranges_underreplicated` — non-zero indicates ranges below the zone's `num_replicas` -```sql -SELECT build_tag AS version, COUNT(*) AS node_count, - array_agg(node_id ORDER BY node_id) AS node_ids -FROM crdb_internal.gossip_nodes GROUP BY build_tag; -``` +For finer-grained range breakdown, use the DB Console **Replication** page. -- Single row = healthy. Two rows = acceptable during rolling upgrade. Three+ = investigate. +### Check 2: Storage Capacity -### Query 3: Storage Capacity +No production-safe SQL view exposes per-store capacity. Use: +- DB Console **Overview** → **Storage** for per-node usage +- The Prometheus metric endpoint on each node: `curl -ks https://:8080/_status/vars | grep '^capacity'` (`capacity`, `capacity_used`, `capacity_available`) -```sql -SELECT node_id, store_id, - ROUND(capacity / 1073741824.0, 2) AS total_gb, - ROUND(available / 1073741824.0, 2) AS available_gb, - ROUND((1 - (available::FLOAT / capacity::FLOAT)) * 100, 2) AS utilization_pct, - CASE WHEN (available::FLOAT / capacity::FLOAT) < 0.10 THEN 'CRITICAL' - WHEN (available::FLOAT / capacity::FLOAT) < 0.30 THEN 'WARNING' - ELSE 'OK' END AS capacity_status, - range_count, lease_count -FROM crdb_internal.kv_store_status ORDER BY utilization_pct DESC; -``` +### Check 3: Certificate Expiration -### Query 4: Range Health +No SQL view exposes node certificate expiration. Use one of: +- `cockroach cert list --certs-dir=` to inspect certs locally on each node +- `openssl x509 -in -noout -enddate` for a single cert file +- The Prometheus metric endpoint: `curl -ks https://:8080/_status/vars | grep '^security_certificate_expiration_'` (UNIX-timestamp seconds; `node`, `ca`, `client_ca`, `ui_ca`) -```sql -SELECT - CASE WHEN array_length(replicas, 1) >= 3 THEN 'fully_replicated' - WHEN array_length(replicas, 1) = 2 THEN 'under_replicated' - WHEN array_length(replicas, 1) = 1 THEN 'critically_under_replicated' - ELSE 'unknown' END AS replication_status, - COUNT(*) AS range_count -FROM crdb_internal.ranges_no_leases GROUP BY 1 ORDER BY 1; -``` +Treat anything within 90 days as `EXPIRING_SOON`. -### Query 5: Certificate Expiration - -```sql -SELECT node_id, - to_timestamp((metrics->>'security.certificate.expiration.ca')::FLOAT)::TIMESTAMPTZ AS ca_expires, - to_timestamp((metrics->>'security.certificate.expiration.node')::FLOAT)::TIMESTAMPTZ AS node_cert_expires, - CASE WHEN to_timestamp((metrics->>'security.certificate.expiration.node')::FLOAT)::TIMESTAMPTZ - < now() + INTERVAL '90 days' THEN 'EXPIRING_SOON' - ELSE 'OK' END AS cert_status -FROM crdb_internal.kv_node_status ORDER BY node_cert_expires; -``` - -### Query 6: Critical Settings +### Check 4: Critical Settings ```sql SELECT variable, value FROM [SHOW ALL CLUSTER SETTINGS] WHERE variable IN ( 'kv.rangefeed.enabled', 'sql.stats.automatic_collection.enabled', 'server.time_until_store_dead', 'admission.kv.enabled', - 'cluster.preserve_downgrade_option', 'gc.ttlseconds' + 'cluster.preserve_downgrade_option' ) ORDER BY variable; ``` -### Query 7: Consolidated Summary +`gc.ttlseconds` is a zone-config parameter, not a cluster setting; check the effective value with `SHOW ZONE CONFIGURATION FOR ...` against the relevant table/database/range. + +### Check 5: Consolidated Summary + +The DB Console **Cluster Overview** page consolidates live/dead node count, version distribution, range counts, and storage. From the CLI: + +```bash +cockroach node status --decommission --certs-dir= --host= +``` + +then aggregate the columns of interest in your shell. The cluster's logical version comes from SQL: ```sql -SELECT 'live_nodes' AS metric, COUNT(*)::TEXT AS value -FROM crdb_internal.gossip_nodes WHERE is_live = true -UNION ALL SELECT 'dead_nodes', COUNT(*)::TEXT -FROM crdb_internal.gossip_nodes WHERE is_live = false -UNION ALL SELECT 'distinct_versions', COUNT(DISTINCT build_tag)::TEXT -FROM crdb_internal.gossip_nodes -UNION ALL SELECT 'total_ranges', COUNT(*)::TEXT -FROM crdb_internal.ranges_no_leases -UNION ALL SELECT 'min_store_available_pct', - ROUND(MIN(available::FLOAT / capacity::FLOAT) * 100, 2)::TEXT -FROM crdb_internal.kv_store_status -UNION ALL SELECT 'cluster_version', value -FROM [SHOW CLUSTER SETTING version]; +SELECT value AS cluster_version FROM [SHOW CLUSTER SETTING version]; ``` **If reason = Pre-maintenance**, also check for running jobs: @@ -180,18 +140,18 @@ WITH j AS (SHOW JOBS) SELECT job_type, COUNT(*) FROM j WHERE status = 'running' GROUP BY job_type; ``` -### Query 8: Production Readiness Assessment +### Check 6: Production Readiness Assessment Use when verifying a cluster is ready for production workloads or during periodic operational reviews. -```sql --- Node count and replication (minimum 3 nodes for production) -SELECT COUNT(*) AS total_nodes, - COUNT(*) FILTER (WHERE n.is_live) AS live_nodes, - COUNT(DISTINCT n.locality) AS distinct_localities -FROM crdb_internal.gossip_nodes n -JOIN crdb_internal.gossip_liveness l USING (node_id); +```bash +# Node count, liveness, and locality diversity +cockroach node status --decommission --certs-dir= --host= +``` + +In the output, count rows with `is_live = true` (production wants ≥ 3) and check that `locality` shows multiple regions/zones. +```sql -- Critical production settings check SELECT variable, value, CASE @@ -208,7 +168,7 @@ FROM [SHOW ALL CLUSTER SETTINGS] WHERE variable IN ( 'kv.rangefeed.enabled', 'sql.stats.automatic_collection.enabled', 'admission.kv.enabled', 'cluster.preserve_downgrade_option', - 'server.time_until_store_dead', 'gc.ttlseconds' + 'server.time_until_store_dead' ) ORDER BY variable; -- Enterprise license status (Self-Hosted only) @@ -231,22 +191,16 @@ Advanced clusters are dedicated single-tenant clusters managed by Cockroach Labs 2. **Metrics** — CPU utilization, QPS, P99 latency, storage utilization 3. **Alerts** — check for active alerts -### SQL Checks - -```sql --- Node liveness (nodes are visible on Advanced) -SELECT n.node_id, n.build_tag, n.is_live -FROM crdb_internal.gossip_nodes n -JOIN crdb_internal.gossip_liveness l USING (node_id) ORDER BY n.node_id; +### CLI + SQL Checks --- Version consistency -SELECT build_tag AS version, COUNT(*) FROM crdb_internal.gossip_nodes GROUP BY 1; +```bash +# Node liveness, version, and replication status +cockroach node status --decommission --certs-dir= --host= +``` --- Range health -SELECT CASE WHEN array_length(replicas, 1) >= 3 THEN 'fully_replicated' - ELSE 'under_replicated' END AS status, COUNT(*) -FROM crdb_internal.ranges_no_leases GROUP BY 1; +Look at `is_live`, `build`, and `ranges_underreplicated` per node. +```sql -- Recent failed jobs WITH j AS (SHOW JOBS) SELECT job_type, status, COUNT(*) FROM j @@ -333,7 +287,7 @@ WHERE status = 'failed' AND created > now() - INTERVAL '24 hours'; - **Storage growth** — plan based on usage trends - **Compute utilization** — increase provisioned vCPUs if utilization is consistently high -**Note:** Node-level system tables (`crdb_internal.gossip_nodes`, `kv_store_status`, etc.) are not available on Standard. Use Cloud Console for all infrastructure health monitoring. +**Note:** Node-level visibility is not available on Standard. Use Cloud Console for all infrastructure health monitoring. --- @@ -376,19 +330,19 @@ WHERE status = 'failed' AND created > now() - INTERVAL '24 hours'; ## Safety Considerations -All queries in this skill are read-only. No data is modified. +All checks in this skill are read-only. No data is modified. -- **Self-Hosted:** `crdb_internal.ranges_no_leases` can be slow on large clusters — consider using `LIMIT` -- **Advanced/BYOC:** Some system tables may have restricted access depending on SQL user role -- **Standard/Basic:** Node-level system tables are not available — this is expected, not an error +- **Self-Hosted:** `cockroach node status` requires CLI access (or admin SQL privilege if you need to fall back to internal tables). Most node-level health queries have no production-safe SQL alternative. +- **Advanced/BYOC:** `cockroach node status` works the same way; certificate inspection is managed by Cockroach Labs. +- **Standard/Basic:** No node-level visibility by design — use the Cloud Console. ## Troubleshooting | Issue | Tier | Fix | |-------|------|-----| -| `crdb_internal.kv_node_status` empty | SH | Grant admin or VIEWCLUSTERMETADATA | -| `crdb_internal` table not found | STD/BAS | Expected — use Cloud Console | -| Node missing from gossip_nodes | SH | Check node process; verify --join address | +| `cockroach node status` errors with permission denied | SH | Use a cert with admin or `VIEWCLUSTERMETADATA` | +| Node missing from `cockroach node status` output | SH | Check node process; verify `--join` address | +| Standard/Basic SQL doesn't expose node tables | STD/BAS | Expected — use Cloud Console | | Cloud Console shows degraded | ADV/BYOC | Check Cloud status page; contact support | | High RU consumption | BAS | Profile queries; set spending limits | | Cloud API returns 401 | ADV/BYOC | Regenerate API key | @@ -403,11 +357,11 @@ All queries in this skill are read-only. No data is modified. - [upgrading-cluster-version](../upgrading-cluster-version/SKILL.md) - [managing-cluster-capacity](../managing-cluster-capacity/SKILL.md) - [performing-cluster-maintenance](../performing-cluster-maintenance/SKILL.md) -- [monitoring-background-jobs](../../observability-and-diagnostics/monitoring-background-jobs/SKILL.md) +- [monitoring-background-jobs](../../cockroachdb-observability-and-diagnostics/monitoring-background-jobs/SKILL.md) **Official CockroachDB Documentation:** - [Monitoring and Alerting](https://www.cockroachlabs.com/docs/stable/monitoring-and-alerting) -- [crdb_internal](https://www.cockroachlabs.com/docs/stable/crdb-internal.html) +- [cockroach node status](https://www.cockroachlabs.com/docs/stable/cockroach-node) - [Production Checklist](https://www.cockroachlabs.com/docs/stable/recommended-production-settings) - [Cloud Console Monitoring](https://www.cockroachlabs.com/docs/cockroachcloud/cluster-overview-page) - [Export Metrics (Advanced)](https://www.cockroachlabs.com/docs/cockroachcloud/export-metrics) diff --git a/skills/operations-and-lifecycle/reviewing-cluster-health/references/production-readiness.md b/skills/cockroachdb-operations-and-lifecycle/reviewing-cluster-health/references/production-readiness.md similarity index 100% rename from skills/operations-and-lifecycle/reviewing-cluster-health/references/production-readiness.md rename to skills/cockroachdb-operations-and-lifecycle/reviewing-cluster-health/references/production-readiness.md diff --git a/skills/operations-and-lifecycle/upgrading-cluster-version/SKILL.md b/skills/cockroachdb-operations-and-lifecycle/upgrading-cluster-version/SKILL.md similarity index 91% rename from skills/operations-and-lifecycle/upgrading-cluster-version/SKILL.md rename to skills/cockroachdb-operations-and-lifecycle/upgrading-cluster-version/SKILL.md index 67a2fb8..6e401c5 100644 --- a/skills/operations-and-lifecycle/upgrading-cluster-version/SKILL.md +++ b/skills/cockroachdb-operations-and-lifecycle/upgrading-cluster-version/SKILL.md @@ -82,11 +82,14 @@ Guides CockroachDB version upgrades end-to-end. Before providing procedures, thi ### Pre-Upgrade Validation -```sql --- All nodes live -SELECT n.node_id, n.build_tag, n.is_live -FROM crdb_internal.gossip_nodes n ORDER BY n.node_id; +```bash +# All nodes live, version-consistent, fully replicated +cockroach node status --decommission --certs-dir= --host= +``` + +In the output: every node should show `is_live = true`, the `build` column should be a single value, and `ranges_underreplicated` should be `0` everywhere. +```sql -- No bulk operations running WITH j AS (SHOW JOBS) SELECT job_id, job_type, status, now() - created AS running_for FROM j @@ -95,11 +98,6 @@ WHERE status IN ('running', 'paused') -- No pending finalization from a previous upgrade SHOW CLUSTER SETTING cluster.preserve_downgrade_option; - --- Ranges fully replicated -SELECT CASE WHEN array_length(replicas, 1) >= 3 THEN 'fully_replicated' - ELSE 'under_replicated' END AS status, COUNT(*) -FROM crdb_internal.ranges_no_leases GROUP BY 1; ``` ### Disable Auto-Finalization (Major Version — Recommended) @@ -137,25 +135,23 @@ kubectl set image statefulset/cockroachdb cockroachdb=cockroachdb/cockroach:; +```bash +cockroach node status --certs-dir= --host= ``` +The targeted node should show `is_live = true` on the new `build`. ### Monitor Progress -```sql -SELECT n.node_id, n.build_tag AS version, - CASE WHEN n.build_tag = (SELECT MAX(build_tag) FROM crdb_internal.gossip_nodes) - THEN 'UPGRADED' ELSE 'PENDING' END AS status -FROM crdb_internal.gossip_nodes n ORDER BY n.node_id; +```bash +cockroach node status --certs-dir= --host= ``` +Compare the `build` column across all rows. Nodes still on the old version are pending; rolling upgrade is complete when every row shows the new version. ### Finalize (Major Version Only — Irreversible) +Confirm via `cockroach node status` that the `build` column has a single value (every node upgraded). Then: + ```sql -SELECT COUNT(DISTINCT build_tag) FROM crdb_internal.gossip_nodes; -- Must be 1 RESET CLUSTER SETTING cluster.preserve_downgrade_option; SHOW CLUSTER SETTING version; -- Monitor until updated ``` @@ -183,10 +179,11 @@ Advanced clusters are managed by Cockroach Labs. You initiate major upgrades; pa 4. Monitor progress in Cloud Console 5. Finalize via Cloud Console when testing is complete -**SQL verification during upgrade:** -```sql -SELECT build_tag AS version, COUNT(*) FROM crdb_internal.gossip_nodes GROUP BY 1; +**Verification during upgrade:** +```bash +cockroach node status --certs-dir= --host= ``` +Tally the `build` column to see how many nodes are on the new version vs the old. ### Patch Upgrades diff --git a/skills/performance-and-scaling/.gitkeep b/skills/cockroachdb-performance-and-scaling/.gitkeep similarity index 100% rename from skills/performance-and-scaling/.gitkeep rename to skills/cockroachdb-performance-and-scaling/.gitkeep diff --git a/skills/query-and-schema-design/.gitkeep b/skills/cockroachdb-query-and-schema-design/.gitkeep similarity index 100% rename from skills/query-and-schema-design/.gitkeep rename to skills/cockroachdb-query-and-schema-design/.gitkeep diff --git a/skills/query-and-schema-design/cockroachdb-sql/SKILL.md b/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/SKILL.md similarity index 100% rename from skills/query-and-schema-design/cockroachdb-sql/SKILL.md rename to skills/cockroachdb-query-and-schema-design/cockroachdb-sql/SKILL.md diff --git a/skills/query-and-schema-design/cockroachdb-sql/references/EXAMPLES.md b/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/EXAMPLES.md similarity index 100% rename from skills/query-and-schema-design/cockroachdb-sql/references/EXAMPLES.md rename to skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/EXAMPLES.md diff --git a/skills/query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/00-fundamental-principles.md b/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/00-fundamental-principles.md similarity index 100% rename from skills/query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/00-fundamental-principles.md rename to skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/00-fundamental-principles.md diff --git a/skills/query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/01-schema-design.md b/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/01-schema-design.md similarity index 100% rename from skills/query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/01-schema-design.md rename to skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/01-schema-design.md diff --git a/skills/query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/02-dml-operations.md b/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/02-dml-operations.md similarity index 100% rename from skills/query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/02-dml-operations.md rename to skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/02-dml-operations.md diff --git a/skills/query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/03-query-patterns.md b/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/03-query-patterns.md similarity index 100% rename from skills/query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/03-query-patterns.md rename to skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/03-query-patterns.md diff --git a/skills/query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/04-optimization.md b/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/04-optimization.md similarity index 100% rename from skills/query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/04-optimization.md rename to skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/04-optimization.md diff --git a/skills/query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/05-operational.md b/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/05-operational.md similarity index 100% rename from skills/query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/05-operational.md rename to skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/05-operational.md diff --git a/skills/resilience-and-disaster-recovery/.gitkeep b/skills/cockroachdb-resilience-and-disaster-recovery/.gitkeep similarity index 100% rename from skills/resilience-and-disaster-recovery/.gitkeep rename to skills/cockroachdb-resilience-and-disaster-recovery/.gitkeep diff --git a/skills/security-and-governance/.gitkeep b/skills/cockroachdb-security-and-governance/.gitkeep similarity index 100% rename from skills/security-and-governance/.gitkeep rename to skills/cockroachdb-security-and-governance/.gitkeep diff --git a/skills/security-and-governance/auditing-cloud-cluster-security/SKILL.md b/skills/cockroachdb-security-and-governance/auditing-cloud-cluster-security/SKILL.md similarity index 97% rename from skills/security-and-governance/auditing-cloud-cluster-security/SKILL.md rename to skills/cockroachdb-security-and-governance/auditing-cloud-cluster-security/SKILL.md index eabbee6..7383e84 100644 --- a/skills/security-and-governance/auditing-cloud-cluster-security/SKILL.md +++ b/skills/cockroachdb-security-and-governance/auditing-cloud-cluster-security/SKILL.md @@ -285,13 +285,17 @@ ccloud cluster info -o json - **Advanced plan with Advanced Security Add-on, CMEK enabled:** PASS **Enterprise Encryption (self-hosted — skip CMEK, check this instead):** -```bash -# Enterprise Encryption is configured via --enterprise-encryption flag at node startup -cockroach node status --certs-dir= --host= --format=records -``` -```sql -SHOW CLUSTER SETTING enterprise.encryption.type; -``` + +Enterprise Encryption-at-Rest is configured at node start via the +`--enterprise-encryption` flag and is not exposed as a SQL cluster setting. +Confirm it by: +- Inspecting the node's startup arguments (process command line / systemd unit + / Kubernetes pod spec) for `--enterprise-encryption=...` +- Checking the per-node Prometheus endpoint: + `curl -ks https://:8080/_status/vars | grep '^rocksdb_encryption_'` +- The DB Console **Advanced Debug** → **Stores** view reports the active + encryption type per store + - **FAIL** if not enabled and cluster stores sensitive data - **WARN** if encryption status cannot be determined - **PASS** if enabled with AES-256 diff --git a/skills/security-and-governance/auditing-cloud-cluster-security/references/ccloud-commands.md b/skills/cockroachdb-security-and-governance/auditing-cloud-cluster-security/references/ccloud-commands.md similarity index 100% rename from skills/security-and-governance/auditing-cloud-cluster-security/references/ccloud-commands.md rename to skills/cockroachdb-security-and-governance/auditing-cloud-cluster-security/references/ccloud-commands.md diff --git a/skills/security-and-governance/auditing-cloud-cluster-security/references/permissions.md b/skills/cockroachdb-security-and-governance/auditing-cloud-cluster-security/references/permissions.md similarity index 100% rename from skills/security-and-governance/auditing-cloud-cluster-security/references/permissions.md rename to skills/cockroachdb-security-and-governance/auditing-cloud-cluster-security/references/permissions.md diff --git a/skills/security-and-governance/auditing-cloud-cluster-security/references/sample-report.md b/skills/cockroachdb-security-and-governance/auditing-cloud-cluster-security/references/sample-report.md similarity index 100% rename from skills/security-and-governance/auditing-cloud-cluster-security/references/sample-report.md rename to skills/cockroachdb-security-and-governance/auditing-cloud-cluster-security/references/sample-report.md diff --git a/skills/security-and-governance/auditing-cloud-cluster-security/references/sql-queries.md b/skills/cockroachdb-security-and-governance/auditing-cloud-cluster-security/references/sql-queries.md similarity index 100% rename from skills/security-and-governance/auditing-cloud-cluster-security/references/sql-queries.md rename to skills/cockroachdb-security-and-governance/auditing-cloud-cluster-security/references/sql-queries.md diff --git a/skills/security-and-governance/configuring-audit-logging/SKILL.md b/skills/cockroachdb-security-and-governance/configuring-audit-logging/SKILL.md similarity index 100% rename from skills/security-and-governance/configuring-audit-logging/SKILL.md rename to skills/cockroachdb-security-and-governance/configuring-audit-logging/SKILL.md diff --git a/skills/security-and-governance/configuring-audit-logging/references/sql-queries.md b/skills/cockroachdb-security-and-governance/configuring-audit-logging/references/sql-queries.md similarity index 100% rename from skills/security-and-governance/configuring-audit-logging/references/sql-queries.md rename to skills/cockroachdb-security-and-governance/configuring-audit-logging/references/sql-queries.md diff --git a/skills/security-and-governance/configuring-ip-allowlists/SKILL.md b/skills/cockroachdb-security-and-governance/configuring-ip-allowlists/SKILL.md similarity index 100% rename from skills/security-and-governance/configuring-ip-allowlists/SKILL.md rename to skills/cockroachdb-security-and-governance/configuring-ip-allowlists/SKILL.md diff --git a/skills/security-and-governance/configuring-ip-allowlists/references/ccloud-commands.md b/skills/cockroachdb-security-and-governance/configuring-ip-allowlists/references/ccloud-commands.md similarity index 100% rename from skills/security-and-governance/configuring-ip-allowlists/references/ccloud-commands.md rename to skills/cockroachdb-security-and-governance/configuring-ip-allowlists/references/ccloud-commands.md diff --git a/skills/security-and-governance/configuring-log-export/SKILL.md b/skills/cockroachdb-security-and-governance/configuring-log-export/SKILL.md similarity index 100% rename from skills/security-and-governance/configuring-log-export/SKILL.md rename to skills/cockroachdb-security-and-governance/configuring-log-export/SKILL.md diff --git a/skills/security-and-governance/configuring-log-export/references/cloud-provider-setup.md b/skills/cockroachdb-security-and-governance/configuring-log-export/references/cloud-provider-setup.md similarity index 100% rename from skills/security-and-governance/configuring-log-export/references/cloud-provider-setup.md rename to skills/cockroachdb-security-and-governance/configuring-log-export/references/cloud-provider-setup.md diff --git a/skills/security-and-governance/configuring-private-connectivity/SKILL.md b/skills/cockroachdb-security-and-governance/configuring-private-connectivity/SKILL.md similarity index 100% rename from skills/security-and-governance/configuring-private-connectivity/SKILL.md rename to skills/cockroachdb-security-and-governance/configuring-private-connectivity/SKILL.md diff --git a/skills/security-and-governance/configuring-private-connectivity/references/ccloud-commands.md b/skills/cockroachdb-security-and-governance/configuring-private-connectivity/references/ccloud-commands.md similarity index 100% rename from skills/security-and-governance/configuring-private-connectivity/references/ccloud-commands.md rename to skills/cockroachdb-security-and-governance/configuring-private-connectivity/references/ccloud-commands.md diff --git a/skills/security-and-governance/configuring-private-connectivity/references/cloud-provider-setup.md b/skills/cockroachdb-security-and-governance/configuring-private-connectivity/references/cloud-provider-setup.md similarity index 100% rename from skills/security-and-governance/configuring-private-connectivity/references/cloud-provider-setup.md rename to skills/cockroachdb-security-and-governance/configuring-private-connectivity/references/cloud-provider-setup.md diff --git a/skills/security-and-governance/configuring-sso-and-scim/SKILL.md b/skills/cockroachdb-security-and-governance/configuring-sso-and-scim/SKILL.md similarity index 100% rename from skills/security-and-governance/configuring-sso-and-scim/SKILL.md rename to skills/cockroachdb-security-and-governance/configuring-sso-and-scim/SKILL.md diff --git a/skills/security-and-governance/configuring-sso-and-scim/references/configuration-steps.md b/skills/cockroachdb-security-and-governance/configuring-sso-and-scim/references/configuration-steps.md similarity index 100% rename from skills/security-and-governance/configuring-sso-and-scim/references/configuration-steps.md rename to skills/cockroachdb-security-and-governance/configuring-sso-and-scim/references/configuration-steps.md diff --git a/skills/security-and-governance/enabling-cmek-encryption/SKILL.md b/skills/cockroachdb-security-and-governance/enabling-cmek-encryption/SKILL.md similarity index 97% rename from skills/security-and-governance/enabling-cmek-encryption/SKILL.md rename to skills/cockroachdb-security-and-governance/enabling-cmek-encryption/SKILL.md index 6cd6a12..b08aa95 100644 --- a/skills/security-and-governance/enabling-cmek-encryption/SKILL.md +++ b/skills/cockroachdb-security-and-governance/enabling-cmek-encryption/SKILL.md @@ -148,10 +148,9 @@ ccloud cluster info -o json # Verify cmek_config shows enabled status and correct key URI ``` -```sql --- Verify encryption via SQL -SHOW CLUSTER SETTING enterprise.encryption.type; -``` +CMEK status is not exposed as a SQL cluster setting; the Cloud Console +**Cluster** → **Settings** → **Encryption** page is authoritative for +managed clusters. ### 5. Test Key Accessibility diff --git a/skills/security-and-governance/enabling-cmek-encryption/references/ccloud-commands.md b/skills/cockroachdb-security-and-governance/enabling-cmek-encryption/references/ccloud-commands.md similarity index 100% rename from skills/security-and-governance/enabling-cmek-encryption/references/ccloud-commands.md rename to skills/cockroachdb-security-and-governance/enabling-cmek-encryption/references/ccloud-commands.md diff --git a/skills/security-and-governance/enforcing-password-policies/SKILL.md b/skills/cockroachdb-security-and-governance/enforcing-password-policies/SKILL.md similarity index 82% rename from skills/security-and-governance/enforcing-password-policies/SKILL.md rename to skills/cockroachdb-security-and-governance/enforcing-password-policies/SKILL.md index 6a612ec..022e457 100644 --- a/skills/security-and-governance/enforcing-password-policies/SKILL.md +++ b/skills/cockroachdb-security-and-governance/enforcing-password-policies/SKILL.md @@ -9,7 +9,7 @@ metadata: # Enforcing Password Policies -Configures and enforces password policies on CockroachDB clusters by setting minimum password length, bcrypt hash cost, and login throttling. Ensures password strength meets organizational and compliance requirements. +Configures and enforces password policies on CockroachDB clusters by setting minimum password length and bcrypt hash cost. Ensures password strength meets organizational and compliance requirements. ## When to Use This Skill @@ -17,7 +17,6 @@ Configures and enforces password policies on CockroachDB clusters by setting min - Setting up password policies for a new production cluster - Responding to a security audit finding about weak password policies - Increasing bcrypt hash cost to improve resistance against brute-force attacks -- Configuring login throttling to mitigate credential stuffing ## Prerequisites @@ -39,10 +38,6 @@ SHOW CLUSTER SETTING server.user_login.min_password_length; -- Password hash cost (bcrypt rounds) SHOW CLUSTER SETTING server.user_login.password_hashes.default_cost.crdb_bcrypt; - --- Login attempt throttling -SHOW CLUSTER SETTING server.user_login.password.min_delay; -SHOW CLUSTER SETTING server.user_login.password.max_delay; ``` See [SQL queries reference](references/sql-queries.md) for additional password-related queries. @@ -83,28 +78,12 @@ SET CLUSTER SETTING server.user_login.password_hashes.default_cost.crdb_bcrypt = **Trade-off:** Higher cost means slower password verification, which affects login latency. Cost 12 is a good balance. -### 4. Configure Login Throttling - -Login throttling introduces delays after failed authentication attempts to slow down brute-force attacks. - -```sql --- Minimum delay after failed login attempt -SET CLUSTER SETTING server.user_login.password.min_delay = '0.5s'; - --- Maximum delay after repeated failures -SET CLUSTER SETTING server.user_login.password.max_delay = '10s'; -``` - -The delay increases exponentially between `min_delay` and `max_delay` with each consecutive failed attempt. - -### 5. Verify Enforcement +### 4. Verify Enforcement ```sql -- Confirm settings SHOW CLUSTER SETTING server.user_login.min_password_length; SHOW CLUSTER SETTING server.user_login.password_hashes.default_cost.crdb_bcrypt; -SHOW CLUSTER SETTING server.user_login.password.min_delay; -SHOW CLUSTER SETTING server.user_login.password.max_delay; ``` **Test enforcement:** @@ -118,7 +97,7 @@ CREATE USER test_strong_password WITH PASSWORD 'a-secure-password-123'; DROP USER test_strong_password; ``` -### 6. Address Existing Users with Weak Passwords +### 5. Address Existing Users with Weak Passwords Password policy changes only apply to new passwords. Existing users retain their old passwords until they change them. @@ -132,15 +111,15 @@ Password policy changes only apply to new passwords. Existing users retain their ALTER USER WITH PASSWORD ''; ``` -### 7. Manage Password Changes and Rotation +### 6. Manage Password Changes and Rotation #### User Self-Service Password Changes SQL users can change their own passwords: ```sql --- User changes their own password -ALTER USER current_user() WITH PASSWORD ''; +-- User changes their own password (CURRENT_USER, no parens) +ALTER USER CURRENT_USER WITH PASSWORD ''; ``` **Note:** Non-admin users can change their own passwords by default. If users report they cannot change their password, verify they are connected as the correct user and that there are no HBA rules blocking password-based authentication. @@ -170,7 +149,7 @@ Changing one does not affect the other. Users must manage both if they use both - Coordinate password rotation with application deployment cycles to avoid downtime - After changing a password, verify the application can connect with the new credentials before decommissioning the old password -### 8. Troubleshoot Common Password Errors +### 7. Troubleshoot Common Password Errors #### "password too short" @@ -204,17 +183,11 @@ If users report authentication failures immediately after changing their passwor ```sql SHOW CLUSTER SETTING server.host_based_authentication.configuration; ``` -4. Check login throttling delays if there were failed attempts: - ```sql - SHOW CLUSTER SETTING server.user_login.password.min_delay; - SHOW CLUSTER SETTING server.user_login.password.max_delay; - ``` ## Safety Considerations - **New passwords only:** Changing `min_password_length` does not invalidate existing passwords. Users with short passwords can still log in until they change their password. - **Hash cost latency:** Increasing `crdb_bcrypt` cost increases login time. Test with realistic connection pools before setting cost above 12. -- **Throttling impact:** Login throttling delays affect all users after failed attempts, including legitimate users who mistype their password. - **Service accounts:** Ensure service accounts use strong passwords or certificate-based authentication (certificates bypass password policy). ## Rollback @@ -225,10 +198,6 @@ SET CLUSTER SETTING server.user_login.min_password_length = 1; -- Reset hash cost to default RESET CLUSTER SETTING server.user_login.password_hashes.default_cost.crdb_bcrypt; - --- Reset login throttling to defaults -RESET CLUSTER SETTING server.user_login.password.min_delay; -RESET CLUSTER SETTING server.user_login.password.max_delay; ``` ## References diff --git a/skills/security-and-governance/enforcing-password-policies/references/sql-queries.md b/skills/cockroachdb-security-and-governance/enforcing-password-policies/references/sql-queries.md similarity index 100% rename from skills/security-and-governance/enforcing-password-policies/references/sql-queries.md rename to skills/cockroachdb-security-and-governance/enforcing-password-policies/references/sql-queries.md diff --git a/skills/security-and-governance/hardening-user-privileges/SKILL.md b/skills/cockroachdb-security-and-governance/hardening-user-privileges/SKILL.md similarity index 83% rename from skills/security-and-governance/hardening-user-privileges/SKILL.md rename to skills/cockroachdb-security-and-governance/hardening-user-privileges/SKILL.md index 342d50d..7a9ed2e 100644 --- a/skills/security-and-governance/hardening-user-privileges/SKILL.md +++ b/skills/cockroachdb-security-and-governance/hardening-user-privileges/SKILL.md @@ -105,16 +105,29 @@ ORDER BY privilege_type, grantee; ### 3. Create Purpose-Specific Roles -Replace broad admin grants with targeted roles: +Replace broad admin grants with targeted roles. Database-level grants in +CockroachDB only support `CONNECT`, `CREATE`, `DROP`, `ZONECONFIG`, `BACKUP`, +`RESTORE`, and `ALL` — data-access privileges (`SELECT`, `INSERT`, `UPDATE`, +`DELETE`) live at the schema or table level. Pair `GRANT ... ON ALL TABLES IN +SCHEMA` (covers existing tables) with `ALTER DEFAULT PRIVILEGES` (covers +future tables created by the listed grantors) so new tables inherit the +intended access. ```sql -- Read-only role for analysts CREATE ROLE analyst_reader; -GRANT SELECT ON DATABASE TO analyst_reader; +GRANT CONNECT ON DATABASE TO analyst_reader; +GRANT USAGE ON SCHEMA .public TO analyst_reader; +GRANT SELECT ON ALL TABLES IN SCHEMA .public TO analyst_reader; +ALTER DEFAULT PRIVILEGES IN SCHEMA .public GRANT SELECT ON TABLES TO analyst_reader; -- Application service role (read + write, no DDL) CREATE ROLE app_service; -GRANT SELECT, INSERT, UPDATE, DELETE ON DATABASE TO app_service; +GRANT CONNECT ON DATABASE TO app_service; +GRANT USAGE ON SCHEMA .public TO app_service; +GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA .public TO app_service; +ALTER DEFAULT PRIVILEGES IN SCHEMA .public + GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO app_service; -- Schema management role (DDL only) CREATE ROLE schema_manager; @@ -152,8 +165,9 @@ REVOKE admin FROM monitoring_user; **Revoke PUBLIC role data grants:** ```sql --- Revoke SELECT from PUBLIC on application databases -REVOKE SELECT ON DATABASE FROM public; +-- Revoke SELECT from PUBLIC on existing tables, plus the default-privilege grant +REVOKE SELECT ON ALL TABLES IN SCHEMA .public FROM public; +ALTER DEFAULT PRIVILEGES IN SCHEMA .public REVOKE SELECT ON TABLES FROM public; -- Revoke all data privileges from PUBLIC on specific tables REVOKE ALL ON TABLE FROM public; @@ -212,10 +226,10 @@ If an application breaks after revoking a grant: GRANT admin TO ; -- Re-grant specific privileges -GRANT SELECT, INSERT, UPDATE ON DATABASE TO ; +GRANT SELECT, INSERT, UPDATE ON ALL TABLES IN SCHEMA .public TO ; -- Re-grant PUBLIC privileges -GRANT SELECT ON DATABASE TO public; +GRANT SELECT ON ALL TABLES IN SCHEMA .public TO public; ``` **Best practice:** Keep a record of all grants before revoking so you can restore them if needed: diff --git a/skills/security-and-governance/hardening-user-privileges/references/sql-queries.md b/skills/cockroachdb-security-and-governance/hardening-user-privileges/references/sql-queries.md similarity index 100% rename from skills/security-and-governance/hardening-user-privileges/references/sql-queries.md rename to skills/cockroachdb-security-and-governance/hardening-user-privileges/references/sql-queries.md diff --git a/skills/security-and-governance/managing-tls-certificates/SKILL.md b/skills/cockroachdb-security-and-governance/managing-tls-certificates/SKILL.md similarity index 100% rename from skills/security-and-governance/managing-tls-certificates/SKILL.md rename to skills/cockroachdb-security-and-governance/managing-tls-certificates/SKILL.md diff --git a/skills/security-and-governance/managing-tls-certificates/references/connection-examples.md b/skills/cockroachdb-security-and-governance/managing-tls-certificates/references/connection-examples.md similarity index 100% rename from skills/security-and-governance/managing-tls-certificates/references/connection-examples.md rename to skills/cockroachdb-security-and-governance/managing-tls-certificates/references/connection-examples.md diff --git a/skills/security-and-governance/managing-tls-certificates/references/troubleshooting.md b/skills/cockroachdb-security-and-governance/managing-tls-certificates/references/troubleshooting.md similarity index 100% rename from skills/security-and-governance/managing-tls-certificates/references/troubleshooting.md rename to skills/cockroachdb-security-and-governance/managing-tls-certificates/references/troubleshooting.md diff --git a/skills/security-and-governance/preparing-compliance-documentation/SKILL.md b/skills/cockroachdb-security-and-governance/preparing-compliance-documentation/SKILL.md similarity index 100% rename from skills/security-and-governance/preparing-compliance-documentation/SKILL.md rename to skills/cockroachdb-security-and-governance/preparing-compliance-documentation/SKILL.md diff --git a/skills/security-and-governance/preparing-compliance-documentation/references/compliance-matrix.md b/skills/cockroachdb-security-and-governance/preparing-compliance-documentation/references/compliance-matrix.md similarity index 100% rename from skills/security-and-governance/preparing-compliance-documentation/references/compliance-matrix.md rename to skills/cockroachdb-security-and-governance/preparing-compliance-documentation/references/compliance-matrix.md diff --git a/submodules/cockroachdb-skills b/submodules/cockroachdb-skills index a3bd37d..8716a65 160000 --- a/submodules/cockroachdb-skills +++ b/submodules/cockroachdb-skills @@ -1 +1 @@ -Subproject commit a3bd37d3aec14f63182bfaebba91a948654d2cbb +Subproject commit 8716a6593b7ef577e17d87c4d196ba18d9349c52