Класс 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 где-то в пути поиска include.

Помните, что вы должны связать свое приложение с библиотекой клиента базы данных. Убедитесь, что библиотека клиента находится в пути поиска вашего линкера и добавьте такие строки в ваш .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 если существует активный запрос QSqlQuery, использующий базу данных для SELECT. Сделайте запрос неактивным перед выполнением фиксации.

Вызовите 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())

Устанавливает параметры, специфичные для базы данных. Это должно быть сделано до открытия соединения, в противном случае это не повлияет. Другой вариант - закрыть соединение, вызвать 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().

Примечание: Имя базы данных не равно имени подключения. Имя подключения необходимо передать в 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 этому объекту.