docs: clarify Oracle testing status and simplify driver documentation

- Add prominent warning that Oracle is NOT tested in CI or integration tests
- Simplify Database Drivers section by removing redundant driver list,
  keeping only SQLAlchemy documentation link
- Add Notes section with MSSQL ODBC driver installation requirement
- Document Oracle Database Free limitation across all relevant files:
  - README.md
  - CLAUDE.md
  - .github/workflows/python-package.yml
  - db.docker-compose.yml
  - scripts/run-test.sh

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: tanbro

.github/workflows/python-package.yml

@@ -140,14 +140,15 @@ jobs:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
 
-      # NOTE: Oracle testing skipped in CI
+      # NOTE: Oracle testing requires full Oracle Database installation
       # Oracle Database Free (23c/23ai) does NOT support DBMS_LOCK.REQUEST
       # which is required for distributed lock functionality. This is a known
-      # limitation of the Free/Express edition. Oracle testing should be done
-      # locally using a full Oracle Database installation.
+      # limitation of the Free/Express edition. CI cannot test Oracle; use
+      # local testing with a full Oracle Database installation.
       #
-      # For local testing, use:
+      # For local Oracle testing:
       #   docker compose -f db.docker-compose.yml up
+      #   OR use a self-hosted runner with access to Oracle Enterprise/Standard
       #
       # Reference: https://github.com/gvenzl/oci-oracle-free
       # The "slim" and "full" flavors of gvenzl/oracle-free both lack

CLAUDE.md

@@ -38,6 +38,13 @@ cd tests
 docker compose up --abort-on-container-exit
 ```
 
+> **Note:** Oracle testing requires **Oracle Database Enterprise/Standard Edition**. Oracle Database Free (23c/23ai) does NOT support `DBMS_LOCK.REQUEST` which is required for distributed lock functionality. This is a fundamental limitation of the Free/Express edition, not related to the container image flavor.
+
+For local Oracle testing, ensure you have a full Oracle Database installation or use the official Oracle image:
+```bash
+docker compose -f db.docker-compose.yml up
+```
+
 ### Pre-commit Hooks
 ```bash
 # Install pre-commit hooks

README.md

