QSqlDatabase Class

Documentación de funciones miembro

QSqlDatabase::QSqlDatabase()

Crea un objeto QSqlDatabase vacío e inválido. Utilice addDatabase(), removeDatabase() y database() para obtener objetos QSqlDatabase válidos.

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

Crea una conexión a una base de datos utilizando la dirección driver.

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

Crea una conexión QSqlDatabase que utiliza el controlador referenciado por type. Si no se reconoce el type, la conexión a la base de datos no tendrá ninguna funcionalidad.

Los tipos de controladores disponibles actualmente son:

Controladores adicionales de terceros, incluyendo sus propios controladores personalizados, pueden ser cargados dinámicamente.

Véase también Controladores de bases de datos SQL, registerSqlDriver(), y drivers().

QSqlDatabase::QSqlDatabase(const QSqlDatabase &other)

Crea una copia de other.

[noexcept] QSqlDatabase::~QSqlDatabase()

Destruye el objeto y libera los recursos asignados.

Véase también close().

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

Añade una base de datos a la lista de conexiones de bases de datos utilizando el controlador type y el nombre de conexión connectionName. Si ya existe una conexión de base de datos llamada connectionName, dicha conexión se elimina.

Se hace referencia a la conexión de base de datos mediante connectionName. Se devuelve la nueva conexión de base de datos añadida.

Si type no está disponible o no se ha podido cargar, isValid() devuelve false.

Si no se especifica connectionName, la nueva conexión se convierte en la conexión por defecto de la aplicación, y las siguientes llamadas a database() sin el argumento del nombre de la conexión devolverán la conexión por defecto. Si se proporciona un connectionName aquí, utilice database(connectionName) para recuperar la conexión.

Antes de utilizar la conexión, ésta debe ser inicializada. Por ejemplo, llame a algunas o todas las funciones setDatabaseName(), setUserName(), setPassword(), setHostName(), setPort(), y setConnectOptions(), y, finalmente, open().

Nota: Esta función es thread-safe.

Véase también database(), removeDatabase(), y Threads and the SQL Module.

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

Esta sobrecarga es útil cuando quieres crear una conexión a una base de datos con un driver instanciado por ti mismo. Puede ser tu propio controlador de base de datos, o puede que sólo necesites instanciar uno de los controladores de Qt. Si haces esto, es recomendable que incluyas el código del driver en tu aplicación. Por ejemplo, puede crear una conexión PostgreSQL con su propio controlador QPSQL de esta manera:

PGconn *con = PQconnectdb("host=server user=bart password=simpson dbname=springfield");
QPSQLDriver *drv = new QPSQLDriver(con);
QSqlDatabase db = QSqlDatabase::addDatabase(drv); // becomes the new default connection
QSqlQuery query;
query.exec("SELECT NAME, ID FROM STAFF");

El código anterior establece una conexión PostgreSQL e instancia un objeto QPSQLDriver. Luego, se llama a addDatabase() para agregar la conexión a las conexiones conocidas para que pueda ser usada por las clases Qt SQL. Cuando se instancia un controlador con un manejador de conexión (o conjunto de manejadores), Qt asume que ya se ha abierto la conexión a la base de datos.

Recuerde que debe enlazar su aplicación con la librería cliente de la base de datos. Asegúrate de que la librería cliente está en la ruta de búsqueda de tu enlazador, y añade líneas como estas a tu archivo .pro:

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

El método descrito funciona para todos los controladores suministrados. La única diferencia estará en los argumentos del constructor del controlador. Aquí hay una tabla de los controladores incluidos con Qt, sus archivos de código fuente, y sus argumentos constructores:

Véase también drivers().

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

Clona la conexión a la base de datos other y la almacena como connectionName. Todas las configuraciones de la base de datos original, por ejemplo databaseName(), hostName(), etc., se copian. No hace nada si other es una base de datos inválida. Devuelve la conexión a la base de datos recién creada.

Nota: Esta función es reentrante.

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

Clona la conexión a la base de datos other y la almacena como connectionName. Todas las configuraciones de la base de datos original, por ejemplo databaseName(), hostName(), etc., se copian. No hace nada si other es una base de datos inválida. Devuelve la conexión a la base de datos recién creada.

Esta sobrecarga es útil cuando se clona la base de datos en otro hilo al que utiliza la base de datos representada por other.

void QSqlDatabase::close()

Cierra la conexión a la base de datos, liberando cualquier recurso adquirido e invalidando cualquier objeto QSqlQuery existente que se utilice con la base de datos.

