Главная · Все классы · Основные классы · Классы по группам · Модули · Функции

Описание класса QSqlDatabase
^{[модуль QtSql]}

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

 #include <QSqlDatabase>

• Список всех членов, включая унаследованные
• Поддерживаемые члены Qt 3

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

• QSqlDatabase ()
• QSqlDatabase ( const QSqlDatabase & other )
• ~QSqlDatabase ()
• void close ()
• bool commit ()
• QString connectOptions () const
• QString databaseName () const
• QSqlDriver * driver () const
• QString driverName () const
• QSqlQuery exec ( const QString & query = QString() ) const
• QString hostName () const
• bool isOpen () const
• bool isOpenError () const
• bool isValid () const
• QSqlError lastError () const
• bool open ()
• bool open ( const QString & user, const QString & password )
• QString password () const
• int port () const
• QSqlIndex primaryIndex ( const QString & tablename ) const
• QSqlRecord record ( const QString & tablename ) const
• bool rollback ()
• void setConnectOptions ( const QString & options = QString() )
• void setDatabaseName ( const QString & name )
• void setHostName ( const QString & host )
• void setPassword ( const QString & password )
• void setPort ( int port )
• void setUserName ( const QString & name )
• QStringList tables ( QSql::TableType type = QSql::Tables ) const
• bool transaction ()
• QString userName () const
• QSqlDatabase & operator= ( const QSqlDatabase & other )

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

• QSqlDatabase addDatabase ( const QString & type, const QString & connectionName = QLatin1String( defaultConnection ) )
• QSqlDatabase addDatabase ( QSqlDriver * driver, const QString & connectionName = QLatin1String( defaultConnection ) )
• QSqlDatabase cloneDatabase ( const QSqlDatabase & other, const QString & connectionName )
• QStringList connectionNames ()
• bool contains ( const QString & connectionName = QLatin1String( defaultConnection ) )
• QSqlDatabase database ( const QString & connectionName = QLatin1String( defaultConnection ), bool open = true )
• QStringList drivers ()
• bool isDriverAvailable ( const QString & name )
• void registerSqlDriver ( const QString & name, QSqlDriverCreatorBase * creator )
• void removeDatabase ( const QString & connectionName )

Защищенные функции

• QSqlDatabase ( const QString & type )
• QSqlDatabase ( QSqlDriver * driver )

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

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

Класс QSqlDatabase предоставляет абстрактный интерфейс для доступа к базе данных. Он использует специальный QSqlDriver базы данных для доступа и манипуляции данными.

В следующем коде показано как установить соединение:

     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() для открытия соединения.

Соединение определеное выше - безымянное соединение. Оно определено по умолчанию, и доступ к нему может быть получен позже, используя database():

     QSqlDatabase db = QSqlDatabase::database();

Чтобы сделать програмирование более удобным, QSqlDatabase реализован как класс-значение (англ. "value class"). Любые изменения, сделаные в соединении с базой данных через один объект QSqlDatabase, будут влиять на другие объекты QSqlDatabase, представляющие это же соединение. Вызовите cloneDatabase(), если вы хотите создать независимое соединение с базой данных на основе существующего.

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

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

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

Если произошла ошибка, она может быть получена посредством lastError().

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

Смотрите также QSqlDriver, QSqlQuery, QtSql Module и Threads and the SQL Module.

Описание функций-членов

QSqlDatabase::QSqlDatabase ()

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

QSqlDatabase::QSqlDatabase ( const QSqlDatabase & other )

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

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

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

На текущий момент доступны следующие типы драйверов:

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

Смотрите также SQL Database Drivers, registerSqlDriver() и drivers().

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

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

QSqlDatabase::~QSqlDatabase ()

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

Если QSqlDatabase является последним, то соединение с базой данных автоматически закрывается.

Смотрите также close().

QSqlDatabase QSqlDatabase::addDatabase ( const QString & type, const QString & connectionName = QLatin1String( defaultConnection ) )   [static]

Добавляет базу данных в список соединений баз данных используя драйвер type и имя соединения connectionName. Если уже существует соединение с базой данных, называющееся connectionName, оно удаляется.

Соединения с базой данных в дальнейшем именуется connectionName. Будет возвращено вновь добавленое соединение.

Если connectionName не определено, вновь добавленное соединение становится для приложения соединением по умолчанию, и последующие вызовы database() без параметра вернут ссылку на него. Если connectionName задано, используйте его при вызове той функции database(connectionName), чтобы вернуть указатель на соединение.

