$szTitle = "Qt 4.5: Описание класса QSqlDatabase"; include "./_header.inc"; ?>
Главная · Все пространства имен · Все классы · Основные классы · Классы по группам · Модули · Функции |
Класс QSqlDatabase представляет подключение к базе данных. Далее...
#include <QSqlDatabase>
Класс QSqlDatabase представляет подключение к базе данных.
Класс QSqlDatabase предоставляет интерфейс для подключения к базе данных через соединение. Экземпляр класса QSqlDatabase представляет соединение. Соединение предоставляет доступ к базе данных через один из поддерживаемых драйверов баз данных, которые унаследованы от QSqlDriver. В качестве альтернативы, вы может создать подкласс от QSqlDriver для драйвера вашей базы данных. Для получения дополнительной информации смотрите Как написать собственный драйвер БД.
Создать соединение (т.е. экземпляр класса QSqlDatabase) можно с помощью одной из статических функций addDatabase(), где вы задаете используемый драйвер или тип драйвера (т.е., к какому виду базы данных вы обращаетесь?) и имя соединения. Соединение известно под своим собственным именем, а не по имени базы данных с которой оно соединяет. Вы можете иметь множество соединений с одной и той же базой данных. QSqlDatabase также поддерживает концепцию соединения по умолчанию, которое является неименованным (unnamed) соединением. Чтобы создать соединения по умолчанию при вызове 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 является классом-значением (value class). Изменения, произведенные в базе данных через один экземпляр класса QSqlDatabase, затронут все остальные экземпляры класса QSqlDatabase, которые представляют то же самое соединение. Используйте cloneDatabase() для создания независимого соединения с базой данных на основе существующего.
Если вы создаете несколько соединений с базой данных, то при вызове addDatabase() задавайте уникальное имя соединения для каждого из них. Используйте database() вместе с именем соединения, чтобы получить это соединение. Используйте removeDatabase() вместе с именем соединения, чтобы удалить соединение. QSqlDatabase выведет предупреждение, если вы попытаетесь удалить соединение, на которое ссылаются другие объекты QSqlDatabase. Используйте contains() чтобы узнать, есть ли заданное имя в списке соединений.
Как только соединение установлено, вы можете вызвать tables() для получения списка таблиц базы данных, primaryIndex() - для получения первичного индекса (primary index) таблицы и record() - для получения мета-информации о полях таблиц (например, имена полей).
Замечание: QSqlDatabase::exec() является устаревшей (deprecated). Используйте взамен QSqlQuery::exec().
Если драйвер поддерживает транзакции, используйте transaction() чтобы начать транзакцию, и commit() или rollback() чтобы завершить её. Используйте hasFeature() чтобы узнать, поддерживает ли драйвер транзакции. Замечание: При использовании транзакций вы должны начать её прежде, чем создадите свой запрос.
Если возникнет ошибка, то lastError() возвратит информацию о ней.
Получить имена доступных SQL-драйверов можно с помощью drivers(). Проверить наличие специфичного драйвера можно с помощью isDriverAvailable(). Если вы создали свой собственный драйвер, вы должны зарегистрировать его с помощью registerSqlDriver().
Смотрите также QSqlDriver, QSqlQuery, Модуль QtSql и Потоки и модуль SQL.
Создает пустой, недействительный объект QSqlDatabase. Используйте addDatabase(), removeDatabase() и database() для того, чтобы получить действительные объекты QSqlDatabase.
Создаёт копию other.
Это перегруженная функция.
Создаёт соединение QSqlDatabase, которое использует драйвер указанного типа type. Если type не распознаётся, соединение с базой данных не будет функционировать.
На текущий момент доступны следующие типы драйверов:
Тип драйвера | Описание |
---|---|
QDB2 | IBM DB2 |
QIBASE | Драйвер Borland InterBase |
QMYSQL | Драйвер MySQL |
QOCI | Драйвер Oracle Call Interface |
QODBC | Драйвер ODBC (включая Microsoft SQL Server) |
QPSQL | Драйвер PostgreSQL |
QSQLITE | SQLite версии 3 или выше |
QSQLITE2 | SQLite версии 2 |
QTDS | Драйвер Sybase Adaptive Server |
Дополнительные сторонние драйвера, включая ваши собственные, можно загрузить динамически.
Смотрите также Драйвера баз данных SQL, registerSqlDriver() и drivers().
Это перегруженная функция.
Создаёт соединение с базой данных, используя переданный driver.
Удаляет объект и освобождает все выделенные ему ресурсы.
Если объект QSqlDatabase является последним, то соединение с базой данных автоматически закрывается.
Смотрите также close().
Добавляет базу данных в список соединений баз данных, используя драйвер типа type и имя соединения connectionName. Если соединение с базой данных с именем connectionName уже существует, то оно будет удалено.
Соединение с базой данных в дальнейшем именуется connectionName. Будет возвращено вновь добавленное соединение.
Если аргумент connectionName не задан, то вновь добавленное соединение становится для приложения соединением по умолчанию, и последующие вызовы database() без аргумента с именем соединения будут возвращать соединение по умолчанию. Если connectionName предоставляется, используйте database(connectionName) чтобы найти соединение.
Внимание: Если вы добавили соединение с именем, совпадающим с именем существующего соединения, то старое соединение будет замещено новым. Если вы вызовите эту функцию более одного раза без заданного connectionName, то соединение по умолчанию будет замещено этим соединением.
Перед использованием соединение должно быть инициализировано. например, вызовом всех или одной из функций setDatabaseName(), setUserName(), setPassword(), setHostName(), setPort() и setConnectOptions(), и, в заключение, open().
Замечание: Эта функция потокобезопасна.
Смотрите также database(), removeDatabase() и Потоки и модуль SQL.
Данная перегруженная функция полезна, когда вы хотите создать соединение с базой данных с помощью созданного вами самостоятельно driver. Это может быть ваш собственный драйвер базы данных, или же вам может понадобиться собственный экземпляр одного из драйверов Qt. Если вы это сделаете, то рекомендуем вам включить код драйвера в ваше приложение. Например, вы можете создать соединение с PostgreSQL с помощью собственного драйвера наподобие такого:
#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); // становится новым соединением по умолчанию
QSqlQuery query;
query.exec("SELECT NAME, ID FROM STAFF");
...
Вышеуказанный код устанавливает соединение с PostgreSQL и создает экземпляр объекта QPSQLDriver. Затем вызывается addDatabase(), чтобы добавить соединение в известные соединения так, что оно может быть использовано классами SQL Qt. Когда создан экземпляр драйвера с обработчиком соединения (или набором обработчиков), Qt предполагает, что вы уже открыли соединение с базой данных.
Замечание: Мы предполагаем, что qtdir - каталог, куда установлена Qt. Это будет подключать код, который нужно использовать клиентской библиотеке PostgreSQL и создавать экземпляр объекта QPSQLDriver, если предположить, что у вас есть заголовочные файлы PostgreSQL где-нибудь по вашему пути поиска.
Помните, что вы должны скомпоновать свое приложение вместе с клиентской библиотекой базы данных. Убедитесь, что клиентская библиотека находится в путях поиска вашего компоновщика, и добавьте в ваш .pro-файл такие строки:
unix:LIBS += -lpq win32:LIBS += libpqdll.lib
Описанный способ работает для всех поставляемых драйверов. Отличия будут только в аргументах конструктора драйвера. Вот таблица драйверов, включенных в состав Qt, файлы с исходным кодом и аргументы конструктора:
Драйвер | Имя класса | Аргументы конструктора | Файл для подключения |
---|---|---|---|
QPSQL | QPSQLDriver | PGconn *connection | qsql_psql.cpp |
QMYSQL | QMYSQLDriver | MYSQL *connection | qsql_mysql.cpp |
QOCI | QOCIDriver | OCIEnv *environment, OCISvcCtx *serviceContext | qsql_oci.cpp |
QODBC | QODBCDriver | SQLHANDLE environment, SQLHANDLE connection | qsql_odbc.cpp |
QDB2 | QDB2 | SQLHANDLE environment, SQLHANDLE connection | qsql_db2.cpp |
QTDS | QTDSDriver | LOGINREC *loginRecord, DBPROCESS *dbProcess, const QString &hostName | qsql_tds.cpp |
QSQLITE | QSQLiteDriver | sqlite *connection | qsql_sqlite.cpp |
QIBASE | QIBaseDriver | isc_db_handle connection | qsql_ibase.cpp |
Имя узла (или имя службы) необходимо, когда конструируется QTDSDriver для создания новых соединений для внутренних запросов. Это для предотвращения блокировок, когда используются одновременно несколько объектов QSqlQuery.
Внимание: Добавление соединения с именем, совпадающим с именем существующего соединения, послужит причиной замены старого соединения новым.
Внимание: Инструментарий SQL становится владельцем driver. Он не может быть удален. Для удаления подключения используйте removeDatabase().
Смотрите также drivers().
Клонирует соединение с БД other и сохраняет копию с именем connectionName. Все настройки исходной БД, такие как databaseName(), hostName() и т.д., дублируются. Если other является некорректным, то ничего не происходит. Будет возвращено вновь добавленное соединение.
Замечание: Новое соединение не будет открыто. Перед использованием нового соединения вы должны вызвать open().
Закрывает соединения с базой данных, освобождает занятые ресурсы и делает недействительными все существующие объекты QSqlQuery, которые использовались вместе с базой данных.
Это сработает для всех копий объекта QSqlDatabase.
Смотрите также removeDatabase().
Выполняет транзакцию в базу данных, если она поддерживается драйвером и уже была начата транзакция посредством transaction(). Возвращает true в случае успеха операции. В противном случае возвращает false.
Замечание: Для некоторых баз данных фиксация транзакции завершится неудачно и возвратит false, если использовалась active query базы данных для SELECT. Сделайте запрос inactive перед выполнением фиксации транзакции.
Вызовите lastError() чтобы получить информацию об ошибках.
Смотрите также QSqlQuery::isActive(), QSqlDriver::hasFeature() и rollback().
Возвращает строку используемых опций соединения. Строка может быть пустой.
Смотрите также setConnectOptions().
Возвращает имя соединения; может быть пустым. Замечание: Имя соединения - это не имя базы данных.
Эта функция была введена в Qt 4.4.
Смотрите также addDatabase().
Возвращает список, содержащий имена всех соединений.
Замечание: Эта функция потокобезопасна.
Смотрите также contains(), database() и Потоки и модуль SQL.
Возвращает true, если список соединений содержит соединение connectionName; в противном случае возвращает false.
Замечание: Эта функция потокобезопасна.
Смотрите также connectionNames(), database() и Потоки и модуль SQL.
Возвращает соединение с базой данных с именем connectionName. Оно должно быть заранее добавлено с помощью addDatabase(). Если open равно true (по умолчанию это так) и такое соединение ещё не открыто, оно открывается. Если connectionName не задано, используется соединение по умолчанию. Если connectionName отсутствует в списке баз данных, возвращается неверное соединение.
Замечание: Эта функция потокобезопасна.
Смотрите также isOpen() и Потоки и модуль SQL.
Возвращает имя соединения с базой данных; может быть пустым. Замечание: Имя базы данных - это не имя соединения.
Смотрите также setDatabaseName().
Возвращает драйвер базы данных, используемый для соединения с базой данных.
Смотрите также addDatabase() и drivers().
Возвращает имя драйвера соединения.
Смотрите также addDatabase() и driver().
Возвращает список доступных драйверов баз данных.
Смотрите также registerSqlDriver().
Выполняет оператор SQL на базе данных и возвращает объект QSqlQuery. Используйте lastError() для получения информации об ошибках. Если query является пустым, соответственно, пустой, неправильный запрос будет возвращён и lastError() не будет задействован.
Смотрите также QSqlQuery и lastError().
Возвращает имя узла соединения; может быть пустым.
Смотрите также setHostName().
Возвращает true, если драйвер с именем name доступен; в противном случае возвращает false.
Смотрите также drivers().
Возвращает true, если соединение с базой данных открыто; в противном случае возвращает false.
Возвращает true, если произошла ошибка соединения с базой данных; в противном случае возвращает false. Информацию об ошибке можно получить с помощью функции lastError().
Возвращает true, если QSqlDatabase является корректным драйвером.
Пример:
QSqlDatabase db; qDebug() << db.isValid(); // Возвращает false db = QSqlDatabase::database("sales"); qDebug() << db.isValid(); // Возвращает true, если соединение "sales" существует QSqlDatabase::removeDatabase("sales"); qDebug() << db.isValid(); // Возвращает false
Возвращает информацию о последней ошибке, случившейся при работе с базой данных.
При помощи QSqlQuery::lastError() можно узнать о неудавшихся попытках связывания и отдельных запросов.
Смотрите также QSqlError и QSqlQuery::lastError().
Открывает соединение с базой данных, используя текущие значения параметров соединения. Возвращает true, если всё прошло успешно; в противном случае возвращает false. Информацию об ошибке можно получить с помощью функции lastError().
Смотрите также lastError(), setDatabaseName(), setUserName(), setPassword(), setHostName(), setPort() и setConnectOptions().
Это перегруженная функция.
Открывает соединения с базой данных, используя переданные имя пользователя user и пароль password. Возвращает true, если всё прошло успешно; в противном случае возвращает false. Информацию об ошибке можно получить с помощью функции lastError().
Данная функция не сохраняет пароль, если он был передан. Вместо этого он передаётся непосредственно драйверу для открытия соединения, после чего сбрасывается.
Смотрите также lastError().
Возвращает пароль соединения. Если он не был установлен с помощью setPassword() и был передан посредством вызова open() или же он не используется, возвращается пустая строка.
Смотрите также setPassword().
Возвращает номер порта соединения. Если номер порта не был установлен, это значение не будет определено.
Смотрите также setPort().
Возвращает первичный индекс таблицы tablename. Если такой не определён, возвращается пустой QSqlIndex.
Смотрите также tables() и record().
Возвращает QSqlRecord, заполненный именами полей таблицы (или представления) tablename. Порядок, в котором поля будут представлены, не определён. Если указанной таблицы (или представления) не существует, возвращается пустая запись (record).
Эта функция регистрирует новый SQL-драйвер под именем name внутри инструментария SQL. Это используется для пользовательских SQL-драйверов, которые не компилируются как подключаемый модуль (plugin).
Пример:
QSqlDatabase::registerSqlDriver("MYDRIVER", new QSqlDriverCreator<MyDatabaseDriver>); QSqlDatabase db = QSqlDatabase::addDatabase("MYDRIVER");
QSqlDatabase берёт на себя управление указателем на creator, потому вы не должны беспокоиться о его удалении.
Смотрите также drivers().
Убирает соединение connectionName из списка соединений с базой данных.
Внимание: Во время вызова этой функции не должно быть открытых запросов к данной базе данных, в противном случае произойдёт утечка ресурса (resource leak).
Пример:
// НЕПРАВИЛЬНО QSqlDatabase db = QSqlDatabase::database("sales"); QSqlQuery query("SELECT NAME, DOB FROM EMPLOYEES", db); QSqlDatabase::removeDatabase("sales"); // породит предупреждение // "db" в данный момент висит на неправильном соединении с БД, // "query" содержит неправильный результат
Вот правильный вариант реализации:
{ QSqlDatabase db = QSqlDatabase::database("sales"); QSqlQuery query("SELECT NAME, DOB FROM EMPLOYEES", db); } // Оба, "db" и "query", уничтожаются при выходе из их блока QSqlDatabase::removeDatabase("sales"); // правильно
Для удаления соединения по умолчанию, которое может быть создано вызовом addDatabase() без указания имени соединения, вы можете отыскать имя соединения по умолчанию вызвав connectionName() на базе данных, возвращаемой database(). Обратите внимание на то, что если база данных по умолчанию не была создана, то будет возвращена неверная база данных.
Замечание: Эта функция потокобезопасна.
Смотрите также database(), connectionName() и Потоки и модуль SQL.
Откатывает транзакцию БД, если драйвер поддерживает их и транзакция transaction() была начата. Возвращает true в случае успеха операции. В противном случае возвращает false.
Замечание: Для некоторых баз данных откат транзакции завершится неудачно и возвратит false, если использовалась active query базы данных для SELECT. Сделайте запрос inactive перед выполнением отката транзакции.
Вызовите lastError() чтобы получить информацию об ошибках.
Смотрите также QSqlQuery::isActive(), QSqlDriver::hasFeature() и commit().
Устанавливает специфичные для разных баз данных настройки options. Это должно быть сделано до того, как произойдёт соединение с базой данных, иначе оно не будет работать (или вы можете закрыть соединение с помощью close(), вызвать эту функцию, а затем open() для повтора соединения).
Формат строки options является списком имён или пар параметр=значение (option=value), разделённых точкой с запятой. В зависимости от базы данных используются следующие опции:
ODBC | MySQL | PostgreSQL |
---|---|---|
|
|
|
DB2 | OCI | TDS |
|
| none |
SQLite | Interbase | |
|
|
Примеры:
... // соединение с MySQL db.setConnectOptions("CLIENT_SSL=1;CLIENT_IGNORE_SPACE=1"); // используйте SSL соединение с сервером if (!db.open()) { db.setConnectOptions(); // очищает список параметров ... } ... // соединение с PostgreSQL db.setConnectOptions("requiressl=1"); // включает PostgreSQL SSL соединения if (!db.open()) { db.setConnectOptions(); // clear options ... } ... // ODBC соединение db.setConnectOptions("SQL_ATTR_ACCESS_MODE=SQL_MODE_READ_ONLY;SQL_ATTR_TRACE=SQL_OPT_TRACE_ON"); // устанавливаем опции ODBC if (!db.open()) { db.setConnectOptions(); // не пытайтесь задать этот параметр ... }
Сверьтесь с документацией по клиентской библиотеки для получения большей информации о различных опциях.
Смотрите также connectOptions().
Устанавливает name как имя базы данных для соединения. Чтобы получить эффект, имя базы данных должно быть установлено перед тем, как соединение будет открыто opened. В качестве альтернативы, вы можете закрыть соединение (close()), установить имя базы данных и снова вызвать open(). Замечание: Имя базы данных - не имя соединения. Имя соединения должно быть передано в addDatabase() во время создания объекта соединения.
Для драйвера QOCI (Oracle) имя базы данных - это TNS Service Name.
Для драйвера QODBC, name может быть DSN, имя файла DSN (в это случае файл должен иметь расширение .dsn) или строкой соединения.
Например, пользователи Microsoft Access могут использовать вместо создания DSN записи в менеджере ODBC следующую строку соединения для открытия непосредственно файлов .mdb:
...
db = QSqlDatabase::addDatabase("QODBC");
db.setDatabaseName("DRIVER={Microsoft Access Driver (*.mdb)};FIL={MS Access};DBQ=myaccessfile.mdb");
if (db.open()) {
// успех!
}
...
У этого параметра нет значения по умолчанию.
Смотрите также databaseName(), setUserName(), setPassword(), setHostName(), setPort(), setConnectOptions() и open().
Устанавливает host как имя узла соединения. Чтобы получить эффект, имя узла должно быть установлено перед тем, как соединение будет открыто opened. В качестве альтернативы, вы можете закрыть соединение (close()), установить имя узла и снова вызвать open().
У этого параметра нет значения по умолчанию.
Смотрите также hostName(), setUserName(), setPassword(), setDatabaseName(), setPort(), setConnectOptions() и open().
Устанавливает password как пароль соединения. Чтобы получить эффект, пароль должен быть установлен перед тем, как соединение будет открыто opened. В качестве альтернативы, вы можете закрыть соединение (close()), установить пароль и снова вызвать open().
У этого параметра нет значения по умолчанию.
Внимание: Эта функция сохраняет пароль в виде простого текста внутри Qt. Используйте open() для получения пароля в виде параметра, не зависящего от его поведения.
Смотрите также password(), setUserName(), setDatabaseName(), setHostName(), setPort(), setConnectOptions() и open().
Устанавливает порт соединения как port. Чтобы получить эффект, номер порта должен быть установлен перед тем, как соединение будет открыто. В качестве альтернативы, вы можете закрыть соединение (close()), установить номер порта и снова вызвать open().
У этого параметра нет значения по умолчанию.
Смотрите также port(), setUserName(), setPassword(), setHostName(), setDatabaseName(), setConnectOptions() и open().
Устанавливает name как имя пользователя для соединения с базой данных. Чтобы получить эффект, имя пользователя должно быть установлено перед тем, как соединение будет открыто opened. В качестве альтернативы, вы можете закрыть соединение (close()), установить имя пользователя и снова вызвать open().
У этого параметра нет значения по умолчанию.
Смотрите также userName(), setDatabaseName(), setPassword(), setHostName(), setPort(), setConnectOptions() и open().
Возвращает список таблиц, системных таблиц и представлений базы данных, заданной в параметре type.
Смотрите также primaryIndex() и record().
Начинает транзакцию при работе с базой данных, если драйвер их поддерживает. Возвращает true с случае успеха операции. В противном случае возвращает false.
Смотрите также QSqlDriver::hasFeature(), commit() и rollback().
Возвращает имя пользователя для соединения; может быть пустым.
Смотрите также setUserName().
Ассоциирует other с текущим объектом.
Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies) | Торговые марки | Qt 4.5.3 |