Класс QSqlDatabase

Класс QSqlDatabase обрабатывает подключение к базе данных. Подробнее...

• Список всех членов, включая унаследованные

Открытые функции

Статические открытые члены

Защищённые функции

Подробное описание

Класс QSqlDatabase предоставляет интерфейс для доступа к базе данных через подключение. Экземпляр QSqlDatabase представляет подключение. Подключение предоставляет доступ к базе данных через один из поддерживаемых драйверов баз данных, которые производны от QSqlDriver. В качестве альтернативы можно создать свой драйвер базы данных, унаследовав его от QSqlDriver. Дополнительную информацию см. в разделе Как создать свой драйвер базы данных.

Создайте соединение (т.е., экземпляр QSqlDatabase), вызвав одну из статических функций addDatabase(), где вы укажите драйвер или тип драйвера для использования (в зависимости от типа базы данных) и имя соединения. Соединение известно по своему имени, а не по имени базы данных, к которой оно подключено. Вы можете иметь несколько соединений с одной базой данных. QSqlDatabase также поддерживает понятие по умолчанию соединения, которое является безымянным соединением. Чтобы создать соединение по умолчанию, не передавайте аргумент имени соединения при вызове addDatabase(). Впоследствии, соединение по умолчанию будет предполагаться, если вы вызываете любую статическую функцию без указания имени соединения. Следующий фрагмент показывает, как создать и открыть соединение по умолчанию с базой данных PostgreSQL:

    QSqlDatabase db = QSqlDatabase::addDatabase("QPSQL");
    db.setHostName("acidalia");
    db.setDatabaseName("customdb");
    db.setUserName("mojito");
    db.setPassword("J0a1m8");
    bool ok = db.open();

После создания объекта QSqlDatabase, задайте параметры соединения с помощью setDatabaseName(), setUserName(), setPassword(), setHostName(), setPort() и setConnectOptions(). Затем вызовите open(), чтобы активировать физическое подключение к базе данных. Соединение не может быть использовано до тех пор, пока вы его не откроете.

Определенное выше соединение будет соединением по умолчанию, потому что мы не передали имя соединения функции addDatabase(). Впоследствии, вы можете получить соединение по умолчанию, вызвав database() без аргумента имени соединения:

    QSqlDatabase db = QSqlDatabase::database();

QSqlDatabase — это класс-значения. Изменения, внесенные в соединение с базой данных через один экземпляр QSqlDatabase, повлияют на другие экземпляры QSqlDatabase, которые представляют то же соединение. Используйте cloneDatabase(), чтобы создать независимое соединение с базой данных на основе существующего.

Если вы создаёте несколько соединений с базой данных, укажите уникальное имя соединения для каждого из них, когда вы вызываете addDatabase(). Используйте database() с именем соединения, чтобы получить это соединение. Используйте removeDatabase() с именем соединения, чтобы удалить соединение. QSqlDatabase выводит предупреждение, если вы пытаетесь удалить соединение, на которое ссылаются другие объекты QSqlDatabase. Используйте contains(), чтобы увидеть, есть ли данное имя соединения в списке соединений.

См. также QSqlDriver, QSqlQuery, Qt SQL и Потоки и модуль SQL.

Документация по членам-функциям

[protected] QSqlDatabase::QSqlDatabase(QSqlDriver *driver)

Это перегруженная функция.

Создаёт подключение к базе данных с использованием заданного драйвера.

[protected] QSqlDatabase::QSqlDatabase(const QString &type)

Это перегруженная функция.

Создаёт соединение QSqlDatabase, которое использует драйвер, указанный параметром type. Если type не распознаётся, соединение базы данных не будет функциональным.

Доступные типы драйверов:

Дополнительные драйверы сторонних разработчиков, включая ваши собственные пользовательские драйверы, могут быть загружены динамически.

См. также SQL драйверы баз данных, registerSqlDriver() и drivers().

