First connection smoke test

Verify that a freshly installed Delta Forge ODBC Driver authenticates and returns a result row from the engine.

Category: getting-started

Syntax

isql -v <DSN> | iodbctest 'DSN=...' | pyodbc.connect(...)

Description

## Why a smoke test Before wiring up Power BI or Tableau, prove that the driver loads, the credentials are accepted, and the engine returns a row. This isolates problems to one of three layers (driver registration, auth, query path) instead of debugging through a BI tool's opaque error dialog. ## Three-statement smoke check After the connection succeeds, run these three statements at the `SQL>` prompt: ```sql SELECT 1 AS hello; SHOW SCHEMAS; SELECT current_user; ``` - `SELECT 1` exercises the round-trip with no catalog lookup; if this fails, the issue is auth or transport. - `SHOW SCHEMAS` exercises catalog metadata; if this fails but `SELECT 1` worked, the user lacks read permission on the default zone or the default zone is not set. - `SELECT current_user` confirms the identity the engine sees, which can differ from the `Uid` you supplied if the auth provider applies a mapping. ## Interpreting failures - **The driver manager cannot load the shared object** (Linux: `Can't open lib '...': file not found`). The driver is not registered for this user, or the path in `odbcinst.ini` is wrong. Run `odbcinst -j` to print the resolved file path and `ldd` against the .so to confirm dependencies. - **`08001` SQLSTATE during connect**. The URL is unreachable, DNS does not resolve, or the network path is blocked. The diagnostic message body names the specific cause. - **`28000` SQLSTATE during connect**. The control plane rejected the credentials. The message body carries the engine-side reason: bad password, expired token, account locked. - **Connect succeeds, `SELECT 1` returns `HYC00 Optional feature not implemented`**. Almost always a misconfigured cursor type. The driver is forward-only; if the application asks for `SQL_CURSOR_STATIC`, the driver returns this code. Reset the cursor type to `SQL_CURSOR_FORWARD_ONLY`. ## Tip: keep the smoke test in your runbook When a customer reports "Power BI cannot connect", the very first ask is the output of the smoke test on the same machine, with the same DSN, by the same user account. If the smoke test works and Power BI fails, the problem is in Power BI's process (often an environment variable, proxy, or a 32-bit / 64-bit mismatch). If the smoke test also fails, the BI tool is innocent.

Examples

# unixODBC (Linux)
isql -v DeltaForge alice@example.com 'hunter2'
SQL> SELECT 1 AS hello;

# iODBC (macOS)
iodbctest 'DSN=DeltaForge;Uid=alice@example.com;Pwd=hunter2'

# Python (any platform)
python3 -c "import pyodbc; c = pyodbc.connect('DSN=DeltaForge;Uid=alice@example.com;Pwd=hunter2'); print(c.cursor().execute('SELECT 1').fetchone())"

# Driver-string form (no system DSN required)
isql -v -k 'Driver={DeltaForge ODBC Driver};Server=https://df.example.com;Uid=alice@example.com;Pwd=hunter2'

Pitfalls

`isql` joins positional arguments with single space; if your password contains spaces or shell metacharacters, wrap it in single quotes or use `-k` with a full driver-string form.
A password expiry policy on the auth provider can produce `28000` even though the password worked yesterday. Rotate via the auth provider, not the connection string.
On Windows, the smoke test must run from the same bitness as the BI tool. A 64-bit `isql` from a unixODBC port may report success while a 32-bit Power Query agent still fails because the 32-bit driver is not registered.

First connection smoke test

Syntax

Description

Examples

Pitfalls

See Also