Use auto-generated session settings from CockroachDB source code

[rmloveland]

Fixes DOC-12507

[netlify]

✅ Deploy Preview for cockroachdb-api-docs canceled.

Name	Link
🔨 Latest commit	de4b67d
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-api-docs/deploys/6a05ed37a2a4ac0008ae2da1

[netlify]

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

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

[netlify]

✅ Netlify Preview

Name	Link
🔨 Latest commit	de4b67d
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-docs/deploys/6a05ed36a1c27d0008be2794
😎 Deploy Preview	https://deploy-preview-23251--cockroachdb-docs.netlify.app
📱 Preview on mobile	Toggle 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]

Files changed:

• src/current/_includes/v26.2/misc/session-vars.md:
• src/current/v26.2/set-vars.md
• src/current/v26.2/session-variables.md
• src/current/v26.2/show-vars.md

[rmloveland]

@rafiss this is the docs update to pull in the autogenerated session settings you added in cockroachdb/cockroach#142228 !

[rafiss]

amazing! thanks for doing htis

[taroface]

I think this automation is badly needed and overdue, so thank you for making it happen.

That said, I'm concerned that it completely erases the manual documentation of the settings, which in many cases were more descriptive and refined. Modest example: inject_retry_errors_enabled here versus in our docs. I'm not sure how to address this gap. What do you think about it?

Technical issue: The code formatting in the autogenerated table is not rendering correctly. I think we encountered this in the logging reference docs but don't recall how we fixed it.

[rmloveland]

I think this automation is badly needed and overdue, so thank you for making it happen.

thanks Ryan!

That said, I'm concerned that it completely erases the manual documentation of the settings, which in many cases were more descriptive and refined. Modest example: inject_retry_errors_enabled here versus in our docs. I'm not sure how to address this gap. What do you think about it?

it's a valid concern. i'm not entirely sure if the gap can be fully addressed tbh. i did participate on the review of Rafi's original PR (see here for my comments) to try to help offset some of the loss of fidelity due to the lack of support for e.g. links to docs pages from inside the generated docs.

that said i think it's an overall win for users (and their agents ofc) due to the dozens of settings that were previously not documented at all. I'm def open to making a followup issue to try to improve the docs in the settings file even more. what do you think?

Technical issue: The code formatting in the autogenerated table is not rendering correctly. I think we encountered this in the logging reference docs but don't recall how we fixed it.

i think i found an example - the backticks inside the table cell are not rendering.

my guess is because Jekyll's markdown renderer gets confused since it's quite likely regex-based and it's already inside an HTML table. Here's a representative row:

<tr><td><code>sql_safe_updates</code></td><td>When enabled, disallows potentially unsafe SQL statements: `DROP DATABASE` of a non-empty database, `DELETE` and `UPDATE` without a `WHERE` clause (unless a `LIMIT` clause is included), `SELECT ... FOR UPDATE`/`FOR SHARE` without a `WHERE` or `LIMIT` clause, `ALTER TABLE ... DROP COLUMN`, and converting an existing table to `REGIONAL BY ROW` unless a region column has already been added.</td><td><code>off</code></td><td>No</td><td>-</td></tr>

i think the fix is to PR cockroachdb/cockroach to make everything in backticks use HTML code tags instead. In other words, everything should be HTML. I will also file a followup issue to fix that

[taroface]

LGTM provided those 2 followup issues are created sometime!

[rmloveland]

LGTM provided those 2 followup issues are created sometime!

thanks Ryan!

Filed the followup issues:

1. https://cockroachlabs.atlassian.net/browse/DOC-17094 to do the work on updating the descriptions in the CRDB repo

2. https://cockroachlabs.atlassian.net/browse/DOC-17095 to fix the HTML formatting in the session var docs in the DB repo