Connect: Harmonize sections to use "SSL connection" across the board

[amotl]

Based on recent improvements, broadcast the same change to other pages.

[coderabbitai]

Walkthrough

Documentation across multiple language drivers (Elixir, Go, Java, ODBC, R, Rust) updated: rubric headings renamed from "CrateDB Cloud" to "SSL connection," guidance text generalized by removing CrateDB Cloud-specific phrasing, and clarifying notes added explaining that SSL variants connect to CrateDB Cloud.

Changes

Cohort / File(s)	Summary
Elixir docs/connect/elixir/index.md	Renamed rubric from "CrateDB Cloud" to "SSL connection"; simplified guidance text and added clarifying note about using SSL variant for Cloud connections.
Go docs/connect/go/ksql.md, docs/connect/go/pgx.md, docs/connect/go/pq.md	Renamed rubric headings to "SSL connection"; generalized guidance by removing Cloud-specific phrasing; added clarifying notes and concrete example URLs with sslmode=require; updated example headers and added include directives and shell commands in ksql.md.
Java docs/connect/java/cratedb-jdbc.md, docs/connect/java/postgresql-jdbc.md	Renamed rubric to "SSL connection"; updated narrative from CrateDB Cloud-specific to generic form; added clarifying notes and updated code examples with SSL parameters and Cloud credentials.
ODBC docs/connect/odbc/csharp.md, docs/connect/odbc/python.md	Renamed rubric headers to "SSL connection"; updated guidance text by removing Cloud-specific language; added clarifying notes; updated connection strings to include Sslmode=require parameter.
R docs/connect/r/index.md	Renamed rubric to "SSL connection"; generalized guidance text; added clarifying note; updated code example to demonstrate SSL-enabled Cloud variant with Cloud hostname and credentials.
Rust docs/connect/rust/index.md	Renamed synopsis to "SSL connection"; updated narrative instructions for TLS support; added new code example blocks showing TLS usage with CrateDB Cloud; added clarifying note about SSL variant for Cloud connections.

Sequence Diagram(s)

No sequence diagram applicable—changes are documentation refactoring and text updates without control-flow modifications.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~20 minutes

The changes follow a highly consistent pattern across all files: renaming section headers, generalizing guidance text, and adding clarifying notes. While spanning 10 files, the repetitive nature and documentation-only scope keep complexity low.

• Attention areas: Verify consistency of phrasing and SSL parameter values across all language drivers; confirm code examples in go/ksql.md and rust/index.md match their respective language conventions.

Possibly related PRs

• Driver: Add page about Rust #407: Modifies docs/connect/rust/index.md with Rust connection examples and CrateDB Cloud SSL usage—directly related to changes in this PR.
• Driver: Improve section about Java #402: Modifies docs/connect/java/cratedb-jdbc.md—directly related to Java JDBC documentation updates in this PR.

Suggested labels

guidance, refactoring

Suggested reviewers

• kneth
• surister
• matriv

Poem

🐰 With SSL now clear and Cloud usage bright,
Our docs unite in harmonious flight,
From Go to Rust, from Java to R,
One vision glows like a guiding star—
Secure connections for all to find,
Simpler guidance, unified mind! ✨

Pre-merge checks and finishing touches

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: harmonizing section headers from 'CrateDB Cloud' to 'SSL connection' across multiple documentation files.
Description check	✅ Passed	The description is related to the changeset, referencing 'recent improvements' and broadcasting the same change to other pages, which aligns with the harmonization of SSL connection sections across documentation.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch ssl-vs-cloud

---

📜 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 fa9a0c9 and 428c128.

📒 Files selected for processing (10)

• docs/connect/elixir/index.md (1 hunks)
• docs/connect/go/ksql.md (1 hunks)
• docs/connect/go/pgx.md (1 hunks)
• docs/connect/go/pq.md (1 hunks)
• docs/connect/java/cratedb-jdbc.md (1 hunks)
• docs/connect/java/postgresql-jdbc.md (1 hunks)
• docs/connect/odbc/csharp.md (1 hunks)
• docs/connect/odbc/python.md (1 hunks)
• docs/connect/r/index.md (1 hunks)
• docs/connect/rust/index.md (1 hunks)

