Материал из Wiki.crossplatform.ru

Внимание: Актуальная версия перевода документации находится здесь

__NOTOC__

Описание класса 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 и Потоки и Модуль QtSql.

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

QSqlDatabase::QSqlDatabase ()

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

QSqlDatabase::QSqlDatabase ( const QSqlDatabase & other )

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

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

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

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

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

Смотрите также Драйвера баз данных SQL, 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]

Clones the database connection other and and stores it as connectionName. All the settings from the original database, e.g. databaseName(), hostName(), etc., are copied across. Does nothing if other is an invalid database. Returns the newly created database connection.

Note that the connection is not opened, to use it, it is necessary to call open() first.

void QSqlDatabase::close ()

Closes the database connection, freeing any resources acquired, and invalidating any existing QSqlQuery objects that are used with the database.

This will also affect copies of this QSqlDatabase object.

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

bool QSqlDatabase::commit ()

Commits a transaction to the database if the driver supports transactions and a transaction() has been started. Returns true if the operation succeeded; otherwise returns false.

Note that on some databases, this function will not work if there is an active QSqlQuery on the database. Use the lastError() function to retrieve database-specific error data about the error that occurred.

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

QString QSqlDatabase::connectOptions () const

Returns the connection options string used for this connection. The string may be empty.

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

QStringList QSqlDatabase::connectionNames () [static]

Returns a list containing the names of all connections.

Note: This function is thread-safe.

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

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

Returns true if the list of database connections contains connectionName; otherwise returns false.

Note: This function is thread-safe.

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

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

Returns the database connection called connectionName. The database connection must have been previously added with addDatabase(). If open is true (the default) and the database connection is not already open it is opened now. If no connectionName is specified the default connection is used. If connectionName does not exist in the list of databases, an invalid connection is returned.

Note: This function is thread-safe.

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

QString QSqlDatabase::databaseName () const

Returns the connection's database name; it may be empty.

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

QSqlDriver * QSqlDatabase::driver () const

Returns the database driver used to access the database connection.

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

QString QSqlDatabase::driverName () const

Returns the connection's driver name.

Смотрите также addDatabase() and driver().

QStringList QSqlDatabase::drivers () [static]

Returns a list of all the available database drivers.

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

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

Executes a SQL statement on the database and returns a QSqlQuery object. Use lastError() to retrieve error information. If query is empty, an empty, invalid query is returned and lastError() is not affected.

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

QString QSqlDatabase::hostName () const

Returns the connection's host name. It may be empty.

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

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

Returns true if a driver called name is available; otherwise returns false.

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

bool QSqlDatabase::isOpen () const

Returns true if the database connection is currently open; otherwise returns false.

bool QSqlDatabase::isOpenError () const

Returns true if there was an error opening the database connection; otherwise returns false. Error information can be retrieved using the lastError() function.

bool QSqlDatabase::isValid () const

Returns true if the QSqlDatabase has a valid driver.

Example:

 QSqlDatabase db;
 qDebug() << db.isValid();    // Returns false
 
 db = QSqlDatabase::database("sales");
 qDebug() << db.isValid();    // Returns true if "sales" connection exists
 
 QSqlDatabase::removeDatabase("sales");
 qDebug() << db.isValid();    // Returns false

QSqlError QSqlDatabase::lastError () const

Returns information about the last error that occurred on the database.

Failures that occur in conjunction with an individual query are reported by 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

Returns the primary index for table tablename. If no primary index exists an empty QSqlIndex is returned.

Смотрите также tables() and record().

QSqlRecord QSqlDatabase::record ( const QString & tablename ) const

Returns a QSqlRecord populated with the names of all the fields in the table (or view) called tablename. The order in which the fields appear in the record is undefined. If no such table (or view) exists, an empty record is returned.

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

This function registers a new SQL driver called name, within the SQL framework. This is useful if you have a custom SQL driver and don't want to compile it as a plugin.

Example:

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

QSqlDatabase takes ownership of the creator pointer, so you mustn't delete it yourself.

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

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

Removes the database connection connectionName from the list of database connections.

Warning: There should be no open queries on the database connection when this function is called, otherwise a resource leak will occur.

Example:

 // 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

The correct way to do it:

 {
     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

Note: This function is thread-safe.

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

bool QSqlDatabase::rollback ()

Rolls a transaction back on the database if the driver supports transactions and a transaction() has been started. Returns true if the operation succeeded; otherwise returns false.

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

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

Sets database-specific options. This must be done before the connection is opened or it has no effect (or you can close() the connection, call this function and open() the connection again).

The format of the options string is a semicolon separated list of option names or option=value pairs. The options depend on the database client used:

Примеры:

 ...
 // MySQL connection
 db.setConnectOptions("CLIENT_SSL=1;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
     ...
 }

Refer to the client library documentation for more information about the different options.

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

void QSqlDatabase::setDatabaseName ( const QString & name )

Sets the connection's name to name. This must be done before the connection is opened or it has no effect; (or you can close() the connection, call this function and open() the connection again). The name is database-specific.

For the QOCI (Oracle) driver, the database name is the TNS Service Name.

For the QODBC driver, the name can either be a DSN, a DSN filename (in which case the file must have a .dsn extension), or a connection string.

For example, Microsoft Access users can use the following connection string to open an .mdb file directly, instead of having to create a DSN entry in the ODBC manager:

 ...
 db = QSqlDatabase::addDatabase("QODBC");
 db.setDatabaseName("DRIVER={Microsoft Access Driver (*.mdb)};FIL={MS Access};DBQ=myaccessfile.mdb");
 if (db.open()) {
     // success!
 }
 ...

There is no default value.

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

void QSqlDatabase::setHostName ( const QString & host )

Sets the connection's host name to host. This must be done before the connection is opened or it has no effect (or you can close() the connection, call this function and open() the connection again).

There is no default value.

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

void QSqlDatabase::setPassword ( const QString & password )

Sets the connection's password to password. This must be done before the connection is opened or it has no effect (or you can close() the connection, call this function and open() the connection again).

There is no default value.

Warning: This function stores the password in plain text within Qt. Use the open() call that takes a password as parameter to avoid this behavior.

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

void QSqlDatabase::setPort ( int port )

Sets the connection's port number to port. This must be done before the connection is opened or it has no effect (or you can close() the connection, call this function and open() the connection again).

There is no default value.

setDatabaseName() setConnectOptions() open()

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

void QSqlDatabase::setUserName ( const QString & name )

Sets the connection's user name to name. This must be done before the connection is opened or it has no effect (or you can close() the connection, call this function and open() the connection again).

There is no default value.

setPort() setConnectOptions() open()

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

QStringList QSqlDatabase::tables ( QSql::TableType type = QSql::Tables ) const

Returns a list of the database's tables, system tables and views, as specified by the parameter type.

Смотрите также primaryIndex() and record().

bool QSqlDatabase::transaction ()

Begins a transaction on the database if the driver supports transactions. Returns true if the operation succeeded; otherwise returns false.

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

QString QSqlDatabase::userName () const

Возвращает имя пользователя для соединения , может вернуть пустую строку.

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

QSqlDatabase & QSqlDatabase::operator= ( const QSqlDatabase & other )

Assigns other to this object.