diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 616cbed..1a3dabc 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -3,7 +3,11 @@ on:
pull_request: ~
push:
branches:
- - master
+ - main
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
jobs:
documentation:
@@ -15,11 +19,11 @@ jobs:
os: [ubuntu-latest, macos-latest]
steps:
- - uses: actions/checkout@v2
+ - uses: actions/checkout@v3
- name: Set up Python
- uses: actions/setup-python@v1
+ uses: actions/setup-python@v4
with:
- python-version: 3.7
+ python-version: 3.11
- name: Build docs
run: |
cd docs && make check
diff --git a/.gitignore b/.gitignore
index ba53d36..dc4edd0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,6 +4,7 @@
.crate-docs
.DS_Store
.env
+.idea
.style
.utils
*.lint
diff --git a/.readthedocs.yml b/.readthedocs.yml
index 07393e9..cd4b00c 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,11 +1,22 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+
+# Details
+# - https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+# Required
version: 2
+build:
+ os: "ubuntu-22.04"
+ tools:
+ python: "3.11"
+
sphinx:
builder: html
configuration: docs/conf.py
fail_on_warning: true
python:
- version: 3.7
install:
- requirements: docs/requirements.txt
diff --git a/BACKLOG.md b/BACKLOG.md
new file mode 100644
index 0000000..7b478d0
--- /dev/null
+++ b/BACKLOG.md
@@ -0,0 +1,59 @@
+# Backlog
+
+
+## Iteration +1
+- [ ] Add item about Admin UI
+- [ ] Add item about `psycopg3`
+- [ ] Connect: Add more properties, like `schema`
+
+## Iteration +2
+- [ ] Refer to more artefacts/resources
+ - Prometheus (Server Metrics/Monitoring)
+ - Terraform (Administration)
+- [ ] Add section about testing frameworks
+- [ ] Add section "highlights", or "awesome", bundling corresponding resources.
+ - https://community.crate.io/t/how-we-scaled-ingestion-to-one-million-rows-per-second/1069
+- [ ] Add [HTTPie Desktop]
+ Screenshot: https://github.com/crate/crate-clients-tools/assets/453543/9f724518-ee83-43ac-9ea1-7be63e7c9805
+
+## Iteration +3
+- [ ] Drivers: Outline multiple dimensions
+ - protocol: http vs. pg
+ - maintained/unmaintained
+ - recommended
+- [ ] Drivers: Layout overview list/table differently, to better convey more detailed
+ information per item. Maybe use [Info Card].
+
+## Evaluate
+
+- Via https://getsqlpad.com/en/introduction/#alternatives
+ - [Querybook](https://www.querybook.org/) (open source)
+ - [Superset](https://github.com/apache/superset) (open source) / [Preset](https://preset.io/) (company)
+ - [Chartbrew](https://github.com/chartbrew/chartbrew) (open source) / [Chartbrew](https://chartbrew.com/) (company)
+ - [Lightdash](https://github.com/lightdash/lightdash) (open source) / [Lightdash](https://www.lightdash.com/) (company)
+ - [CloudBeaver](https://github.com/dbeaver/cloudbeaver) (open source)
+ - [Awesome DB tools GUIs](https://github.com/mgramin/awesome-db-tools#gui)
+
+- Via https://github.com/crate/crate-clients-tools/issues
+ - [Looker](https://cloud.google.com/looker)
+ - [Metabase](https://github.com/metabase/metabase)
+ - [pgweb](https://sosedoff.github.io/pgweb/)
+ - [Redash](https://github.com/getredash/redash)
+ - [usql](https://github.com/xo/usql)
+
+- Re-evaluate
+ - Add [DataGrip]
+ - Add [pgAdmin]
+
+
+## Done
+- [x] CLI: Dedicated section per program, with code examples
+- [x] Connect: Improve "Configure" section about connection properties
+- [x] .NET driver got lost
+- [x] Remove DataGrip and pgAdmin again, they do not work
+
+
+[DataGrip]: https://www.jetbrains.com/datagrip/
+[HTTPie Desktop]: https://httpie.io/desktop
+[Info Card]: https://sphinx-design-elements.readthedocs.io/en/latest/infocard.html
+[pgAdmin]: https://www.pgadmin.org/
diff --git a/DEVELOP.rst b/DEVELOP.rst
index df01690..dca1904 100644
--- a/DEVELOP.rst
+++ b/DEVELOP.rst
@@ -45,9 +45,9 @@ You must install `fswatch`_ to use the ``dev`` target.
Continuous integration and deployment
-------------------------------------
-|build| |travis| |rtd|
+|build| |gha| |rtd|
-Travis CI is `configured`_ to run ``make check`` from the ``docs`` directory.
+GHA is `configured`_ to run ``make check`` from the ``docs`` directory.
Please do not merge pull requests until the tests pass.
`Read the Docs`_ automatically deploys the documentation whenever a configured
@@ -58,21 +58,21 @@ release version), please contact the `@crate/tech-writing`_ team.
.. _@crate/tech-writing: https://github.com/orgs/crate/teams/tech-writing
-.. _configured: https://github.com/crate/crate-clients-tools/blob/master/.travis.yml
+.. _configured: https://github.com/crate/crate-clients-tools/blob/main/.github/workflows/docs.yml
.. _fswatch: https://github.com/emcrisostomo/fswatch
.. _Read the Docs: http://readthedocs.org
.. _ReStructuredText: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx-doc.org/
-.. |build| image:: https://img.shields.io/endpoint.svg?color=blue&url=https%3A%2F%2Fraw.githubusercontent.com%2Fcrate%2Fcrate-clients-toolss%2Fmaster%2Fdocs%2Fbuild.json
+.. |build| image:: https://img.shields.io/endpoint.svg?color=blue&url=https%3A%2F%2Fraw.githubusercontent.com%2Fcrate%2Fcrate-clients-toolss%2Fmain%2Fdocs%2Fbuild.json
:alt: Build version
- :target: https://github.com/crate/crate-clients-tools/blob/master/docs/build.json
+ :target: https://github.com/crate/crate-clients-tools/blob/main/docs/build.json
-.. |travis| image:: https://img.shields.io/travis/crate/crate-clients-tools.svg?style=flat
+.. |gha| image:: https://github.com/crate/crate-clients-tools/actions/workflows/docs.yml/badge.svg
:alt: Travis CI status
:scale: 100%
- :target: https://travis-ci.org/crate/crate-clients-tools
+ :target: https://github.com/crate/crate-clients-tools/actions/workflows/docs.yml
.. |rtd| image:: https://readthedocs.org/projects/crate-clients-tools/badge/?version=latest
:alt: Read The Docs status
diff --git a/LICENSE b/LICENSE
index d645695..f433b1a 100644
--- a/LICENSE
+++ b/LICENSE
@@ -175,28 +175,3 @@
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
-
- APPENDIX: How to apply the Apache License to your work.
-
- To apply the Apache License to your work, attach the following
- boilerplate notice, with the fields enclosed by brackets "[]"
- replaced with your own identifying information. (Don't include
- the brackets!) The text should be enclosed in the appropriate
- comment syntax for the file format. We also recommend that a
- file or class name and description of purpose be included on the
- same "printed page" as the copyright notice for easier
- identification within third-party archives.
-
- Copyright [yyyy] [name of copyright owner]
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
diff --git a/MAINTAINERS.rst b/MAINTAINERS.rst
new file mode 100644
index 0000000..5c8e5c3
--- /dev/null
+++ b/MAINTAINERS.rst
@@ -0,0 +1,67 @@
+###########
+Maintainers
+###########
+
+
+About
+=====
+
+At Crate.io we are defining so called Power Users to ensure the integrations
+keep working.
+
+Responsibilities of Power Users:
+
+* Keep track of releases, updates and developments of the tools.
+* Test integration after minor and mayor CrateDB releases.
+* Test integration after tool releases.
+* Have a working setup available including a quick demo.
+* Being able to answer questions for the specific tool.
+* Ensuring guides are up to date.
+
+
+Power Users
+===========
+
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| Tool | User | Version | CrateDB Version | |
++=================+===================+=========+=================+======================================================+
+| Grafana | `proddata`_ | *X.Y* | *X.Y.Z* | `Known Issues Grafana`_ |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| PowerBI | `WolfgangHerbst`_ | *X.Y* | *X.Y.Z* | `Known Issues PowerBI`_ |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| Tableau | `marregui`_ | *X.Y* | *X.Y.Z* | `Known Issues Tableau`_ |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| Zeppelin | | | | |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| Looker | `proddata`_ | *X.Y* | *X.Y.Z* | `Known Issues Looker`_ |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| Node-Red | `proddata`_ | *X.Y* | *X.Y.Z* | `Known Issues Node Red`_ |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| NiFi | `proddata`_ | *X.Y* | *X.Y.Z* | `Known Issues NiFi`_ |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| Telegraf | | | | |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| Prometheus | `infoverload`_ | *X.Y* | *X.Y.Z* | `Known Issues Prometheus`_, `Known Issues Adapter`_ |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| R | `autophagy`_ | *X.Y* | *X.Y.Z* | `Known Issues R`_ |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+| Azure Functions | `autophagy`_ | *X.Y* | *X.Y.Z* | `Known Issues Azure Functions`_ |
++-----------------+-------------------+---------+-----------------+------------------------------------------------------+
+
+
+.. _autophagy: https://github.com/autophagy
+.. _infoverload: https://github.com/infoverload
+.. _marregui: https://github.com/marregui
+.. _proddata: https://github.com/proddata
+.. _WolfgangHerbst: https://github.com/WolfgangHerbst
+
+.. _Known Issues Adapter: https://github.com/crate/crate_adapter/issues
+.. _Known Issues Azure Functions: https://github.com/crate/crate/labels/tool%3A%20Azure%20Functions
+.. _Known Issues Grafana: https://github.com/crate/crate/labels/tool%3A%20Grafana
+.. _Known Issues Looker: https://github.com/crate/crate/labels/tool%3A%20Looker
+.. _Known Issues NiFi: https://github.com/crate/crate/labels/tool%3A%20NiFi
+.. _Known Issues Node Red: https://github.com/crate/crate/labels/tool%3A%20Node-Red
+.. _Known Issues PowerBI: https://github.com/crate/crate/labels/tool%3A%20PowerBI
+.. _Known Issues Prometheus: https://github.com/crate/crate/labels/tool%3A%20Prometheus
+.. _Known Issues R: https://github.com/crate/crate/labels/tool%3A%20R
+.. _Known Issues Tableau: https://github.com/crate/crate/labels/tool%3A%20Tableau
diff --git a/README.rst b/README.rst
index 5f632bd..a097338 100644
--- a/README.rst
+++ b/README.rst
@@ -2,92 +2,31 @@
CrateDB Clients and Tools
=========================
-Clients and tools for working with `CrateDB`_.
-We are also maintaining a more up-to-date list of `CrateDB integration tutorials`_.
+Client libraries, applications, tools, and integrations for `CrateDB`_.
+We are also maintaining an up-to-date list of `CrateDB integration tutorials`_.
Contributing
============
-This project is primarily maintained by `Crate.io`_, but we welcome community
-contributions!
-
-See the `developer docs`_ and the `contribution docs`_ for more information.
-
-
-Tool Power User
-===============
-
-At Crate.io we are defining so called Power Users to ensure the integrations
-keep working.
-
-Responsiblities of Power Users:
-
- * Keep track of releases, updates and developments of the tools.
- * Test integration after minor and mayor CrateDB releases.
- * Test integration after tool releases.
- * Have a working setup available including a quick demo.
- * Being able to answer questions for the specific tool.
- * Ensuring guides are up to date.
-
-
-Power Users
------------
-
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| Tool | User | Version | CrateDB Version | |
-+=================+===================+=========+=================+======================================================+
-| Grafana | `proddata`_ | *X.Y* | *X.Y.Z* | `Known Issues Grafana`_ |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| PowerBI | `WolfgangHerbst`_ | *X.Y* | *X.Y.Z* | `Known Issues PowerBI`_ |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| Tableau | `marregui`_ | *X.Y* | *X.Y.Z* | `Known Issues Tableau`_ |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| Zeppelin | | | | |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| Looker | `proddata`_ | *X.Y* | *X.Y.Z* | `Known Issues Looker`_ |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| Node-Red | `proddata`_ | *X.Y* | *X.Y.Z* | `Known Issues Node Red`_ |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| NiFi | `proddata`_ | *X.Y* | *X.Y.Z* | `Known Issues NiFi`_ |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| Telegraf | | | | |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| Prometheus | `infoverload`_ | *X.Y* | *X.Y.Z* | `Known Issues Prometheus`_, `Known Issues Adapter`_ |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| R | `autophagy`_ | *X.Y* | *X.Y.Z* | `Known Issues R`_ |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-| Azure Functions | `autophagy`_ | *X.Y* | *X.Y.Z* | `Known Issues Azure Functions`_ |
-+-----------------+-------------------+---------+-----------------+------------------------------------------------------+
-
+This project is primarily maintained by `Crate.io`_, and community contributions
+are welcome. See the `developer docs`_ and the `contribution docs`_ for more
+information.
Help
====
-Looking for more help?
+Looking for help?
- Read the `live docs`_
- Check out our `support channels`_
+- Visit the `community forum`_
-.. _autophagy: https://github.com/autophagy
.. _contribution docs: CONTRIBUTING.rst
+.. _community forum: https://community.crate.io/
.. _Crate.io: http://crate.io/
.. _CrateDB: https://crate.io/products/cratedb/
.. _CrateDB integration tutorials: https://community.crate.io/t/overview-of-cratedb-integration-tutorials/1015
.. _developer docs: DEVELOP.rst
-.. _infoverload: https://github.com/infoverload
-.. _Known Issues Adapter: https://github.com/crate/crate_adapter/issues
-.. _Known Issues Azure Functions: https://github.com/crate/crate/labels/tool%3A%20Azure%20Functions
-.. _Known Issues Grafana: https://github.com/crate/crate/labels/tool%3A%20Grafana
-.. _Known Issues Looker: https://github.com/crate/crate/labels/tool%3A%20Looker
-.. _Known Issues NiFi: https://github.com/crate/crate/labels/tool%3A%20NiFi
-.. _Known Issues Node Red: https://github.com/crate/crate/labels/tool%3A%20Node-Red
-.. _Known Issues PowerBI: https://github.com/crate/crate/labels/tool%3A%20PowerBI
-.. _Known Issues Prometheus: https://github.com/crate/crate/labels/tool%3A%20Prometheus
-.. _Known Issues R: https://github.com/crate/crate/labels/tool%3A%20R
-.. _Known Issues Tableau: https://github.com/crate/crate/labels/tool%3A%20Tableau
.. _live docs: https://crate.io/docs/crate/clients-tools/en/latest/
-.. _marregui: https://github.com/marregui
-.. _proddata: https://github.com/proddata
.. _support channels: https://crate.io/support/
-.. _WolfgangHerbst: https://github.com/WolfgangHerbst
diff --git a/docs/analyze.md b/docs/analyze.md
new file mode 100644
index 0000000..5a7d2a2
--- /dev/null
+++ b/docs/analyze.md
@@ -0,0 +1,104 @@
+(analyze)=
+# Analytics with CrateDB
+
+This documentation section enumerates analytics applications and frameworks for
+analyzing data in CrateDB.
+
+
+## Business analytics with Microsoft Power BI
+
+```{div}
+:style: "float: right"
+[{w=180px}](https://powerbi.microsoft.com/en-us/desktop/)
+```
+
+[Power BI Desktop] is a powerful business intelligence tool that provides a set of
+data analytics and visualizations. Using Power BI Desktop, users can create reports
+and dashboards from large datasets.
+
+For connecting to CrateDB with Power BI, you can use the [Power Query PostgreSQL connector].
+Earlier versions used the [PostgreSQL ODBC driver]. [](#cratedb-powerbi-desktop) walks
+you through the process of configuring that correctly.
+
+The [Power BI Service] is an online data analysis and visualization tool, making it
+possible to publish your dashboards, in order to share them with others.
+[](#cratedb-powerbi-service) has a corresponding tutorial.
+
+{h=160px}
+{h=160px}
+{h=160px}
+
+```{seealso}
+[CrateDB and Power BI]
+```
+
+
+## Business intelligence with Tableau
+
+```{div}
+:style: "float: right"
+[{w=180px}](https://www.tableau.com/)
+```
+
+[Tableau] is a visual business intelligence and analytics software platform. It expresses
+data by translating drag-and-drop actions into data queries through an intuitive interface.
+
+[Connecting to CrateDB from Tableau with JDBC] and [Using CrateDB with Tableau] will
+guide you through the process of setting it up correctly with CrateDB.
+
+{h=200px}
+
+```{seealso}
+[CrateDB and Tableau]
+```
+
+
+## Data analysis with pandas and scikit-learn
+
+```{div}
+:style: "float: right"
+[{w=180px}](https://pandas.pydata.org/)
+
+[{w=180px}](https://scikit-learn.org/)
+
+[{w=180px}](https://jupyter.org/)
+```
+
+
+Using [pandas] and [scikit-learn] to run a regression analysis within a [Jupyter Notebook].
+
+- [Machine Learning and CrateDB: An introduction]
+- [Machine Learning and CrateDB: Getting Started With Jupyter]
+- [Machine Learning and CrateDB: Experiment Design & Linear Regression]
+
+More resources:
+
+- [Automating financial data collection and storage in CrateDB with Python and pandas 2.0.0]
+- [From data storage to data analysis: Tutorial on CrateDB and pandas]
+
+
+## Machine Learning and CrateDB
+
+Using pandas, NumPy, Matplotlib, Merlion, and MLFlow, to analyze timeseries anomalies.
+
+- [Running Time Series Models in Production using CrateDB]
+
+
+[Automating financial data collection and storage in CrateDB with Python and pandas 2.0.0]: https://community.crate.io/t/automating-financial-data-collection-and-storage-in-cratedb-with-python-and-pandas-2-0-0/916
+[Connecting to CrateDB from Tableau with JDBC]: https://crate.io/blog/connecting-to-cratedb-from-tableau-with-jdbc
+[CrateDB and Tableau]: https://crate.io/integrations/cratedb-and-tableau
+[CrateDB and Power BI]: https://crate.io/integrations/cratedb-and-power-bi
+[From data storage to data analysis: Tutorial on CrateDB and pandas]: https://community.crate.io/t/from-data-storage-to-data-analysis-tutorial-on-cratedb-and-pandas/1440/1
+[Jupyter Notebook]: https://jupyter.org/
+[Machine Learning and CrateDB: An introduction]: https://crate.io/blog/machine-learning-and-cratedb-part-one
+[Machine Learning and CrateDB: Getting Started With Jupyter]: https://crate.io/blog/machine-learning-cratedb-jupyter
+[Machine Learning and CrateDB: Experiment Design & Linear Regression]: https://crate.io/blog/machine-learning-and-cratedb-part-three-experiment-design-and-linear-regression
+[pandas]: https://pandas.pydata.org/
+[PostgreSQL ODBC driver]: https://odbc.postgresql.org/
+[Power BI Desktop]: https://powerbi.microsoft.com/en-us/desktop/
+[Power BI Service]: https://powerbi.microsoft.com/en-us/
+[Power Query PostgreSQL connector]: https://learn.microsoft.com/en-us/power-query/connectors/postgresql
+[Running Time Series Models in Production using CrateDB]: https://github.com/crate/ml-sandbox/blob/main/timeseries-blog/timeseries-blog.md
+[scikit-learn]: https://scikit-learn.org/
+[Tableau]: https://www.tableau.com/
+[Using CrateDB with Tableau]: https://community.crate.io/t/using-cratedb-with-tableau/1192
diff --git a/docs/build.json b/docs/build.json
index 49cbd2b..5647caf 100644
--- a/docs/build.json
+++ b/docs/build.json
@@ -1,5 +1,5 @@
{
"schemaVersion": 1,
"label": "docs build",
- "message": "2.1.0"
+ "message": "2.1.1"
}
diff --git a/docs/cli.md b/docs/cli.md
new file mode 100644
index 0000000..912498b
--- /dev/null
+++ b/docs/cli.md
@@ -0,0 +1,180 @@
+(cli)=
+(connect-cli)=
+# Using command-line programs with CrateDB
+
+This section provides a quick overview about a few CLI programs, and how to
+use them for connecting to CrateDB clusters. We recommend to use crash,
+psql, http ([HTTPie]), or curl.
+
+You can use them to quickly validate HTTP and PostgreSQL connectivity to your
+database cluster, or to conduct basic scripting.
+
+Before running the command-line snippets outlined below, please use the correct
+settings instead of the placeholder tokens ``, ``, and
+``.
+
+
+(crash)=
+## crash
+
+```{div}
+:style: "float: right"
+{w=240px}
+```
+
+The **CrateDB Shell** is an interactive command-line interface (CLI) tool for
+working with CrateDB. For more information, see the documentation about [crash].
+
+```{div}
+:style: "clear: both"
+```
+
+::::{tab-set}
+
+:::{tab-item} CrateDB Server and Cloud
+:sync: server
+
+```{code-block} shell
+CRATEPW= \
+ crash --hosts 'https://.cratedb.net:4200' --username '' \
+ --command "SELECT 42.42;"
+```
+:::
+
+:::{tab-item} CrateDB on localhost
+:sync: localhost
+
+```{code-block} shell
+# No authentication.
+crash --command "SELECT 42.42;"
+
+```
+:::
+
+::::
+
+
+(psql)=
+## psql
+
+```{div}
+:style: "float: right"
+{w=240px}
+```
+
+**psql** is a terminal-based front-end to PostgreSQL. It enables you to type in
+queries interactively, issue them to PostgreSQL, and see the query results.
+For more information, see the documentation about [psql].
+
+```{div}
+:style: "clear: both"
+```
+
+::::{tab-set}
+
+:::{tab-item} CrateDB Server and Cloud
+:sync: server
+
+```{code-block} shell
+PGUSER= PGPASSWORD= \
+ psql postgresql://.cratedb.net/crate --command "SELECT 42.42;"
+```
+:::
+
+:::{tab-item} CrateDB on localhost
+:sync: localhost
+
+```{code-block} shell
+# No authentication.
+psql postgresql://crate@localhost:5432/crate --command "SELECT 42.42;"
+```
+:::
+
+::::
+
+
+(httpie)=
+## HTTPie
+
+```{div}
+:style: "float: right"
+{w=240px}
+```
+
+The **HTTPie CLI** is a modern, user-friendly command-line HTTP client with
+JSON support, colors, sessions, downloads, plugins & more.
+For more information, see the documentation about [HTTPie].
+
+```{div}
+:style: "clear: both"
+```
+
+::::{tab-set}
+
+:::{tab-item} CrateDB Server and Cloud
+:sync: server
+
+```{code-block} shell
+http https://:@.cratedb.net:4200/_sql?pretty" \
+ stmt="SELECT 42.42;"
+```
+:::
+
+:::{tab-item} CrateDB on localhost
+:sync: localhost
+
+```{code-block} shell
+http "localhost:4200/_sql?pretty" \
+ stmt="SELECT 42.42;"
+```
+:::
+
+::::
+
+
+(curl)=
+## curl
+
+```{div}
+:style: "float: right"
+{w=240px}
+```
+
+The venerable **curl** is the ubiquitous command line tool and library for transferring
+data with URLs. For more information, see the documentation about [curl].
+
+This example combines it with [jq], a lightweight and flexible command-line JSON processor.
+
+```{div}
+:style: "clear: both"
+```
+
+::::{tab-set}
+
+:::{tab-item} CrateDB Server and Cloud
+:sync: server
+
+```{code-block} shell
+echo '{"stmt": "SELECT 42.42;"}' \
+ | curl "https://:@.cratedb.net:4200/_sql?pretty" --silent --data @- | jq
+```
+:::
+
+:::{tab-item} CrateDB on localhost
+:sync: localhost
+
+```{code-block} shell
+echo '{"stmt": "SELECT 42.42;"}' \
+ | curl "localhost:4200/_sql?pretty" --silent --data @- | jq
+```
+:::
+
+::::
+
+
+
+[curl]: https://curl.se/
+[crash]: inv:crate-crash:*:label#index
+[HTTPie]: https://httpie.io/
+[jq]: https://jqlang.github.io/jq/
+[psql]: https://www.postgresql.org/docs/current/app-psql.html
diff --git a/docs/connect/index.md b/docs/connect/index.md
new file mode 100644
index 0000000..559c853
--- /dev/null
+++ b/docs/connect/index.md
@@ -0,0 +1,472 @@
+(connect)=
+
+# Connect to a CrateDB cluster
+
+This documentation section is about connecting your applications and drivers to CrateDB.
+
+
+## Configure
+
+CrateDB supports both the [HTTP protocol] {tags-success}`HTTP`,
+and the [PostgreSQL wire protocol] {tags-primary}`PG`.
+
+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.
+
+::::::{tab-set}
+
+:::::{tab-item} CrateDB Server and Cloud
+
+::::{grid}
+:margin: 0
+:padding: 0
+
+:::{grid-item}
+:columns: 5
+:margin: 0
+:padding: 0
+
+**Connection properties**
+
+Make sure to use the correct connection properties.
+
+:Host: ``.cratedb.net
+:Port: 5432 (PostgreSQL) or 4200 (HTTP)
+:User: ``
+:Pass: ``
+
+:::
+
+:::{grid-item}
+:columns: 7
+:margin: 0
+:padding: 0
+
+**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`
+
+A connection string for SQLAlchemy or Apache Flink.
+`crate://@.cratedb.net/crate`
+
+An HTTP URL to visit Admin UI.
+`https://@.cratedb.net:4200/`
+
+:::
+
+::::
+
+:::::
+
+:::::{tab-item} CrateDB on localhost
+
+::::{grid}
+:margin: 0
+:padding: 0
+
+:::{grid-item}
+:columns: 5
+:margin: 0
+:padding: 0
+
+**Connection properties**
+
+Make sure to use the correct connection properties.
+
+:Host: localhost
+:Port: 5432 (PostgreSQL) or 4200 (HTTP)
+:User: `crate`
+:Pass: (empty)
+
+:::
+
+:::{grid-item}
+:columns: 7
+:margin: 0
+:padding: 0
+
+**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`
+
+A connection string for SQLAlchemy or Apache Flink.
+`crate://crate@localhost/crate`
+
+An HTTP URL to visit Admin UI.
+`http://crate@localhost:4200/`
+
+:::
+
+::::
+:::::
+
+::::::
+
+
+```{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.
+```
+
+
+## Client libraries
+
+We recommend to use those drivers and adapters for the corresponding languages and frameworks.
+
+### Overview
+
+::::{sd-table}
+:widths: 2 3 5 2
+:row-class: top-border
+
+:::{sd-row}
+```{sd-item} **Language**
+```
+```{sd-item} **Driver/Adapter**
+```
+```{sd-item} **Description**
+```
+```{sd-item} **Properties**
+```
+:::
+
+:::{sd-row}
+```{sd-item} .NET
+```
+```{sd-item}
+[Npgsql](https://www.npgsql.org/)
+```
+```{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`
+```
+:::
+
+:::{sd-row}
+```{sd-item} .NET
+```
+```{sd-item}
+[CrateDB Npgsql fork](https://crate.io/docs/npgsql/)
+```
+```{sd-item}
+This fork of the official driver was needed prior to CrateDB 4.2.
+```
+```{sd-item}
+{tags-primary}`PG`
+```
+:::
+
+:::{sd-row}
+```{sd-item} Golang
+```
+```{sd-item}
+[pgx](https://github.com/jackc/pgx)
+```
+```{sd-item}
+A pure Go driver and toolkit for PostgreSQL.
+```
+```{sd-item}
+{tags-primary}`PG`
+```
+:::
+
+:::{sd-row}
+```{sd-item} Java
+```
+```{sd-item}
+[PostgreSQL JDBC](https://jdbc.postgresql.org/)
+```
+```{sd-item}
+For connecting to CrateDB from any environment that supports it.
+```
+```{sd-item}
+{tags-primary}`PG`
+```
+:::
+
+:::{sd-row}
+```{sd-item} Java
+```
+```{sd-item}
+[CrateDB PgJDBC fork](https://crate.io/docs/jdbc/)
+```
+```{sd-item}
+For connecting to CrateDB within special scenarios, in order to leverage more
+features of its type system, and to ignore the `ROLLBACK` statement.
+```
+```{sd-item}
+{tags-primary}`PG`
+```
+:::
+
+:::{sd-row}
+```{sd-item} JavaScript, TypeScript
+```
+```{sd-item}
+[node-postgres](https://node-postgres.com/)
+```
+```{sd-item}
+A collection of Node.js modules for interfacing with a PostgreSQL database. [^node-postgres]
+```
+```{sd-item}
+{tags-primary}`PG`
+```
+:::
+
+:::{sd-row}
+```{sd-item} PHP
+```
+```{sd-item}
+[PHP PDO driver](https://crate.io/docs/pdo/)
+```
+```{sd-item}
+For connecting to CrateDB from PHP.
+```
+```{sd-item}
+{tags-success}`HTTP`
+```
+:::
+
+:::{sd-row}
+```{sd-item} PHP
+```
+```{sd-item}
+[PHP DBAL adapter](https://crate.io/docs/dbal/)
+```
+```{sd-item}
+For connecting to CrateDB from PHP, using DBAL and Doctrine.
+```
+```{sd-item}
+{tags-success}`HTTP`
+```
+:::
+
+:::{sd-row}
+```{sd-item} Python
+```
+```{sd-item}
+[DB-API driver](https://crate.io/docs/python/)
+```
+```{sd-item}
+For connecting to CrateDB from Python. [^blob-support].
+```
+```{sd-item}
+{tags-success}`HTTP`
+```
+:::
+
+:::{sd-row}
+```{sd-item} Python
+```
+```{sd-item}
+[SQLAlchemy dialect](https://crate.io/docs/python/en/latest/sqlalchemy.html)
+```
+```{sd-item}
+For connecting to CrateDB from Python, using SQLAlchemy.
+```
+```{sd-item}
+{tags-success}`HTTP`
+```
+:::
+
+:::{sd-row}
+```{sd-item} Python
+```
+```{sd-item}
+[asyncpg](https://github.com/MagicStack/asyncpg)
+```
+```{sd-item}
+For connecting to CrateDB from Python. [^asyncio-support]
+```
+```{sd-item}
+{tags-primary}`PG`
+```
+:::
+
+:::{sd-row}
+```{sd-item} Python
+```
+```{sd-item}
+[psycopg3](https://www.psycopg.org/psycopg3/docs/)
+```
+```{sd-item}
+For connecting to CrateDB from Python. [^asyncio-support]
+```
+```{sd-item}
+{tags-primary}`PG`
+```
+:::
+
+::::
+
+```{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} **Guideline and code example**
+```
+:::
+
+:::{sd-row}
+```{sd-item}
+.NET/C#
+```
+```{sd-item}
+[Connect to CrateDB from .NET (C#) (runnable)](https://github.com/crate/cratedb-examples/tree/main/by-language/csharp-npgsql)
+```
+:::
+
+:::{sd-row}
+```{sd-item}
+Java
+```
+```{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)
+```
+:::
+
+:::{sd-row}
+```{sd-item}
+JavaScript, TypeScript
+```
+```{sd-item}
+[Connect to CrateDB from Node.js using `node-postgres` or `node-crate`](#javascript)
+```
+:::
+
+:::{sd-row}
+```{sd-item}
+PHP
+```
+```{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)
+```
+:::
+
+:::{sd-row}
+```{sd-item}
+Python
+```
+```{sd-item}
+[Connect to CrateDB from Python using different kinds of drivers](#python)
+```
+:::
+
+:::{sd-row}
+```{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)
+```
+:::
+
+::::
+
+
+### 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**
+```
+```{sd-item} **Guideline and code example**
+```
+:::
+
+:::{sd-row}
+```{sd-item}
+Java
+```
+```{sd-item}
+[Use CrateDB with Apache Flink and Apache Kafka](https://github.com/crate/cratedb-examples/tree/main/stacks/kafka-flink)
+```
+:::
+
+:::{sd-row}
+```{sd-item}
+Java
+```
+```{sd-item}
+[Use CrateDB with JDBC and jOOQ](https://github.com/crate/cratedb-examples/tree/main/by-language/java-jooq)
+```
+:::
+
+::::
+
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+java
+javascript
+php
+python
+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
+[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.
diff --git a/docs/connect/java.rst b/docs/connect/java.rst
new file mode 100644
index 0000000..1d237d2
--- /dev/null
+++ b/docs/connect/java.rst
@@ -0,0 +1,41 @@
+.. _connect-java:
+
+====
+Java
+====
+
+JDBC is a standard Java API that provides a common interfaces for accessing
+databases in Java.
+
+Example method used in implementation:
+
+.. code-block:: java
+
+ import java.sql.*;
+ import java.util.Properties;
+
+ public class Main {
+ public static void main(String[] args) {
+ try {
+ Properties properties = new Properties();
+ properties.put("user", "admin");
+ properties.put("password", "");
+ properties.put("ssl", true);
+ Connection conn = DriverManager.getConnection(
+ "crate://.cratedb.net:5432/",
+ properties
+ );
+
+ Statement statement = conn.createStatement();
+ ResultSet resultSet = statement.executeQuery("SELECT name FROM sys.cluster");
+ resultSet.next();
+ String name = resultSet.getString("name");
+
+ System.out.println(name);
+ } catch (SQLException e) {
+ e.printStackTrace();
+ }
+ }
+ }
+
+See full documentation :ref:`here `.
\ No newline at end of file
diff --git a/docs/connect/javascript.rst b/docs/connect/javascript.rst
new file mode 100644
index 0000000..751e740
--- /dev/null
+++ b/docs/connect/javascript.rst
@@ -0,0 +1,60 @@
+.. _connect-javascript:
+
+==========
+JavaScript
+==========
+
+This section provides a quick overview of available node.js modules and
+drivers for CrateDB Cloud.
+
+node-postgres
+-------------
+
+node-postgres is a collection of node.js modules for interfacing with a CrateDB
+Cloud database.
+
+Example implementation will look like this:
+
+.. code-block:: javascript
+
+ const { Client } = require("pg");
+
+ const crateClient = new Client({
+ host: ".cratedb.net",
+ port: 5432,
+ user: "admin",
+ password: "",
+ ssl: true,
+ });
+
+ (async () => {
+ await crateClient.connect();
+ const result = await crateClient.query("SELECT name FROM sys.cluster");
+ console.log(result.rows[0]);
+ })();
+
+For more information see `node-postgres documentation`_.
+
+node-crate
+----------
+
+node-crate is an independent node.js driver implementation for CRATE using the _sql endpoint REST API.
+
+Example implementation will look like this:
+
+.. code-block:: javascript
+
+ const crate = require("node-crate");
+
+ crate.connect(`https://admin:${encodeURIComponent("")}@.cratedb.net:4200`);
+
+ (async () => {
+ const result = await crate.execute("SELECT name FROM sys.cluster");
+ console.log(result.rows[0]);
+ })();
+
+
+For more information see `node-crate documentation`_.
+
+.. _node-postgres documentation: https://www.npmjs.com/package/pg
+.. _node-crate documentation: https://www.npmjs.com/package/node-crate
diff --git a/docs/connect/php.rst b/docs/connect/php.rst
new file mode 100644
index 0000000..2ebae4d
--- /dev/null
+++ b/docs/connect/php.rst
@@ -0,0 +1,70 @@
+.. _connect-php:
+
+===
+PHP
+===
+
+This section provides a quick overview of available PHP extensions for CrateDB
+Cloud.
+
+PDO
+---
+
+The PHP Data Objects (PDO) is a standard PHP extension that defines a common
+interface for accessing databases in PHP.
+
+Example implementation will look like this:
+
+.. code-block:: php
+
+ .cratedb.net:4200',
+ 'admin',
+ ''
+ );
+
+ $stm = $pdo->query('SELECT name FROM sys.cluster');
+ $name = $stm->fetch();
+ print $name[0];
+
+ ?>
+
+See full documentation :ref:`here `.
+
+DBAL
+----
+
+DBAL is a PHP database abstraction layer that comes with database schema
+introspection, schema management, and PDO support.
+
+Example implementation will look like this:
+
+.. code-block:: console
+
+ 'Crate\DBAL\Driver\PDOCrate\Driver',
+ 'user' => 'admin',
+ 'password' = '',
+ 'host' => '.cratedb.net',
+ 'port' => 4200
+ );
+
+ $connection = \Doctrine\DBAL\DriverManager::getConnection($params);
+ $sql = 'SELECT name FROM sys.cluster';
+ $name = $connection->query($sql)->fetch();
+
+ print $name['name'];
+
+ ?>
+
+See full documentation :ref:`here `.
diff --git a/docs/connect/python.rst b/docs/connect/python.rst
new file mode 100644
index 0000000..82a2ded
--- /dev/null
+++ b/docs/connect/python.rst
@@ -0,0 +1,102 @@
+.. _connect-python:
+
+======
+Python
+======
+
+This guide demonstrates how to connect to a CrateDB Cloud cluster using different
+kinds of Python drivers. Individual drivers offer specific features for specific
+needs of your application, so consider reading this enumeration carefully.
+
+crate-python
+------------
+
+The ``crate`` Python package offers a database client implementation compatible
+with the Python Database API 2.0 specification, and also includes the CrateDB
+SQLAlchemy dialect. See the full documentation :ref:`here `.
+The package can be installed using ``pip install crate[sqlalchemy]``.
+
+.. code-block:: python
+
+ from crate import client
+
+ conn = client.connect("https://.cratedb.net:4200", username="admin", password="", verify_ssl_cert=True)
+
+ with conn:
+ cursor = conn.cursor()
+ cursor.execute("SELECT name FROM sys.cluster")
+ result = cursor.fetchone()
+ print(result)
+
+psycopg2
+--------
+
+Psycopg is a popular PostgreSQL database adapter for Python. Its main features
+are the complete implementation of the Python DB API 2.0 specification and the
+thread safety (several threads can share the same connection).
+For more information, see the `psycopg documentation`_.
+
+.. code-block:: python
+
+ import psycopg2
+
+ conn = psycopg2.connect(host=".cratedb.net", port=5432, user="admin", password="", sslmode="require")
+
+ with conn:
+ with conn.cursor() as cursor:
+ cursor.execute("SELECT name FROM sys.cluster")
+ result = cursor.fetchone()
+ print(result)
+
+aiopg
+-----
+
+aiopg is a python library for accessing a PostgreSQL database from the asyncio
+PEP-3156/tulip) framework. It wraps asynchronous features of the Psycopg
+database driver.
+For more information, see the `aiopg documentation`_.
+
+.. code-block:: python
+
+ import asyncio
+ import aiopg
+
+ async def run():
+ async with aiopg.create_pool(host=".cratedb.net", port=5432, user="admin", password="", sslmode="require") as pool:
+ async with pool.acquire() as conn:
+ async with conn.cursor() as cursor:
+ await cursor.execute("SELECT name FROM sys.cluster")
+ result = await cursor.fetchone()
+ print(result)
+
+ loop = asyncio.get_event_loop()
+ loop.run_until_complete(run())
+
+asyncpg
+-------
+
+asyncpg is a database interface library designed specifically for PostgreSQL
+and Python/asyncio. asyncpg is an efficient, clean implementation of the
+PostgreSQL server binary protocol for use with Python's asyncio framework.
+For more information, see the `asyncpg documentation`_.
+
+.. code-block:: python
+
+ import asyncio
+ import asyncpg
+
+ async def run():
+ conn = await asyncpg.connect(host=".cratedb.net", port=5432, user="admin", password="", ssl=True)
+ try:
+ result = await conn.fetch("SELECT name FROM sys.cluster")
+ finally:
+ await conn.close()
+ print(result)
+
+ loop = asyncio.get_event_loop()
+ loop.run_until_complete(run())
+
+
+.. _psycopg documentation: https://www.psycopg.org/docs/
+.. _aiopg documentation: https://aiopg.readthedocs.io/
+.. _asyncpg documentation: https://magicstack.github.io/asyncpg/current/
diff --git a/docs/connect/ruby.rst b/docs/connect/ruby.rst
new file mode 100644
index 0000000..29458ec
--- /dev/null
+++ b/docs/connect/ruby.rst
@@ -0,0 +1,20 @@
+.. _connect-ruby:
+
+====
+Ruby
+====
+
+This section shows an example implementation of Ruby client library for CrateDB
+Cloud:
+
+.. code-block:: ruby
+
+ require 'crate_ruby'
+
+ client = CrateRuby::Client.new(servers=[".cratedb.net:4200"], username: "admin", password: "", ssl: true)
+ result = client.execute("SELECT name FROM sys.cluster")
+ p result.to_a
+
+For additional information see `our GitHub documentation`_.
+
+.. _our GitHub documentation: https://github.com/crate/crate_ruby/blob/main/README.rst
\ No newline at end of file
diff --git a/docs/etl.md b/docs/etl.md
new file mode 100644
index 0000000..11ac512
--- /dev/null
+++ b/docs/etl.md
@@ -0,0 +1,184 @@
+(etl)=
+# ETL with CrateDB
+
+Use ETL applications and frameworks for transferring data in and out of CrateDB.
+
+```{note}
+This section is a work in progress.
+```
+
+
+## General
+
+- [Automating recurrent CrateDB queries]
+
+
+## Apache Airflow
+
+[Apache Airflow] is a software platform to programmatically author, schedule, and
+monitor workflows, written in Python.
+
+```{div}
+:style: "float: right"
+[{w=180px}](https://airflow.apache.org/)
+```
+
+A set of starter tutorials.
+
+- [Automating the import of Parquet files with Apache Airflow]
+- [Updating stock market data automatically with CrateDB and Apache Airflow]
+- [Automating stock data collection and storage with CrateDB and Apache Airflow]
+
+A set of elaborated tutorials, including blueprint implementations.
+
+- [Automating export of CrateDB data to S3 using Apache Airflow]
+- [Implementing a data retention policy in CrateDB using Apache Airflow]
+- [CrateDB and Apache Airflow: Building a data ingestion pipeline]
+- [Building a hot and cold storage data retention policy in CrateDB with Apache Airflow]
+
+```{seealso}
+[CrateDB and Apache Airflow]
+```
+
+
+## Apache Flink
+
+```{div}
+:style: "float: right"
+[{w=180px}](https://flink.apache.org/)
+```
+
+[Apache Flink] is a framework and distributed processing engine for stateful
+computations over unbounded and bounded data streams. Flink has been designed
+to run in all common cluster environments, perform computations at in-memory
+speed and at any scale.
+
+- [Build a data ingestion pipeline using Kafka, Flink, and CrateDB]
+- [Community Day: Stream processing with Apache Flink and CrateDB]
+- [Executable stack: Apache Kafka, Apache Flink, and CrateDB]
+
+{h=200px}
+
+
+## Apache Kafka
+
+```{div}
+:style: "float: right"
+[{w=180px}](https://kafka.apache.org/)
+```
+
+[Apache Kafka] is an open-source distributed event streaming platform used by
+thousands of companies for high-performance data pipelines, streaming analytics,
+data integration, and mission-critical applications.
+
+- [Data Ingestion using Kafka and Kafka Connect]
+
+```{seealso}
+[CrateDB and Apache Kafka]
+```
+
+
+## Debezium
+
+```{div}
+:style: "float: right"
+[{w=180px}](https://debezium.io/)
+```
+
+[Debezium] is an open source distributed platform for change data capture. After
+pointing it at your databases, you are able to subscribe to the event stream of
+all database update operations.
+
+- [Tutorial: Replicating data to CrateDB with Debezium and Kafka]
+- [Webinar: How to replicate data from other databases to CrateDB with Debezium and Kafka]
+
+
+
+## Node-RED
+
+```{div}
+:style: "float: right"
+[{w=180px}](https://nodered.org/)
+```
+
+[Node-RED] is a programming tool for wiring together hardware devices, APIs
+and online services within a low-code programming environment for event-driven
+applications. It allows orchestrating message flows and transformations through
+an intuitive web interface.
+
+It provides a browser-based editor that makes it easy to wire together flows
+using the wide range of elements called "nodes" from the palette that can be
+deployed to its runtime in a single-click.
+
+- [Ingesting MQTT messages into CrateDB using Node-RED]
+
+```{seealso}
+[CrateDB and Node-RED]
+```
+
+
+## pandas
+
+[pandas] is a fast, powerful, flexible and easy to use open source data analysis
+and manipulation tool, built on top of the Python programming language.
+
+```{div}
+:style: "float: right"
+[{w=180px}](https://pandas.pydata.org/)
+```
+
+- [Importing Parquet files into CrateDB using Apache Arrow and SQLAlchemy]
+- [Guide to efficient data ingestion to CrateDB with pandas]
+- [Guide to efficient data ingestion to CrateDB with pandas and Dask]
+
+
+## Telegraf
+
+```{div}
+:style: "float: right"
+[{w=180px}](https://www.influxdata.com/time-series-platform/telegraf/)
+```
+
+[Telegraf] is a leading open source server agent to help you collect metrics
+from your stacks, sensors, and systems. More than 200 adapters to connect
+to other systems leaves nothing to be desired.
+
+- [Use CrateDB With Telegraf, an Agent for Collecting & Reporting Metrics]
+
+{h=200px}
+
+```{seealso}
+[CrateDB and Telegraf]
+```
+
+
+[Apache Airflow]: https://airflow.apache.org/
+[Apache Flink]: https://flink.apache.org/
+[Apache Kafka]: https://kafka.apache.org/
+[Automating recurrent CrateDB queries]: https://community.crate.io/t/automating-recurrent-cratedb-queries/788
+[Automating export of CrateDB data to S3 using Apache Airflow]: https://community.crate.io/t/cratedb-and-apache-airflow-automating-data-export-to-s3/901
+[Automating stock data collection and storage with CrateDB and Apache Airflow]: https://community.crate.io/t/automating-stock-data-collection-and-storage-with-cratedb-and-apache-airflow/990
+[Automating the import of Parquet files with Apache Airflow]: https://community.crate.io/t/automating-the-import-of-parquet-files-with-apache-airflow/1247
+[Build a data ingestion pipeline using Kafka, Flink, and CrateDB]: https://dev.to/crate/build-a-data-ingestion-pipeline-using-kafka-flink-and-cratedb-1h5o
+[Building a hot and cold storage data retention policy in CrateDB with Apache Airflow]: https://community.crate.io/t/cratedb-and-apache-airflow-building-a-hot-cold-storage-data-retention-policy/934
+[Community Day: Stream processing with Apache Flink and CrateDB]: https://crate.io/blog/cratedb-community-day-2nd-edition-summary-and-highlights
+[CrateDB and Apache Airflow]: https://crate.io/integrations/cratedb-and-apache-airflow
+[CrateDB and Apache Airflow: Building a data ingestion pipeline]: https://community.crate.io/t/cratedb-and-apache-airflow-building-a-data-ingestion-pipeline/926
+[CrateDB and Apache Kafka]: https://crate.io/integrations/cratedb-and-kafka
+[CrateDB and Node-RED]: https://crate.io/integrations/cratedb-and-node-red
+[CrateDB and Telegraf]: https://crate.io/integrations/cratedb-and-telegraf
+[Data Ingestion using Kafka and Kafka Connect]: https://crate.io/docs/crate/howtos/en/latest/integrations/kafka-connect.html
+[Debezium]: https://debezium.io/
+[Executable stack: Apache Kafka, Apache Flink, and CrateDB]: https://github.com/crate/cratedb-examples/tree/main/stacks/kafka-flink
+[Guide to efficient data ingestion to CrateDB with pandas]: https://community.crate.io/t/guide-to-efficient-data-ingestion-to-cratedb-with-pandas/1541
+[Guide to efficient data ingestion to CrateDB with pandas and Dask]: https://community.crate.io/t/guide-to-efficient-data-ingestion-to-cratedb-with-pandas-and-dask/1482
+[Implementing a data retention policy in CrateDB using Apache Airflow]: https://community.crate.io/t/implementing-a-data-retention-policy-in-cratedb-using-apache-airflow/913
+[Importing Parquet files into CrateDB using Apache Arrow and SQLAlchemy]: https://community.crate.io/t/importing-parquet-files-into-cratedb-using-apache-arrow-and-sqlalchemy/1161
+[Ingesting MQTT messages into CrateDB using Node-RED]: https://community.crate.io/t/ingesting-mqtt-messages-into-cratedb-using-node-red/803
+[Node-RED]: https://nodered.org/
+[pandas]: https://pandas.pydata.org/
+[Telegraf]: https://www.influxdata.com/time-series-platform/telegraf/
+[Tutorial: Replicating data to CrateDB with Debezium and Kafka]: https://community.crate.io/t/replicating-data-to-cratedb-with-debezium-and-kafka/1388
+[Updating stock market data automatically with CrateDB and Apache Airflow]: https://community.crate.io/t/updating-stock-market-data-automatically-with-cratedb-and-apache-airflow/1304
+[Use CrateDB With Telegraf, an Agent for Collecting & Reporting Metrics]: https://crate.io/blog/use-cratedb-with-telegraf-an-agent-for-collecting-reporting-metrics
+[Webinar: How to replicate data from other databases to CrateDB with Debezium and Kafka]: https://crate.io/resources/webinars/lp-wb-debezium-kafka
diff --git a/docs/ide.md b/docs/ide.md
new file mode 100644
index 0000000..a1d541b
--- /dev/null
+++ b/docs/ide.md
@@ -0,0 +1,29 @@
+(ide)=
+
+# Using database IDEs with CrateDB
+
+Mostly through its PostgreSQL interface, CrateDB supports working with popular
+database IDE (Integrated Development Environment) applications.
+
+
+## DBeaver
+
+```{div}
+:style: "float: right"
+[{w=120px}](https://dbeaver.io/)
+```
+
+[DBeaver] is a multipurpose database tool for developers and database administrators.
+Because CrateDB provides a JDBC driver, you can access CrateDB with any client tool that supports JDBC drivers.
+
+Connecting DBeaver to CrateDB uses the legacy PostgreSQL JDBC Driver, the blog
+article [Blog: Use CrateDB With DBeaver] explains how it works.
+
+{h=200px}
+{h=200px}
+
+
+
+[Blog: Use CrateDB With DataGrip]: https://crate.io/blog/use-cratedb-with-datagrip-an-advanced-database-ide
+[Blog: Use CrateDB With DBeaver]: https://crate.io/blog/cratedb-dbeaver
+[DBeaver]: https://dbeaver.io/
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..241abd2
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,144 @@
+(index)=
+
+# CrateDB Clients and Tools
+
+
+## About CrateDB
+
+CrateDB is a distributed and scalable open-source SQL database for storing and
+analyzing massive amounts of data in near real-time, even with complex queries.
+It is PostgreSQL-compatible, and based on Lucene.
+
+Users are operating CrateDB clusters that store information in the range of
+billions of records, and terabytes of data, equally accessible without any
+retrieval penalty on data point age.
+
+
+## Connectivity
+
+This section introduces you to the canonical set of database drivers, client-
+and developer-applications, and how to configure them to connect to CrateDB.
+Just to name a few, it is about the CrateDB Admin UI, `crash`, `psql`,
+DataGrip, and DBeaver applications, the Java/JDBC/Python drivers, the SQLAlchemy
+and Flink dialects, and more.
+
+::::{grid} 1 2 2 3
+:margin: 4 4 0 0
+:gutter: 1
+
+
+:::{grid-item-card} {material-outlined}`code;2em` IDE
+:link: ide
+:link-type: ref
+
+Learn how to connect to CrateDB using a database IDE like DataGrip
+or DBeaver.
+:::
+
+
+:::{grid-item-card} {material-outlined}`terminal;2em` CLI
+:link: cli
+:link-type: ref
+
+Learn how to connect to a CrateDB cluster using command-line
+based terminal programs.
+:::
+
+
+:::{grid-item-card} {material-outlined}`link;2em` Library
+:link: connect
+:link-type: ref
+
+Learn how to configure your favorite client library to connect to a
+CrateDB cluster.
+:::
+
+
+::::
+
+
+## Integrations
+
+CrateDB integrates well with a diverse set of applications and tools concerned
+with analytics, visualization, and data wrangling, in the areas of ETL, BI,
+metrics aggregation and monitoring, and more.
+
+::::{grid} 1 2 2 4
+:margin: 4 4 0 0
+:gutter: 1
+
+
+:::{grid-item-card} {material-outlined}`integration_instructions;2em` Overview
+:link: https://community.crate.io/t/overview-of-cratedb-integration-tutorials/1015
+:link-type: url
+
+Use CrateDB with popular applications, frameworks, and tools.
+:::
+
+
+:::{grid-item-card} {material-outlined}`transform;2em` ETL
+:link: etl
+:link-type: ref
+
+Use ETL applications and frameworks for transferring data in and out of CrateDB.
+:::
+
+
+:::{grid-item-card} {material-outlined}`analytics;2em` Analytics
+:link: analyze
+:link-type: ref
+
+Analyze information in your CrateDB cluster.
+:::
+
+
+:::{grid-item-card} {material-outlined}`bar_chart;2em` Visualization
+:link: visualize
+:link-type: ref
+
+Visualize information in your CrateDB cluster.
+:::
+
+
+::::
+
+
+
+```{note} Contributions are welcome.
+
+If you would like to add items about integrations with other tools to this
+documentation section, please [get in touch], or directly edit this page on
+GitHub. You will find corresponding links within the topmost right navigation
+element.
+```
+
+```{seealso}
+Looking for the previous content on this page? Visit [](#index-legacy).
+```
+
+
+```{toctree}
+:hidden:
+
+IDE applications
+CLI programs
+Database drivers
+
+```
+
+```{toctree}
+:hidden:
+
+Load and export data
+Analyze data
+Visualize data
+```
+
+```{toctree}
+:hidden:
+
+Legacy documentation
+```
+
+
+[get in touch]: https://crate.io/contact
diff --git a/docs/index.rst b/docs/legacy.rst
similarity index 95%
rename from docs/index.rst
rename to docs/legacy.rst
index 9abf37b..e4da24c 100644
--- a/docs/index.rst
+++ b/docs/legacy.rst
@@ -1,8 +1,8 @@
-.. _index:
+.. _index-legacy:
-=========================
-CrateDB Clients and Tools
-=========================
+==================================
+[Legacy] CrateDB Clients and Tools
+==================================
CrateDB is a distributed SQL database that makes it simple to store and analyze
massive amounts of machine data in real-time.
@@ -178,8 +178,9 @@ CrateDB integrates with many different tools. Some of these are:
.. NOTE::
- If you would like to add to this page, please `get in touch`_ or
- `edit this page`_ on GitHub.
+ If you would like to add items to this page, please `get in touch`_ or
+ directly edit this page on GitHub. You will find corresponding links within
+ the topmost right navigation element.
.. _activerecord-crate-adaptor: https://rubygems.org/gems/activerecord-crate-adapter
@@ -204,7 +205,6 @@ CrateDB integrates with many different tools. Some of these are:
.. _create a data enrichment pipeline: https://crate.io/docs/crate/howtos/en/latest/integrations/azure-functions.html
.. _create a Machine Learning pipeline: https://crate.io/docs/crate/howtos/en/latest/integrations/r.html
.. _DBD::Crate: https://github.com/mamod/DBD-Crate
-.. _edit this page: https://github.com/crate/crate-clients-tools/blob/master/docs/index.rst
.. _get in touch: https://crate.io/contact
.. _GitHub: https://github.com/crate/crate-clients-tools
.. _Grafana: https://grafana.com
diff --git a/docs/visualize.md b/docs/visualize.md
new file mode 100644
index 0000000..5f1c446
--- /dev/null
+++ b/docs/visualize.md
@@ -0,0 +1,84 @@
+(visualize)=
+# Visualize data in CrateDB
+
+
+## Apache Superset
+
+```{div}
+:style: "float: right"
+[{w=180px}](https://superset.apache.org/)
+```
+
+[Apache Superset] is an open-source modern data exploration and visualization
+platform, written in Python.
+
+- [Introduction to Time-Series Visualization in CrateDB and Superset]
+- [Use CrateDB and Apache Superset for Open Source Data Warehousing and Visualization]
+- [Set up an Apache Superset development sandbox with CrateDB]
+
+{h=200px}
+{h=200px}
+
+```{seealso}
+[CrateDB and Superset]
+```
+
+
+## Explo Explore
+
+```{div}
+:style: "float: right"
+[{w=180px}](https://www.explo.co/)
+```
+
+[Explo] is a software platform for personalized and real-time customer facing
+analytics. Organizations use Explo’s platform services "Explore", "Host", "Report
+builder", and "Email", to activate and share data with their customers.
+
+[Explo Explore] integrates directly into your web portal or application and provides
+your customers with a complete self-service data toolkit, which can also be used to
+run white-labeled data portals.
+
+- [Introduction to Time Series Visualization in CrateDB and Explo]
+
+{h=200px}
+{h=200px}
+
+
+## Grafana
+
+```{div}
+:style: "float: right"
+[{w=180px}](https://grafana.com/grafana/)
+```
+
+[Grafana] is the leading open-source metrics visualization tool that helps you
+build real-time dashboards, graphs, and many other sorts of data visualizations.
+It complements CrateDB in monitoring large volumes of machine data in real-time.
+
+Connecting to a CrateDB cluster will use the Grafana PostgreSQL data source adapter.
+The following tutorials outline how to configure Grafana to connect to CrateDB, and
+how to run a database query.
+
+- [Using Grafana with CrateDB Cloud]
+
+{h=200px}
+{h=200px}
+
+```{seealso}
+[CrateDB and Grafana]
+```
+
+
+
+[Apache Superset]: https://superset.apache.org/
+[CrateDB and Grafana]: https://crate.io/integrations/cratedb-and-grafana
+[CrateDB and Superset]: https://crate.io/integrations/cratedb-and-apache-superset
+[Explo]: https://www.explo.co/
+[Explo Explore]: https://www.explo.co/products/explore
+[Grafana]: https://grafana.com/grafana/
+[Introduction to Time Series Visualization in CrateDB and Explo]: https://crate.io/blog/introduction-to-time-series-visualization-in-cratedb-and-explo
+[Introduction to Time-Series Visualization in CrateDB and Superset]: https://community.crate.io/t/introduction-to-time-series-visualization-in-cratedb-and-superset/1041
+[Set up an Apache Superset development sandbox with CrateDB]: https://community.crate.io/t/set-up-an-apache-superset-development-sandbox-with-cratedb/1163
+[Use CrateDB and Apache Superset for Open Source Data Warehousing and Visualization]: https://crate.io/blog/use-cratedb-and-apache-superset-for-open-source-data-warehousing-and-visualization
+[Using Grafana with CrateDB Cloud]: inv:cloud-howtos:std:label#visualize-data-with-grafana