@@ -17,8 +17,11 @@ sqlalchemy-dlock provides distributed locking capabilities using your existing d
 | MySQL      | [Named Lock](https://dev.mysql.com/doc/refman/en/locking-functions.html) (`GET_LOCK` / `RELEASE_LOCK`)                                         |
 | MariaDB    | [Named Lock](https://mariadb.com/kb/en/get_lock/) (compatible with MySQL)                                                                      |
 | MSSQL      | [Application Lock](https://learn.microsoft.com/sql/relational-databases/system-stored-procedures/sp-getapplock-transact-sql) (`sp_getapplock`) |
-| Oracle     | [User Lock](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_LOCK.html) (`DBMS_LOCK`)                                     |
-| PostgreSQL | [Advisory Lock](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS)                                                  |
+| Oracle     | [User Lock](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_LOCK.html) (`DBMS_LOCK`) |
+| PostgreSQL | [Advisory Lock](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS) |
+
+> ⚠️ **Oracle Not Tested:**
+> Oracle Database Free (23c/23ai) does NOT support `DBMS_LOCK.REQUEST`. We do NOT test Oracle in CI or integration tests. Use with Oracle Enterprise/Standard Edition at your own risk.
 
 ---
 
@@ -59,34 +62,15 @@ pip install sqlalchemy-dlock
 
 ### Database Drivers
 
-This library requires a database driver to be installed separately. Since you're already using SQLAlchemy, you likely have the appropriate driver installed.
-
-**MySQL / MariaDB:**
-- `mysqlclient` - Recommended C extension (synchronous)
-- `pymysql` - Pure Python (synchronous)
-- `aiomysql` - Async I/O
-
-**PostgreSQL:**
-- `psycopg2` or `psycopg2-binary` - v2 (synchronous)
-- `psycopg` - v3 (synchronous and asynchronous)
-- `asyncpg` - Async I/O
-
-**MSSQL:**
-- `pyodbc` - ODBC driver (synchronous, recommended)
-- `pymssql` - FreeTDS driver (synchronous)
-- `aioodbc` - Async wrapper for pyodbc
+This library requires a database driver to be installed separately. Since you're already using SQLAlchemy, you likely have the appropriate driver installed. For a complete list of SQLAlchemy-supported drivers, see the [SQLAlchemy Dialects documentation](https://docs.sqlalchemy.org/en/latest/dialects/).
 
-**Oracle:**
-- `oracledb` - Official driver (synchronous & asynchronous, recommended)
-- `cx_Oracle` - Legacy driver (synchronous)
-
-> ℹ️ **Note:** \
-> The drivers listed above are commonly used options. In general, any driver supported by SQLAlchemy for your target database should work with sqlalchemy-dlock. For a complete list of SQLAlchemy-supported drivers, see the [SQLAlchemy Dialects documentation](https://docs.sqlalchemy.org/en/latest/dialects/).
-
-Example installation:
-```bash
-pip install sqlalchemy-dlock mysqlclient psycopg2-binary pyodbc oracledb
-```
+> ℹ️ **Notes**:
+> - **MSSQL**: The `pyodbc` driver requires the Microsoft ODBC driver to be installed on your system. On Ubuntu/Debian:
+>   ```bash
+>   sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18
+>   ```
+> - **Oracle**:
+>   Oracle Database Free (23c/23ai) does NOT support `DBMS_LOCK.REQUEST` which is required for distributed lock functionality. For production use with Oracle, a full Oracle Database (Enterprise/Standard Edition) installation is required.
 
 ### Basic Usage
 

db.docker-compose.yml

@@ -38,4 +38,12 @@ services:
     environment:
       ORACLE_PASSWORD: "YourStrong@Passw0rd"
     # Note: Oracle Free container requires at least 2GB RAM to run properly
+    #
+    # IMPORTANT: Oracle Database Free (23c/23ai) does NOT support DBMS_LOCK.REQUEST
+    # which is required for distributed lock functionality. This is a known
+    # limitation of the Free/Express edition.
+    #
+    # For production use, a full Oracle Database (Enterprise/Standard Edition)
+    # is required. Use a self-hosted runner or cloud database service.
+    #
     # Connection string: oracle+oracledb://sys:YourStrong@Passw0rd@127.0.0.1:1521/?service_name=FREEPDB1

scripts/run-test.sh

@@ -1,16 +1,19 @@
 set -eu
 
 export TEST_URLS="mysql://$MYSQL_USER:$MYSQL_PASSWORD@mysql/$MYSQL_DATABASE postgresql://postgres:$POSTGRES_PASSWORD@postgres/ mssql+pyodbc://sa:$MSSQL_SA_PASSWORD@mssql:1433/master?driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes"
+
 export TEST_ASYNC_URLS="mysql+aiomysql://$MYSQL_USER:$MYSQL_PASSWORD@mysql/$MYSQL_DATABASE postgresql+asyncpg://postgres:$POSTGRES_PASSWORD@postgres/ mssql+aioodbc://sa:$MSSQL_SA_PASSWORD@mssql:1433/master?driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes"
 
 # Note: Database health is ensured by docker-compose healthcheck + depends_on condition
+# Note: Oracle testing skipped - Oracle Database Free does NOT support DBMS_LOCK.REQUEST
 
 export SETUPTOOLS_SCM_PRETEND_VERSION=0
 export PIP_DISABLE_PIP_VERSION_CHECK=1
 export PIP_ROOT_USER_ACTION=ignore
 export PIP_NO_WARN_SCRIPT_LOCATION=1
 
-PYTHON_LIST=(python3.9 python3.10 python3.11 python3.12 python3.13 python3.14)
+export PYTHON_LIST=(python3.9 python3.10 python3.11 python3.12 python3.13 python3.14)
+
 REQUIRES_LIST=("SQLAlchemy[asyncio]>=1.4.3,<2" "SQLAlchemy[asyncio]>=2,<3")
 
 trap 'rm -rf /tmp/sqlalchemy-dlock-test-*' EXIT
@@ -23,7 +26,6 @@ do
         echo "---------------------------------------------------------------"
         echo "Begin of ${PYTHON} ${REQUIRES}"
         echo "---------------------------------------------------------------"
-        echo
         TMPDIR=$(mktemp -d -t sqlalchemy-dlock-test-${PYTHON}-${REQUIRES//[^a-zA-Z0-9]/-})
         (
             set -e