From 3911172be3a9dc7a4d78d3f7a93e0e2590222285 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Wed, 2 Aug 2023 16:08:03 +0200 Subject: [PATCH] NG/Connect: Improve sections "Introduction" and "Guides" --- docs/connect/index.md | 92 ++++++++++++++++++++++++++++--------------- 1 file changed, 61 insertions(+), 31 deletions(-) diff --git a/docs/connect/index.md b/docs/connect/index.md index 62fe613..f31b27f 100644 --- a/docs/connect/index.md +++ b/docs/connect/index.md @@ -3,19 +3,26 @@ # Connect to a CrateDB cluster -## Getting started +## Introduction -CrateDB supports both the HTTP protocol, and the [PostgreSQL wire protocol]. -Accordingly, many clients that work with PostgreSQL will also work with CrateDB. +CrateDB supports both the [HTTP protocol], and the [PostgreSQL wire protocol]. +Accordingly, many clients that work with either HTTP, or PostgreSQL, will also +work with CrateDB. -### PostgreSQL +```{tip} +- Specify the [schema] name `doc`, if you are asked for a *database name*. +- The default [superuser] on a vanilla CrateDB cluster is called `crate`, + without a password. +- When aiming to authenticate properly, please learn about the available + [authentication] options. +``` + +### Command-line -You can try this out for yourself: +This section outlines a few test flight commands which can be used to validate +PostgreSQL connectivity using the `psql` program, and HTTP connectivity using +the `curl` and [HTTPie] programs. -- Using your favorite tool of choice, configure a PostgreSQL connection, - but point your client to a CrateDB server instead of a PostgreSQL server. -- [Authenticate] as the ``crate`` [superuser] with no password. -- Specify the ``doc`` [schema], if you are asked for a *database name*. For example, your connection string to a CrateDB cluster instance might look like: @@ -200,10 +207,10 @@ and [CrateDB BLOBs], which are not supported by the PostgreSQL protocol. ``` -### Examples and Tutorials +### Starter guides -This section enumerates a few client libraries by example, and demonstrates -how to connect to your CrateDB cluster. +This section enumerates a few client libraries by example, demonstrating +how to connect to your CrateDB cluster correspondingly. ::::{sd-table} :widths: 2 10 @@ -214,7 +221,7 @@ how to connect to your CrateDB cluster. **Language/ Framework** ``` -```{sd-item} **Getting started tutorial / Basic code example** +```{sd-item} **Guideline and code example** ``` ::: @@ -223,7 +230,9 @@ Framework** .NET/C# ``` ```{sd-item} -[Basic example for connecting to CrateDB and CrateDB Cloud using .NET (C#)](https://github.com/crate/cratedb-examples/tree/main/by-language/csharp-npgsql) +[Connect to CrateDB from .NET (C#)](https://github.com/crate/cratedb-examples/tree/main/by-language/csharp-npgsql) +
+[Connect to CrateDB from .NET (C#) (runnable)](https://github.com/crate/cratedb-examples/tree/main/by-language/csharp-npgsql) ``` ::: @@ -232,70 +241,89 @@ Framework** Java ``` ```{sd-item} -[A basic connection example code](#java) +[Connect to CrateDB from Java using JDBC](#java) +
+[Connect to CrateDB from Java using JDBC (runnable)](https://github.com/crate/cratedb-examples/tree/main/by-language/java-jdbc) ``` ::: :::{sd-row} ```{sd-item} -Java +JavaScript, TypeScript ``` ```{sd-item} -[Basic example for connecting to CrateDB and CrateDB Cloud using JDBC](https://github.com/crate/cratedb-examples/tree/main/by-language/java-jdbc) +[Connect to CrateDB from Node.js using `node-postgres` or `node-crate`](#javascript) ``` ::: :::{sd-row} ```{sd-item} -Java +PHP ``` ```{sd-item} -[Apache Kafka, Apache Flink, and CrateDB](https://github.com/crate/cratedb-examples/tree/main/stacks/kafka-flink) +[Connect to CrateDB from PHP using PDO and DBAL drivers](#php) +
+[Connect to CrateDB from PHP using PDO (runnable)](https://github.com/crate/cratedb-examples/tree/main/by-language/php-pdo) +
+[Connect to CrateDB from PHP using AMPHP (runnable)](https://github.com/crate/cratedb-examples/tree/main/by-language/php-amphp) ``` ::: :::{sd-row} ```{sd-item} -Java +Python ``` ```{sd-item} -[jOOQ example application with CrateDB and JDBC connectivity](https://github.com/crate/cratedb-examples/tree/main/by-language/java-jooq) +[Connect to CrateDB from Python using different kinds of drivers](#python) ``` ::: :::{sd-row} ```{sd-item} -JavaScript +Ruby ``` ```{sd-item} -[How to connect using node-postgres or node-crate](#javascript) +[Connect to CrateDB from Ruby](#ruby) +
+[Connect to CrateDB from Ruby (runnable)](https://github.com/crate/cratedb-examples/tree/main/by-language/ruby) ``` ::: +:::: + + +### Advanced guides + +This section enumerates a few more advanced uses cases by example. + +::::{sd-table} +:widths: 2 10 +:row-class: top-border + :::{sd-row} ```{sd-item} -PHP +**Language/ +Framework** ``` -```{sd-item} -[Connect to CrateDB using PHP PDO and DBAL drivers](#php) +```{sd-item} **Guideline and code example** ``` ::: :::{sd-row} ```{sd-item} -Python +Java ``` ```{sd-item} -[How to connect to CrateDB using different kinds of Python drivers](#python) +[Use CrateDB with Apache Flink and Apache Kafka](https://github.com/crate/cratedb-examples/tree/main/stacks/kafka-flink) ``` ::: :::{sd-row} ```{sd-item} -Ruby +Java ``` ```{sd-item} -[Connect to CrateDB using Ruby](#ruby) +[Use CrateDB with JDBC and jOOQ](https://github.com/crate/cratedb-examples/tree/main/by-language/java-jooq) ``` ::: @@ -314,9 +342,11 @@ ruby ``` -[Authenticate]: https://crate.io/docs/crate/reference/en/latest/admin/auth/index.html +[Authentication]: https://crate.io/docs/crate/reference/en/latest/admin/auth/index.html [CrateDB BLOBs]: https://crate.io/docs/crate/reference/en/latest/general/blobs.html [CrateDB bulk operations]: https://crate.io/docs/crate/reference/en/latest/interfaces/http.html#bulk-operations +[HTTP protocol]: https://en.wikipedia.org/wiki/HTTP +[HTTPie]: https://httpie.io/ [PostgreSQL wire protocol]: https://crate.io/docs/crate/reference/en/latest/interfaces/postgres.html [schema]: https://crate.io/docs/crate/reference/en/latest/general/ddl/create-table.html#schemas [superuser]: https://crate.io/docs/crate/reference/en/latest/admin/user-management.html