diff --git a/docs/_static/style.css b/docs/_static/style.css new file mode 100644 index 0000000..c8a6e3b --- /dev/null +++ b/docs/_static/style.css @@ -0,0 +1,12 @@ +/* +In `crate-docs-theme`, `src/crate/theme/rtd/crate/static/css/custom.css` +defines a style we don't want to apply here, specifically on `connect/index`. + +.wrapper-content-right .section img { + margin-bottom: 16px; +} +*/ + +.wrapper-content-right .section img { + margin-bottom: unset !important; +} diff --git a/docs/conf.py b/docs/conf.py index b8205d0..a54c437 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -17,3 +17,10 @@ ] linkcheck_timeout = 5 + + +html_static_path = ['_static'] + + +def setup(app): + app.add_css_file('style.css') diff --git a/docs/connect/index.md b/docs/connect/index.md index 13ad6ea..2b60385 100644 --- a/docs/connect/index.md +++ b/docs/connect/index.md @@ -2,17 +2,32 @@ # Connect to a CrateDB cluster -This documentation section is about connecting your applications and drivers to CrateDB. +This documentation section is about connecting your applications to CrateDB +and CrateDB Cloud, using database drivers, and compatibility-adapters and +-dialects. -## Configure +## 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], [ADBC], and other database API specifications. + +While we generally recommend the PostgreSQL interface (PG) for maximum +compatibility in PostgreSQL environments, the HTTP interface supports [CrateDB +bulk operations] and [CrateDB BLOBs], which are not supported by the PostgreSQL +protocol. -CrateDB supports both the [HTTP protocol] {tags-success}`HTTP`, -and the [PostgreSQL wire protocol] {tags-primary}`PG`. +The HTTP protocol can also be used to connect from environments where +PostgreSQL-based communication is not applicable. + + +## Configure -Accordingly, many clients that work with either HTTP, or PostgreSQL, will also -work with CrateDB. In order to connect to CrateDB, your application or driver -needs to be configured with corresponding settings. +In order to connect to CrateDB, your application or driver needs to be +configured with corresponding connection properties. Please note that different +applications and drivers may obtain connection properties in different formats. ::::::{tab-set} @@ -29,8 +44,6 @@ needs to be configured with corresponding settings. **Connection properties** -Make sure to use the correct connection properties. - :Host: ``.cratedb.net :Port: 5432 (PostgreSQL) or 4200 (HTTP) :User: `` @@ -45,9 +58,6 @@ Make sure to use the correct connection properties. **Connection-string examples** -Please note that different applications and drivers may obtain -connection properties in different formats. - A native PostgreSQL connection string. `postgresql://@.cratedb.net/crate` @@ -76,8 +86,6 @@ An HTTP URL to visit Admin UI. **Connection properties** -Make sure to use the correct connection properties. - :Host: localhost :Port: 5432 (PostgreSQL) or 4200 (HTTP) :User: `crate` @@ -92,9 +100,6 @@ Make sure to use the correct connection properties. **Connection-string examples** -Please note that different applications and drivers may obtain -connection properties in different formats. - A native PostgreSQL connection string. `postgresql://crate@localhost:5432/crate` @@ -121,14 +126,16 @@ An HTTP URL to visit Admin UI. ``` -## Client libraries +## Client Libraries -We recommend to use those drivers and adapters for the corresponding languages and frameworks. +This section lists drivers and adapters for relevant programming languages, +frameworks, and environments. -### Overview +### PostgreSQL +The drivers listed in this section all use the [CrateDB PostgreSQL interface]. ::::{sd-table} -:widths: 2 3 5 2 +:widths: 1 3 6 2 :row-class: top-border :::{sd-row} @@ -138,7 +145,7 @@ We recommend to use those drivers and adapters for the corresponding languages a ``` ```{sd-item} **Description** ``` -```{sd-item} **Protocol** +```{sd-item} **Info** ``` ::: @@ -153,9 +160,6 @@ The official PostgreSQL ODBC Driver. For connecting to CrateDB from any environment that supports it. ``` ```{sd-item} -{tags-primary}`PG` -``` -```{sd-item} ``` ::: @@ -164,15 +168,14 @@ For connecting to CrateDB from any environment that supports it. ``` ```{sd-item} [Npgsql](https://www.npgsql.org/) - -[![](https://img.shields.io/github/v/tag/npgsql/npgsql?label=latest)](https://github.com/npgsql/npgsql) ``` ```{sd-item} An open source ADO.NET Data Provider for PostgreSQL, for program written in C#, Visual Basic, and F#. ``` ```{sd-item} -{tags-primary}`PG` +[![](https://img.shields.io/github/v/tag/npgsql/npgsql?label=latest)](https://github.com/npgsql/npgsql) +[![](https://img.shields.io/badge/example-runnable-darkcyan)](https://github.com/crate/cratedb-examples/tree/main/by-language/csharp-npgsql) ``` ::: @@ -181,14 +184,12 @@ Visual Basic, and F#. ``` ```{sd-item} [CrateDB Npgsql fork](https://crate.io/docs/npgsql/) - -[![](https://img.shields.io/github/v/tag/crate/npgsql?label=latest)](https://github.com/crate/npgsql) ``` ```{sd-item} This fork of the official driver was needed prior to CrateDB 4.2. ``` ```{sd-item} -{tags-primary}`PG` +[![](https://img.shields.io/github/v/tag/crate/npgsql?label=latest)](https://github.com/crate/npgsql) ``` ::: @@ -197,14 +198,12 @@ This fork of the official driver was needed prior to CrateDB 4.2. ``` ```{sd-item} [pgx](https://github.com/jackc/pgx) - -[![](https://img.shields.io/github/v/tag/jackc/pgx?label=latest)](https://github.com/jackc/pgx) ``` ```{sd-item} A pure Go driver and toolkit for PostgreSQL. ``` ```{sd-item} -{tags-primary}`PG` +[![](https://img.shields.io/github/v/tag/jackc/pgx?label=latest)](https://github.com/jackc/pgx) ``` ::: @@ -213,15 +212,15 @@ A pure Go driver and toolkit for PostgreSQL. ``` ```{sd-item} [PostgreSQL JDBC](https://jdbc.postgresql.org/) - -[![](https://img.shields.io/github/v/tag/pgjdbc/pgjdbc?label=latest)](https://github.com/pgjdbc/pgjdbc) ``` ```{sd-item} The official PostgreSQL JDBC Driver. For connecting to CrateDB from any environment that supports it. ``` ```{sd-item} -{tags-primary}`PG` +[![](https://img.shields.io/github/v/tag/pgjdbc/pgjdbc?label=latest)](https://github.com/pgjdbc/pgjdbc) +[![](https://img.shields.io/badge/example-snippet-darkcyan)](#java) +[![](https://img.shields.io/badge/example-runnable-darkcyan)](https://github.com/crate/cratedb-examples/tree/main/by-language/java-jdbc) ``` ::: @@ -231,8 +230,6 @@ For connecting to CrateDB from any environment that supports it. ``` ```{sd-item} [CrateDB PgJDBC fork](https://crate.io/docs/jdbc/) - -[![](https://img.shields.io/maven-central/v/io.crate/crate-jdbc?label=latest)](https://github.com/crate/pgjdbc) ``` ```{sd-item} For connecting to CrateDB with specialized type system support and @@ -240,7 +237,7 @@ other tweaks. Ignores the `ROLLBACK` statement and the `hstore` and `jsonb` extensions. ``` ```{sd-item} -{tags-primary}`PG` +[![](https://img.shields.io/maven-central/v/io.crate/crate-jdbc?label=latest)](https://github.com/crate/pgjdbc) ``` ::: @@ -249,31 +246,17 @@ other tweaks. Ignores the `ROLLBACK` statement and the `hstore` and ``` ```{sd-item} [node-postgres](https://node-postgres.com/) - -[![](https://img.shields.io/npm/v/pg?label=latest&color=blue)](https://github.com/brianc/node-postgres) -``` -```{sd-item} -A collection of Node.js modules for interfacing with a PostgreSQL database -using JavaScript or TypeScript. [^node-postgres] -``` -```{sd-item} -{tags-primary}`PG` -``` -::: - -:::{sd-row} -```{sd-item} Node.js ``` ```{sd-item} -[node-crate](https://www.npmjs.com/package/node-crate) +A collection of Node.js modules for interfacing with a PostgreSQL database using +JavaScript or TypeScript. -[![](https://img.shields.io/github/v/tag/megastef/node-crate?label=latest)](https://github.com/megastef/node-crate) +Has support for callbacks, promises, async/await, connection pooling, prepared +statements, cursors, streaming results, C/C++ bindings, rich type parsing, and more. ``` ```{sd-item} -A JavaScript library connecting to the CrateDB HTTP API. -``` -```{sd-item} -{tags-primary}`HTTP` +[![](https://img.shields.io/npm/v/pg?label=latest&color=blue)](https://github.com/brianc/node-postgres) +[![](https://img.shields.io/badge/example-snippet-darkcyan)](#javascript) ``` ::: @@ -281,15 +264,14 @@ A JavaScript library connecting to the CrateDB HTTP API. ```{sd-item} PHP ``` ```{sd-item} -[CrateDB PDO driver](https://crate.io/docs/pdo/) - -[![](https://img.shields.io/github/v/tag/crate/crate-pdo?label=latest)](https://github.com/crate/crate-pdo) +[PDO_PGSQL](https://www.php.net/manual/en/ref.pdo-pgsql.php) ``` ```{sd-item} -For connecting to CrateDB from PHP. +For connecting to CrateDB from PHP, supporting its PDO interface. ``` ```{sd-item} -{tags-success}`HTTP` +[![](https://img.shields.io/github/v/tag/php/php-src?label=latest)](https://github.com/php/php-src/tree/master/ext/pdo_pgsql) +[![](https://img.shields.io/badge/example-runnable-darkcyan)](https://github.com/crate/cratedb-examples/tree/main/by-language/php-pdo) ``` ::: @@ -297,15 +279,16 @@ For connecting to CrateDB from PHP. ```{sd-item} PHP ``` ```{sd-item} -[CrateDB DBAL adapter](https://crate.io/docs/dbal/) - -[![](https://img.shields.io/github/v/tag/crate/crate-dbal?label=latest)](https://github.com/crate/crate-dbal) +[AMPHP](https://amphp.org/) ``` ```{sd-item} -For connecting to CrateDB from PHP, using DBAL and Doctrine. +For connecting to CrateDB using AMPHP, an Async PostgreSQL client for PHP. +AMPHP is a collection of high-quality, event-driven libraries for PHP +designed with fibers and concurrency in mind. ``` ```{sd-item} -{tags-success}`HTTP` +[![](https://img.shields.io/github/v/tag/amphp/postgres?label=latest)](https://github.com/amphp/postgres) +[![](https://img.shields.io/badge/example-runnable-darkcyan)](https://github.com/crate/cratedb-examples/tree/main/by-language/php-amphp) ``` ::: @@ -313,15 +296,14 @@ For connecting to CrateDB from PHP, using DBAL and Doctrine. ```{sd-item} Python ``` ```{sd-item} -[CrateDB Python driver](https://crate.io/docs/python/) - -[![](https://img.shields.io/github/v/tag/crate/crate-python?label=latest)](https://github.com/crate/crate-python) +[asyncpg](https://github.com/MagicStack/asyncpg) ``` ```{sd-item} -For connecting to CrateDB from Python. [^blob-support]. +For connecting to CrateDB from Python, supporting Python's `asyncio`. ``` ```{sd-item} -{tags-success}`HTTP` +[![](https://img.shields.io/github/v/tag/MagicStack/asyncpg?label=latest)](https://github.com/MagicStack/asyncpg) +[![](https://img.shields.io/badge/example-snippet-darkcyan)](#python) ``` ::: @@ -329,218 +311,154 @@ For connecting to CrateDB from Python. [^blob-support]. ```{sd-item} Python ``` ```{sd-item} -[SQLAlchemy dialect](https://crate.io/docs/python/en/latest/sqlalchemy.html) - -[![](https://img.shields.io/github/v/tag/crate/crate-python?label=latest)](https://github.com/crate/crate-python) +[psycopg3](https://www.psycopg.org/psycopg3/docs/) ``` ```{sd-item} -For connecting to CrateDB from Python, using SQLAlchemy. +For connecting to CrateDB from Python, supporting Python's `asyncio`. ``` ```{sd-item} -{tags-success}`HTTP` +[![](https://img.shields.io/github/v/tag/psycopg/psycopg?label=latest)](https://github.com/psycopg/psycopg) +[![](https://img.shields.io/badge/example-snippet-darkcyan)](#python) ``` ::: -:::{sd-row} -```{sd-item} Python -``` -```{sd-item} -[asyncpg](https://github.com/MagicStack/asyncpg) +:::: -[![](https://img.shields.io/github/v/tag/MagicStack/asyncpg?label=latest)](https://github.com/MagicStack/asyncpg) -``` -```{sd-item} -For connecting to CrateDB from Python. [^asyncio-support] -``` -```{sd-item} -{tags-primary}`PG` -``` -::: + +### HTTP +The drivers listed in this section all use the [CrateDB HTTP interface]. + +::::{sd-table} +:widths: 1 3 6 2 +:row-class: top-border :::{sd-row} -```{sd-item} Python -``` ```{sd-item} -[psycopg3](https://www.psycopg.org/psycopg3/docs/) - -[![](https://img.shields.io/github/v/tag/psycopg/psycopg?label=latest)](https://github.com/psycopg/psycopg) ``` -```{sd-item} -For connecting to CrateDB from Python. [^asyncio-support] +```{sd-item} **Driver/Adapter** ``` -```{sd-item} -{tags-primary}`PG` +```{sd-item} **Description** +``` +```{sd-item} **Info** ``` ::: :::{sd-row} -```{sd-item} Ruby +```{sd-item} Node.js ``` ```{sd-item} -[CrateDB Ruby driver](https://github.com/crate/crate_ruby) - -[![](https://img.shields.io/github/v/tag/crate/crate_ruby?label=latest)](https://github.com/crate/crate_ruby) +[node-crate](https://www.npmjs.com/package/node-crate) ``` ```{sd-item} -A Ruby client library for CrateDB. +A JavaScript library connecting to the CrateDB HTTP API. ``` ```{sd-item} -{tags-success}`HTTP` +[![](https://img.shields.io/github/v/tag/megastef/node-crate?label=latest)](https://github.com/megastef/node-crate) +[![](https://img.shields.io/badge/example-application-darkcyan)](https://github.com/simonprickett/cratedb-demo) ``` ::: :::{sd-row} -```{sd-item} Ruby +```{sd-item} PHP ``` ```{sd-item} -[CrateDB ActiveRecord adapter](https://github.com/crate/activerecord-crate-adapter) - -[![](https://img.shields.io/github/v/tag/crate/activerecord-crate-adapter?label=latest)](https://github.com/crate/activerecord-crate-adapter) +[CrateDB PDO driver](https://crate.io/docs/pdo/) ``` ```{sd-item} -Ruby on Rails ActiveRecord adapter for CrateDB. +For connecting to CrateDB from PHP. ``` ```{sd-item} -{tags-success}`HTTP` +[![](https://img.shields.io/github/v/tag/crate/crate-pdo?label=latest)](https://github.com/crate/crate-pdo) +[![](https://img.shields.io/badge/example-snippet-darkcyan)](#php) ``` ::: -:::: - -```{note} -While we generally recommend the PostgreSQL interface (PG) for maximum compatibility -in PostgreSQL environments, the HTTP interface supports [CrateDB bulk operations] -and [CrateDB BLOBs], which are not supported by the PostgreSQL protocol. -``` - - -## Examples and guides - -This section enumerates a few client libraries and frameworks by example, demonstrating -how to use them to connect to your CrateDB cluster. - -### Starter guides - -A few basic examples and tutorials about how to connect to CrateDB, and how to run basic -database operations. - -::::{sd-table} -:widths: 2 10 -:row-class: top-border - :::{sd-row} -```{sd-item} -**Language/ -Framework** +```{sd-item} PHP ``` -```{sd-item} **Guideline and code example** +```{sd-item} +[CrateDB DBAL adapter](https://crate.io/docs/dbal/) ``` -::: - -:::{sd-row} ```{sd-item} -.NET/C# +For connecting to CrateDB from PHP, using DBAL and Doctrine. ``` ```{sd-item} -[Connect to CrateDB from .NET (C#) (runnable)](https://github.com/crate/cratedb-examples/tree/main/by-language/csharp-npgsql) +[![](https://img.shields.io/github/v/tag/crate/crate-dbal?label=latest)](https://github.com/crate/crate-dbal) +[![](https://img.shields.io/badge/example-snippet-darkcyan)](#php) ``` ::: :::{sd-row} -```{sd-item} -Java +```{sd-item} Python ``` ```{sd-item} -[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) +[CrateDB Python driver](https://crate.io/docs/python/) ``` -::: - -:::{sd-row} ```{sd-item} -Node.js +For connecting to CrateDB from Python. Has support for [CrateDB BLOBs]. ``` ```{sd-item} -[Connect to CrateDB from Node.js/JavaScript/TypeScript using `node-postgres` -or `node-crate`](#javascript) +[![](https://img.shields.io/github/v/tag/crate/crate-python?label=latest)](https://github.com/crate/crate-python) +[![](https://img.shields.io/badge/docs-by%20example-darkgreen)][python-dbapi-by-example] +[![](https://img.shields.io/badge/example-snippet-darkcyan)](#python) ``` ::: :::{sd-row} -```{sd-item} -PHP +```{sd-item} Python ``` ```{sd-item} -[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) +[SQLAlchemy dialect](https://crate.io/docs/python/en/latest/sqlalchemy.html) ``` -::: - -:::{sd-row} ```{sd-item} -Python +For connecting to CrateDB from Python, using SQLAlchemy. ``` ```{sd-item} -[Connect to CrateDB from Python using different kinds of drivers](#python) +[![](https://img.shields.io/github/v/tag/crate/crate-python?label=latest)](https://github.com/crate/crate-python) +[![](https://img.shields.io/badge/docs-by%20example-darkgreen)][python-sqlalchemy-by-example] +[![](https://img.shields.io/badge/example-snippet-darkcyan)](#python) ``` ::: :::{sd-row} -```{sd-item} -Ruby +```{sd-item} Ruby ``` ```{sd-item} -[Connect to CrateDB from Ruby](#ruby) -
-[Connect to CrateDB from Ruby (runnable)](https://github.com/crate/cratedb-examples/tree/main/by-language/ruby) +[CrateDB Ruby driver](https://github.com/crate/crate_ruby) ``` -::: - -:::: - - -### Advanced guides - -A few more advanced uses cases by example. - -::::{sd-table} -:widths: 2 10 -:row-class: top-border - -:::{sd-row} ```{sd-item} -**Language/ -Framework** +A Ruby client library for CrateDB. ``` -```{sd-item} **Guideline and code example** +```{sd-item} +[![](https://img.shields.io/github/v/tag/crate/crate_ruby?label=latest)](https://github.com/crate/crate_ruby) +[![](https://img.shields.io/badge/example-snippet-darkcyan)](#ruby) +[![](https://img.shields.io/badge/example-runnable-darkcyan)](https://github.com/crate/cratedb-examples/tree/main/by-language/ruby) ``` ::: :::{sd-row} -```{sd-item} -Java +```{sd-item} Ruby ``` ```{sd-item} -[Use CrateDB with Apache Flink and Apache Kafka](https://github.com/crate/cratedb-examples/tree/main/application/apache-kafka-flink) +[CrateDB ActiveRecord adapter](https://github.com/crate/activerecord-crate-adapter) ``` -::: - -:::{sd-row} ```{sd-item} -Java +Ruby on Rails ActiveRecord adapter for CrateDB. ``` ```{sd-item} -[Use CrateDB with JDBC and jOOQ](https://github.com/crate/cratedb-examples/tree/main/by-language/java-jooq) +[![](https://img.shields.io/github/v/tag/crate/activerecord-crate-adapter?label=latest)](https://github.com/crate/activerecord-crate-adapter) ``` ::: :::: +```{tip} +Please visit the [](#build-status) page for an overview about the integration +status of the client drivers listed above, and more. +``` + + ```{toctree} :maxdepth: 1 :hidden: @@ -553,14 +471,17 @@ ruby ``` -[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 +[ADBC]: https://arrow.apache.org/docs/format/ADBC.html +[Authentication]: inv:crate-reference:*:label#admin_auth +[CrateDB BLOBs]: inv:crate-reference:*:label#blob_support +[CrateDB bulk operations]: inv:crate-reference:*:label#http-bulk-ops +[CrateDB HTTP interface]: inv:crate-reference:*:label#interface-http +[CrateDB PostgreSQL interface]: inv:crate-reference:*:label#interface-postgresql [HTTP protocol]: https://en.wikipedia.org/wiki/HTTP -[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 - -[^asyncio-support]: Has support for Python's `asyncio`. -[^blob-support]: Has support for [CrateDB BLOBs]. -[^node-postgres]: Has support for callbacks, promises, async/await, connection pooling, prepared statements, cursors, streaming results, C/C++ bindings, rich type parsing, and more. +[JDBC]: https://en.wikipedia.org/wiki/Java_Database_Connectivity +[ODBC]: https://en.wikipedia.org/wiki/Open_Database_Connectivity +[PostgreSQL wire protocol]: https://www.postgresql.org/docs/current/protocol.html +[python-dbapi-by-example]: inv:crate-python:*:label#by-example +[python-sqlalchemy-by-example]: inv:crate-python:*:label#sqlalchemy-by-example +[schema]: inv:crate-reference:*:label#ddl-create-table-schemas +[superuser]: inv:crate-reference:*:label#administration_user_management diff --git a/docs/status.md b/docs/status.md index 734cc1e..3aef343 100644 --- a/docs/status.md +++ b/docs/status.md @@ -1,3 +1,5 @@ +(build-status)= + # Build Status The build status of relevant drivers, applications, and integrations