QSqlDatabase::QSqlDatabase(const QSqlDatabase &other)

Создаёт копию other.

QSqlDatabase::QSqlDatabase()

Создаёт пустой, недействительный объект QSqlDatabase. Используйте addDatabase(), removeDatabase() и database(), чтобы получить действительные объекты QSqlDatabase.

QSqlDatabase &QSqlDatabase::operator=(const QSqlDatabase &other)

Присваивает other данному объекту.

QSqlDatabase::~QSqlDatabase()

Удаляет объект и освобождает все выделенные ресурсы.

См. также close().

[static] QSqlDatabase QSqlDatabase::addDatabase(const QString &type, const QString &connectionName = QLatin1String(defaultConnection))

Добавляет базу данных в список подключений к базам данных с использованием драйвера type и имени соединения connectionName. Если уже существует соединение с базой данных с именем connectionName, это соединение удаляется.

Подключение к базе данных обозначается именем connectionName. Возвращается вновь добавленное соединение с базой данных.

Если type недоступен или не может быть загружен, isValid() возвращает false.

Если connectionName не указан, новое соединение становится соединением по умолчанию для приложения, и последующие вызовы database() без аргумента имени соединения вернут соединение по умолчанию. Если здесь указано connectionName, используйте database(connectionName), чтобы получить соединение.

Перед использованием соединения оно должно быть инициализировано. Например, вызовите некоторые или все функции setDatabaseName(), setUserName(), setPassword(), setHostName(), setPort() и setConnectOptions(), и, наконец, open().

Примечание: Эта функция потокобезопасна.

См. также database(), removeDatabase() и Потоки и модуль SQL.

[static] QSqlDatabase QSqlDatabase::addDatabase(QSqlDriver *driver, const QString &connectionName = QLatin1String(defaultConnection))

Эта перегрузка полезна, когда вы хотите создать соединение с базой данных с помощью драйвера, который вы сами создали. Это может быть ваш собственный драйвер базы данных, или вам просто нужно создать один из Qt-драйверов самостоятельно. Если вы это сделаете, рекомендуется включить код драйвера в ваше приложение. Например, вы можете создать подключение к PostgreSQL с помощью вашего собственного QPSQL драйвера так:

PGconn *con = PQconnectdb("host=server user=bart password=simpson dbname=springfield");
QPSQLDriver *drv = new QPSQLDriver(con);
QSqlDatabase db = QSqlDatabase::addDatabase(drv); // becomes the new default connection
QSqlQuery query;
query.exec("SELECT NAME, ID FROM STAFF");

Вышеприведенный код устанавливает подключение к PostgreSQL и инициализирует объект QPSQLDriver. Затем вызывается addDatabase(), чтобы добавить подключение к известным подключениям, чтобы его можно было использовать классами Qt SQL. При инициализации драйвера с дескриптором подключения (или набором дескрипторов) Qt предполагает, что вы уже открыли подключение к базе данных.

Помните, что вы должны связать ваше приложение с библиотекой клиента базы данных. Убедитесь, что библиотека клиента находится в пути поиска вашего компоновщика, и добавьте такие строки в свой файл .pro:

unix:LIBS += -lpq
win32:LIBS += libpqdll.lib

Описанный метод работает для всех предоставленных драйверов. Единственное различие будет в аргументах конструктора драйвера. Вот таблица драйверов, включенных в Qt, их файлов исходного кода и аргументов конструктора:

См. также drivers().

[static] QSqlDatabase QSqlDatabase::cloneDatabase(const QSqlDatabase &other, const QString &connectionName)

Создает копию подключения к базе данных other и сохраняет ее как connectionName. Все настройки из исходной базы данных, например, databaseName(), hostName() и т.д., копируются. Ничего не делает, если other — недопустимая база данных. Возвращает вновь созданное подключение к базе данных.

