Материал из 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.