Driver: Add page about ODBC

[amotl]

About

What the title says.

Preview

https://cratedb-guide--411.org.readthedocs.build/connect/odbc/

[coderabbitai]

Walkthrough

Adds ODBC driver documentation: a new ODBC docs section (index, setup body, setup widget), ODBC links, and a Language-agnostic ODBC card plus a toctree entry on the Connect index page; also adds an isql subsection to CLI docs.

Changes

Cohort / File(s)	Summary
Connect index & links docs/connect/index.md, docs/_include/links.md	Inserts a Language-agnostic "ODBC" card into the drivers grid and adds odbc/index to the toctree; adds external links for psqlODBC, psqlODBC download, and unixODBC.
ODBC documentation pages docs/connect/odbc/index.md	Adds a new ODBC documentation page with overview, driver/DSN guidance, multi-language connectivity examples (C#, Erlang, Python pyodbc/turbodbc, Visual Basic), sample queries, cleanup steps, and external references.
ODBC setup fragments docs/connect/odbc/setup-body.md, docs/connect/odbc/setup-widget.md	Adds setup instructions for Windows/Linux/macOS, sample odbcinst.ini and registration command, DSN/DSN-less connection examples, and a reusable setup widget that embeds the setup body.
CLI docs docs/connect/application.md	Adds an isql subsection describing unixODBC usage, setup-widget reference, and tabbed INI/echo examples for CrateDB Cloud and localhost.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Diátaxis: Index how-to guides and tutorials #364 — Adds/modifies entries in docs/_include/links.md, overlapping link additions.
• Navigation: Relocate reference links in learning path sections #379 — Edits the documentation link registry and connect index entries related to ODBC resources.
• Connect: Reorganize and clean up section #361 — Adjusts drivers layout on docs/connect/index.md, likely overlapping where the ODBC card and toctree entry were inserted.

Suggested labels

guidance

Suggested reviewers

• kneth
• surister

Poem

🐰 I hopped through docs with a tiny cheer,

Added ODBC trails both far and near,
Drivers, setup, and examples galore,
From isql to Python — connections adore! 🥕

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title "Driver: Add page about ODBC" directly summarizes the main objective of the pull request. The changeset adds comprehensive ODBC documentation across multiple new files (docs/connect/odbc/index.md, setup-body.md, setup-widget.md) and integrates it into the existing documentation structure by updating docs/connect/index.md, docs/_include/links.md, and docs/connect/application.md. The title captures the primary purpose—adding ODBC documentation to the guide—in a clear and specific manner without vague language or unnecessary noise.
Description Check	✅ Passed	The description is minimalist but directly related to the changeset. It explicitly states the PR purpose is "What the title says," referencing the ODBC documentation addition, and provides a preview link to the deployed documentation. While the description lacks detailed explanation of the changes, it remains on-topic and related to the changeset, meeting the lenient criteria for this check.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch odbc

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0614231 and 65c3c71.

📒 Files selected for processing (3)

• docs/connect/application.md (1 hunks)
• docs/connect/odbc/index.md (1 hunks)
• docs/connect/odbc/setup-widget.md (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/connect/odbc/setup-widget.md

🧰 Additional context used

🧠 Learnings (2)

📚 Learning: 2025-10-10T17:58:26.545Z

Learnt from: amotl
PR: crate/cratedb-guide#395
File: docs/install/cloud/azure/terraform.md:108-127
Timestamp: 2025-10-10T17:58:26.545Z
Learning: In the crate/cratedb-guide repository, during documentation format conversions (e.g., from reStructuredText to MyST/Markdown), markdownlint warnings such as MD053 (unused reference-style links) should be ignored and not flagged as issues.

Applied to files:

• docs/connect/odbc/index.md

📚 Learning: 2025-10-07T10:19:41.866Z

Learnt from: amotl
PR: crate/cratedb-guide#364
File: docs/tutorial/index.md:48-55
Timestamp: 2025-10-07T10:19:41.866Z
Learning: In MyST (Markdown Structured Text) syntax used in the CrateDB Guide docs, bare URLs in directive options like `:link:` are perfectly valid and expected. For example, `:::{card} :link: https://learn.cratedb.com/ :::` is correct MyST syntax. The markdownlint MD034 warning for bare URLs in these directive options is a false positive because markdownlint doesn't understand MyST-specific syntax.

Applied to files:

• docs/connect/odbc/index.md

🪛 markdownlint-cli2 (0.18.1)

docs/connect/odbc/index.md

35-35: No space inside hashes on closed atx style heading

(MD020, no-missing-space-closed-atx)

---

81-81: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

151-151: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (6)

docs/connect/application.md (1)

109-155: Well-integrated isql documentation.

The new isql section follows the established pattern of other CLI tools (crash, psql, HTTPie, curl) with properly structured tab-set examples, correct sync attributes, and accurate description of unixODBC tool functionality. The INI configuration examples and piped iusql commands align with the documentation style.

docs/connect/odbc/index.md (5)

1-27: Header and includes properly structured.

The document correctly includes the links file for reference definitions, establishes clear labels for cross-references, and includes the setup-widget content as documented in the broader ODBC surface.

---

35-66: C# example is correct and well-structured.

The code example demonstrates proper ODBC usage: connection initialization with connection string, OdbcCommand correctly instantiated with the connection, GetInt32() properly retrieving the integer column, and resources cleaned up in the correct order. Previous issues have been resolved.

---

68-116: Erlang and Python examples are clear and idiomatic.

Both examples follow DB API conventions appropriate to their respective languages. The pyodbc example uses standard connection/cursor/execute patterns, and the Erlang example correctly demonstrates the ODBC application interface. Code samples are concise and demonstrate the key operations (connect, query, iterate, cleanup).

---

118-187: Python turbodbc and Visual Basic examples are complete and correct.

The turbodbc example mirrors pyodbc structure for consistency while highlighting the high-performance library option. The Visual Basic example uses appropriate ADODB patterns with proper field access notation (rs!field) and iteration (MoveNext). Both examples maintain the establish pattern of connect → query → display → cleanup.

---

190-197: Reference links properly defined.

All reference-style links used in the file are defined locally. The combination of the included links.md file (providing shared references like [ODBC]) and local definitions (language-specific links) creates appropriate separation of concerns.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[amotl]

See also

• https://learn.microsoft.com/en-us/sql/odbc/microsoft-open-database-connectivity-odbc

[amotl]

See also Windows Data Access Components (Windows DAC) cmdlets.

• https://learn.microsoft.com/en-us/powershell/module/wdac/

E.g., let's add an example using Add-OdbcDsn?