turbodbc: Improve demo program and documentation

Author: amotl

by-language/python-turbodbc/README.rst

@@ -2,23 +2,13 @@
 Using CrateDB with turbodbc
 ###########################
 
+This document and its accompanying code example describes how to connect
+to `CrateDB`_ using `turbodbc`_.
 
-*****
-About
-*****
-
-This section of the documentation describes how to connect to `CrateDB`_
-with `turbodbc`_, by providing a few example programs.
-
-The examples use the `unixODBC`_ implementation of `ODBC`_, and the `PostgreSQL
+The example uses the `unixODBC`_ implementation of `ODBC`_, and the `PostgreSQL
 ODBC driver`_, for connecting to the `PostgreSQL wire protocol`_ interface of
 `CrateDB`_.
 
-This folder also contains ``Dockerfile`` files providing environments to
-exercise the examples on different operating systems, like Arch Linux,
-Red Hat (CentOS), Debian, and SUSE Linux.
-
-
 ************
 Introduction
 ************
@@ -77,35 +67,28 @@ Setup
 Install prerequisites
 =====================
 
-Arch Linux::
-
-    # See `dockerfiles/archlinux.Dockerfile`.
-
-CentOS Stream::
-
-    dnf install --enablerepo=crb -y boost-devel g++ postgresql-odbc python3 python3-devel python3-pip unixODBC-devel
-
-Debian::
-
-    apt-get install --yes build-essential libboost-dev odbc-postgresql unixodbc-dev
-
 macOS/Homebrew::
 
-    brew install psqlodbc unixodbc
+    brew install psqlodbc pybind11 simdutf unixodbc
 
-SUSE Linux Enterprise Server::
+If you can't install the required software components on your machine,
+head over to the `README-OCI`_ document.
 
-    # See `dockerfiles/sles.Dockerfile`.
+This folder also contains ``Dockerfile`` files providing environments to
+exercise the code example on different operating systems, like Arch Linux,
+Red Hat (CentOS), Debian, and SUSE Linux.
 
 Install Python sandbox
 ======================
-::
+Create Python virtualenv and install dependency packages::
 
-    # Create Python virtualenv and install dependency packages.
-    python3 -m venv .venv
+    uv venv --python 3.12 --seed
     source .venv/bin/activate
-    pip install --upgrade --requirement=requirements-prereq.txt
-    pip install --upgrade --requirement=requirements.txt --verbose
+    uv pip install --upgrade --verbose \
+        --requirement=requirements-prereq.txt
+    uv pip install --upgrade --verbose \
+        --requirement=requirements-dev.txt \
+        --requirement=requirements.txt
 
 .. note::
 
@@ -125,21 +108,11 @@ Usage
 Run CrateDB::
 
     docker run --rm -it --publish=4200:4200 --publish=5432:5432 crate \
-        -Cdiscovery.type=single-node -Ccluster.routing.allocation.disk.threshold_enabled=false
-
-Invoke demo program on workstation::
-
-	python demo.py
-
-Exercise demo program using Docker, on different operating systems::
-
-    docker build --progress=plain --tag local/python-turbodbc-demo --file=dockerfiles/archlinux.Dockerfile .
-    docker build --progress=plain --tag local/python-turbodbc-demo --file=dockerfiles/centos.Dockerfile .
-    docker build --progress=plain --tag local/python-turbodbc-demo --file=dockerfiles/debian.Dockerfile .
-    docker build --progress=plain --tag local/python-turbodbc-demo --file=dockerfiles/sles.Dockerfile .
+        -Cdiscovery.type=single-node
 
-    docker run --rm -it --volume=$(pwd):/src --network=host local/python-turbodbc-demo python3 /src/demo.py
+Invoke demo program::
 
+    python demo.py
 
 *******
 Backlog
@@ -152,10 +125,11 @@ examples to be exercised are tracked within the `backlog`_.
 
 .. _Apache Arrow: https://en.wikipedia.org/wiki/Apache_Arrow
 .. _Apache Arrow support: https://turbodbc.readthedocs.io/en/latest/pages/advanced_usage.html#advanced-usage-arrow
-.. _backlog: https://github.com/crate/cratedb-examples/blob/main/python-turbodbc/backlog.rst
-.. _CrateDB: https://github.com/crate/crate
+.. _backlog: https://github.com/crate/cratedb-examples/blob/main/by-language/python-turbodbc/backlog.rst
+.. _CrateDB: https://cratedb.com/database
 .. _NumPy: https://en.wikipedia.org/wiki/NumPy
 .. _NumPy support: https://turbodbc.readthedocs.io/en/latest/pages/advanced_usage.html#advanced-usage-numpy
+.. _README-OCI: ./README-OCI.md
 .. _ODBC: https://en.wikipedia.org/wiki/Open_Database_Connectivity
 .. _Open Database Connectivity (ODBC): https://en.wikipedia.org/wiki/Open_Database_Connectivity
 .. _PostgreSQL ODBC driver: https://odbc.postgresql.org/

by-language/python-turbodbc/backlog.rst

@@ -8,6 +8,9 @@ Various items how this little code example can be improved.
 - [x] Insert multiple records using parameters
 - [x] Docs: Add installation on SUSE
 - [x] Provide example(s) for different operating systems (Linux, macOS)
+- [x] Using turbodbc 4 is not an option, see https://github.com/blue-yonder/turbodbc/issues/437
+- [x] Note turbodbc=5.0.1 should only require numpy>=2 in the build environment but should run also with e.g. numpy=1.26
+- [x] Let's use NumPy 2 across the board
 - [o] Docs: Drop a note about connecting with driver file vs. connecting via DSN
 - [o] Evaluate different ODBC drivers
 - [o] Provide an example scenario how to run it on Windows

by-language/python-turbodbc/demo.py

@@ -1,17 +1,24 @@
+"""
+Example program connecting to CrateDB [1] using turbodbc [2].
+
+[1] https://cratedb.com/database
+[2] https://turbodbc.readthedocs.io/
+"""
+
 import os
 import sys
 
 from turbodbc import connect
 
 
-def demo_pg():
+def main():
     # Connect to database.
     # https://turbodbc.readthedocs.io/en/latest/pages/getting_started.html#establish-a-connection-with-your-database
 
     # Either connect per data source name defined within the ODBC configuration,
     # connection = connect(dsn="postgresql", server="localhost", database="testdrive", uid="crate", pwd=None)
 
-    # or connect per connection string, referencing a driver file directly.
+    # ... or connect per connection string, referencing a driver file directly.
     if sys.platform == "linux":
         candidates = [
             # archlinux
@@ -29,16 +36,31 @@ def demo_pg():
     else:
         raise NotImplementedError(f"Platform {sys.platform} not supported yet")
 
-    connection_string = f"Driver={driver_file};Server=localhost;Port=5432;Database=testdrive;Uid=crate;Pwd=;"
+    connection_string = (
+        f"Driver={driver_file};Server=localhost;Port=5432;Database=testdrive;Uid=crate;Pwd=;"
+    )
     print(f"INFO: Connecting to '{connection_string}'")
     connection = connect(connection_string=connection_string)
+    print()
+
+    # Query `sys.summits`.
+    print("sys.summits")
+    cursor = connection.cursor()
+    cursor.execute("SELECT * FROM sys.summits ORDER by height DESC LIMIT 10")
+    for row in cursor:
+        print(row)
+    cursor.close()
+    print()
 
     # Insert data.
+    print("doc.testdrive")
     cursor = connection.cursor()
     cursor.execute("CREATE TABLE IF NOT EXISTS testdrive (id INT PRIMARY KEY, data TEXT);")
     cursor.execute("DELETE FROM testdrive;")
     cursor.execute("INSERT INTO testdrive VALUES (0, 'zero'), (1, 'one'), (2, 'two');")
-    cursor.executemany("INSERT INTO testdrive VALUES (?, ?);", [(3, "three"), (4, "four"), (5, "five")])
+    cursor.executemany(
+        "INSERT INTO testdrive VALUES (?, ?);", [(3, "three"), (4, "four"), (5, "five")]
+    )
     cursor.execute("REFRESH TABLE testdrive;")
     cursor.close()
 
@@ -54,6 +76,7 @@ def demo_pg():
         print(row)
 
     cursor.close()
+    print()
 
     # Terminate database connection.
     connection.close()
@@ -66,4 +89,4 @@ def find_program(candidates):
 
 
 if __name__ == "__main__":
-    demo_pg()
+    main()