Driver: Add page about Erlang

[amotl]

About

What the title says.

Preview

https://cratedb-guide--420.org.readthedocs.build/connect/erlang/

[coderabbitai]

Walkthrough

Adds an Erlang driver card to the Connect index and a new docs/connect/erlang/ section with pages for odbc.md and epgsql.md containing examples, build/run instructions, dependency hints, and CrateDB Cloud SSL connection guidance.

Changes

Cohort / File(s)	Summary
Connect index docs/connect/index.md	Added an Erlang grid-item-card (link connect-erlang, link-type ref, classes sd-fs-1 sd-text-center / footer sd-fs-5 sd-font-weight-bold) with {fab\erlang`}icon and insertederlang/index` into the languages toctree.
Erlang docs (new) docs/connect/erlang/index.md, docs/connect/erlang/epgsql.md, docs/connect/erlang/odbc.md	Added Erlang section index and two pages: epgsql.md (rebar dependency epgsql tag 4.8.0, epgsql_example.erl, connect/query/cleanup examples, Cloud SSL ssl_opts usage and verify_none sample) and odbc.md (includes ODBC install include, odbc_example.erl, connection string examples including sslmode=require, escript/run instructions, and references).

Sequence Diagram(s)

sequenceDiagram
  participant App as Erlang app
  participant Driver as epgsql / ODBC
  participant CrateDB as CrateDB (Local / Cloud)

  rect rgba(220,240,255,0.6)
  App->>Driver: configure deps / start
  Driver->>CrateDB: connect(host, port, ssl_opts / conn_str)
  alt connection succeeds
    App->>Driver: execute query
    Driver->>CrateDB: send SQL
    CrateDB-->>Driver: result set
    Driver-->>App: return results
  else connection fails
    CrateDB-->>Driver: error
    Driver-->>App: error / cleanup
  end
  App->>Driver: close / cleanup
  end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Verify docs/connect/index.md toctree path and connect-erlang reference.
• Check Erlang code snippets in epgsql.md and odbc.md for syntax and runnable commands.
• Confirm Cloud SSL examples (ssl_opts, verify_none, sslmode=require) are accurate and clearly labeled.

Possibly related PRs

• Chore: Improve UI responsiveness, specifically for smaller screen sizes #426 — Modifies docs/connect/index.md driver cards/layout in the same area where Erlang card was added.
• Driver: Add page about Rust #407 — Adds a language driver card and toctree entry similar to this change (another language addition).
• Connect: Migrate pages from crate-clients-tools, to be retired soon #221 — Earlier change that created/adjusted the Connect section and toctree which this PR extends.

Suggested labels

cross linking

Suggested reviewers

• seut
• matriv

Poem

🐇 I hopped through markdown, pencil bright,
Planted Erlang pages, tucked them right.
epgsql and ODBC, examples in a row,
SSL tips snug, and ready to go.
Hops, docs, and a tidy show.

Pre-merge checks and finishing touches

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title 'Driver: Add page about Erlang' directly and clearly describes the main change in the changeset. The title accurately reflects that new Erlang driver documentation pages are being added, which is the primary focus of all four modified files. The title is concise, specific, and a teammate scanning the history would immediately understand that this PR introduces Erlang integration documentation.
Description check	✅ Passed	The pull request description is related to the changeset, though minimal. It states 'What the title says' which confirms alignment with the title's intent, and provides a preview link to the Erlang documentation page being added. While the description lacks detailed information about the specific files and changes, it is directly relevant to the changeset and not off-topic.

✨ Finishing touches

🧪 Generate unit tests (beta)

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

---

📜 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 589b8a4 and 6398449.

📒 Files selected for processing (4)

• docs/connect/erlang/epgsql.md (1 hunks)
• docs/connect/erlang/index.md (1 hunks)
• docs/connect/erlang/odbc.md (1 hunks)
• docs/connect/index.md (2 hunks)

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

• docs/connect/index.md
• docs/connect/erlang/index.md
• docs/connect/erlang/odbc.md

🧰 Additional context used

🧠 Learnings (4)

📚 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/erlang/epgsql.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/erlang/epgsql.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/erlang/epgsql.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/erlang/epgsql.md

🔇 Additional comments (4)

docs/connect/erlang/epgsql.md (4)

21-21: SSL configuration and dependencies look appropriate.

The SSL setup correctly guides users to start the SSL application before connecting, and the ssl_opts with verify_none aligns with CrateDB Cloud connection guidance. The version pin at 4.8.0 is explicit.

Also applies to: 47-48, 54-66

---

71-79: Build and run instructions are clear.

The example workflow (create files, compile with rebar3, and run) is straightforward and follows standard Erlang/rebar3 conventions.

---

73-74: No issues found; include file verified.

The file docs/connect/_cratedb.md exists at the expected location and contains appropriate generic content (Docker startup instructions) suitable for inclusion in the Erlang epgsql guide.

---

34-34: Based on my web search results, epgsql supports the map-based connect syntax with the database parameter: #{database => "test_db"}. The concern raised in the review comment appears to overgeneralize from a Postgrex-specific learning.

The learning from PR 408 explicitly addressed the Elixir Postgrex driver, which is a completely separate implementation from Erlang epgsql. While the Postgrex learning mentioned potential issues with the database parameter in CrateDB, my research found no evidence that epgsql has the same incompatibility. Different PostgreSQL-compatible drivers can behave differently depending on how they implement the PostgreSQL protocol.

The review comment incorrectly applies a Postgrex-specific concern to epgsql without verifying whether epgsql exhibits the same behavior with CrateDB. The file's use of database => "doc" in the map-based epgsql:connect() call aligns with the officially documented epgsql API.

---

Likely an incorrect or invalid review comment.

---

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

[matriv]

I think that the ssl example is not only relevant for the cloud, so I would change the title to SSL connection or similar and then explain that this is mandatory for cloud.

[amotl]

I've added an adjustment: 6398449. Let me know if you want to phrase it differently, or add a suggestion right away. Thanks!

[matriv]

Sorry if I wasn't clear, I meant about the header CreateDB Cloud.

[amotl]

Maybe I am confused? The commit replaces the header :::{rubric} CrateDB Cloud with :::{rubric} SSL connection, as you suggested.

[matriv]

I see it in the commit, but not in the PR somehow, anyway I'm approving, maybe some github hiccup? you'll figure it out.

[matriv]

It's fixed in the epgsql file but not here.

[amotl]

That was clearly an oversight, thanks. I've fixed it with GH-474.

NB: Somehow I memorized that Erlang/ODBC/SSL would not be possible / failed for me while exercising it the other day. Apparently, I remembered it wrongly, but that's the reason I didn't look into this file again. Thanks for your understanding.

[matriv]

thx!

[matriv]

I see it in the commit, but not in the PR somehow, anyway I'm approving, maybe some github hiccup? you'll figure it out.

[amotl]

FYI @matriv: This is the new text. It is included in the PR for me. Thanks again!

[matriv]

There is another place (odbc) which also says Cloud