[static, since 5.13] QSqlDatabase QSqlDatabase::cloneDatabase(const QString &other, const QString &connectionName)

Это перегруженный метод.

Создает копию подключения к базе данных other и сохраняет ее как connectionName. Все настройки из исходной базы данных, например, databaseName(), hostName() и т.д., копируются. Ничего не делает, если other — недопустимая база данных. Возвращает вновь созданное подключение к базе данных.

Эта перегрузка полезна при клонировании базы данных в другой поток, чем тот, который используется базой данных, представленной other.

Эта функция была добавлена в Qt 5.13.

void QSqlDatabase::close()

Закрывает подключение к базе данных, освобождая любые выделенные ресурсы и делая недействительными все существующие объекты QSqlQuery, используемые с базой данных.

Это также повлияет на копии этого объекта QSqlDatabase.

См. также removeDatabase().

bool QSqlDatabase::commit()

Выполняет фиксацию транзакции в базе данных, если драйвер поддерживает транзакции и была запущена транзакция transaction(). Возвращает true, если операция выполнена успешно. В противном случае возвращает false.

Вызовите lastError(), чтобы получить информацию об ошибках.

См. также QSqlQuery::isActive(), QSqlDriver::hasFeature() и rollback().

QString QSqlDatabase::connectOptions() const

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

См. также setConnectOptions().

QString QSqlDatabase::connectionName() const

Возвращает имя подключения, которое может быть пустым.

См. также addDatabase().

[static] QStringList QSqlDatabase::connectionNames()

Возвращает список, содержащий имена всех подключений.

Примечание: Эта функция является потокобезопасной.

См. также contains(), database() и Потоки и модуль SQL.

[static] bool QSqlDatabase::contains(const QString &connectionName = QLatin1String(defaultConnection))

Возвращает true, если список подключений к базам данных содержит connectionName; в противном случае возвращает false.

Примечание: Эта функция является потокобезопасной.

См. также connectionNames(), database() и Потоки и модуль SQL.

[static] QSqlDatabase QSqlDatabase::database(const QString &connectionName = QLatin1String(defaultConnection), bool open = true)

Возвращает подключение к базе данных с именем connectionName. Подключение к базе данных должно быть предварительно добавлено с помощью addDatabase(). Если open равно true (по умолчанию) и подключение к базе данных еще не открыто, оно открывается сейчас. Если имя connectionName не указано, используется имя подключения по умолчанию. Если connectionName не существует в списке баз данных, возвращается недопустимое подключение.

Примечание: Эта функция является потокобезопасной.

См. также isOpen() и Потоки и модуль SQL.

QString QSqlDatabase::databaseName() const

Возвращает имя базы данных подключения, которое может быть пустым.

См. также setDatabaseName().

QSqlDriver *QSqlDatabase::driver() const

Возвращает драйвер базы данных, используемый для доступа к подключению к базе данных.

См. также addDatabase() и drivers().

QString QSqlDatabase::driverName() const

Возвращает имя драйвера подключения.

См. также addDatabase() и driver().

[static] QStringList QSqlDatabase::drivers()

Возвращает список всех доступных драйверов баз данных.

См. также registerSqlDriver().

QSqlQuery QSqlDatabase::exec(const QString &query = QString()) const

Выполняет SQL-запрос в базе данных и возвращает объект QSqlQuery. Используйте lastError(), чтобы получить информацию об ошибках. Если query пусто, возвращается пустой, недопустимый запрос, и lastError() не затрагивается.

См. также QSqlQuery и lastError().

QString QSqlDatabase::hostName() const

Возвращает имя хоста подключения; оно может быть пустым.

См. также setHostName().

[static] bool QSqlDatabase::isDriverAvailable(const QString &name)

Возвращает true, если драйвер с именем name доступен; в противном случае возвращает false.

См. также drivers().

bool QSqlDatabase::isOpen() const

