Windows qsqldatabase qpsql driver not loaded

If you’re trying to use Postgres with PyQt5/6 or PySide2/PySide6 you may have come across an issue with loading the driver.
Qt (correctly) lists the driver as available in Qt, but when trying to load it the load will fail. This is because the Qt
library depends on Postgres’ own library, which must be available in the path to load.

The following script will let you test if the Postgres library is loading correctly.

from PyQt5.QtSql import QSqlDatabase
from PyQt5.QtWidgets import QApplication

app = QApplication([])

db = QSqlDatabase("QPSQL")
print("Available drivers", db.drivers())

if not db.open():
    print("Unable to connect.")
    print('Last error', db.lastError().text())
else:
    print("Connection to the database successful")

from PyQt6.QtSql import QSqlDatabase
from PyQt6.QtWidgets import QApplication

app = QApplication([])

db = QSqlDatabase("QPSQL")
print("Available drivers", db.drivers())

if not db.open():
    print("Unable to connect.")
    print('Last error', db.lastError().text())
else:
    print("Connection to the database successful")

from PySide2.QtSql import QSqlDatabase
from PySide2.QtWidgets import QApplication

app = QApplication([])

db = QSqlDatabase("QPSQL")
print("Available drivers", db.drivers())

if not db.open():
    print("Unable to connect.")
    print('Last error', db.lastError().text())
else:
    print("Connection to the database successful")

from PySide6.QtSql import QSqlDatabase
from PySide6.QtWidgets import QApplication

app = QApplication([])

db = QSqlDatabase("QPSQL")
print("Available drivers", db.drivers())

if not db.open():
    print("Unable to connect.")
    print('Last error', db.lastError().text())
else:
    print("Connection to the database successful")

Executing the above script in a new command prompt will give the following
output (if Postgres is not accessible).

>python test.py
QSqlDatabase: QPSQL driver not loaded
QSqlDatabase: available drivers: QSQLITE QODBC QODBC3 QPSQL QPSQL7
Available drivers ['QSQLITE', 'QODBC', 'QODBC3', 'QPSQL', 'QPSQL7']
Unable to connect.
Last error Driver not loaded Driver not loaded

The list of «available drivers» shows the Qt drivers which are available in your PyQt5 (or PyQt6, or PySide2, or PySide6) installation. For example, in my installation the driver files are under site-packages\PyQt5\Qt5\plugins\sqldrivers

C:\Users\Martin\AppData\Local\Programs\Python\Python37\Lib\site-packages\PyQt5\Qt5\plugins\sqldrivers> dir

 Volume in drive C has no label.
 Volume Serial Number is 0A6A-65ED

 Directory of C:\Users\Martin\AppData\Local\Programs\Python\Python37\Lib\site-packages\PyQt5\Qt5\plugins\sqldrivers

02/12/2021  14:35    <DIR>          .
02/12/2021  14:35    <DIR>          ..
02/12/2021  14:35         1,412,080 qsqlite.dll
02/12/2021  14:35            98,288 qsqlodbc.dll
02/12/2021  14:35            79,856 qsqlpsql.dll
               3 File(s)      1,590,224 bytes
               2 Dir(s)  174,429,970,432 bytes free

The Driver not loaded error is occurring because the Qt Postgres driver cannot find the Postgres libraries. The Qt Postgres driver is a wrapper around these libraries, rather than a complete implementation of Postgres itself.

To get this working you need to ensure the required Postgres library files are available in your path.
You can do this by adding your Postgres installation bin folder to your path. For example, on my computer Postgres is installed under C:\Program Files\PostgreSQL\14\ (I’m using version 14). We need to add to the Postgres bin folder to the PATH as this contains libpq.dll (Postgres Access Library) which Qt needs.

SET PATH=%PATH%;C:\Program Files\PostgreSQL\14\bin

With that in place, running the script again will show that that driver has loaded successfully. The
connection still isn’t working, since it needs the username and password set. But if you get this far
you know the driver is working properly.

U:\home\martin\www\pythonguis\content\faq\qt-postgres-driver>python test.py
Available drivers ['QSQLITE', 'QODBC', 'QODBC3', 'QPSQL', 'QPSQL7']
Unable to connect.
Last error connection to server at "localhost" (::1), port 5432 failed: fe_sendauth: no password supplied
QPSQL: Unable to connect

