Класс QSqlDatabase

Класс 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(), чтобы создать независимое соединение с базой данных на основе существующего.

Предупреждение: Крайне рекомендуется не хранить копию QSqlDatabase в качестве члена класса, так как это помешает экземпляру корректно очиститься при выходе. Если вам нужно получить доступ к существующему QSqlDatabase, к нему следует обращаться с помощью database(). Если вы выбрали иметь переменную-член QSqlDatabase, она должна быть удалена до удаления экземпляра QCoreApplication, иначе это может привести к неопределенному поведению.

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

Примечание: QSqlDatabase::exec() устарела. Используйте QSqlQuery::exec() вместо этого.

Примечание: При использовании транзакций необходимо начать транзакцию перед созданием запроса.

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

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

QSqlDatabase::QSqlDatabase()

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

QSqlDatabase::QSqlDatabase(const QSqlDatabase &other)

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

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

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

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

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

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

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

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

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

Создает соединение с базой данных, используя указанный драйвер driver.

QSqlDatabase::~QSqlDatabase()

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

Примечание: При уничтожении последнего соединения деструктор неявно вызывает close(), чтобы освободить соединение с базой данных.

См. также 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) для получения подключения.

Предупреждение: Если вы добавляете подключение с тем же именем, что и существующее подключение, новое подключение заменяет старое. Если вы вызываете эту функцию более одного раза без указания 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 следующим образом:

#include "qtdir/src/sql/drivers/psql/qsql_psql.cpp"

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 предполагает, что вы уже открыли подключение к базе данных.

Примечание: Мы предполагаем, что qtdir — это каталог, где установлен Qt. Это подтянет код, необходимый для использования библиотеки клиента PostgreSQL и для инициализации объекта QPSQLDriver, предполагая, что у вас есть заголовочные файлы PostgreSQL где-то в пути поиска заголовочных файлов.

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

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

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

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

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

Предупреждение: Фреймворк SQL получает во владение драйвер. Его не следует удалять. Чтобы удалить подключение, используйте removeDatabase().

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

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

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

Примечание: Новое подключение не открыто. Прежде чем использовать новое подключение, вы должны вызвать open().

void QSqlDatabase::close()

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

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

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

bool QSqlDatabase::commit()

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

Примечание: Для некоторых баз данных фиксация завершится ошибкой и вернет false , если используется активный запрос (active query) к базе данных для SELECT. Сделайте запрос (inactive) неактивным перед выполнением фиксации.

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

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

QString QSqlDatabase::connectOptions() const

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

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

QString QSqlDatabase::connectionName() const

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

Примечание: Имя подключения не является именем базы данных.

Эта функция была представлена в Qt 4.4.

См. также 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

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

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

См. также 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<MyDatabaseDriver>);
QSqlDatabase db = QSqlDatabase::addDatabase("MYDRIVER");

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.

Примечание: Для некоторых баз данных откат завершится ошибкой и вернёт false если существует активный запрос, использующий базу данных в SELECT. Сделайте запрос неактивным перед выполнением отката.

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

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

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

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

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

Примеры:

...
// MySQL connection
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(). В качестве альтернативы, можно закрыть подключение close(), установить имя базы данных и вызвать open() снова.

Примечание: Имя базы данных не является именем подключения. Имя подключения должно быть передано в addDatabase() при создании объекта подключения.

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

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

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

...
db = QSqlDatabase::addDatabase("QODBC");
db.setDatabaseName("DRIVER={Microsoft Access Driver (*.mdb)};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 не повлияет на активные в данный момент запросы.

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

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

void QSqlDatabase::setPassword(const QString &password)

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

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

Предупреждение: Эта функция хранит пароль в открытом виде в Qt. Используйте вызов 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().

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

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