QSqlDatabase Class

멤버 함수 문서

QSqlDatabase::QSqlDatabase()

빈 상태의 유효하지 않은 QSqlDatabase 객체를 생성합니다. 유효한 QSqlDatabase 객체를 얻으려면 addDatabase(), removeDatabase() 및 database()을 사용하십시오.

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

지정된 driver 를 사용하여 데이터베이스 연결을 생성합니다.

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

type 에서 지정한 드라이버를 사용하는 QSqlDatabase 연결을 생성합니다. type 가 인식되지 않으면 데이터베이스 연결은 아무런 기능을 수행하지 못합니다.

현재 사용 가능한 드라이버 유형은 다음과 같습니다:

사용자 정의 드라이버를 포함한 추가적인 타사 드라이버를 동적으로 로드할 수 있습니다.

SQL 데이터베이스 드라이버, registerSqlDriver() 및 drivers()도 참조하십시오 .

QSqlDatabase::QSqlDatabase(const QSqlDatabase &other)

other 의 복사본을 생성합니다.

[noexcept] QSqlDatabase::~QSqlDatabase()

객체를 소멸시키고 할당된 자원을 모두 해제합니다.

close()도 참조하십시오 .

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

type 드라이버와 connectionName 연결 이름을 사용하여 데이터베이스 연결 목록에 데이터베이스를 추가합니다. connectionName 라는 데이터베이스 연결이 이미 존재하는 경우, 해당 연결은 제거됩니다.

데이터베이스 연결은 connectionName 로 참조됩니다. 새로 추가된 데이터베이스 연결이 반환됩니다.

type 을 사용할 수 없거나 로드할 수 없는 경우, isValid()은 false 을 반환합니다.

connectionName 가 지정되지 않은 경우, 새 연결이 애플리케이션의 기본 연결이 되며, 이후 연결 이름 인수를 지정하지 않고 database()를 호출하면 기본 연결이 반환됩니다. 여기서 connectionName 가 제공된 경우, database(connectionName)를 사용하여 연결을 가져오십시오.

연결을 사용하기 전에 반드시 초기화해야 합니다. 예를 들어, setDatabaseName(), setUserName(), setPassword(), setHostName(), setPort() 및 setConnectOptions() 중 일부 또는 전부를 호출한 후, 마지막으로 open()를 호출하십시오.

참고: 이 함수는 스레드 안전합니다.

database(), removeDatabase() 및 “스레드와 SQL 모듈”항목도 참조하십시오 .

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

이 오버로드는 직접 인스턴스화한 ` driver `를 사용하여 데이터베이스 연결을 설정하려는 경우에 유용합니다. 이는 사용자 정의 데이터베이스 드라이버일 수도 있고, Qt 드라이버 중 하나를 직접 인스턴스화해야 하는 경우일 수도 있습니다. 이 경우, 드라이버 코드를 애플리케이션에 포함시키는 것이 좋습니다. 예를 들어, 다음과 같이 자체 QPSQL 드라이버를 사용하여 PostgreSQL 연결을 설정할 수 있습니다.

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");

위의 코드는 PostgreSQL 연결을 설정하고 QPSQLDriver 객체를 생성합니다. 다음으로, addDatabase()를 호출하여 연결을 알려진 연결 목록에 추가함으로써 Qt SQL 클래스에서 이를 사용할 수 있도록 합니다. 드라이버가 연결 핸들(또는 핸들 집합)과 함께 인스턴스화될 때, Qt는 데이터베이스 연결이 이미 열려 있다고 가정합니다.

응용 프로그램을 데이터베이스 클라이언트 라이브러리에 링크해야 한다는 점을 기억하십시오. 클라이언트 라이브러리가 링커의 검색 경로에 있는지 확인하고, .pro 파일에 다음과 같은 줄을 추가하십시오:

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

설명된 방법은 제공되는 모든 드라이버에 적용됩니다. 유일한 차이점은 드라이버 생성자 인자뿐입니다. 다음은 Qt에 포함된 드라이버, 해당 소스 코드 파일 및 생성자 인자를 정리한 표입니다:

drivers()도 참조하십시오 .

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