We can modify the test script to add your username and password to complete the connection.

from PyQt5.QtSql import QSqlDatabase
from PyQt5.QtWidgets import QApplication

app = QApplication([])

db = QSqlDatabase("QPSQL")
db.setUserName("postgres")  # postgres is the default root username
db.setPassword("")    # add your password here
print("Available drivers", db.drivers())

if not db.open():
    print("Unable to connect.")
    print('Last error', db.lastError().text())
else:
    print("Connection to the database successful")

from PyQt6.QtSql import QSqlDatabase
from PyQt6.QtWidgets import QApplication

app = QApplication([])

db = QSqlDatabase("QPSQL")
db.setUserName("postgres")  # postgres is the default root username
db.setPassword("")    # add your password here
print("Available drivers", db.drivers())

if not db.open():
    print("Unable to connect.")
    print('Last error', db.lastError().text())
else:
    print("Connection to the database successful")

from PySide2.QtSql import QSqlDatabase
from PySide2.QtWidgets import QApplication

app = QApplication([])

db = QSqlDatabase("QPSQL")
db.setUserName("postgres")  # postgres is the default root username
db.setPassword("")    # add your password here
print("Available drivers", db.drivers())

if not db.open():
    print("Unable to connect.")
    print('Last error', db.lastError().text())
else:
    print("Connection to the database successful")

from PySide6.QtSql import QSqlDatabase
from PySide6.QtWidgets import QApplication

app = QApplication([])

db = QSqlDatabase("QPSQL")
db.setUserName("postgres")  # postgres is the default root username
db.setPassword("")    # add your password here
print("Available drivers", db.drivers())

if not db.open():
    print("Unable to connect.")
    print('Last error', db.lastError().text())
else:
    print("Connection to the database successful")

…and then the connection will complete as expected.

>python test-userpass.py
Available drivers ['QSQLITE', 'QODBC', 'QODBC3', 'QPSQL', 'QPSQL7']
Connection to the database successful

При вызове QSqlDatabase::addDatabse(«QPSQL») программа пишет:

В процессе работы программы при вызове QSqlDatabase::addDatabse делается динамический поиск dll-файлов SQL-драйверов в определенных каталогах. Для драйвера QPSQL должна быть найдена библиотека qsqlpsql.dll, после чего выполняется попытка ее загрузки.

Для этого загружаются другие неявно связанные с ней dll-библиотеки вместе со своими зависимостями. Если всё дерево необходимых dll-библиотек найдено, то qsqlpsql.dll будет успешно загружена и Qt сможет использовать этот драйвер.

Но сложность в том, что при отсутствии какой-либо библиотеки Windows не выдаст красивого сообщения об этом и придется разбираться другими способами.

Разбираемся

Нам надо выяснить, какие dll-библиотеки требуются для работы программы и куда их нужно положить.

Для этого достаточно в общих чертах представлять, как Windows ищет dll, а именно, что сначала производится поиск в каталоге exe-файла, а в конце — по путям, указанным в переменной окружения PATH. PATH удобно использовать на машине разработчика, но этот вариант рассматривать не будем т.к. это не соответствует изначальной задаче. 

Также надо знать, в каких каталогах QSqlDatabase::addDatabse ищет драйверы SQL. Существуют способы указать Qt альтернативные пути, где искать плагины (в т.ч. SQL), но не будем заниматься и этим.

Исследуем

Используем Прекрасную программы DependencyWalker, которая показывает дерево зависимостей dll и exe-файлов.

Сначала открываем с помощью неё исполняемый файл программы и смотрим, какие dll-библиотеки должны быть доступны, ищем их в каталоге установки Qt и компилятора и кладем рядом с исполняемым файлом. Теперь программа должна запускаться и доходить до вызова QSqlDatabase::addDatabse.

Чтобы увидеть, где Qt ищет SQL-драйверы, добавляем переменную окружения QT_PLUGIN_PATH = 1 (например, в настройках параметров запуска приложения в QtCreator), запускаем программу и изучаем ее вывод. Кроме прочего должны быть примерно такие строки:

QFactoryLoader::QFactoryLoader() checking directory path «C:/Qt/Qt5.5.1/5.5/mingw492_32/plugins/sqldrivers»
…
QFactoryLoader::QFactoryLoader() checking directory path «C:/projects/build-foobar-Desktop-Release/release/sqldrivers»

