Skip to content

Vendor SQL diagrams as local includes#23404

Merged
rmloveland merged 4 commits into
mainfrom
2026-05-28-DOC-17061-remote_include-sql-diagrams
May 29, 2026
Merged

Vendor SQL diagrams as local includes#23404
rmloveland merged 4 commits into
mainfrom
2026-05-28-DOC-17061-remote_include-sql-diagrams

Conversation

@rmloveland
Copy link
Copy Markdown
Contributor

Fixes DOC-17061

Summary of changes:

  • Vendored generated SQL diagram HTML into local include files.

  • Replaced SQL diagram remote includes with local versioned includes.

  • Added scripts to vendor and verify SQL diagram includes.

Fixes DOC-17061

Summary of changes:

- Vendored generated SQL diagram HTML into local include files.

- Replaced SQL diagram remote includes with local versioned includes.

- Added scripts to vendor and verify SQL diagram includes.
@rmloveland rmloveland requested a review from a team as a code owner May 28, 2026 18:56
@rmloveland rmloveland requested a review from ebembi-crdb May 28, 2026 18:56
@netlify
Copy link
Copy Markdown

netlify Bot commented May 28, 2026

Deploy Preview for cockroachdb-api-docs ready!

Name Link
🔨 Latest commit cac39f8
🔍 Latest deploy log https://app.netlify.com/projects/cockroachdb-api-docs/deploys/6a19e07d958b880008696634
😎 Deploy Preview https://deploy-preview-23404--cockroachdb-api-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 28, 2026

Files changed:

  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/alter_backup.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/alter_backup_schedule.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/alter_changefeed.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/alter_database.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/alter_default_privileges.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/alter_func.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/alter_index.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/alter_range.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/alter_role.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/alter_schema.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/alter_sequence.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/alter_table.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/alter_table_cmds.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/alter_type.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/alter_view.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/alter_zone_partition.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/analyze.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/backup.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/cancel_all_jobs.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/cancel_job.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/cancel_query.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/cancel_session.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/check_column_level.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/check_table_level.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/close_cursor.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/col_qualification.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/column_table_def.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/comment.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/commit_transaction.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/copy.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_as_col_qual_list.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_as_constraint_def.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_changefeed.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_database.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_external_connection.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_func.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_index.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_index_with_storage_param.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_inverted_index.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_role.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_schedule_for_changefeed.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_schema.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_sequence.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_stats.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_table.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_table_as.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_table_with_storage_param.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_type.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/create_view.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/declare_cursor.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/default_value_column_level.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/delete.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/drop_database.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/drop_external_connection.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/drop_func.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/drop_index.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/drop_owned_by.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/drop_role.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/drop_schedule.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/drop_schema.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/drop_sequence.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/drop_table.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/drop_type.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/drop_view.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/explain.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/explain_analyze.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/export.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/family_def.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/fetch_cursor.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/for_locking.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/foreign_key_column_level.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/foreign_key_table_level.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/grant.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/import_dump.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/import_into.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/index_def.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/insert.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/joined_table.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/legacy_begin.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/like_table_option_list.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/not_null_column_level.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/on_conflict.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/opt_frame_clause.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/opt_locality.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/opt_persistence_temp_table.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/opt_with_storage_parameter_list.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/pause_all_jobs.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/pause_job.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/pause_schedule.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/primary_key_column_level.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/primary_key_table_level.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/reassign_owned_by.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/refresh_materialized_views.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/release_savepoint.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/reset_csetting.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/reset_session.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/restore.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/resume_all_jobs.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/resume_job.html
  • src/current/_includes/cockroach-generated/release-23.1/sql-diagrams/resume_schedule.html

@netlify
Copy link
Copy Markdown

netlify Bot commented May 28, 2026

Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Name Link
🔨 Latest commit cac39f8
🔍 Latest deploy log https://app.netlify.com/projects/cockroachdb-interactivetutorials-docs/deploys/6a19e07dfcfac0000834ffa8

