QSQLOLEDB - Qt MSOLEDB Driver Plugin for Microsoft SQL Server

A Qt SQL driver plugin that connects to Microsoft SQL Server using the OLE DB interface instead of ODBC. A native Qt SQL driver for Microsoft SQL Server using OLE DB (no ODBC required). Use Microsoft’s official MSOLEDBSQL driver directly in Qt — without ODBC.

Why OLE DB instead of ODBC?

Feature	QSQLOLEDB (this project)	Qt QODBC
DSN configuration	Not required	Requires DSN or driver string
Connection timeout	TCP pre-check (~500ms fail-fast)	OS TCP stack timeout (~21s)
BLOB/Stream	Native ISequentialStream	Limited
Parameter binding	COM-based precise type control	ODBC type mapping
Named Instance support	SQL Server Browser auto-discovery	Via connection string only
Provider	MSOLEDBSQL / MSOLEDBSQL19 direct	Through ODBC Driver Manager
Dependency	No ODBC Driver Manager needed	ODBC Driver Manager required

The Timeout Problem

When SQL Server is offline or unreachable, OLE DB (and ODBC) DBPROP_INIT_TIMEOUT is effectively ignored — the OS TCP/IP stack retries SYN packets for ~21 seconds on Windows. This plugin solves this by performing a non-blocking TCP socket check before attempting the OLE DB connection, failing fast within 500ms.

For Named Instances (e.g., SERVER\SQLEXPRESS), the plugin queries the SQL Server Browser service (UDP 1434) to resolve the dynamic port before the TCP check.

Supported Providers

The plugin automatically detects the best available OLE DB provider:

1. MSOLEDBSQL19 (preferred — Microsoft OLE DB Driver 19)
2. MSOLEDBSQL (Microsoft OLE DB Driver 18)
3. SQLOLEDB (legacy fallback)

Requirements

• Windows (OLE DB is a Windows COM technology)
• Qt 5.x (tested with Qt 5.14.2)
• Visual Studio 2017+ (v143 toolset)
• Microsoft OLE DB Driver for SQL Server

Platform

• Windows only (OLE DB / COM based)

Usage

Loading the Driver

Copy the built DLL (qsqloledb.dll) into your Qt installation's plugins/sqldrivers/ directory.

#include <QSqlDatabase>
#include <QSqlQuery>

QSqlDatabase db = QSqlDatabase::addDatabase("QSQLOLEDB");
db.setHostName("192.168.1.100");          // or "192.168.1.100\\SQLEXPRESS"
db.setDatabaseName("MyDatabase");
db.setUserName("sa");
db.setPassword("password");

// Connection options (optional)
// db.setConnectOptions("provider=MSOLEDBSQL19");

if (db.open()) {
    QSqlQuery query;
    query.exec("SELECT * FROM MyTable");
    while (query.next()) {
        qDebug() << query.value(0);
    }
}

Connection Options

Pass options via setConnectOptions() separated by ;:

Option	Description	Example
provider=	Force specific OLE DB provider	provider=MSOLEDBSQL19
failover partner=	Mirror/failover server address	failover partner=192.168.1.101
big query=1	Use server-side cursor (for large result sets)	big query=1

Windows Authentication

Leave username and password empty to use Windows Integrated Authentication (SSPI):

db.setUserName("");
db.setPassword("");

Building

Prerequisites

1. Install Qt 5.x with source (or headers for QtCore, QtSql, QtGui)
2. Install Visual Studio 2017 or later
3. Install Microsoft OLE DB Driver for SQL Server
4. Set MSSQL_SDK environment variable to your SQL Server SDK path (for msoledbsql.h)

Build with Visual Studio

Open qsqloledb.vcxproj in Visual Studio and build.

The output DLL will be placed in the sqldrivers/ directory.

Architecture

qsqloledb/
├── qsqloledb.h          # QSqlOLEDBDriver and QSqlOLEDBResult declarations
├── qsqloledb.cpp         # Main driver implementation (QSqlDriver interface)
├── OLEDBManager.h        # OLE DB provider detection & connection pre-check
├── OLEDBManager.cpp       # TCP pre-check & SQL Server Browser query
├── smain.cpp             # Qt SQL driver plugin entry point
├── stdafx.h / stdafx.cpp  # Precompiled header
└── qsqloledb.json        # Qt plugin metadata

Key Classes

• QSqlOLEDBDriver — Implements QSqlDriver. Handles connection, transactions, table/index queries.
• QSqlOLEDBResult — Implements QSqlResult. Handles query execution, parameter binding, data retrieval.
• OLEDBManager — Singleton. Detects available OLE DB providers, performs TCP pre-check and SQL Server Browser port resolution.
• CDynamicParameterAccessorEx — Extended ATL accessor that preserves original DB types for correct type mapping.

Supported Data Types

SQL Server Type	Qt Type
int, smallint, tinyint	QVariant::Int
bigint	QVariant::LongLong
float, real	QVariant::Double
numeric, decimal, money	QVariant::LongLong
bit	QVariant::Bool
varchar, nvarchar, text, ntext	QVariant::String
varbinary, image	QVariant::ByteArray
datetime, datetime2, date	QVariant::DateTime
time	QVariant::Time

License

This project is licensed under the MIT License. See LICENSE for details. This project uses Qt (LGPL licensed). Users must comply with Qt licensing terms when using this plugin.

Keywords: Qt MSSQL, OLE DB, MSOLEDBSQL, Qt SQL driver, SQL Server plugin

QSQLOLEDB - Qt OLE DB MSSQL 드라이버 플러그인

Microsoft SQL Server용 OLE DB 기반 Qt SQL 드라이버 플러그인입니다. ODBC 대신 OLE DB를 직접 사용하며, 현재 알려진 유일한 오픈소스 Qt OLE DB MSSQL 구현체입니다.

주요 특징

• DSN 설정 불필요 — ODBC처럼 DSN을 등록할 필요 없음
• 빠른 연결 실패 감지 — SQL Server가 꺼져있을 때 OLE DB/ODBC는 ~21초 대기하지만, TCP 선검사로 500ms 내 실패 감지
• Named Instance 자동 포트 탐색 — SQL Server Browser (UDP 1434) 질의로 동적 포트 자동 해석
• OLE DB Provider 자동 감지 — MSOLEDBSQL19 > MSOLEDBSQL > SQLOLEDB 순서로 최적 프로바이더 선택
• BLOB 스트리밍 — ISequentialStream 네이티브 지원
• Failover Partner — 미러링/장애 조치 서버 자동 전환

사용법

빌드한 DLL을 Qt의 plugins/sqldrivers/ 디렉터리에 복사한 후:

QSqlDatabase db = QSqlDatabase::addDatabase("QSQLOLEDB");
db.setHostName("192.168.1.100\\SQLEXPRESS");
db.setDatabaseName("MyDB");
db.setUserName("sa");
db.setPassword("password");
db.open();

자세한 사용법은 위 영문 섹션을 참고하세요.