Из них становится ясно, что по умолчанию Qt ищет SQL-драйверы в каталоге установки и в подкаталоге sqldrivers рядом с exe-файлом. Поэтому находим qsqlpsql.dll в каталоге установки Qt (примерно в C:\Qt\5.5.1\mingw491_32\bin\plugins\sqldrivers) и копируем в подкаталог sqldrivers рядом с exe-файлом.
Если все сделано верно, то после вызова QSqlDatabase::addDatabse должно вывестись:

Если не удалось, то попробовать положить qsqlpsql.dll в plugins/sqldrivers.

Далее с помощью DependencyWalker исследуем зависимости qsqlpsql.dll.

Кроме зависимостей от библиотек Qt и компилятора, будет зависимость от libpq.dll.

Проще всего взять libpq.dll из каталога установки PostgreSQL (примерно в C:\Program Files (x86)\PostgreSQL\10\bin). Здесь есть две важнейшие особенности:

1) разрядность libpq.dll должна совпадать с разрядностью приложения. Под Windows стандартный SDK Qt5 с официального сайта 32-разрядный. т.е. необходима 32-разрядная версия libpq.dll, которую можно взять из x86-версии PostgreSQL. Это не влияет на разрядность сервера PostgreSQL, к которому будет подключаться приложение;

2) libpq.dll необходимо располагать рядом с exe-файлом, а не рядом с qsqlpsql.dll. Все остальные dll, от которых зависит libpq.dll, необходимо класть также рядом с exe-файлом приложения.

Теперь все тем же DependencyWalker исследуем зависимости libpq.dll в каталоге установки PostgreSQL.

В зависимости от версии PostgreSQL у libpq.dll могут быть разные dll-зависимости. Находим их все в каталоге установки PostgreSQL и копируем рядом с exe-файлом. Не забываем пройтись по всем зависимостям всех добавляемых dll. 

Сравниваем

Для PostgreSQL 10 набор уже другой:

libpq.dll

libssl-1_1.dll

libcrypto-1_1.dll

libintl-8.dll

libiconv-2.dll

Необходимо создать минимально работающее Qt приложение для подключения и взаимодействия с СУБД PostgreSQL. Из коробки не работает. ОС — windows 10 64bit, Версия Qt — Qt 5.9.5 MSVC 2015, MS Visual Studio 2017 Community, PostgreSQL 9.6 (пробовал как 32bit, так и 64bit)
Проверяю таким кодом:

QSqlDatabase db = QSqlDatabase::addDatabase("QPSQL");
    qDebug() << db.isValid();
    db.setHostName("hostname");
    db.setPort(5432);
    db.setDatabaseName("dbname");
    db.setUserName("username");
    db.setPassword("password");
    if (!db.open())
    {
        qDebug() << db.lastError().text();
        return;
    }

В результате:

QSqlDatabase: QPSQL driver not loaded
QSqlDatabase: available drivers: QSQLITE QMYSQL QMYSQL3 QODBC QODBC3 QPSQL QPSQL7
false

При этом файл qsqlpsql.dll в поддиректории Qt msvc2017_64\plugins\sqldrivers есть. Из чего я сделал вывод, что драйвер надо скомпилировать вручную.
Открываю командную строку Qt 5.9.5 64bit for Desktop (MSVC 2017), перехожу в папку C:\Qt\Qt5.9.5\5.9.5\Src\qtbase\src\plugins\sqldrivers\psql, набираю команду

qmake «INCLUDEPATH+=\»C:\Program Files (x86)\PostgreSQL\9.6\include\»» «LIBS+=\»C:\Program Files (x86)\PostgreSQL\9.6\lib\libpq.lib\»» psql.pro

В результате:

Project ERROR: Library ‘psql’ is not defined.

Пытался также собрать через Qt Creator

Project ERROR: Library ‘psql’ is not defined.
Cannot read /qtsqldrivers-config.pri: No such file or directory
Project ERROR: Library ‘psql’ is not defined.

Пытался собрать также всю ветку sqldrivers, аналогично:

Project ERROR: Library ‘psql’ is not defined.

Есть ли вообще возможность собрать какую-то работающую связку?