Возвращает true, если подключение к базе данных в настоящее время открыто; в противном случае возвращает false.

bool QSqlDatabase::isOpenError() const

Возвращает true, если при открытии подключения к базе данных произошла ошибка; в противном случае возвращает false. Информацию об ошибке можно получить с помощью функции lastError().

bool QSqlDatabase::isValid() const

Возвращает true, если у QSqlDatabase есть допустимый драйвер.

Пример:

QSqlDatabase db;
qDebug() << db.isValid();    // Returns false

db = QSqlDatabase::database("sales");
qDebug() << db.isValid();    // Returns \c true if "sales" connection exists

QSqlDatabase::removeDatabase("sales");
qDebug() << db.isValid();    // Returns false

QSqlError QSqlDatabase::lastError() const

Возвращает информацию об последней ошибке, произошедшей в базе данных.

Ошибки, которые возникают в сопряжении с отдельным запросом, сообщаются функцией QSqlQuery::lastError().

См. также QSqlError и QSqlQuery::lastError().

QSql::NumericalPrecisionPolicy QSqlDatabase::numericalPrecisionPolicy() const

Возвращает текущую политику точности чисел для подключения к базе данных.

См. также QSql::NumericalPrecisionPolicy, setNumericalPrecisionPolicy(), QSqlQuery::numericalPrecisionPolicy(), и QSqlQuery::setNumericalPrecisionPolicy().

bool QSqlDatabase::open()

Открывает подключение к базе данных, используя текущие значения подключения. Возвращает true при успехе; в противном случае возвращает false. Информацию об ошибке можно получить с помощью lastError().

См. также lastError(), setDatabaseName(), setUserName(), setPassword(), setHostName(), setPort() и setConnectOptions().

bool QSqlDatabase::open(const QString &user, const QString &password)

Это перегруженная функция.

Открывает подключение к базе данных, используя заданное имя пользователя user и пароль password. Возвращает true при успехе; в противном случае возвращает false. Информацию об ошибке можно получить с помощью функции lastError().

Эта функция не сохраняет полученный пароль. Вместо этого пароль передаётся непосредственно драйверу для открытия соединения и затем отбрасывается.

См. также lastError().

QString QSqlDatabase::password() const

Возвращает пароль подключения. Пустая строка будет возвращена, если пароль не был задан с помощью setPassword(), и если пароль был передан в вызове open(), или если пароль не использовался.

См. также setPassword().

int QSqlDatabase::port() const

Возвращает номер порта подключения. Значение неопределено, если номер порта не был задан.

См. также setPort().

QSqlIndex QSqlDatabase::primaryIndex(const QString &tablename) const

Возвращает первичный индекс для таблицы tablename. Если первичный индекс не существует, возвращается пустой QSqlIndex.

См. также tables() и record().

QSqlRecord QSqlDatabase::record(const QString &tablename) const

Возвращает QSqlRecord, заполненный именами всех полей в таблице (или представлении) с именем tablename. Порядок, в котором поля появляются в записи, не определён. Если такой таблицы (или представления) не существует, возвращается пустая запись.

[static] void QSqlDatabase::registerSqlDriver(const QString &name, QSqlDriverCreatorBase *creator)

Эта функция регистрирует новый драйвер SQL с именем name в рамках фреймворка SQL. Это полезно, если у вас есть собственный драйвер SQL и вы не хотите компилировать его как плагин.

Пример:

QSqlDatabase::registerSqlDriver("MYDRIVER", new QSqlDriverCreator<QSqlDriver>);
QVERIFY(QSqlDatabase::drivers().contains("MYDRIVER"));
QSqlDatabase db = QSqlDatabase::addDatabase("MYDRIVER");
QVERIFY(db.isValid());

QSqlDatabase принимает во владение указатель creator, поэтому вам не следует удалять его самостоятельно.

См. также drivers().

[static] void QSqlDatabase::removeDatabase(const QString &connectionName)

