Skip to content

Connect: Improve guidance re. learning path and reference styles #383

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 8, 2025
Merged

Connect: Improve guidance re. learning path and reference styles #383

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 61 additions & 55 deletions docs/connect/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,66 +4,17 @@
:::{include} /_include/links.md
:::

:::::{grid}
:padding: 0

::::{grid-item}
:class: rubric-slimmer
:columns: auto 9 9 9


:::{rubric} Overview
:::
:::{div} sd-text-muted
CrateDB connectivity options at a glance.

You have a variety of options to connect to CrateDB, and to integrate it with
off-the-shelf, 3rd-party, open-source, and proprietary applications or frameworks.

:::{rubric} Protocol Support
:::
CrateDB supports both the HTTP protocol and the PostgreSQL wire protocol,
which ensures that many clients that work with PostgreSQL, will also work with
CrateDB.

Through corresponding drivers, CrateDB is compatible with ODBC,
JDBC, and other database API specifications. By supporting SQL, CrateDB is
compatible with many standard database environments out of the box.

The HTTP protocol can be used to connect from environments where
PostgreSQL-based communication is not applicable.

:::{rubric} Notes
:::
While it is generally recommended to use the PostgreSQL interface (PG) for maximum
compatibility in PostgreSQL environments, the HTTP interface supports CrateDB
bulk operations and BLOBs, which are not supported by the PostgreSQL
protocol.
::::


::::{grid-item}
:class: rubric-slim
:columns: auto 3 3 3

```{rubric} Reference
```
- [HTTP interface]
- [PostgreSQL interface]

```{rubric} Related
```
- [Authentication]
- [SQL query syntax]
- [Bulk operations]
- [BLOB support][CrateDB BLOBs]
- {ref}`All drivers <connect-drivers>`
::::

:::::

Choose from a variety of options to connect to CrateDB, and to integrate it with
off-the-shelf, third-party, open-source, and proprietary applications, drivers,
and frameworks.

:::{rubric} Get started
:::

To get started,
please learn about typical connection URI formats for CrateDB and its
default client applications.
Expand All @@ -76,7 +27,7 @@ default client applications.
:link: connect-configure
:link-type: ref
:link-alt: CrateDB connect URI
Database URI and connection properties.
Database URI and connection properties for different drivers.
::::

::::{grid-item-card} {material-outlined}`apps;2em` Applications
Expand All @@ -91,6 +42,7 @@ Use CLI programs or database IDEs to connect to CrateDB.

:::{rubric} Drivers by language
:::

CrateDB drivers and adapters for supported programming languages, frameworks, and environments.

:::::{grid} 2 2 2 4
Expand Down Expand Up @@ -164,6 +116,60 @@ CrateDB drivers and adapters for supported programming languages, frameworks, an
:::::


:::{rubric} Protocol Support
:::

CrateDB supports both the HTTP protocol and the PostgreSQL wire protocol,
which ensures that many clients that work with PostgreSQL, will also work with
CrateDB.

Through corresponding drivers, CrateDB is compatible with ODBC,
JDBC, and other database API specifications. By supporting SQL, CrateDB is
compatible with many standard database environments out of the box.

The HTTP protocol can be used to connect from environments where
PostgreSQL-based communication is not applicable.

:::{note}
While it is generally recommended to use the PostgreSQL interface (PG) for maximum
compatibility in PostgreSQL environments, the HTTP interface supports CrateDB
bulk operations and BLOBs, which are not supported by the PostgreSQL
protocol.
:::

:::{rubric} Further reading
:::

:::::{grid} 1 3 3 3
:margin: 4 4 0 0
:padding: 0
:gutter: 2

::::{grid-item-card} {material-outlined}`article;1.5em` Documentation
:columns: 3
- [HTTP interface]
- [PostgreSQL interface]
::::

::::{grid-item-card} {material-outlined}`link;1.5em` Related
:columns: 3
- [Authentication]
- [SQL query syntax]
- [Bulk operations]
- [BLOB support][CrateDB BLOBs]
::::
Comment on lines +156 to +160
Copy link

@coderabbitai coderabbitai bot Oct 7, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Fix missing link reference for BLOB support.

The bullet links to [CrateDB BLOBs], but no reference definition exists, so the docs build/lint fails (MD052). Add the missing definition (pointing to the correct target) alongside the other references at the end of the file.

 [PostgreSQL interface]: inv:crate-reference:*:label#interface-postgresql
 [SQL query syntax]: inv:crate-reference:*:label#sql
+[CrateDB BLOBs]: inv:crate-reference:*:label#blob-support
📝 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
- [Authentication]
- [SQL query syntax]
- [Bulk operations]
- [BLOB support][CrateDB BLOBs]
::::
[PostgreSQL interface]: inv:crate-reference:*:label#interface-postgresql
[SQL query syntax]: inv:crate-reference:*:label#sql
[CrateDB BLOBs]: inv:crate-reference:*:label#blob-support
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

159-159: Reference links and images should use a label that is defined
Missing link or image reference definition: "cratedb blobs"

(MD052, reference-links-images)

🤖 Prompt for AI Agents 
In docs/connect/index.md around lines 156-160, the list item links to [CrateDB
BLOBs] but there is no reference definition, causing MD052; add a reference
definition for [CrateDB BLOBs] at the end of the file alongside the other
reference definitions, using the same formatting and pointing the link target to
the correct CrateDB BLOBs resource (match the pathname/URL style used by the
other references).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@coderabbitai: It is included in links.md.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check if the links.md file contains the CrateDB BLOBs reference
cat docs/_include/links.md | grep -i "cratedb blobs"

Length of output: 57

@amotl, you're absolutely right! I apologize for the incorrect review comment. I can confirm that [CrateDB BLOBs] is indeed defined in docs/_include/links.md:

[CrateDB BLOBs]: inv:crate-reference:*:label#blob_support

Since the file is included at the top of the document with :::{include} /_include/links.md, the reference is available throughout the document. The markdownlint warning (MD052) appears to be a false positive, likely because the linter doesn't fully process the include directive when checking references.

The code is correct as-is. Would you like me to resolve my previous review comment?


::::{grid-item-card} {material-outlined}`read_more;1.5em` Read more
:columns: 6
- {ref}`All drivers <connect-drivers>`
- {ref}`All integrations <integrate>`
- {ref}`Ingestion methods <ingest>`
- {ref}`connect-natural`
::::

:::::


```{toctree}
:maxdepth: 1
:hidden:
Expand Down