데이터베이스 연결 ` other `을 복제하여 ` connectionName`으로 저장합니다. 원본 데이터베이스의 모든 설정(예: ` databaseName()`, ` hostName()` 등)이 그대로 복사됩니다. ` other `이 유효하지 않은 데이터베이스인 경우 아무 작업도 수행하지 않습니다. 새로 생성된 데이터베이스 연결을 반환합니다.

참고: 이 함수는 재진입 가능합니다.

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

데이터베이스 연결 ` other `을 복제하여 ` connectionName`으로 저장합니다. 원본 데이터베이스의 모든 설정(예: ` databaseName()`, ` hostName()` 등)이 그대로 복사됩니다. ` other `가 유효하지 않은 데이터베이스인 경우 아무 작업도 수행하지 않습니다. 새로 생성된 데이터베이스 연결을 반환합니다.

이 오버로드는 other 로 표현되는 데이터베이스가 사용되는 스레드와 다른 스레드에서 데이터베이스를 복제할 때 유용합니다.

void QSqlDatabase::close()

데이터베이스 연결을 닫고, 확보된 모든 리소스를 해제하며, 해당 데이터베이스와 함께 사용되는 기존 QSqlQuery 객체를 무효화합니다.

이는 이 QSqlDatabase 객체의 복사본에도 영향을 미칩니다.

removeDatabase()도 참조하십시오 .

bool QSqlDatabase::commit()

드라이버가 트랜잭션을 지원하고 transaction()가 시작된 경우, 트랜잭션을 데이터베이스에 커밋합니다. 작업이 성공하면 true 를 반환합니다. 그렇지 않으면 false 를 반환합니다.

오류에 대한 정보를 얻으려면 lastError()를 호출하십시오.

QSqlQuery::isActive(), QSqlDriver::hasFeature() 및 rollback()도 참조하십시오 .

QString QSqlDatabase::connectOptions() const

이 연결에 사용된 연결 옵션 문자열을 반환합니다. 이 문자열은 비어 있을 수도 있습니다.

setConnectOptions()도 참조하십시오 .

QString QSqlDatabase::connectionName() const

연결 이름을 반환합니다. 이 값은 비어 있을 수도 있습니다.

addDatabase()도 참조하십시오 .

[static] QStringList QSqlDatabase::connectionNames()

모든 연결의 이름을 포함하는 목록을 반환합니다.

참고: 이 함수는 스레드 안전합니다.

contains(), database() 및 ‘스레드와 SQL 모듈’항목도 참조하십시오 .

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

데이터베이스 연결 목록에 ` connectionName`이 포함되어 있으면 ` true `을 반환하고, 그렇지 않으면 ` false`을 반환합니다.

참고: 이 함수는 스레드 안전합니다.

connectionNames(), database() 및 ‘스레드와 SQL 모듈’항목도 참조하십시오 .

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

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()도 참조하십시오 .

[static] QStringList QSqlDatabase::drivers()

사용 가능한 모든 데이터베이스 드라이버 목록을 반환합니다.

registerSqlDriver()도 참조하십시오 .

QString QSqlDatabase::hostName() const

연결의 호스트 이름을 반환합니다. 빈 값일 수도 있습니다.

setHostName()도 참조하십시오 .

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

name 라는 드라이버가 사용 가능한 경우 true 를 반환하고, 그렇지 않은 경우 false 를 반환합니다.

drivers()도 참조하십시오 .

bool QSqlDatabase::isOpen() const

데이터베이스 연결이 현재 열려 있으면 ` true `를 반환하고, 그렇지 않으면 ` false`를 반환합니다.

bool QSqlDatabase::isOpenError() const

데이터베이스 연결을 여는 과정에서 오류가 발생하면 ` true `를 반환하고, 그렇지 않으면 ` false`를 반환합니다. 오류 정보는 ` lastError()` 함수를 사용하여 확인할 수 있습니다.

bool QSqlDatabase::isValid() const

QSqlDatabase 에 유효한 드라이버가 있는 경우 ` true `를 반환합니다.

예시:

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

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

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

QSqlError QSqlDatabase::lastError() const

데이터베이스에서 발생한 마지막 오류에 대한 정보를 반환합니다.

개별 쿼리와 관련하여 발생한 오류는 ` QSqlQuery::lastError()` 함수를 통해 보고됩니다.

QSqlError 및 QSqlQuery::lastError()도 참조하십시오 .

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

