Skip to content

Commit 86d292b

Browse files
amotlamotl
authored
Driver: Add page about ODBC (#411)
1 parent 2b024d3 commit 86d292b

File tree

13 files changed

+587
-1
lines changed

13 files changed

+587
-1
lines changed

‎docs/_assets/icon/odbc-logo.png‎

3.96 KB
Loading

‎docs/_include/links.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,6 @@
6767
[Multi-model Database]: https://cratedb.com/solutions/multi-model-database
6868
[nearest neighbor search]: https://en.wikipedia.org/wiki/Nearest_neighbor_search
6969
[Nested Data Structure]: https://cratedb.com/product/features/nested-data-structure
70-
[ODBC]: https://en.wikipedia.org/wiki/Open_Database_Connectivity
7170
[PostgreSQL JDBC Driver]: https://jdbc.postgresql.org/
7271
[PostgreSQL wire protocol]: https://www.postgresql.org/docs/current/protocol.html
7372
[python-dbapi-by-example]: inv:crate-python:*:label#by-example

‎docs/connect/application.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -186,6 +186,54 @@ crash --command "SELECT 42.42;"
186186
::::
187187

188188

189+
(isql)=
190+
### isql
191+
192+
`isql` and `iusql` are unixODBC command-line tools allowing users to execute
193+
SQL interactively or in batches.
194+
The tools provide several useful features, including an option to generate
195+
output wrapped in an HTML table.
196+
197+
:::{include} /connect/odbc/install-dropdown.md
198+
:::
199+
200+
::::{tab-set}
201+
202+
:::{tab-item} CrateDB Cloud
203+
:sync: server
204+
```{code} ini
205+
[CrateDB Cloud]
206+
Driver = PostgreSQL ODBC
207+
Servername = testcluster.cratedb.net
208+
Port = 5432
209+
Sslmode = require
210+
Username = admin
211+
Password = password
212+
```
213+
```shell
214+
echo "SELECT 42.42" | iusql "CrateDB Cloud"
215+
```
216+
:::
217+
218+
:::{tab-item} CrateDB on localhost
219+
:sync: localhost
220+
```{code} ini
221+
[CrateDB]
222+
Driver = PostgreSQL ODBC
223+
Servername = localhost
224+
Port = 5432
225+
Sslmode = disable
226+
Username = crate
227+
Password = crate
228+
```
229+
```shell
230+
echo "SELECT 42.42" | iusql "CrateDB"
231+
```
232+
:::
233+
234+
::::
235+
236+
189237
(psql)=
190238
### psql
191239

‎docs/connect/index.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,29 @@ CrateDB drivers and adapters for supported programming languages, frameworks, an
110110

111111
:::::
112112

113+
:::{rubric} Language-agnostic drivers
114+
:::
115+
116+
:::::{grid} 2 2 2 4
117+
:margin: 4 4 0 0
118+
:padding: 0
119+
120+
::::{grid-item-card} ODBC
121+
:link: connect-odbc
122+
:link-type: ref
123+
:link-alt: Connect to CrateDB using ODBC
124+
:padding: 3
125+
:text-align: center
126+
:class-card: sd-pt-3
127+
:class-body: sd-fs-1
128+
:class-title: sd-fs-6
129+
```{image} /_assets/icon/odbc-logo.png
130+
:height: 80px
131+
```
132+
::::
133+
134+
:::::
135+
113136

114137
:::{rubric} Protocol Support
115138
:::
@@ -181,6 +204,7 @@ javascript
181204
php
182205
python
183206
ruby
207+
odbc/index
184208
natural
185209
All drivers <drivers>
186210
```

‎docs/connect/odbc/configure.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
orphan: true
3+
---
4+
5+
For connecting to CrateDB, either address the database using a named
6+
connection (DSN), e.g. using `Dsn=CrateDB`, or address it directly
7+
using the driver, like `Driver={PostgreSQL Unicode}`.
8+
9+
:::{rubric} DSN configuration
10+
:::
11+
12+
When using a DSN, a typical connection string for CrateDB is:
13+
```text
14+
Dsn=CrateDB
15+
```
16+
17+
:::::{tab-set}
18+
19+
::::{tab-item} Windows
20+
On Windows, you will create a DSN using the ODBC driver manager UI.
21+
To set up a DSN (Data Source Name), click the "System DSN" tab. Click "Add".
22+
Select "PostgreSQL Unicode" and click "Finish".
23+
The [illustrated walkthrough][Installing PostgreSQL ODBC drivers on Windows]
24+
also covers that part.
25+
::::
26+
27+
::::{tab-item} Linux and macOS
28+
With unixODBC, configure a DSN within an `.odbc.ini` or `/etc/odbc.ini`
29+
file.
30+
31+
`~/.odbc.ini`
32+
```ini
33+
[CrateDB]
34+
Description=CrateDB
35+
Driver=PostgreSQL Unicode
36+
Server=localhost
37+
Port=5432
38+
Uid=crate
39+
Pwd=crate
40+
MaxVarcharSize=1073741824
41+
```
42+
43+
::::
44+
45+
:::::
46+
47+
48+
:::{rubric} DSN-less configuration
49+
:::
50+
51+
For directly connecting using a driver, without a registered DSN,
52+
a typical connection string for CrateDB is:
53+
```text
54+
Driver={PostgreSQL Unicode};Server=localhost;Port=5432;Uid=crate;Pwd=crate;MaxVarcharSize=1073741824
55+
```

‎docs/connect/odbc/csharp.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
(odbc-csharp)=
2+
3+
# ODBC with C#
4+
5+
:::{rubric} About
6+
:::
7+
8+
Use the ODBC .NET Data Provider to access data from your C Sharp ADO\.NET
9+
applications. The [.NET Framework Data Provider for ODBC] is available
10+
through the [System.Data.Odbc] namespace.
11+
12+
:::{rubric} Install
13+
:::
14+
15+
:::{include} /connect/odbc/install-dropdown.md
16+
:::
17+
18+
:::{rubric} Synopsis
19+
:::
20+
21+
`example.csproj`
22+
```xml
23+
<Project Sdk="Microsoft.NET.Sdk">
24+
25+
<PropertyGroup>
26+
<OutputType>Exe</OutputType>
27+
<TargetFramework>net$(NETCoreAppMaximumVersion)</TargetFramework>
28+
<GenerateProgramFile>false</GenerateProgramFile>
29+
</PropertyGroup>
30+
31+
<ItemGroup>
32+
<PackageReference Include="System.Data.Odbc" Version="9.*" />
33+
</ItemGroup>
34+
35+
</Project>
36+
```
37+
`example.cs`
38+
```c#
39+
using System;
40+
using System.Data.Odbc;
41+
42+
// Connect to database
43+
string connection_string = "Driver={PostgreSQL Unicode};Server=localhost;Port=5432;Uid=crate;Pwd=crate;MaxVarcharSize=1073741824";
44+
using (OdbcConnection connection = new OdbcConnection(connection_string))
45+
{
46+
connection.Open();
47+
48+
// Invoke query
49+
using (OdbcCommand command = new OdbcCommand("SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 5", connection))
50+
using (OdbcDataReader reader = command.ExecuteReader())
51+
{
52+
// Display results
53+
while (reader.Read())
54+
Console.WriteLine($"{reader.GetString(0)}: {reader.GetInt32(1)}");
55+
}
56+
}
57+
```
58+
59+
:::{rubric} Example
60+
:::
61+
62+
Create the files `example.csproj` and `example.cs` including the synopsis code shared above.
63+
64+
:::{include} ../_cratedb.md
65+
:::
66+
Invoke program.
67+
```shell
68+
dotnet run
69+
```
70+
71+
:::{rubric} CrateDB Cloud
72+
:::
73+
74+
For connecting to CrateDB Cloud, use the `Sslmode=require` parameter,
75+
and replace username, password, and hostname with values matching
76+
your environment.
77+
```csharp
78+
string connection_string = "Driver={PostgreSQL Unicode};Server=testcluster.cratedb.net;Port=5432;Sslmode=require;Uid=admin;Pwd=password";
79+
```
80+
81+
82+
[.NET Framework Data Provider for ODBC]: https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/data-providers#net-framework-data-provider-for-odbc
83+
[System.Data.Odbc]: https://learn.microsoft.com/en-us/dotnet/api/system.data.odbc

‎docs/connect/odbc/erlang.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
(odbc-erlang)=
2+
3+
# ODBC with Erlang
4+
5+
:::{rubric} About
6+
:::
7+
8+
The [Erlang ODBC application] provides an interface to communicate
9+
with relational SQL-databases out of the box.
10+
11+
:::{rubric} Install
12+
:::
13+
14+
:::{include} /connect/odbc/install-dropdown.md
15+
:::
16+
17+
:::{rubric} Synopsis
18+
:::
19+
20+
`example.erl`
21+
```erlang
22+
odbc:start(),
23+
{ok, Ref} = odbc:connect("Driver={PostgreSQL Unicode};Server=localhost;Port=5432;Uid=crate;Pwd=crate", []),
24+
io:fwrite("~p~n", [odbc:sql_query(Ref, "SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 3")]),
25+
```
26+
27+
:::{rubric} Example
28+
:::
29+
30+
:::{todo}
31+
Enable with the [Erlang patch](https://github.com/crate/cratedb-guide/pull/420).
32+
```md
33+
- {ref}`connect-erlang`
34+
```
35+
:::
36+
37+
38+
[Erlang ODBC application]: https://www.erlang.org/docs/28/apps/odbc/odbc.html

‎docs/connect/odbc/index.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
(odbc)=
2+
(connect-odbc)=
3+
4+
# ODBC
5+
6+
:::{include} /_include/links.md
7+
:::
8+
9+
:::{div} sd-text-muted
10+
Connect to CrateDB with ODBC.
11+
:::
12+
13+
:::{div}
14+
Open Database Connectivity ([ODBC][ODBC definition]) is a standard application programming
15+
interface (API) for accessing database management systems (DBMS),
16+
conceived to be independent of database systems and operating systems.
17+
The application uses ODBC functions through an _ODBC driver manager_ and
18+
addresses the driver and database using a _Data Source Name (DSN)_.
19+
:::
20+
21+
## Installation
22+
23+
:::{include} /connect/odbc/install.md
24+
:::
25+
26+
## Configuration
27+
28+
:::{include} /connect/odbc/configure.md
29+
:::
30+
31+
## Examples
32+
33+
A few examples that demonstrate CrateDB connectivity with ODBC.
34+
35+
:::{toctree}
36+
:maxdepth: 1
37+
38+
C# <csharp>
39+
Erlang <erlang>
40+
Python <python>
41+
Visual Basic <visualbasic>
42+
:::
43+
44+
45+
[ODBC definition]: https://en.wikipedia.org/wiki/Open_Database_Connectivity

‎docs/connect/odbc/install-dropdown.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
orphan: true
3+
---
4+
5+
:::{div}
6+
The PostgreSQL ODBC driver
7+
can be used to connect to CrateDB from ODBC environments.
8+
:::
9+
10+
::::{dropdown} Install and configure the PostgreSQL ODBC driver
11+
:::{include} /connect/odbc/install.md
12+
:::
13+
::::

0 commit comments

Comments
 (0)