Класс QSqlDatabase

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

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

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

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

Protected Functions

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

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

Устанавливает специфичные для базы данных 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 этому объекту.