QSqlDatabase 및 관련 드라이버의 스레드 어피니티를 변경합니다. 이 함수는 성공하면 true 를 반환합니다. 이벤트 처리는 targetThread 에서 계속됩니다.

이 작업 중에는 이 인스턴스에 바인딩된 QSqlQuery 가 없어야 합니다. 그렇지 않으면 QSqlDatabase 가 지정된 스레드로 이동되지 않으며, 함수는 false 를 반환합니다.

관련 드라이버가 QObject 에서 파생되었으므로, QObject 를 다른 스레드로 이동하는 데 적용되는 모든 제약 조건이 이 함수에도 동일하게 적용됩니다.

이 함수는 Qt 6.8에서 도입되었습니다.

QObject::moveToThread() 및 스레드와 SQL 모듈항목도 참조하십시오 .

QSql::NumericalPrecisionPolicy QSqlDatabase::numericalPrecisionPolicy() const

numericalPrecisionPolicy를 반환합니다.

setNumericalPrecisionPolicy()도 참조하십시오 .

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

tablename 라는 테이블(또는 뷰)에 포함된 모든 필드의 이름이 채워진 QSqlRecord 를 반환합니다. 레코드 내에서 필드가 나타나는 순서는 정의되지 않습니다. 해당 테이블(또는 뷰)이 존재하지 않으면 빈 레코드가 반환됩니다.

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

이 함수는 SQL 프레임워크 내에 ‘ name ’라는 새로운 SQL 드라이버를 등록합니다. 이 기능은 사용자 정의 SQL 드라이버가 있지만 이를 플러그인으로 컴파일하고 싶지 않은 경우에 유용합니다.

예시:

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

QSqlDatabase creator 포인터에 대한 소유권을 가져오므로, 직접 삭제해서는 안 됩니다.

drivers()도 참조하십시오 .

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

데이터베이스 연결 목록에서 connectionName 데이터베이스 연결을 제거합니다.

예시:

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

올바른 방법:

{
    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

addDatabase() 호출 시 연결 이름을 지정하지 않아 생성되었을 수 있는 기본 연결을 제거하려면, database()가 반환한 데이터베이스에 대해 connectionName()를 호출하여 기본 연결 이름을 가져올 수 있습니다. 기본 데이터베이스가 생성되지 않은 경우, 유효하지 않은 데이터베이스가 반환된다는 점에 유의하십시오.

참고: 이 함수는 스레드 안전합니다.

database(), connectionName() 및 “스레드와 SQL 모듈”항목도 참조하십시오 .

bool QSqlDatabase::rollback()

드라이버가 트랜잭션을 지원하고 ` transaction()`가 시작된 경우, 데이터베이스의 트랜잭션을 롤백합니다. 작업이 성공하면 ` true `를 반환합니다. 그렇지 않으면 ` false`를 반환합니다.

오류에 대한 정보를 얻으려면 lastError()를 호출하십시오.

QSqlQuery::isActive(), QSqlDriver::hasFeature() 및 commit()도 참조하십시오 .

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

데이터베이스별 연결 옵션( options)을 설정합니다. 이는 연결이 열리기 전에 수행해야 하며, 그렇지 않으면 효과가 없습니다. 또 다른 방법은 연결을 닫은 후 QSqlDatabase::setConnectOptions()를 호출하고, 다시 open()를 호출하여 연결을 재개하는 것입니다.

options 문자열의 형식은 세미콜론으로 구분된 옵션 이름 목록 또는 ‘옵션=값’ 쌍의 목록입니다. 옵션은 사용되는 데이터베이스 클라이언트에 따라 다르며, 각 플러그인에 대한 설명은 SQL 데이터베이스 드라이버 페이지에서 확인할 수 있습니다.

예시:

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

다양한 옵션에 대한 자세한 내용은 클라이언트 라이브러리 문서를 참조하십시오.

connectOptions()도 참조하십시오 .

void QSqlDatabase::setDatabaseName(const QString &name)

연결의 데이터베이스 이름을 ` name`로 설정합니다. 이 설정이 적용되려면 연결이 ` opened`되기 전에 데이터베이스 이름을 설정해야 합니다. 또는 연결을 ` close()`로 초기화한 후 데이터베이스 이름을 설정하고, 다시 ` open()`를 호출할 수도 있습니다.

QSQLITE 드라이버의 경우, 지정된 데이터베이스 이름이 존재하지 않으면 QSQLITE_OPEN_READONLY 옵션이 설정되어 있지 않은 한 해당 파일을 자동으로 생성합니다.

또한, name 를 ":memory:" 로 설정하면 애플리케이션이 실행되는 동안에만 사용할 수 있는 임시 데이터베이스가 생성됩니다.

QOCI(Oracle) 드라이버의 경우, 데이터베이스 이름은 TNS 서비스 이름입니다.

QODBC 드라이버의 경우, name 는 DSN, DSN 파일 이름(이 경우 파일의 확장자는 .dsn 이어야 함) 또는 연결 문자열일 수 있습니다.

예를 들어, Microsoft Access 사용자는 ODBC 관리자에서 DSN 항목을 생성할 필요 없이 다음 연결 문자열을 사용하여 .mdb 파일을 직접 열 수 있습니다.

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

기본값은 없습니다.

databaseName(), setUserName(), setPassword(), setHostName(), setPort(), setConnectOptions() 및 open()도 참조하십시오 .

void QSqlDatabase::setHostName(const QString &host)

연결의 호스트 이름을 host 로 설정합니다. 이 설정이 적용되려면 연결이 opened 되기 전에 호스트 이름을 설정해야 합니다. 또는 연결에 대해 close()를 호출하여 호스트 이름을 설정한 후, 다시 open()를 호출할 수도 있습니다.

기본값은 없습니다.

hostName(), setUserName(), setPassword(), setDatabaseName(), setPort(), setConnectOptions() 및 open()도 참조하십시오 .

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

numericalPrecisionPolicy 를 precisionPolicy 로 설정합니다.

numericalPrecisionPolicy()도 참조하십시오 .

void QSqlDatabase::setPassword(const QString &password)

연결의 비밀번호를 ` password`로 설정합니다. 이 설정이 적용되려면 연결이 ` opened`되기 전에 비밀번호를 설정해야 합니다. 또는 ` close()`를 호출하여 연결을 닫은 후 비밀번호를 설정하고, 다시 ` open()`를 호출할 수도 있습니다.

기본값은 없습니다.

참조: password(), setUserName(), setDatabaseName(), setHostName(), setPort(), setConnectOptions() 및 open().

void QSqlDatabase::setPort(int port)

연결의 포트 번호를 port 로 설정합니다. 이 설정이 적용되려면, 연결이 opened 되기 전에 포트 번호를 설정해야 합니다. 또는, 연결에 close()를 호출하여 포트 번호를 설정한 후, 다시 open()를 호출할 수도 있습니다.

기본값은 없습니다.

port(), setUserName(), setPassword(), setHostName(), setDatabaseName(), setConnectOptions(), open()도 참조하십시오 .

void QSqlDatabase::setUserName(const QString &name)

연결의 사용자 이름을 name 로 설정합니다. 이 설정이 적용되려면 연결이 opened 되기 전에 사용자 이름을 설정해야 합니다. 또는 연결에 대해 close()을 호출하여 사용자 이름을 설정한 후, 다시 open()를 호출할 수도 있습니다.

기본값은 없습니다.

userName(), setDatabaseName(), setPassword(), setHostName(), setPort(), setConnectOptions() 및 open()도 참조하십시오 .

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

type 매개변수에 지정된 대로 데이터베이스의 테이블, 시스템 테이블 및 뷰 목록을 반환합니다.

primaryIndex() 및 record()도 참조하십시오 .

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

연관된 ` QThread ` 인스턴스에 대한 포인터를 반환합니다.

이 함수는 Qt 6.8에서 도입되었습니다.

bool QSqlDatabase::transaction()

드라이버가 트랜잭션을 지원하는 경우, 데이터베이스에서 트랜잭션을 시작합니다. 작업이 성공하면 ` true `을 반환합니다. 그렇지 않으면 ` false`을 반환합니다.

QSqlDriver::hasFeature(), commit(), rollback()도 참조하십시오 .

QString QSqlDatabase::userName() const

연결의 사용자 이름을 반환합니다. 빈 값일 수도 있습니다.

setUserName()도 참조하십시오 .

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

이 객체에 ` other `를 할당합니다.