🧰 Additional context used

🧠 Learnings (10)

📓 Common learnings

Learnt from: amotl
Repo: crate/cratedb-guide PR: 420
File: docs/connect/erlang.md:100-113
Timestamp: 2025-10-19T19:21:49.864Z
Learning: In the cratedb-guide repository, when documenting cloud or alternative connection methods, show only the differences from the canonical example (e.g., SSL configuration) rather than repeating the entire workflow (query execution, cleanup, etc.). This pattern is used consistently across pages to avoid repetition.

Learnt from: bmunkholm
Repo: crate/cratedb-guide PR: 340
File: docs/home/index.md:84-97
Timestamp: 2025-09-25T19:31:54.320Z
Learning: In the CrateDB Guide docs (MyST), the CrateDB Cloud card on the homepage should link to `getting-started` using `:link-type: ref` instead of the previous `cloud:index` intersphinx target. This change was implemented in PR #340 to direct users to the getting started section rather than directly to the Cloud documentation.

Learnt from: amotl
Repo: crate/cratedb-guide PR: 406
File: docs/connect/go.md:110-137
Timestamp: 2025-10-20T21:49:18.785Z
Learning: In the cratedb-guide repository, documentation examples for connecting to CrateDB (e.g., Go examples in docs/connect/go.md) should be kept minimal and focused on demonstrating basic functionality, rather than including comprehensive error handling. Full examples with proper error handling are maintained separately in the cratedb-examples repository.

Learnt from: amotl
Repo: crate/cratedb-guide PR: 253
File: docs/integrate/mindsdb/index.md:21-33
Timestamp: 2025-08-14T19:02:43.308Z
Learning: In CrateDB integration documentation examples, default connection parameters (user="crate", password="", host="127.0.0.1") are intentionally used to provide working out-of-the-box examples for users with local CrateDB instances, rather than using placeholder values that require customization.

Learnt from: amotl
Repo: crate/cratedb-guide PR: 408
File: docs/connect/elixir.md:18-22
Timestamp: 2025-10-16T10:58:18.401Z
Learning: When connecting to CrateDB using PostgreSQL-compatible drivers like Postgrex (Elixir), the `database` parameter handling may differ from standard PostgreSQL usage because CrateDB has no notion of databases like PostgreSQL does. CrateDB uses schemas to separate concerns instead. The `database` parameter might need to be omitted or handled differently to avoid connection issues.

Learnt from: amotl
Repo: crate/cratedb-guide PR: 0
File: :0-0
Timestamp: 2025-10-06T16:40:16.322Z
Learning: In the crate/cratedb-guide repository, documentation is organized by content type: files in `docs/feature/`, `docs/integrate/`, and `docs/ingest/` are reference material designed for quick access, while `docs/start/` contains learning path content. Reference material sections use top-right reference layouts for efficient navigation.

Learnt from: amotl
Repo: crate/cratedb-guide PR: 385
File: docs/connect/java.md:48-51
Timestamp: 2025-10-08T01:34:18.867Z
Learning: CrateDB JDBC driver uses the `jdbc:crate://` protocol scheme but communicates via the PostgreSQL wire protocol on port 5432, just like the PostgreSQL JDBC driver (`jdbc:postgresql://`). Do not confuse the `jdbc:crate://` scheme with other protocol schemes like `crate://` (used by SQLAlchemy dialect for CrateDB) or assume it uses the HTTP endpoint on port 4200.

Learnt from: hammerhead
Repo: crate/cratedb-guide PR: 221
File: docs/connect/configure.md:58-66
Timestamp: 2025-08-05T07:14:57.416Z
Learning: In CrateDB connection strings, the user:password@ syntax is valid for HTTP Basic authentication on port 4200, but PostgreSQL JDBC drivers do not support this format and require credentials as query parameters (?user=<user>&password=<password>) instead.

