diff --git a/docs/_assets/icon/odbc-logo.png b/docs/_assets/icon/odbc-logo.png new file mode 100644 index 00000000..ad1e061a Binary files /dev/null and b/docs/_assets/icon/odbc-logo.png differ diff --git a/docs/_include/links.md b/docs/_include/links.md index 21385cd8..cbe34c74 100644 --- a/docs/_include/links.md +++ b/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 diff --git a/docs/connect/application.md b/docs/connect/application.md index 4ebf1f0f..82a829f7 100644 --- a/docs/connect/application.md +++ b/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 diff --git a/docs/connect/index.md b/docs/connect/index.md index c22c8f1a..e9e6b458 100644 --- a/docs/connect/index.md +++ b/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 ``` diff --git a/docs/connect/odbc/configure.md b/docs/connect/odbc/configure.md new file mode 100644 index 00000000..643cc3b7 --- /dev/null +++ b/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 +``` diff --git a/docs/connect/odbc/csharp.md b/docs/connect/odbc/csharp.md new file mode 100644 index 00000000..0f9a849f --- /dev/null +++ b/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 + + + + Exe + net$(NETCoreAppMaximumVersion) + false + + + + + + + +``` +`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 diff --git a/docs/connect/odbc/erlang.md b/docs/connect/odbc/erlang.md new file mode 100644 index 00000000..481ba087 --- /dev/null +++ b/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 diff --git a/docs/connect/odbc/index.md b/docs/connect/odbc/index.md new file mode 100644 index 00000000..0ad8ac5e --- /dev/null +++ b/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# +Erlang +Python +Visual Basic +::: + + +[ODBC definition]: https://en.wikipedia.org/wiki/Open_Database_Connectivity diff --git a/docs/connect/odbc/install-dropdown.md b/docs/connect/odbc/install-dropdown.md new file mode 100644 index 00000000..494c80e4 --- /dev/null +++ b/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 +::: +:::: diff --git a/docs/connect/odbc/install.md b/docs/connect/odbc/install.md new file mode 100644 index 00000000..8fbad255 --- /dev/null +++ b/docs/connect/odbc/install.md @@ -0,0 +1,80 @@ +--- +orphan: true +--- + +:::{include} /connect/odbc/links.md +::: + +:::{div} +While Windows 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]. +::: + +:::::{tab-set} + +::::{tab-item} Windows +Please navigate to the [psqlODBC download site] to download and install +the latest psqlODBC driver for Windows systems. +[Installing PostgreSQL ODBC drivers on Windows] includes an illustrated walkthrough. +:::: + +::::{tab-item} Linux +On Linux, install the [unixODBC] ODBC driver manager +and the psqlODBC driver. +[Installing PostgreSQL ODBC drivers on Linux] includes an illustrated walkthrough. + +Arch Linux +```shell +pacman -Sy psqlodbc +``` +Debian and derivatives +```shell +apt install --yes odbc-postgresql odbcinst unixodbc +``` +Red Hat and derivatives +```shell +yum install -y postgresql-odbc +``` + +Verify installation. +```shell +odbcinst -q -d +``` +```text +[PostgreSQL ANSI] +[PostgreSQL Unicode] +``` +:::: + +::::{tab-item} macOS +On macOS, install the [unixODBC] ODBC driver manager +and the psqlODBC driver, then register it. + +```shell +# macOS +brew install psqlodbc unixodbc +``` +`odbcinst.ini` +```ini +[PostgreSQL Unicode] +Description = PostgreSQL ODBC driver (Unicode version) +Driver = /usr/local/lib/psqlodbcw.so +``` +```shell +odbcinst -i -d -f odbcinst.ini +``` +Verify installation. +```shell +odbcinst -q -d +``` +```text +[PostgreSQL Unicode] +``` +:::: + +::::: + + +[Installing PostgreSQL ODBC drivers on Linux]: https://www.dbi-services.com/blog/installing-the-odbc-drivers-for-postgresql/ +[Installing PostgreSQL ODBC drivers on Windows]: https://help.campbellsci.com/PC400%20Manual/viewpro/installing_postgresql_odbc_drivers.htm diff --git a/docs/connect/odbc/links.md b/docs/connect/odbc/links.md new file mode 100644 index 00000000..914ef147 --- /dev/null +++ b/docs/connect/odbc/links.md @@ -0,0 +1,11 @@ +--- +orphan: true +--- + + + + +[ODBC]: https://en.wikipedia.org/wiki/Open_Database_Connectivity +[psqlODBC]: https://odbc.postgresql.org/ +[psqlODBC download site]: https://www.postgresql.org/ftp/odbc/releases/ +[unixODBC]: https://www.unixodbc.org/ diff --git a/docs/connect/odbc/python.md b/docs/connect/odbc/python.md new file mode 100644 index 00000000..173392e0 --- /dev/null +++ b/docs/connect/odbc/python.md @@ -0,0 +1,139 @@ +(odbc-python)= + +# ODBC with Python + +(odbc-pyodbc)= + +## pyodbc + +:::{rubric} About +::: + +[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]. + +:::{rubric} Install +::: + +:::{include} /connect/odbc/install-dropdown.md +::: + +Install the required Python package. +```shell +pip install --upgrade pyodbc +``` + +:::{rubric} Synopsis +::: + +`example.py` +```python +import pyodbc + +# Connect to database +connection_string = \ + "Driver={PostgreSQL Unicode};Server=localhost;Port=5432;" \ + "Uid=crate;Pwd=crate;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() +``` + +(odbc-turbodbc)= + +## turbodbc + +:::{rubric} About +::: + +```{div} .float-right .text-right +[![Python turbodbc](https://github.com/crate/cratedb-examples/actions/workflows/lang-python-turbodbc.yml/badge.svg)](https://github.com/crate/cratedb-examples/actions/workflows/lang-python-turbodbc.yml) +``` + +[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. + +```{div} .clearfix +``` + +:::{rubric} Install +::: + +```shell +pip install --upgrade turbodbc +``` + +:::{rubric} Synopsis +::: + +`example.py` +```python +import turbodbc + +# Connect to database +connection_string = \ + "Driver={PostgreSQL Unicode};Server=localhost;Port=5432;" \ + "Uid=crate;Pwd=crate;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). +```md +- {ref}`Turbodbc -- a high-performance ODBC library ` +``` +::: + +## Example + +Create the file `example.py` including the synopsis code shared above and +install the prerequisites like outlined above. + +:::{include} ../_cratedb.md +::: +Invoke program. +```shell +python example.py +``` + +## CrateDB Cloud + +For connecting to CrateDB Cloud, use the `Sslmode=require` parameter, +and replace username, password, and hostname with values matching +your environment. +```python +connection_string = \ + "Driver={PostgreSQL Unicode};Server=testcluster.cratedb.net;Port=5432;" \ + "Uid=admin;Pwd=password;MaxVarcharSize=1073741824" +``` + + +[connecting to PostgreSQL with pyodbc]: https://github.com/mkleehammer/pyodbc/wiki/Connecting-to-PostgreSQL +[pyodbc]: https://github.com/mkleehammer/pyodbc +[pyodbc installation instructions]: https://github.com/mkleehammer/pyodbc/wiki/Install +[turbodbc]: https://turbodbc.readthedocs.io/ diff --git a/docs/connect/odbc/visualbasic.md b/docs/connect/odbc/visualbasic.md new file mode 100644 index 00000000..4c1fa119 --- /dev/null +++ b/docs/connect/odbc/visualbasic.md @@ -0,0 +1,51 @@ +(odbc-visualbasic)= + +# ODBC with Visual Basic + +:::{rubric} About +::: + +Use ADODB to access data from your Visual Basic applications. + +:::{rubric} Install +::: + +:::{include} /connect/odbc/install-dropdown.md +::: + +:::{rubric} Synopsis +::: + +`example.vb` +```visualbasic +Dim cn as New ADODB.Connection +Dim rs as New ADODB.Recordset + +'Connect to database +cn.Open "Dsn=;" & _ + "Server=localhost;" & _ + "Port=5432;" & _ + "Uid=crate;" & _ + "Pwd=crate;" & _ + "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 +``` + +:::{seealso} +Example: [psqlODBC with Visual Basic]. +::: + + +[psqlODBC with Visual Basic]: https://odbc.postgresql.org/howto-vb.html