Esto también afectará a las copias de este objeto QSqlDatabase.

Véase también removeDatabase().

bool QSqlDatabase::commit()

Consigna una transacción en la base de datos si el controlador admite transacciones y se ha iniciado una transaction(). Devuelve true si la operación ha tenido éxito. En caso contrario, devuelve false.

Llame a lastError() para obtener información sobre errores.

Véase también QSqlQuery::isActive(), QSqlDriver::hasFeature(), y rollback().

QString QSqlDatabase::connectOptions() const

Devuelve la cadena de opciones de conexión utilizada para esta conexión. La cadena puede estar vacía.

Véase también setConnectOptions().

QString QSqlDatabase::connectionName() const

Devuelve el nombre de la conexión, que puede estar vacío.

Véase también addDatabase().

[static] QStringList QSqlDatabase::connectionNames()

Devuelve una lista con los nombres de todas las conexiones.

Nota: Esta función es segura para hilos.

Véase también contains(), database(), y Threads and the SQL Module.

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

Devuelve true si la lista de conexiones a la base de datos contiene connectionName; en caso contrario devuelve false.

Nota: Esta función es segura para hilos.

Véase también connectionNames(), database(), y Threads and the SQL Module.

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

Devuelve la conexión a la base de datos llamada connectionName. La conexión a la base de datos debe haberse añadido previamente con addDatabase(). Si open es verdadero (por defecto) y la conexión a la base de datos no está ya abierta, se abrirá ahora. Si no se especifica connectionName se utiliza la conexión por defecto. Si connectionName no existe en la lista de bases de datos, se devuelve una conexión inválida.

Nota: Esta función es segura para hilos.

Ver también isOpen() y Threads and the SQL Module.

QString QSqlDatabase::databaseName() const

Devuelve el nombre de la base de datos de la conexión, que puede estar vacío.

Véase también setDatabaseName().

QSqlDriver *QSqlDatabase::driver() const

Devuelve el controlador de base de datos utilizado para acceder a la conexión de base de datos.

Véase también addDatabase() y drivers().

QString QSqlDatabase::driverName() const

Devuelve el nombre del controlador de la conexión.

Véase también addDatabase() y driver().

[static] QStringList QSqlDatabase::drivers()

Devuelve una lista de todos los controladores de bases de datos disponibles.

Véase también registerSqlDriver().

QString QSqlDatabase::hostName() const

Devuelve el nombre de host de la conexión; puede estar vacío.

Véase también setHostName().

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

Devuelve true si hay disponible un controlador llamado name; en caso contrario devuelve false.

Véase también drivers().

bool QSqlDatabase::isOpen() const

Devuelve true si la conexión a la base de datos está actualmente abierta; en caso contrario devuelve false.

bool QSqlDatabase::isOpenError() const

Devuelve true si se ha producido un error al abrir la conexión a la base de datos; en caso contrario, devuelve false. La información de error puede recuperarse utilizando la función lastError().

bool QSqlDatabase::isValid() const

Devuelve true si QSqlDatabase tiene un controlador válido.

Ejemplo:

QSqlDatabase db;qDebug() << db.isValid();    // Returns false

db = QSqlDatabase::base de datos("ventas");qDebug() << db.isValid();    // Returns \c true if "sales" connection exists

QSqlDatabase::removeDatabase("ventas");qDebug() << db.isValid();    // Returns false

QSqlError QSqlDatabase::lastError() const

Devuelve información sobre el último error que se ha producido en la base de datos.

Los fallos que se producen junto con una consulta individual se notifican mediante QSqlQuery::lastError().

Véase también QSqlError y QSqlQuery::lastError().

[since 6.8] bool QSqlDatabase::moveToThread(QThread *targetThread)

Cambia la afinidad de hilos para QSqlDatabase y su controlador asociado. Esta función devuelve true cuando la función tiene éxito. El procesamiento de eventos continuará en targetThread.

Durante esta operación hay que asegurarse de que no hay ningún QSqlQuery vinculado a esta instancia, de lo contrario el QSqlDatabase no se moverá al hilo dado y la función devuelve false.

Dado que el controlador asociado se deriva de QObject, todas las restricciones para mover un QObject a otro hilo también se aplican a esta función.

Esta función se introdujo en Qt 6.8.

Véase también QObject::moveToThread() y Threads and the SQL Module.

QSql::NumericalPrecisionPolicy QSqlDatabase::numericalPrecisionPolicy() const