Learnt from: amotl
Repo: crate/cratedb-guide PR: 465
File: docs/admin/troubleshooting/system-tables.md:6-6
Timestamp: 2025-10-30T23:12:30.204Z
Learning: In the cratedb-guide repository, documentation headers and titles should use sentence case (e.g., "Diagnostics with system tables") rather than title case (e.g., "Diagnostics with System Tables"). This style choice enables headers to be referenced more fluently within sentences.

Learnt from: amotl
Repo: crate/cratedb-guide PR: 279
File: docs/integrate/airflow/data-retention-hot-cold.md:14-14
Timestamp: 2025-09-22T22:05:05.734Z
Learning: When searching for labels in the CrateDB Guide documentation, remember that reStructuredText files (.rst) use the syntax `.. _label:` while MyST Markdown files (.md) use the syntax `(label)=`. Cross-references work between formats, so {ref}`label` in MyST can reference an RST label defined with `.. _label:`.

📚 Learning: 2025-10-19T19:21:49.864Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 420
File: docs/connect/erlang.md:100-113
Timestamp: 2025-10-19T19:21:49.864Z
Learning: In the cratedb-guide repository, when documenting cloud or alternative connection methods, show only the differences from the canonical example (e.g., SSL configuration) rather than repeating the entire workflow (query execution, cleanup, etc.). This pattern is used consistently across pages to avoid repetition.

Applied to files:

• docs/connect/java/cratedb-jdbc.md
• docs/connect/java/postgresql-jdbc.md
• docs/connect/rust/index.md
• docs/connect/r/index.md
• docs/connect/go/ksql.md
• docs/connect/odbc/python.md
• docs/connect/go/pgx.md
• docs/connect/go/pq.md
• docs/connect/elixir/index.md
• docs/connect/odbc/csharp.md

📚 Learning: 2025-08-14T19:02:43.308Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 253
File: docs/integrate/mindsdb/index.md:21-33
Timestamp: 2025-08-14T19:02:43.308Z
Learning: In CrateDB integration documentation examples, default connection parameters (user="crate", password="", host="127.0.0.1") are intentionally used to provide working out-of-the-box examples for users with local CrateDB instances, rather than using placeholder values that require customization.

Applied to files:

• docs/connect/java/cratedb-jdbc.md
• docs/connect/java/postgresql-jdbc.md
• docs/connect/rust/index.md
• docs/connect/r/index.md
• docs/connect/go/ksql.md
• docs/connect/odbc/python.md
• docs/connect/go/pgx.md
• docs/connect/go/pq.md
• docs/connect/elixir/index.md
• docs/connect/odbc/csharp.md

📚 Learning: 2025-08-05T07:14:57.416Z

Learnt from: hammerhead
Repo: crate/cratedb-guide PR: 221
File: docs/connect/configure.md:58-66
Timestamp: 2025-08-05T07:14:57.416Z
Learning: In CrateDB connection strings, the user:password@ syntax is valid for HTTP Basic authentication on port 4200, but PostgreSQL JDBC drivers do not support this format and require credentials as query parameters (?user=<user>&password=<password>) instead.

Applied to files:

• docs/connect/java/cratedb-jdbc.md
• docs/connect/java/postgresql-jdbc.md
• docs/connect/rust/index.md
• docs/connect/r/index.md
• docs/connect/go/ksql.md
• docs/connect/odbc/python.md
• docs/connect/go/pgx.md
• docs/connect/go/pq.md
• docs/connect/elixir/index.md
• docs/connect/odbc/csharp.md

📚 Learning: 2025-06-05T14:29:15.512Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 207
File: docs/integrate/etl/iceberg-risingwave.md:205-207
Timestamp: 2025-06-05T14:29:15.512Z
Learning: The `records.Database("crate://", echo=True)` connection string for CrateDB works with defaults: localhost as host, "crate" as user, and blank password. This is valid and functional code in the records library.

