Driver: Add page about ODBC

docs/_include/links.md

@@ -67,6 +67,8 @@
 [ODBC]: https://en.wikipedia.org/wiki/Open_Database_Connectivity
 [PostgreSQL JDBC Driver]: https://jdbc.postgresql.org/
 [PostgreSQL wire protocol]: https://www.postgresql.org/docs/current/protocol.html
+[psqlODBC]: https://odbc.postgresql.org/
+[psqlODBC download site]: https://www.postgresql.org/ftp/odbc/releases/
 [python-dbapi-by-example]: inv:crate-python:*:label#by-example
 [python-sqlalchemy-by-example]: inv:sqlalchemy-cratedb:*:label#by-example
 [query DSL based on JSON]: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html
@@ -79,5 +81,6 @@
 [TF–IDF]: https://en.wikipedia.org/wiki/Tf%E2%80%93idf
 [timeseries-queries-and-visualization-colab]: https://colab.research.google.com/github/crate/cratedb-examples/blob/main/topic/timeseries/timeseries-queries-and-visualization.ipynb
 [timeseries-queries-and-visualization-github]: https://github.com/crate/cratedb-examples/blob/main/topic/timeseries/timeseries-queries-and-visualization.ipynb
+[unixODBC]: https://www.unixodbc.org/
 [Vector Database (Product)]: https://cratedb.com/solutions/vector-database
 [Vector Database]: https://en.wikipedia.org/wiki/Vector_database

docs/connect/application.md

@@ -106,6 +106,54 @@ crash --command "SELECT 42.42;"
 ::::
 
 
+(isql)=
+### isql
+
+`isql` and `iusql` are unixODBC command-line tools allowing users to execute
+SQL interactively or in batches.
+The tools provide several useful features, including an option to generate
+output wrapped in an HTML table.
+
+:::{include} /connect/odbc/setup-widget.md
+:::
+
+::::{tab-set}
+
+:::{tab-item} CrateDB Cloud
+:sync: server
+```{code} ini
+[CrateDB Cloud]
+Driver      = PostgreSQL ODBC
+Servername  = testcluster.cratedb.net
+Port        = 5432
+Sslmode     = require
+Username    = admin
+Password    = password
+```
+```shell
+echo "SELECT 42.42" | iusql "CrateDB Cloud"
+```
+:::
+
+:::{tab-item} CrateDB on localhost
+:sync: localhost
+```{code} ini
+[CrateDB]
+Driver      = PostgreSQL ODBC
+Servername  = localhost
+Port        = 5432
+Sslmode     = disable
+Username    = crate
+Password    = crate
+```
+```shell
+echo "SELECT 42.42" | iusql "CrateDB"
+```
+:::
+
+::::
+
+
 (psql)=
 ### psql
 

docs/connect/index.md

@@ -115,6 +115,29 @@ CrateDB drivers and adapters for supported programming languages, frameworks, an
 
 :::::
 
+:::{rubric} Language-agnostic drivers
+:::
+
+:::::{grid} 2 2 2 4
+:margin: 4 4 0 0
+:padding: 0
+
+::::{grid-item-card} ODBC
+:link: connect-odbc
+:link-type: ref
+:link-alt: Connect to CrateDB using ODBC
+:padding: 3
+:text-align: center
+:class-card: sd-pt-3
+:class-body: sd-fs-1
+:class-title: sd-fs-6
+```{image} /_assets/icon/odbc-logo.png
+:height: 80px
+```
+::::
+
+:::::
+
 
 :::{rubric} Protocol Support
 :::
@@ -187,6 +210,7 @@ javascript
 php
 python
 ruby
+odbc/index
 natural
 All drivers <drivers>
 ```

docs/connect/odbc/index.md

@@ -0,0 +1,197 @@
+(odbc)=
+(connect-odbc)=
+
+# ODBC
+
+:::{include} /_include/links.md
+:::
+
+:::{div} sd-text-muted
+Connect to CrateDB with ODBC.
+:::
+
+## General information
+
+:::{rubric} About
+:::
+
+:::{div}
+Open Database Connectivity ([ODBC]) is a standard application programming
+interface (API) for accessing database management systems (DBMS),
+conceived to be independent of database systems and operating systems.
+The application uses ODBC functions through an _ODBC driver manager_ and
+addresses the driver and database using a _Data Source Name (DSN)_.
+:::
+
+:::{include} /connect/odbc/setup-widget.md
+:::
+
+## Examples
+
+A few examples to demonstrate CrateDB connectivity with ODBC. While the examples
+enumerated below use `Driver={PostgreSQL ODBC}` for addressing the driver, you can
+also address a named connection using `Dsn=your_dsn_name` instead.
+
+### C#
+
+Use the ODBC .NET Data Provider to access data from your C Sharp ADO\.NET
+applications. The [.NET Framework Data Provider for ODBC] is available
+through the [System.Data.Odbc] namespace.
+
+```c#
+using System.Data.Odbc;
+
+// Connect to database
+string connection_string = "ODBC;Driver={PostgreSQL ODBC};Server=localhost;Port=5432;Uid=crate;Pwd=crate;Database=doc;MaxVarcharSize=1073741824";
+OdbcConnection connection = new OdbcConnection(connection_string);
+connection.Open();
+
+// Invoke query
+OdbcCommand command = new OdbcCommand("SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 5", connection);
+OdbcDataReader reader = command.ExecuteReader();
+
+// Display results
+while(reader.Read())
+{
+  String mountain = reader.GetString(0);
+  int height = reader.GetInt32(1);
+  Console.Write(mountain + ": " + height);
+  Console.WriteLine();
+}
+
+// Clean up
+reader.Close();
+command.Dispose();
+connection.Close();
+```
+
+### Erlang
+
+The [Erlang ODBC application] provides an interface to communicate
+with relational SQL-databases out of the box.
+
+```erlang
+odbc:start(),
+{ok, Ref} = odbc:connect("Driver={PostgreSQL ODBC};Server=localhost;Port=5432;Uid=crate;Pwd=crate", []),
+io:fwrite("~p~n", [odbc:sql_query(Ref, "SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 3")]),
+```
+
+:::{todo}
+Enable with the [Erlang patch](https://github.com/crate/cratedb-guide/pull/420).
+```
+- {ref}`connect-erlang`
+```
+:::
+
+### Python (pyodbc)
+
+[pyodbc] is an open-source Python module that makes accessing ODBC databases
+simple. It implements the DB API 2.0 specification and adds other Pythonic
+convenience. For more information, please visit the
+[pyodbc installation instructions] and [connecting to PostgreSQL with pyodbc].
+
+```shell
+pip install --upgrade pyodbc
+```
+```python
+import pyodbc
+
+# Connect to database
+connection_string = \
+    "Driver={PostgreSQL ODBC};Server=localhost;Port=5432;" \
+    "Uid=crate;Pwd=crate;Database=doc;MaxVarcharSize=1073741824"
+connection = pyodbc.connect(connection_string)
+
+# Invoke query
+cursor = connection.cursor()
+cursor.execute("SELECT * FROM sys.summits ORDER BY height DESC LIMIT 5")
+
+# Display results
+for row in cursor:
+    print(row)
+
+# Clean up
+cursor.close()
+connection.close()
+```
+
+### Python (turbodbc)
+
+[turbodbc] is a Python module to access relational databases via the Open
+Database Connectivity (ODBC) interface. turbodbc offers built-in NumPy and
+Apache Arrow for maximum performance.
+
+```shell
+pip install --upgrade turbodbc
+```
+```python
+import turbodbc
+
+# Connect to database
+connection_string = \
+    "Driver={PostgreSQL ODBC};Server=localhost;Port=5432;" \
+    "Uid=crate;Pwd=crate;Database=doc;MaxVarcharSize=1073741824"
+connection = turbodbc.connect(connection_string)
+
+# Invoke query
+cursor = connection.cursor()
+cursor.execute("SELECT * FROM sys.summits ORDER BY height DESC LIMIT 5")
+
+# Display results
+for row in cursor:
+    print(row)
+
+# Clean up
+cursor.close()
+connection.close()
+```
+
+:::{todo}
+Enable with the [Python patch](https://github.com/crate/cratedb-guide/pull/403).
+```
+- {ref}`Turbodbc -- a high-performance ODBC library <turbodbc>`
+```
+:::
+
+### Visual Basic
+
+See also [psqlODBC with Visual Basic]. Please navigate to the
+[psqlODBC download site] to download and install the `psqlodbc`
+driver for Windows systems.
+
+```visualbasic
+Dim cn as New ADODB.Connection
+Dim rs as New ADODB.Recordset
+
+'Connect to database
+cn.Open "Dsn=<MyDataSourceName>;" & _
+        "Server=localhost;" & _
+        "Port=5432;" & _
+        "Uid=crate;" & _
+        "Pwd=crate;" & _
+        "Database=doc;" & _
+        "MaxVarcharSize=1073741824;"
+
+'Invoke query
+rs.Open "SELECT * FROM sys.summits ORDER BY height DESC LIMIT 5", cn
+
+'Display results
+While Not rs.EOF
+  Debug.Print rs!mountain & ": " & rs!height
+  rs.MoveNext
+Wend
+
+'Clean up
+rs.Close
+cn.Close
+```
+
+
+[.NET Framework Data Provider for ODBC]: https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/data-providers#net-framework-data-provider-for-odbc
+[connecting to PostgreSQL with pyodbc]: https://github.com/mkleehammer/pyodbc/wiki/Connecting-to-PostgreSQL
+[Erlang ODBC application]: https://www.erlang.org/docs/28/apps/odbc/odbc.html
+[psqlODBC with Visual Basic]: https://odbc.postgresql.org/howto-vb.html
+[pyodbc]: https://github.com/mkleehammer/pyodbc
+[pyodbc installation instructions]: https://github.com/mkleehammer/pyodbc/wiki/Install
+[System.Data.Odbc]: https://learn.microsoft.com/en-us/dotnet/api/system.data.odbc
+[turbodbc]: https://turbodbc.readthedocs.io/

docs/connect/odbc/setup-body.md

@@ -0,0 +1,66 @@
+---
+orphan: true
+---
+
+:::{rubric} Prerequisites
+:::
+
+While Windows OS typically includes an ODBC driver manager, you can
+install the [unixODBC] driver manager on Linux and macOS systems.
+The PostgreSQL ODBC driver is called [psqlODBC].
+
+:Windows:
+
+  On Windows, download the latest 64-bit driver installer
+  (MSI file) from the [psqlODBC download site] and invoke it.
+  [Installing PostgreSQL ODBC Drivers] includes a walkthrough
+  including screenshots.
+
+:Linux and macOS:
+
+  On Linux and macOS, install the [unixODBC] ODBC driver manager,
+  then install and register psqlODBC.
+
+`odbcinst.ini`
+```ini
+[PostgreSQL ODBC]
+Description     = ODBC Driver for PostgreSQL
+
+# Linux Arch
+# pacman -Sy psqlodbc
+# Driver          = /usr/lib/psqlodbcw.so
+
+# Linux Debian
+# apt install --yes odbc-postgresql odbcinst unixodbc
+# Driver          = /usr/lib/x86_64-linux-gnu/odbc/psqlodbcw.so
+
+# Linux Red Hat
+# yum install -y postgresql-odbc
+# Driver          = /usr/lib64/psqlodbcw.so
+
+# Linux Generic
+# Driver          = /usr/lib64/libodbcpsql.so
+# Setup           = /usr/lib64/libodbcpsqlS.so
+
+# macOS
+# brew install psqlodbc unixodbc
+Driver          = /usr/local/lib/psqlodbcw.so
+```
+Before registering the driver, enable the `Driver` line matching your system.
+```shell
+odbcinst -i -d -f odbcinst.ini
+```
+
+:::{rubric} DSN-less configuration
+:::
+
+A typical connection string for CrateDB is:
+
+```text
+ODBC;Driver={PostgreSQL ODBC};Server=localhost;Port=5432;Uid=crate;Pwd=crate;MaxVarcharSize=1073741824
+```
+
+For some drivers, you will need to omit the `ODBC;` prefix.
+
+
+[Installing PostgreSQL ODBC Drivers]: https://help.campbellsci.com/PC400%20Manual/viewpro/installing_postgresql_odbc_drivers.htm

docs/connect/odbc/setup-widget.md

@@ -0,0 +1,11 @@
+---
+orphan: true
+---
+
+The PostgreSQL ODBC driver [psqlODBC]
+can be used to connect to CrateDB from ODBC environments.
+
+::::{dropdown} Learn how to install and configure the PostgreSQL ODBC driver
+:::{include} /connect/odbc/setup-body.md
+:::
+::::