Devuelve la numericalPrecisionPolicy.

Véase también setNumericalPrecisionPolicy().

bool QSqlDatabase::open()

Abre la conexión a la base de datos utilizando los valores de conexión actuales. Devuelve true en caso de éxito; en caso contrario devuelve false. La información de error puede recuperarse utilizando lastError().

Véase también lastError(), setDatabaseName(), setUserName(), setPassword(), setHostName(), setPort() y setConnectOptions().

bool QSqlDatabase::open(const QString &user, const QString &password)

Abre la conexión a la base de datos utilizando el nombre user y password. Devuelve true en caso de éxito; en caso contrario devuelve false. La información de error puede recuperarse utilizando la función lastError().

Esta función no almacena la contraseña que se le proporciona. En su lugar, la contraseña se pasa directamente al controlador para abrir la conexión y luego se descarta.

Véase también lastError().

QString QSqlDatabase::password() const

Devuelve la contraseña de la conexión. Se devolverá una cadena vacía si la contraseña no se estableció con setPassword(), y si la contraseña se proporcionó en la llamada a open(), o si no se utilizó ninguna contraseña.

Véase también setPassword().

int QSqlDatabase::port() const

Devuelve el número de puerto de la conexión. El valor es indefinido si no se ha establecido el número de puerto.

Véase también setPort().

QSqlIndex QSqlDatabase::primaryIndex(const QString &tablename) const

Devuelve el índice primario de la tabla tablename. Si no existe un índice primario, se devuelve un QSqlIndex vacío.

Véase también tables() y record().

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

Devuelve un QSqlRecord poblado con los nombres de todos los campos de la tabla (o vista) llamada tablename. El orden en que aparecen los campos en el registro no está definido. Si no existe tal tabla (o vista), se devuelve un registro vacío.

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

Esta función registra un nuevo controlador SQL llamado name, dentro del marco SQL. Esto es útil si tienes un controlador SQL personalizado y no quieres compilarlo como un plugin.

Ejemplo:

QSqlDatabase::registerSqlDriver("MYDRIVER", new QSqlDriverCreator<QSqlDriver>);
QVERIFY(QSqlDatabase::drivers().contains("MYDRIVER"));
QSqlDatabase db = QSqlDatabase::addDatabase("MYDRIVER");
QVERIFY(db.isValid());

QSqlDatabase toma posesión del puntero creator, por lo que no debe borrarlo usted mismo.

Ver también drivers().

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

Elimina la conexión de base de datos connectionName de la lista de conexiones de base de datos.

Ejemplo:

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

La forma correcta de hacerlo:

{
    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

Para eliminar la conexión por defecto, que puede haber sido creada con una llamada a addDatabase() sin especificar un nombre de conexión, puede recuperar el nombre de conexión por defecto llamando a connectionName() sobre la base de datos devuelta por database(). Tenga en cuenta que si no se ha creado una base de datos por defecto, se devolverá una base de datos inválida.

Nota: Esta función es thread-safe.

Ver también database(), connectionName(), y Threads and the SQL Module.

bool QSqlDatabase::rollback()

Revierte una transacción en la base de datos, si el controlador admite transacciones y se ha iniciado una transaction(). Devuelve true si la operación ha tenido éxito. En caso contrario, devuelve false.

Llame a lastError() para obtener información sobre errores.

Véase también QSqlQuery::isActive(), QSqlDriver::hasFeature(), y commit().

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

Establece options específico de la base de datos. Esto debe hacerse antes de abrir la conexión, de lo contrario no tiene efecto. Otra posibilidad es cerrar la conexión, llamar a QSqlDatabase::setConnectOptions(), y open() la conexión de nuevo.

El formato de la cadena options es una lista separada por punto y coma de nombres de opciones o pares opción=valor. Las opciones dependen del cliente de base de datos utilizado y se describen para cada complemento en la página Controladores de bases de datos SQL.

Ejemplos:

db.setConnectOptions("SSL_KEY=client-key.pem;SSL_CERT=client-cert.pem;SSL_CA=ca-cert.pem;CLIENT_IGNORE_SPACE=1"); // use an SSL connection to the server
if (!db.open()) {
    db.setConnectOptions(); // clears the connect option string
    // ...
}
// ...
// PostgreSQL connection
db.setConnectOptions("requiressl=1"); // enable PostgreSQL SSL connections
if (!db.open()) {
    db.setConnectOptions(); // clear options
    // ...
}
// ...
// ODBC connection
db.setConnectOptions("SQL_ATTR_ACCESS_MODE=SQL_MODE_READ_ONLY;SQL_ATTR_TRACE=SQL_OPT_TRACE_ON"); // set ODBC options
if (!db.open()) {
    db.setConnectOptions(); // don't try to set this option
    // ...
}
}

