Update docker-compose and README for ODBC support; enhance CI workflow to include ODBC testing

Author: lovasoa

.github/workflows/ci.yml

@@ -46,7 +46,20 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        database: ["postgres", "mysql", "mssql"]
+        include:
+          - database: postgres
+            container: postgres
+            db_url: "postgres://root:[email protected]/sqlpage"
+          - database: mysql
+            container: mysql
+            db_url: "mysql://root:[email protected]/sqlpage"
+          - database: mssql
+            container: mssql
+            db_url: "mssql://root:[email protected]/sqlpage"
+          - database: odbc
+            container: postgres
+            db_url: "Driver={PostgreSQL};Server=127.0.0.1;Port=5432;Database=sqlpage;UID=root;PWD=Password123!"
+            setup_odbc: true
     steps:
       - uses: actions/checkout@v4
       - name: Set up cargo cache
@@ -55,16 +68,21 @@ jobs:
         run: |
           sudo apt-get update
           sudo apt-get install -y unixodbc-dev freetds-dev
+      - name: Setup ODBC for testing
+        if: matrix.setup_odbc
+        run: |
+          # Install PostgreSQL ODBC driver (automatically registers the driver)
+          sudo apt-get install -y odbc-postgresql
       - name: Start database container
-        run: docker compose up --wait ${{ matrix.database }}
+        run: docker compose up --wait ${{ matrix.container }}
       - name: Show container logs
         if: failure()
-        run: docker compose logs ${{ matrix.database }}
+        run: docker compose logs ${{ matrix.container }}
       - name: Run tests against ${{ matrix.database }}
         timeout-minutes: 5
         run: cargo test
         env:
-          DATABASE_URL: ${{ matrix.database }}://root:[email protected]/sqlpage
+          DATABASE_URL: ${{ matrix.db_url }}
           RUST_BACKTRACE: 1
           RUST_LOG: sqlpage=debug
 

README.md

@@ -128,6 +128,7 @@ select
 - [PostgreSQL](https://www.postgresql.org/), and other compatible databases such as *YugabyteDB*, *CockroachDB* and *Aurora*.
 - [MySQL](https://www.mysql.com/), and other compatible databases such as *MariaDB* and *TiDB*.
 - [Microsoft SQL Server](https://www.microsoft.com/en-us/sql-server), and all compatible databases and providers such as *Azure SQL* and *Amazon RDS*.
+- **ODBC-compatible databases** such as *Oracle*, *Snowflake*, *BigQuery*, *IBM DB2*, and many others through ODBC drivers.
 
 ## Get started
 
@@ -175,6 +176,34 @@ An alternative for Mac OS users is to use [SQLPage's homebrew package](https://f
 - In a terminal, run the following commands:
   - `brew install sqlpage`
 
+
+### ODBC Setup
+
+You can skip this section if you want to use one of the built-in database drivers (SQLite, PostgreSQL, MySQL, Microsoft SQL Server).
+
+SQLPage supports ODBC connections to connect to databases that don't have native drivers, such as Oracle, Snowflake, BigQuery, IBM DB2, and many others.
+
+ODBC support requires an ODBC driver manager and appropriate database drivers to be installed on your system.
+
+#### Install ODBC
+
+ - On windows, it's installed by default.
+ - On linux: `sudo apt-get install -y unixodbc odbcinst unixodbc-common libodbcinst2`
+ - On mac: `brew install unixodbc`
+
+
+#### Install your ODBC database driver
+  - [DuckDB](https://duckdb.org/docs/stable/clients/odbc/overview.html)
+  - [Snowflake](https://docs.snowflake.com/en/developer-guide/odbc/odbc)
+  - [BigQuery](https://cloud.google.com/bigquery/docs/reference/odbc-jdbc-drivers)
+  - For other databases, follow your database's official odbc install instructions.
+
+#### Connect to your database
+
+ - Find your connection string. You can use https://www.connectionstrings.com/
+ - Use it in the [DATABASE_URL configuration option](./configuration.md)
+
+
 ## How it works
 
 ![architecture diagram](./docs/architecture-detailed.png)

configuration.md

@@ -66,7 +66,7 @@ If you have a `.env` file in the current directory or in any of its parent direc
 
 The `database_url` parameter sets all the connection parameters for the database, including
 
- - the database engine type (`sqlite`, `postgres`, `mysql`, `mssql`, etc.)
+ - the database engine type (`sqlite`, `postgres`, `mysql`, `mssql`, or ODBC connection strings)
  - the username and password
  - the host (or ip adress) and port
  - the database name
@@ -87,6 +87,26 @@ A full connection string for a PostgreSQL database might look like this:
 postgres://my_user:p%40ss@localhost:5432/my_database?sslmode=verify-ca&sslrootcert=/path/to/ca.pem&sslcert=/path/to/cert.pem&sslkey=/path/to/key.pem&application_name=my_application
 ```
 
+#### ODBC Connection Strings
+
+For ODBC-compatible databases (Oracle, Snowflake, BigQuery, IBM DB2, etc.), you can use ODBC connection strings directly:
+
+```bash
+# Using a Data Source Name (DSN)
+DATABASE_URL="DSN=MyDatabase"
+
+# Using inline connection parameters
+DATABASE_URL="Driver={PostgreSQL};Server=localhost;Port=5432;Database=mydb;UID=myuser;PWD=mypassword"
+
+# Oracle example
+DATABASE_URL="Driver={Oracle ODBC Driver};Server=localhost:1521/XE;UID=hr;PWD=password"
+
+# Snowflake example
+DATABASE_URL="Driver={SnowflakeDSIIDriver};Server=account.snowflakecomputing.com;Database=mydb;UID=user;PWD=password"
+```
+
+ODBC drivers must be installed and configured on your system. On Linux, you typically need `unixodbc` and the appropriate database-specific ODBC driver.
+
 If the `database_password` configuration parameter is set, it will override any password specified in the `database_url`.
 It does not need to be percent-encoded.
 This allows you to keep the password separate from the connection string, which can be useful for security purposes, especially when storing configurations in version control systems.

docker-compose.yml

@@ -59,4 +59,4 @@ services:
     image: mariadb
     environment:
       MYSQL_ROOT_PASSWORD: Password123!
-      MYSQL_DATABASE: sqlpage
+      MYSQL_DATABASE: sqlpage