QSqlDatabase Class

멤버 함수 문서

QSqlDatabase::QSqlDatabase()

비어 있는 유효하지 않은 QSqlDatabase 객체를 만듭니다. addDatabase (), removeDatabase() 및 database()를 사용하여 유효한 QSqlDatabase 개체를 가져옵니다.

[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 = QLatin1StringView(defaultConnection))

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

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

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

connectionName 을 지정하지 않으면 새 연결이 애플리케이션의 기본 연결이 되며, 이후 연결 이름 인수 없이 database()을 호출하면 기본 연결이 반환됩니다. 여기에 connectionName 이 제공되면 데이터베이스(connectionName)를 사용하여 연결을 검색합니다.

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

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

database(), removeDatabase() 및 스레드와 SQL 모듈도참조하세요 .

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

이 함수는 오버로드된 함수입니다.

이 오버로드는 직접 인스턴스화한 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 = QLatin1StringView(defaultConnection))

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

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

connectionNames(), database() 및 스레드와 SQL 모듈을참조하세요 .

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

connectionName 라는 데이터베이스 연결을 반환합니다. 데이터베이스 연결은 이전에 addDatabase()로 추가한 적이 있어야 합니다. open (기본값)가 참이고 데이터베이스 연결이 아직 열려 있지 않은 경우 지금 열립니다. 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 이 객체에 할당합니다.