Удаляет подключение к базе данных connectionName из списка подключений к базам данных.

Пример:

// WRONG
QSqlDatabase db = QSqlDatabase::database("sales");
QSqlQuery query("SELECT NAME, DOB FROM EMPLOYEES", db);
QSqlDatabase::removeDatabase("sales"); // will output a warning
// "db" is now a dangling invalid database connection,
// "query" contains an invalid result set

Правильный способ сделать это:

{
    QSqlDatabase db = QSqlDatabase::database("sales");
    QSqlQuery query("SELECT NAME, DOB FROM EMPLOYEES", db);
}
// Both "db" and "query" are destroyed because they are out of scope
QSqlDatabase::removeDatabase("sales"); // correct

Чтобы удалить подключение по умолчанию, которое, возможно, было создано с помощью вызова addDatabase() без указания имени подключения, можно получить имя подключения по умолчанию, вызвав connectionName() на базе данных, возвращаемой database(). Обратите внимание, что если база данных по умолчанию не была создана, будет возвращена недопустимая база данных.

Примечание: Эта функция безопасна для многопоточного использования.

См. также database(), connectionName() и Потоки и модуль SQL.

bool QSqlDatabase::rollback()

Откатывает транзакцию в базе данных, если драйвер поддерживает транзакции и была начата транзакция с помощью transaction(). Возвращает true, если операция выполнена успешно. В противном случае возвращает false.

Вызовите lastError(), чтобы получить информацию об ошибках.

См. также QSqlQuery::isActive(), QSqlDriver::hasFeature() и commit().

void QSqlDatabase::setConnectOptions(const QString &options = QString())

Устанавливает параметры, специфичные для базы данных options. Это необходимо сделать до открытия подключения, в противном случае это не окажет никакого влияния. Другой вариант — закрыть подключение, вызвать QSqlDatabase::setConnectOptions() и вновь открыть подключение с помощью open().

Формат строки options — список параметров, разделённых точкой с запятой, или пары имя=значение. Параметры зависят от используемого клиента базы данных:

Примеры:

db.setConnectOptions("SSL_KEY=client-key.pem;SSL_CERT=client-cert.pem;SSL_CA=ca-cert.pem;CLIENT_IGNORE_SPACE=1"); // use an SSL connection to the server
if (!db.open()) {
    db.setConnectOptions(); // clears the connect option string
    // ...
}
// ...
// PostgreSQL connection
db.setConnectOptions("requiressl=1"); // enable PostgreSQL SSL connections
if (!db.open()) {
    db.setConnectOptions(); // clear options
    // ...
}
// ...
// ODBC connection
db.setConnectOptions("SQL_ATTR_ACCESS_MODE=SQL_MODE_READ_ONLY;SQL_ATTR_TRACE=SQL_OPT_TRACE_ON"); // set ODBC options
if (!db.open()) {
    db.setConnectOptions(); // don't try to set this option
    // ...
}
}

Для получения дополнительной информации об этих параметрах, обратитесь к документации клиентской библиотеки.

См. такжеconnectOptions().

void QSqlDatabase::setDatabaseName(const QString &name)

Устанавливает имя базы данных соединения на name. Для того, чтобы это имело эффект, имя базы данных должно быть установлено до того, как соединение будет открыто. В качестве альтернативы, вы можете закрыть соединение, установить имя базы данных и снова вызвать open().

Для драйвера QSQLITE, если указанное имя базы данных не существует, то он создаст файл для вас, если только не установлен параметр QSQLITE_OPEN_READONLY.

Кроме того, name может быть установлено на ":memory:", что создаст временную базу данных, доступную только в течение срока действия приложения.

Для драйвера QOCI (Oracle) именем базы данных является имя службы TNS.

Для драйвера QODBC имя name может быть либо именем источника данных (DSN), либо именем файла DSN (в этом случае файл должен иметь .dsn расширение), или строкой подключения.

