Driver: Add page about Zig by amotl · Pull Request #419 · crate/cratedb-guide

amotl · 2025-10-17T19:55:54Z

About

What the title says.

Preview

https://cratedb-guide--419.org.readthedocs.build/connect/zig/

coderabbitai · 2025-10-17T19:56:07Z

Warning

Rate limit exceeded

@amotl has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 19 minutes and 56 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 044df39 and acba932.

⛔ Files ignored due to path filters (1)

docs/_assets/icon/zig-logo.png is excluded by !**/*.png

📒 Files selected for processing (3)

docs/conf.py
docs/connect/index.md
docs/connect/zig/index.md

Walkthrough

Adds documentation for a Zig CrateDB driver: a new driver page with examples and build snippets, updates the main Connect drivers index to include a Zig card and navigation entry, and appends an OpenTelemetry URL to docs linkcheck_ignore.

Changes

Cohort / File(s)	Summary
Zig driver docs `docs/connect/zig/index.md`, `docs/connect/index.md`	New Zig driver page with build and usage examples; main drivers index updated with a Zig grid-item-card and added toctree entry.
Docs config `docs/conf.py`	Added `https://opentelemetry.io/` to `linkcheck_ignore` (read-timeout comment).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

Driver: Add page about Elixir #408 — Adds a new driver page and updates docs/connect/index.md with a driver card/toctree entry (same area changed).
Connect: Migrate pages from crate-clients-tools, to be retired soon #221 — Prior edits to the drivers index; touches the same docs/connect/index.md region.
Driver: Add page about Rust #407 — Similar documentation addition: new language driver page, index card, and docs/conf.py linkcheck update.

Suggested labels

cross linking

Suggested reviewers

seut
matriv

Poem

🐰 I hopped through docs with a twinkling jig,
Wrote a Zig card and a tiny big gig.
Build scripts in burrows, examples so neat,
CrateDB meets Zig — a carrot-y treat! 🥕

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Driver: Add page about Zig' directly matches the main change: adding a new Zig driver documentation page with integration into the drivers index.
Description check	✅ Passed	The description is related to the changeset, confirming the addition of a Zig documentation page and providing a preview link.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

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

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

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

docs/connect/zig/index.md

kneth

Let's discuss https://github.com/crate/tech-content/issues/124#issuecomment-3485676563 before merging

amotl · 2026-01-21T07:33:56Z

I think it's nice to have a dedicated page about Zig, so that all downstream entities (humans and machines) can easily learn how to connect to CrateDB using the PostgreSQL interface, and use a ready-to-run example to exercise it right away.

In the long run, this will also improve network effects, because CrateDB gains a dedicated representation within the corresponding search- and vectorspaces.

Currently, relevant search keywords like cratedb zig will not yield concise results, but this will improve a few days after merging this patch.

matriv

left a couple of comments, thx!

matriv · 2026-01-21T11:02:37Z

docs/connect/zig/index.md

+    const exe = b.addExecutable(.{
+        .name = "example",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("example.zig"),


what is this file: example.zig? I don't think it's explained.

It is the program right below the build script.

I think we should clarify this.

I've tried with acba932, thanks.

matriv · 2026-01-21T11:03:51Z

docs/connect/zig/index.md

+:::{rubric} CrateDB Cloud
+:::
+
+For connecting to CrateDB Cloud, use the `sslmode=require` parameter,


Suggested change

For connecting to CrateDB Cloud, use the `sslmode=require` parameter,

For connecting to a CrateDB node with ssl enabled (e.g.: CrateDB Cloud), use the `sslmode=require` parameter,

Maybe this wording is better to reveal more generic usage?

Right, we even renamed the headline on previous patches. 044df39 does the same here.

coderabbitai

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@docs/connect/zig/index.md`:
- Around line 43-44: Add a one-line clarification after the `example.zig`
filename stating that `example.zig` is the program produced by running
`build.zig`; reference both filenames (`example.zig`, `build.zig`) so readers
understand that `build.zig` builds the `example.zig` executable.
- Around line 55-56: Update the example connection URI to use the default empty
local password: change the const uri assignment that calls std.Uri.parse
(currently "postgresql://crate:crate@localhost/?sslmode=disable") to omit the
password so the URI becomes "postgresql://crate@localhost/?sslmode=disable"
before calling pg.Pool.initUri with allocator and pool.

🧹 Nitpick comments (2)

docs/connect/zig/index.md (2)
23-31: Honor the selected target in the build example.

Using b.graph.host ignores b.standardTargetOptions, so cross-compiles won’t follow the user-selected target. Consider wiring .target = target instead.
♻️ Proposed fix
-        .root_module = b.createModule(.{
-            .root_source_file = b.path("example.zig"),
-            .target = b.graph.host,
-        })
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("example.zig"),
+            .target = target,
+        })
73-75: Pin pg.zig to a tag/commit instead of #master.

Using #master is non-reproducible and may break as upstream changes. Prefer a release tag or commit hash.
♻️ Example pin
-zig fetch --save git+https://github.com/karlseguin/pg.zig#master
+zig fetch --save git+https://github.com/karlseguin/pg.zig#vX.Y.Z

docs/connect/zig/index.md

coderabbitai · 2026-01-21T11:10:25Z

docs/connect/zig/index.md

+    const uri = try std.Uri.parse("postgresql://crate:crate@localhost/?sslmode=disable");
+    var pool = try pg.Pool.initUri(allocator, uri, .{.size=5, .timeout=5_000});


⚠️ Potential issue | 🟠 Major

Use default credentials in the local URI.

The example uses a non-default password (crate), which breaks the out-of-the-box local setup where password is empty. Please align with default connection parameters. Based on learnings, ...

✅ Proposed fix

- const uri = try std.Uri.parse("postgresql://crate:crate@localhost/?sslmode=disable"); + const uri = try std.Uri.parse("postgresql://crate@localhost/?sslmode=disable");

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

const uri = try std.Uri.parse("postgresql://crate:crate@localhost/?sslmode=disable");

var pool = try pg.Pool.initUri(allocator, uri, .{.size=5, .timeout=5_000});

const uri = try std.Uri.parse("postgresql://crate@localhost/?sslmode=disable");

var pool = try pg.Pool.initUri(allocator, uri, .{.size=5, .timeout=5_000});

🤖 Prompt for AI Agents

In `@docs/connect/zig/index.md` around lines 55 - 56, Update the example connection URI to use the default empty local password: change the const uri assignment that calls std.Uri.parse (currently "postgresql://crate:crate@localhost/?sslmode=disable") to omit the password so the URI becomes "postgresql://crate@localhost/?sslmode=disable" before calling pg.Pool.initUri with allocator and pool.

matriv · 2026-01-21T11:15:55Z

docs/connect/zig/index.md

+    b.installArtifact(exe);
+}
+```
+`example.zig`


I would define this first, and then the above code which uses it.

Thanks, I've added acba932.

amotl added the cross linking Linking to different locations of the documentation. label Oct 17, 2025

This comment was marked as resolved.

Sign in to view

amotl force-pushed the zig branch from 0caaf3f to de80888 Compare October 17, 2025 22:32

amotl requested review from kneth and surister October 17, 2025 22:33

This comment was marked as duplicate.

Sign in to view

amotl added new content New content being added. and removed cross linking Linking to different locations of the documentation. labels Oct 18, 2025

amotl force-pushed the zig branch 3 times, most recently from 4722c90 to 12be5ca Compare October 18, 2025 22:23

amotl commented Oct 19, 2025

View reviewed changes

docs/connect/zig/index.md Show resolved Hide resolved

amotl force-pushed the zig branch from 12be5ca to d0efb5a Compare October 21, 2025 13:02

kneth reviewed Nov 14, 2025

View reviewed changes

amotl force-pushed the zig branch from d0efb5a to 9877644 Compare January 21, 2026 07:32

amotl requested review from matriv and seut and removed request for surister January 21, 2026 07:33

matriv reviewed Jan 21, 2026

View reviewed changes

coderabbitai bot reviewed Jan 21, 2026

View reviewed changes

matriv approved these changes Jan 21, 2026

View reviewed changes

amotl added 3 commits January 21, 2026 12:16

Connect: Add Zig

a7a42e1

Chore: Satisfy link checker

6e87ae2

Connect: Improve "SSL connection" option on Zig page

c647844

amotl force-pushed the zig branch from 044df39 to acba932 Compare January 21, 2026 11:17

Connect: Clarify what example.zig is

acba932

amotl merged commit 3b26497 into main Jan 21, 2026
3 checks passed

amotl deleted the zig branch January 21, 2026 11:22

This was referenced Jan 21, 2026

Driver: Add page about Perl #418

Merged

Driver: Add page about Raku #477

Draft

	For connecting to CrateDB Cloud, use the `sslmode=require` parameter,
	For connecting to a CrateDB node with ssl enabled (e.g.: CrateDB Cloud), use the `sslmode=require` parameter,

		const uri = try std.Uri.parse("postgresql://crate:crate@localhost/?sslmode=disable");
		var pool = try pg.Pool.initUri(allocator, uri, .{.size=5, .timeout=5_000});

Conversation

amotl commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

About

Preview

Uh oh!

coderabbitai bot commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rate limit exceeded

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as duplicate.

Uh oh!

Uh oh!

kneth left a comment

Choose a reason for hiding this comment

Uh oh!

amotl commented Jan 21, 2026

Uh oh!

matriv left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai bot Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

amotl commented Oct 17, 2025 •

edited

Loading

coderabbitai bot commented Oct 17, 2025 •

edited

Loading