Applied to files:

• docs/connect/java/cratedb-jdbc.md
• docs/connect/java/postgresql-jdbc.md
• docs/connect/rust/index.md
• docs/connect/r/index.md
• docs/connect/go/ksql.md
• docs/connect/odbc/python.md
• docs/connect/go/pgx.md
• docs/connect/go/pq.md
• docs/connect/elixir/index.md
• docs/connect/odbc/csharp.md

📚 Learning: 2025-10-08T01:34:18.867Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 385
File: docs/connect/java.md:48-51
Timestamp: 2025-10-08T01:34:18.867Z
Learning: CrateDB JDBC driver uses the `jdbc:crate://` protocol scheme but communicates via the PostgreSQL wire protocol on port 5432, just like the PostgreSQL JDBC driver (`jdbc:postgresql://`). Do not confuse the `jdbc:crate://` scheme with other protocol schemes like `crate://` (used by SQLAlchemy dialect for CrateDB) or assume it uses the HTTP endpoint on port 4200.

Applied to files:

• docs/connect/java/cratedb-jdbc.md
• docs/connect/java/postgresql-jdbc.md
• docs/connect/rust/index.md
• docs/connect/r/index.md
• docs/connect/go/ksql.md
• docs/connect/odbc/python.md
• docs/connect/go/pgx.md
• docs/connect/go/pq.md
• docs/connect/odbc/csharp.md

📚 Learning: 2025-10-16T10:58:18.401Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 408
File: docs/connect/elixir.md:18-22
Timestamp: 2025-10-16T10:58:18.401Z
Learning: When connecting to CrateDB using PostgreSQL-compatible drivers like Postgrex (Elixir), the `database` parameter handling may differ from standard PostgreSQL usage because CrateDB has no notion of databases like PostgreSQL does. CrateDB uses schemas to separate concerns instead. The `database` parameter might need to be omitted or handled differently to avoid connection issues.

Applied to files:

• docs/connect/java/cratedb-jdbc.md
• docs/connect/java/postgresql-jdbc.md
• docs/connect/rust/index.md
• docs/connect/r/index.md
• docs/connect/go/ksql.md
• docs/connect/odbc/python.md
• docs/connect/go/pgx.md
• docs/connect/go/pq.md
• docs/connect/elixir/index.md
• docs/connect/odbc/csharp.md

📚 Learning: 2025-08-14T12:42:12.744Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 248
File: docs/integrate/amqp/tutorial.md:36-41
Timestamp: 2025-08-14T12:42:12.744Z
Learning: In the cratedb-guide repository, code examples and tutorials prioritize simplicity and ease of following over security hardening. Security recommendations should be more lenient in tutorial/demo contexts to avoid distracting from the main learning objectives.

Applied to files:

• docs/connect/java/postgresql-jdbc.md

📚 Learning: 2025-09-25T19:31:54.320Z

Learnt from: bmunkholm
Repo: crate/cratedb-guide PR: 340
File: docs/home/index.md:84-97
Timestamp: 2025-09-25T19:31:54.320Z
Learning: In the CrateDB Guide docs (MyST), the CrateDB Cloud card on the homepage should link to `getting-started` using `:link-type: ref` instead of the previous `cloud:index` intersphinx target. This change was implemented in PR #340 to direct users to the getting started section rather than directly to the Cloud documentation.

Applied to files:

• docs/connect/java/postgresql-jdbc.md
• docs/connect/rust/index.md
• docs/connect/odbc/python.md
• docs/connect/elixir/index.md

📚 Learning: 2025-10-20T21:49:18.785Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 406
File: docs/connect/go.md:110-137
Timestamp: 2025-10-20T21:49:18.785Z
Learning: In the cratedb-guide repository, documentation examples for connecting to CrateDB (e.g., Go examples in docs/connect/go.md) should be kept minimal and focused on demonstrating basic functionality, rather than including comprehensive error handling. Full examples with proper error handling are maintained separately in the cratedb-examples repository.