Например, пользователи Microsoft Access могут использовать следующую строку подключения для открытия файла .mdb напрямую, вместо того, чтобы создавать запись DSN в менеджере ODBC:

// ...
QSqlDatabase db = QSqlDatabase::addDatabase("QODBC");
db.setDatabaseName("DRIVER={Microsoft Access Driver (*.mdb, *.accdb)};FIL={MS Access};DBQ=myaccessfile.mdb");
if (db.open()) {
    // success!
}
// ...

Значения по умолчанию нет.

См. такжеdatabaseName(), setUserName(), setPassword(), setHostName(), setPort(), setConnectOptions(), и open().

void QSqlDatabase::setHostName(const QString &host)

Устанавливает имя хоста соединения на host. Для того, чтобы это имело эффект, имя хоста должно быть установлено до того, как соединение будет открыто. В качестве альтернативы, вы можете закрыть соединение, установить имя хоста и снова вызвать open().

Значения по умолчанию нет.

См. такжеhostName(), setUserName(), setPassword(), setDatabaseName(), setPort(), setConnectOptions(), и open().

void QSqlDatabase::setNumericalPrecisionPolicy(QSql::NumericalPrecisionPolicy precisionPolicy)

Устанавливает политику точности чисел по умолчанию, используемую запросами, созданными на этом подключении к базе данных, на precisionPolicy.

Примечание: драйверы, которые не поддерживают извлечение числовых значений с низкой точностью, проигнорируют политику точности. Вы можете использовать QSqlDriver::hasFeature() для того, чтобы узнать, поддерживает ли драйвер эту функцию.

Примечание: установка политики точности по умолчанию на precisionPolicy не влияет на активные запросы.

См. такжеQSql::NumericalPrecisionPolicy, numericalPrecisionPolicy(), QSqlQuery::setNumericalPrecisionPolicy(), и QSqlQuery::numericalPrecisionPolicy().

void QSqlDatabase::setPassword(const QString &password)

Устанавливает пароль соединения на password. Для того, чтобы это имело эффект, пароль должен быть установлен до того, как соединение будет открыто. В качестве альтернативы, вы можете закрыть соединение, установить пароль и снова вызвать open().

Значения по умолчанию нет.

См. такжеpassword(), setUserName(), setDatabaseName(), setHostName(), setPort(), setConnectOptions(), и open().

void QSqlDatabase::setPort(int port)

Устанавливает номер порта соединения на port. Для того, чтобы это имело эффект, номер порта должен быть установлен до того, как соединение будет открыто. В качестве альтернативы, вы можете закрыть соединение, установить номер порта и снова вызвать open().

Значения по умолчанию нет.

См. такжеport(), setUserName(), setPassword(), setHostName(), setDatabaseName(), setConnectOptions(), и open().

void QSqlDatabase::setUserName(const QString &name)

Устанавливает имя пользователя соединения на name. Для того, чтобы это имело эффект, имя пользователя должно быть установлено до того, как соединение будет открыто. В качестве альтернативы, вы можете закрыть соединение, установить имя пользователя и снова вызвать open().

Значения по умолчанию нет.

См. такжеuserName(), setDatabaseName(), setPassword(), setHostName(), setPort(), setConnectOptions(), и open().

QStringList QSqlDatabase::tables(QSql::TableType type = QSql::Tables) const

Возвращает список таблиц базы данных, системных таблиц и представлений, как указано параметром type.

См. такжеprimaryIndex() и record().

bool QSqlDatabase::transaction()

Начинает транзакцию в базе данных, если драйвер поддерживает транзакции. Возвращает true, если операция выполнена успешно. В противном случае возвращает false.

См. такжеQSqlDriver::hasFeature(), commit(), и rollback().

QString QSqlDatabase::userName() const

Возвращает имя пользователя соединения; оно может быть пустым.

См. такжеsetUserName().