Внимание: если вы добавите базу данных с тем же именем, как и у существующей, старая БД будет заменена новой. Это происходит автоматически, если вы вызываете данную функцию больше, чем один раз, без указания connectionName.

Чтобы использовать соединение, вам нужно настроить его, например, вызвав некоторые или все из фунций setDatabaseName(), setUserName(), setPassword(), setHostName(), setPort() и setConnectOptions(), а затем вам нужно открыть соединение с помощью open().

Примечание: эта функция потокобезопасна.

Смотрите также database(), removeDatabase() и Потоки и SQL модуль.

QSqlDatabase QSqlDatabase::addDatabase ( QSqlDriver * driver, const QString & connectionName = QLatin1String( defaultConnection ) )   [static]

Эта перегруженная функция, предоставленная для удобства.

Эта функция полезна, если вам необходимо установить соединение и создать экземпляр самого драйвера. Если вы делаете это, то рекомендуем вам включить код драйвера в ваше собственное приложение. Например, настройка собственного соединения PostgreSQL и экземпляра драйвера QPSQL может быть сделана следующим образом:

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

(Мы допускаем, что qtdir является папкой установки Qt.) Это будет подключать код, который нужно использовать клиентской библиотеке PostgreSQL и создавать экземпляр объекта QPSQLDriver, если предположить, что у вас есть заголочные файлы PostgreSQL где-нибудь по вашему пути поиска.

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

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

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

Вы должны будете иметь клиентскую библиотеку в пути поиска своего компоновщика.

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

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

Внимание: если вы добавите базу данных с тем же именем, как и у существующей, старая БД будет заменена новой.

Внимание: SQL инструментария (framework) становится владельцем указателя на driver, и он не должен удалятся. Если вы хотите явно удалить подключение, используйте removeDatabase().

Смотрите также drivers().

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

Клонирует соединение с БД other и сохраняет копию с именем connectionName. Все настройки исходной БД, такие как databaseName(), hostName() и т.д., дублируются. Если other является некорректным, то ничего не происходит. Будет возвращено вновь добавленое соединение.

Помните, что соединение будет неоткрытым, чтобы это исправить, используйте open().

void QSqlDatabase::close ()

Закрывает соединения с БД, освобождает занятые ресурсы и отменяет все текущие запросы QSqlQuery.

Это сработает для всех копий объекта QSqlDatabase.

Смотрите также removeDatabase().

bool QSqlDatabase::commit ()

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

Помните, что для некоторых баз данных эта функция не будет работать, если нет активной QSqlQuery. Используйте lastError() для получения спецфичной для БД информации о произошедших ошибках.

Смотрите также QSqlDriver::hasFeature() и rollback().

QString QSqlDatabase::connectOptions () const

Возвращает строку используемых опций соединения. Эта строка может быть пустой.

Смотрите также setConnectOptions().

QStringList QSqlDatabase::connectionNames ()   [static]

Возвращает список, содержащий имена всех соединений.

Примечание: эта функция потокобезопасна.

Смотрите также contains(), database() и Потоки и SQL модуль.

bool QSqlDatabase::contains ( const QString & connectionName = QLatin1String( defaultConnection ) )   [static]

Возвращает true, если список соедниней содержит одно с именем connectionName; в противном случае возвращает false.

Примечание: эта функция потокобезопасна.

Смотирте также connectionNames(), database() и Threads and the SQL Module.

QSqlDatabase QSqlDatabase::database ( const QString & connectionName = QLatin1String( defaultConnection ), bool open = true )   [static]

Возвращает соединение с БД с именем 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().

QStringList QSqlDatabase::drivers ()   [static]

Возвращает список доступных драйверов БД.

Смотрите также registerSqlDriver().

QSqlQuery QSqlDatabase::exec ( const QString & query = QString() ) const

Применяет SQL запрос к БД и возвращает объект QSqlQuery. Используйте lastError() для получения информации об ошибках. Если query является пустым, соответственно, пустой, неправильный запрос будет возвращён и lastError() не будет задействован.

Смотрите также QSqlQuery и lastError().

QString QSqlDatabase::hostName () const

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

Смотрите также setHostName().

bool QSqlDatabase::isDriverAvailable ( const QString & name )   [static]

Возвращает 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();    // Возвращает false

 db = QSqlDatabase::database("sales");
 qDebug() << db.isValid();    // Возвращает true, если создано соединение "sales"

 QSqlDatabase::removeDatabase("sales");
 qDebug() << db.isValid();    // Возвращает false

QSqlError QSqlDatabase::lastError () const

Возвращает информацию о последней случившейся при работе с БД ошибке.