Applied to files:

• docs/connect/java/postgresql-jdbc.md
• docs/connect/rust/index.md
• docs/connect/go/ksql.md
• docs/connect/go/pgx.md
• docs/connect/go/pq.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Build docs

🔇 Additional comments (11)

docs/connect/elixir/index.md (1)

55-62: Clear harmonization with good context bridge.

The heading change to "SSL connection" and the updated guidance text successfully harmonize the documentation while maintaining clarity. The added line clarifying that this variant is also used for CrateDB Cloud provides helpful context, bridging the SSL configuration topic with Cloud connectivity without creating ambiguity.

The section structure—showing only the configuration differences from the canonical example rather than repeating the full workflow—aligns with established patterns across the documentation.

docs/connect/go/pgx.md (1)

64-75: Excellent harmonization of SSL connection documentation.

The refactoring successfully establishes a unified "SSL connection" rubric and pattern across the documentation. The guidance text is clear, the Cloud variant note is helpful, and the connection example properly demonstrates the required sslmode parameter.

docs/connect/odbc/csharp.md (1)

59-69: Well-structured SSL connection section for ODBC.

The new section correctly uses ODBC-specific parameter capitalization (Sslmode=require) and follows the established pattern. The guidance text and Cloud variant note align perfectly with the documentation harmonization across other drivers.

docs/connect/go/ksql.md (1)

77-100: Consistent SSL connection refactoring with helpful additions.

The rubric rename and guidance text follow the established pattern well. The addition of code creation instructions and shell commands (lines 92–100) provides practical context for running the example, consistent with similar changes in other Go driver documentation.

docs/connect/java/cratedb-jdbc.md (1)

64-79: Clear SSL connection guidance for CrateDB JDBC.

The refactored section successfully generalizes the guidance from Cloud-specific to SSL-focused, while maintaining the JDBC-specific connection setup (Properties object and credentials). The example correctly demonstrates the required sslmode=require parameter.

docs/connect/java/postgresql-jdbc.md (1)

64-79: Harmonized SSL connection documentation for PostgreSQL JDBC.

Consistent with the CrateDB JDBC changes, this section properly refactors the rubric and guidance to emphasize SSL connection regardless of destination (local or Cloud). The connection example correctly uses sslmode=require and placeholder credentials.

docs/connect/odbc/python.md (1)

124-135: Well-integrated SSL connection section for ODBC Python.

The new section correctly applies ODBC parameter syntax (Sslmode=require) and follows the unified documentation pattern. The connection string example is practical and the Cloud variant note provides clear guidance.

docs/connect/rust/index.md (1)

54-92: Comprehensive SSL/TLS connection example for Rust.

The refactored section effectively demonstrates the Rust-specific TLS setup using native_tls and postgres_native_tls crates. The connection string correctly uses sslmode=require with placeholder format for cluster details. The cargo add commands accurately reflect the additional dependencies required for TLS support.

docs/connect/r/index.md (1)

55-72: Consistent SSL connection documentation for R.

The refactored section properly emphasizes SSL connection guidance with R-specific parameter syntax (sslmode="require" with quotes). The RPostgres connection example correctly demonstrates the Cloud variant with admin credentials and required sslmode parameter.

docs/connect/go/pq.md (2)

44-54: Excellent harmonization of SSL connection guidance.

The section restructuring properly communicates the dual purpose of the SSL variant (local SSL connections and CrateDB Cloud) while maintaining the minimal documentation pattern. The explicit note "Also use this variant to connect to CrateDB Cloud" makes the connection clear without unnecessary verbosity.

---

56-67: Section rename appropriately aligns with documentation structure.

The shift from "Quickstart example" to "Example" maintains consistency with other language driver documentation in this PR while keeping the instructions clear and actionable.

---

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.}