@rmloveland
Copy link
Copy Markdown
Contributor Author

NB this relates to #23297

@netlify
Copy link
Copy Markdown

netlify Bot commented May 28, 2026

Netlify Preview

Name Link
🔨 Latest commit cac39f8
🔍 Latest deploy log https://app.netlify.com/projects/cockroachdb-docs/deploys/6a19e07d229c970007df3068
😎 Deploy Preview https://deploy-preview-23404--cockroachdb-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@ebembi-crdb
Copy link
Copy Markdown
Contributor

Review: PR #23404 — Vendor SQL diagrams as local includes

Overview

This PR adds vendored SQL diagram HTML files under _includes/cockroach-generated/release-*/sql-diagrams/ and replaces remote_include tags pointing to cockroachdb/generated-diagrams with local {% include %} tags. It also adds 2 Python scripts for vendoring and verification.

Key findings

Strengths:

  • SQL diagram HTML files are well-formed SVG diagrams wrapped in <div> elements — spot-checked select.html, insert.html, and alter_table.html
  • Doc page updates follow the established {% capture diagram_include %}...{% endcapture %}{% include {{ diagram_include }} %} pattern consistently
  • The {% include %} path correctly maps grammar_svg/ source paths to sql-diagrams/ local paths
  • Coverage spans versions v23.1 through v26.1+ across 3,000 changed files
  • Consistent with the vendoring approach established in PR DOC-17061: Replace remote_include with vendored includes #23297

Questions / Suggestions (non-blocking):

  1. CI workflow: No GitHub Actions workflow runs the verification script on PRs. Is this planned for a follow-up? Adding a PR check that runs verify_sql_diagrams_vendored.py would prevent regressions.

  2. v26.3 coverage: Does this PR cover v26.3? Based on the file list, I see coverage through v26.1. Given that v26.3 was just added to the repo, the SQL diagrams may need to be extended to v26.3.

  3. Upstream drift: Once vendored, diagrams become static snapshots. If cockroachdb/generated-diagrams pushes grammar changes, the local copies won't update automatically. Consider adding a scheduled workflow or documenting the re-vendoring process.

LGTM overall — the approach is solid and consistent with the other vendoring PRs. @rmloveland

@rmloveland
Copy link
Copy Markdown
Contributor Author

@ebembi-crdb thanks for the review. Replying to your numbered points:

  1. I think CI validation should be follow-up work. In fact, I am fine with not checking in the script here; I included it mostly as a way of showing my work. I am planning to file a separate EDUENG Jira issue to track validation and the periodic syncing work from your point 3 going forward.

  2. Good catch. I will update this PR to vendor the v26.3 diagrams with what exists today, and we can update them going forward.

  3. I will file a separate EDUENG issue to track syncing the diagrams going forward. I would rather have a properly engineered solution from your team than try to hack something into this PR.

The supported sync and validation process should be owned by follow-up EDUENG work.
@rmloveland
Copy link
Copy Markdown
Contributor Author

Updated the PR:

  • Copied the current SQL diagram snapshot into src/current/_includes/cockroach-generated/release-26.3/sql-diagrams/ and pointed the v26.3 SQL diagram includes at that directory. This is intentionally copied from the current release-26.2 diagram snapshot until the 26.3 generated-diagrams branch exists.
  • Removed the Python helper scripts from this PR. The supported sync and validation workflow should be owned by follow-up EDUENG work instead of being improvised here.

Follow-up issue: https://cockroachlabs.atlassian.net/browse/EDUENG-764

@rmloveland rmloveland enabled auto-merge May 29, 2026 18:52
@rmloveland rmloveland merged commit 9763402 into main May 29, 2026
7 checks passed
@rmloveland rmloveland deleted the 2026-05-28-DOC-17061-remote_include-sql-diagrams branch May 29, 2026 19:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants