Driver: Add page about ODBC

docs/_include/links.md

@@ -67,7 +67,6 @@
 [Multi-model Database]: https://cratedb.com/solutions/multi-model-database
 [nearest neighbor search]: https://en.wikipedia.org/wiki/Nearest_neighbor_search
 [Nested Data Structure]: https://cratedb.com/product/features/nested-data-structure
-[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
 [python-dbapi-by-example]: inv:crate-python:*:label#by-example

docs/connect/application.md

@@ -186,6 +186,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/install-dropdown.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

@@ -110,6 +110,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
 :::
@@ -181,6 +204,7 @@ javascript
 php
 python
 ruby
+odbc/index
 natural
 All drivers <drivers>
 ```

docs/connect/odbc/configure.md

@@ -0,0 +1,55 @@
+---
+orphan: true
+---
+
+For connecting to CrateDB, either address the database using a named
+connection (DSN), e.g. using `Dsn=CrateDB`, or address it directly
+using the driver, like `Driver={PostgreSQL Unicode}`.
+
+:::{rubric} DSN configuration
+:::
+
+When using a DSN, a typical connection string for CrateDB is:
+```text
+Dsn=CrateDB
+```
+
+:::::{tab-set}
+
+::::{tab-item} Windows
+On Windows, you will create a DSN using the ODBC driver manager UI.
+To set up a DSN (Data Source Name), click the "System DSN" tab. Click "Add".
+Select "PostgreSQL Unicode" and click "Finish".
+The [illustrated walkthrough][Installing PostgreSQL ODBC drivers on Windows]
+also covers that part.
+::::
+
+::::{tab-item} Linux and macOS
+With unixODBC, configure a DSN within an `.odbc.ini` or `/etc/odbc.ini`
+file.
+
+`~/.odbc.ini` 
+```ini
+[CrateDB]
+Description=CrateDB
+Driver=PostgreSQL Unicode
+Server=localhost
+Port=5432
+Uid=crate
+Pwd=crate
+MaxVarcharSize=1073741824
+```
+
+::::
+
+:::::
+
+
+:::{rubric} DSN-less configuration
+:::
+
+For directly connecting using a driver, without a registered DSN,
+a typical connection string for CrateDB is:
+```text
+Driver={PostgreSQL Unicode};Server=localhost;Port=5432;Uid=crate;Pwd=crate;MaxVarcharSize=1073741824
+```

docs/connect/odbc/csharp.md

@@ -0,0 +1,83 @@
+(odbc-csharp)=
+
+# ODBC with C#
+
+:::{rubric} About
+:::
+
+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.
+
+:::{rubric} Install
+:::
+
+:::{include} /connect/odbc/install-dropdown.md
+:::
+
+:::{rubric} Synopsis
+:::
+
+`example.csproj`
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net$(NETCoreAppMaximumVersion)</TargetFramework>
+    <GenerateProgramFile>false</GenerateProgramFile>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="System.Data.Odbc" Version="9.*" />
+  </ItemGroup>
+
+</Project>
+```
+`example.cs`
+```c#
+using System;
+using System.Data.Odbc;
+
+// Connect to database
+string connection_string = "Driver={PostgreSQL Unicode};Server=localhost;Port=5432;Uid=crate;Pwd=crate;MaxVarcharSize=1073741824";
+using (OdbcConnection connection = new OdbcConnection(connection_string))
+{
+    connection.Open();
+
+    // Invoke query
+    using (OdbcCommand command = new OdbcCommand("SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 5", connection))
+    using (OdbcDataReader reader = command.ExecuteReader())
+    {
+        // Display results
+        while (reader.Read())
+            Console.WriteLine($"{reader.GetString(0)}: {reader.GetInt32(1)}");
+    }
+}
+```
+
+:::{rubric} Example
+:::
+
+Create the files `example.csproj` and `example.cs` including the synopsis code shared above.
+
+:::{include} ../_cratedb.md
+:::
+Invoke program.
+```shell
+dotnet run
+```
+
+:::{rubric} CrateDB Cloud
+:::
+
+For connecting to CrateDB Cloud, use the `Sslmode=require` parameter,
+and replace username, password, and hostname with values matching
+your environment.
+```csharp
+string connection_string = "Driver={PostgreSQL Unicode};Server=testcluster.cratedb.net;Port=5432;Sslmode=require;Uid=admin;Pwd=password";
+```
+
+
+[.NET Framework Data Provider for ODBC]: https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/data-providers#net-framework-data-provider-for-odbc
+[System.Data.Odbc]: https://learn.microsoft.com/en-us/dotnet/api/system.data.odbc

docs/connect/odbc/erlang.md

@@ -0,0 +1,38 @@
+(odbc-erlang)=
+
+# ODBC with Erlang
+
+:::{rubric} About
+:::
+
+The [Erlang ODBC application] provides an interface to communicate
+with relational SQL-databases out of the box.
+
+:::{rubric} Install
+:::
+
+:::{include} /connect/odbc/install-dropdown.md
+:::
+
+:::{rubric} Synopsis
+:::
+
+`example.erl`
+```erlang
+odbc:start(),
+{ok, Ref} = odbc:connect("Driver={PostgreSQL Unicode};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")]),
+```
+
+:::{rubric} Example
+:::
+
+:::{todo}
+Enable with the [Erlang patch](https://github.com/crate/cratedb-guide/pull/420).
+```md
+- {ref}`connect-erlang`
+```
+:::
+
+
+[Erlang ODBC application]: https://www.erlang.org/docs/28/apps/odbc/odbc.html

docs/connect/odbc/index.md

@@ -0,0 +1,45 @@
+(odbc)=
+(connect-odbc)=
+
+# ODBC
+
+:::{include} /_include/links.md
+:::
+
+:::{div} sd-text-muted
+Connect to CrateDB with ODBC.
+:::
+
+:::{div}
+Open Database Connectivity ([ODBC][ODBC definition]) 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)_.
+:::
+
+## Installation
+
+:::{include} /connect/odbc/install.md
+:::
+
+## Configuration
+
+:::{include} /connect/odbc/configure.md
+:::
+
+## Examples
+
+A few examples that demonstrate CrateDB connectivity with ODBC.
+
+:::{toctree}
+:maxdepth: 1
+
+C# <csharp>
+Erlang <erlang>
+Python <python>
+Visual Basic <visualbasic>
+:::
+
+
+[ODBC definition]: https://en.wikipedia.org/wiki/Open_Database_Connectivity

docs/connect/odbc/install-dropdown.md

@@ -0,0 +1,13 @@
+---
+orphan: true
+---
+
+:::{div}
+The PostgreSQL ODBC driver
+can be used to connect to CrateDB from ODBC environments.
+:::
+
+::::{dropdown} Install and configure the PostgreSQL ODBC driver
+:::{include} /connect/odbc/install.md
+:::
+::::