Consulte la documentación de la biblioteca cliente para obtener más información sobre las distintas opciones.

Véase también connectOptions().

void QSqlDatabase::setDatabaseName(const QString &name)

Establece el nombre de la base de datos de la conexión en name. Para que tenga efecto, el nombre de la base de datos debe establecerse antes de que la conexión sea opened. Como alternativa, puede close() la conexión, establecer el nombre de la base de datos y volver a llamar a open().

Para el controlador QSQLITE, si el nombre de la base de datos especificado no existe, entonces creará el archivo por usted a menos que la opción QSQLITE_OPEN_READONLY esté establecida.

Además, name se puede establecer en ":memory:" que creará una base de datos temporal que sólo estará disponible durante el tiempo de vida de la aplicación.

Para el controlador QOCI (Oracle), el nombre de la base de datos es el nombre del servicio TNS.

Para el controlador QODBC, name puede ser un DSN, un nombre de archivo DSN (en cuyo caso el archivo debe tener una extensión .dsn ) o una cadena de conexión.

Por ejemplo, los usuarios de Microsoft Access pueden utilizar la siguiente cadena de conexión para abrir directamente un archivo .mdb, en lugar de tener que crear una entrada DSN en el gestor ODBC:

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

No hay ningún valor por defecto.

Véase también databaseName(), setUserName(), setPassword(), setHostName(), setPort(), setConnectOptions() y open().

void QSqlDatabase::setHostName(const QString &host)

Establece el nombre de host de la conexión en host. Para que tenga efecto, el nombre de host debe establecerse antes de que la conexión sea opened. Alternativamente, puede close() la conexión, establecer el nombre de host, y llamar a open() de nuevo.

No existe un valor por defecto.

Véase también hostName(), setUserName(), setPassword(), setDatabaseName(), setPort(), setConnectOptions() y open().

void QSqlDatabase::setNumericalPrecisionPolicy(QSql::NumericalPrecisionPolicy precisionPolicy)

Establece numericalPrecisionPolicy en precisionPolicy.

Véase también numericalPrecisionPolicy().

void QSqlDatabase::setPassword(const QString &password)

Establece la contraseña de la conexión en password. Para que tenga efecto, la contraseña debe establecerse antes de que la conexión se opened. Como alternativa, puede close() la conexión, establecer la contraseña y volver a llamar a open().

No existe un valor por defecto.

Ver también password(), setUserName(), setDatabaseName(), setHostName(), setPort(), setConnectOptions(), y open().

void QSqlDatabase::setPort(int port)

Establece el número de puerto de la conexión en port. Para que tenga efecto, el número de puerto debe establecerse antes de que la conexión sea opened. Alternativamente, puede close() la conexión, establecer el número de puerto, y llamar a open() de nuevo..

No hay valor por defecto.

Véase también port(), setUserName(), setPassword(), setHostName(), setDatabaseName(), setConnectOptions() y open().

void QSqlDatabase::setUserName(const QString &name)

Establece el nombre de usuario de la conexión en name. Para que tenga efecto, el nombre de usuario debe establecerse antes de que la conexión sea opened. Como alternativa, puede close() la conexión, establecer el nombre de usuario y volver a llamar a open().

No existe un valor por defecto.

Véase también userName(), setDatabaseName(), setPassword(), setHostName(), setPort(), setConnectOptions() y open().

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

Devuelve una lista de las tablas, tablas de sistema y vistas de la base de datos, tal como se especifica en el parámetro type.

Véase también primaryIndex() y record().

[since 6.8] QThread *QSqlDatabase::thread() const

Devuelve un puntero a la instancia QThread asociada.

Esta función se introdujo en Qt 6.8.

bool QSqlDatabase::transaction()

Inicia una transacción en la base de datos si el controlador soporta transacciones. Devuelve true si la operación ha tenido éxito. En caso contrario devuelve false.

Véase también QSqlDriver::hasFeature(), commit(), y rollback().

QString QSqlDatabase::userName() const

Devuelve el nombre de usuario de la conexión; puede estar vacío.

Véase también setUserName().

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

Asigna other a este objeto.