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

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

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

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

Если драйвер поддерживает транзакции, используйте transaction(), чтобы начать транзакцию, и commit() или rollback(), чтобы завершить её. Используйте hasFeature(), чтобы узнать, поддерживает ли драйвер транзакции.

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

Если произошла ошибка, lastError() вернёт информацию об этом.

Получите имена доступных SQL-драйверов с помощью drivers(). Проверьте наличие конкретного драйвера с помощью isDriverAvailable(). Если вы создали свой собственный пользовательский драйвер, вы должны зарегистрировать его с помощью registerSqlDriver().

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

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

Формат строки 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 имя name может быть либо 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 этому объекту.