При помощи QSqlQuery::lastError() можно узнать о неудавшихся попытках связывания и отдельных запросов.

Смотирте также QSqlError и QSqlQuery::lastError().

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. Порядок, в котором поля будут представлены, не определён. Если указанной таблицы (или представления) не существует, созаращается пустая запись (record).

void QSqlDatabase::registerSqlDriver ( const QString & name, QSqlDriverCreatorBase * creator )   [static]

Эта функция регистрирует новый SQL драйвер под именем name внутри SQL инструментария (framework). Это используется для пользовательских SQL драйверов, которые не компилируются как плагин (plugin).

Пример:

 QSqlDatabase::registerSqlDriver("MYDRIVER",
                                 new QSqlDriverCreator<MyDatabaseDriver>);
 QSqlDatabase db = QSqlDatabase::addDatabase("MYDRIVER");

QSqlDatabase берёт на себя управление указателем на creator, потому вы не должны беспокоиться о его удалении.

Смотрите также drivers().

void QSqlDatabase::removeDatabase ( const QString & connectionName )   [static]

Убирает соединение 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"); // правильно

Примечание: эта функция потокобезопасна.

Смотрите также database() и Потоки и SQL модуль.

bool QSqlDatabase::rollback ()

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

Смотрите также QSqlDriver::hasFeature() и commit().

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

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

Формат строки options является списком имён или пар параметр=значение (option=value), разделённых точкой с запятой. В зависимости от БД используются следующие опции:

Примеры:

 ...
 // соденинение MySQL
 db.setConnectOptions("CLIENT_SSL=1;CLIENT_IGNORE_SPACE=1"); // используйте SSL соединение
 if (!db.open()) {
     db.setConnectOptions(); // очищает список параметров
     ...
 }
 ...
 // PostgreSQL connection
 db.setConnectOptions("requiressl=1"); // включает PostgreSQL SSL соединения
 if (!db.open()) {
     db.setConnectOptions(); // очищаем список параметров
     ...
 }
 ...
 // 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().

void QSqlDatabase::setDatabaseName ( const QString & name )

Устанавливает name в качестве имени соединения. Это должно быть сделано до того, как произойдёт соединение с БД, иначе оно не будет работать (или вы можете закрыть соединение с помощью close(), вызвать эту функцию, а затем open() для повтора соединения). Имя зависит от БД.

Для драйвера 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()) {
     // success!
 }
 ...

У этого параметра нет значения по умолчанию.

Смотрите также databaseName(), setUserName(), setPassword(), setHostName(), setPort(), setConnectOptions() и open().

void QSqlDatabase::setHostName ( const QString & host )

Устанавливает host как имя узла. Это должно быть сделано до того, как произойдёт соединение с БД, иначе оно не будет работать (или вы можете закрыть соединение с помощью close(), вызвать эту функцию, а затем open() для повтора соединения).

У этого параметра нет значения по умолчанию.

Смотрите также hostName(), setUserName(), setPassword(), setDatabaseName(), setPort(), setConnectOptions() и open().

void QSqlDatabase::setPassword ( const QString & password )

Устанавливает password как пароль соединения. Это должно быть сделано до того, как произойдёт соединение с БД, иначе оно не будет работать (или вы можете закрыть соединение с помощью close(), вызвать эту функцию, а затем open() для повтора соединения).

У этого параметра нет значения по умолчанию.

Внимание: эта функция хранит пароль в виде открытого текста внутри Qt. Используйте open() для получения пароля в виде параметра, не зависящего от его поведения.

Смотрите также password(), setUserName(), setDatabaseName(), setHostName(), setPort(), setConnectOptions() и open().

void QSqlDatabase::setPort ( int port )

Устанавливает порт соединения как port. Это должно быть сделано до того, как произойдёт соединение с БД, иначе оно не будет работать (или вы можете закрыть соединение с помощью close(), вызвать эту функцию, а затем open() для повтора соединения).

У этого параметра нет значения по умолчанию.

setDatabaseName() setConnectOptions() open()

Смотрите также port(), setUserName(), setPassword() и setHostName().

void QSqlDatabase::setUserName ( const QString & name )

Устанавливает name как имя пользователя для соединения с БД. Это должно быть сделано до того, как произойдёт соединение с БД, иначе оно не будет работать (или вы можете закрыть соединение с помощью close(), вызвать эту функцию, а затем open() для повтора соединения).

У этого параметра нет значения по умолчанию.

setPort() setConnectOptions() open()

Смотрите также userName(), setDatabaseName(), setPassword() и setHostName().

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 к данному объекту.