From 35f9f2bb0014de4a64d5d442ed2a601821dd0ee3 Mon Sep 17 00:00:00 2001 From: Christian Ehrlicher Date: Mon, 19 Dec 2022 20:20:35 +0100 Subject: SQL: rework the connection options documentation Move the documentation of the connection options to the SQL Drivers page and try to add a small but useful documention to each option. Fixes: QTBUG-109507 Change-Id: Id1d51d7a666ac0f15cde8d73bff153dad271d34b Reviewed-by: Andy Shaw --- src/sql/doc/src/sql-driver.qdoc | 197 ++++++++++++++++++++++++++++++++++++++++ src/sql/kernel/qsqldatabase.cpp | 94 +------------------ 2 files changed, 199 insertions(+), 92 deletions(-) (limited to 'src/sql') diff --git a/src/sql/doc/src/sql-driver.qdoc b/src/sql/doc/src/sql-driver.qdoc index 869c4b00a2..57b18c126b 100644 --- a/src/sql/doc/src/sql-driver.qdoc +++ b/src/sql/doc/src/sql-driver.qdoc @@ -154,6 +154,74 @@ Please refer to the MySQL documentation, chapter "libmysqld, the Embedded MySQL Server Library" for more information about the MySQL embedded server. + \section3 Connection options + The Qt MySQL/MariaDB plugin honors the following connection options: + \table + \header \li Attribute \li Possible value + \row + \li CLIENT_COMPRESS + \li If set, switches to compressed protocol after successful authentication + \row + \li CLIENT_FOUND_ROWS + \li If set, send found rows instead of affected rows + \row + \li CLIENT_IGNORE_SPACE + \li If set, ignore spaces before '(' + \row + \li CLIENT_NO_SCHEMA + \li If set, don't allow database.table.column + \row + \li CLIENT_INTERACTIVE + \li If set, client is treated as interactive + \row + \li UNIX_SOCKET + \li Specifies the socket or named pipe to use + \row + \li MYSQL_OPT_RECONNECT + \li TRUE or 1: Automatically reconnect after connection loss\br + FALSE or 0: No automatic reconnect after connection loss (default)\br + See \l {https://dev.mysql.com/doc/c-api/8.0/en/c-api-auto-reconnect.html} + {Automatic Reconnection Control}^ + \row + \li MYSQL_OPT_CONNECT_TIMEOUT + \li The connect timeout in seconds + \row + \li MYSQL_OPT_READ_TIMEOUT + \li The timeout in seconds for each attempt to read from the server + \row + \li MYSQL_OPT_WRITE_TIMEOUT + \li The timeout in seconds for each attempt to write to the server + \row + \li MYSQL_OPT_LOCAL_INFILE + \li Set to 1 to enable the support for local + \l {https://dev.mysql.com/doc/refman/8.0/en/load-data.html} {LOAD_DATA} + \row + \li MYSQL_OPT_SSL_KEY / SSL_KEY (deprecated) + \li The path name of the client private key file + \row + \li MYSQL_OPT_SSL_CERT / SSL_CERT (deprecated) + \li The path name of the client public key certificate file + \row + \li MYSQL_OPT_SSL_CA / SSL_CA (deprecated) + \li The path name of the Certificate Authority (CA) certificate file + \row + \li MYSQL_OPT_SSL_CAPATH / SSL_CAPATH (deprecated) + \li The path name of the directory that contains trusted SSL CA certificate files + \row + \li MYSQL_OPT_SSL_CIPHER / SSL_CIPHER (deprecated) + \li The list of permissible ciphers for SSL encryption + \row + \li MYSQL_OPT_SSL_CRL + \li The path name of the file containing certificate revocation lists + \row + \li MYSQL_OPT_SSL_CRLPATH + \li The path name of the directory that contains files containing certificate revocation lists + \endtable + For more detailed information about the connect options please refer + to the \l {https://dev.mysql.com/doc/c-api/8.0/en/mysql-options.html} + {mysql_options()} MySQL documentation. + + \section3 How to Build the QMYSQL Plugin on Unix and \macos You need the MySQL / MariaDB header files, as well as the shared library @@ -236,6 +304,22 @@ BLOBs are bound to placeholders or QSqlTableModel, which uses a prepared query to do this internally. + \section3 Connection options + The Qt OCI plugin honors the following connection options: + \table + \header \li Attribute \li Possible value + \row + \li OCI_ATTR_PREFETCH_ROWS + \li Sets the OCI attribute + \l {https://docs.oracle.com/database/121/LNOCI/oci04sql.htm#LNOCI16355} + {OCI_ATTR_PREFETCH_ROWS} to the specified value + \row + \li OCI_ATTR_PREFETCH_MEMORY + \li Sets the OCI attribute + \l {https://docs.oracle.com/database/121/LNOCI/oci04sql.htm#LNOCI16355} + {OCI_ATTR_PREFETCH_MEMORY} to the specified value + \endtable + \section3 How to Build the OCI Plugin on Unix and \macos All you need is the " - Basic" and "Instant Client @@ -355,6 +439,56 @@ "SQL_WCHAR support" in the ODBC driver manager otherwise Oracle will convert all Unicode strings to local 8-bit. + \section3 Connection options + The Qt ODBC plugin honors the following connection options: + \table + \header \li Attribute \li Possible value + \row + \li SQL_ATTR_ACCESS_MODE + \li Set to SQL_MODE_READ_ONLY to open the database in read-only + mode, or SQL_MODE_READ_WRITE to open it in read-write mode + \row + \li SQL_ATTR_LOGIN_TIMEOUT + \li Number of seconds to wait for the database connection + during login (a value of 0 will wait forever) + \row + \li SQL_ATTR_CONNECTION_TIMEOUT + \li Number of seconds to wait for any request to the database + (a value of 0 will wait forever) + \row + \li SQL_ATTR_CURRENT_CATALOG + \li The catalog (database) to use for this connection. + \row + \li SQL_ATTR_METADATA_ID + \li SQL_TRUE: the string argument of catalog functions are treated + as identifiers\br + SQL_FALSE: the string arguments of catalog functions are not + treated as identifiers + \row + \li SQL_ATTR_PACKET_SIZE + \li Specifies the network packet size in bytes + \row + \li SQL_ATTR_TRACEFILE + \li A string containing the name of the trace file + \row + \li SQL_ATTR_TRACE + \li SQL_OPT_TRACE_ON: Enable database query tracing\br + SQL_OPT_TRACE_ON: Disable database query tracing (default) + \row + \li SQL_ATTR_CONNECTION_POOLING + \li Enable or disable connection pooling at the environment level. + SQL_CP_DEFAULT, SQL_CP_OFF: Connection pooling is turned off (default)\br + SQL_CP_ONE_PER_DRIVER: A single connection pool is supported for each driver\br + SQL_CP_ONE_PER_HENV: A single connection pool is supported for each environment + \row + \li SQL_ATTR_ODBC_VERSION + \li SQL_OV_ODBC3: The driver should act as a ODBC 3.x driver\br + SQL_OV_ODBC2: The driver should act as a ODBC 2.x driver + \endtable + For more detailed information about the connect options please refer + to the \l {https://learn.microsoft.com/en-us/sql/odbc/reference/syntax/sqlsetconnectattr-function} + {SQLSetConnectAttr()} ODBC documentation. + \section3 How to Build the ODBC Plugin on Unix and \macos It is recommended that you use unixODBC. You can find the latest @@ -452,6 +586,11 @@ \snippet code/doc_src_sql-driver.qdoc 38 + \section3 Connection options + The Qt PostgreSQL plugin honors all connection options specified in the + \l {https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS} + {connect()} PostgreSQL documentation. + \section3 How to Build the QPSQL Plugin on Unix and \macos You need the PostgreSQL client library and headers installed. @@ -491,6 +630,20 @@ We suggest using a forward-only query when calling stored procedures in DB2 (see QSqlQuery::setForwardOnly()). + \section3 Connection options + The Qt IBM DB2 plugin honors the following connection options: + \table + \header \li Attribute \li Possible value + \row + \li SQL_ATTR_ACCESS_MODE + \li Set to SQL_MODE_READ_ONLY to open the database in read-only + mode, or SQL_MODE_READ_WRITE to open it in read-write mode + \row + \li SQL_ATTR_LOGIN_TIMEOUT + \li Number of seconds to wait for the database connection + during login (max: 32767, a value of 0 will wait forever) + \endtable + \section3 How to Build the QDB2 Plugin on Unix and \macos \snippet code/doc_src_sql-driver.qdoc 18 @@ -536,6 +689,39 @@ You can find information about SQLite on \l{http://www.sqlite.org}. + \section3 Connection options + The Qt SQLite plugin honors the following connection options: + \table + \header \li Attribute \li Possible value + \row + \li QSQLITE_BUSY_TIMEOUT + \li Busy handler timeout in milliseconds (val <= 0: disabled), + see \l {https://www.sqlite.org/c3ref/busy_timeout.html} + {SQLite documentation} for more information. + \row + \li QSQLITE_OPEN_READONLY + \li If set, the database is open in read-only mode which will fail + if no database exists. Otherwise the database will be opened in + read-write mode and created if the database file does not yet exist. + \row + \li QSQLITE_OPEN_URI + \li The given filename is interpreted as an uri + (\l {https://www.sqlite.org/c3ref/open.html} {SQLITE_OPEN_URI}) + \row + \li QSQLITE_ENABLE_SHARED_CACHE + \li If set, the database is opened in + \l {https://www.sqlite.org/sharedcache.html} {shared cache mode}, + otherwise in private cache mode + \row + \li QSQLITE_ENABLE_REGEXP + \li If set, the plugin defines a function 'regex' which can be used + in queries. QRegularExpression is used for evaluation of the regex query. + \row + \li QSQLITE_NO_USE_EXTENDED_RESULT_CODES + \li Disables the usage of the \l {https://www.sqlite.org/c3ref/extended_result_codes.html} + {extended result code} feature in SQLite + \endtable + \section3 How to Build the QSQLITE Plugin SQLite version 3 is included as a third-party library within Qt. @@ -604,6 +790,17 @@ database file, no matter whether it is stored locally or on another server. + \section3 Connection options + The Qt Borland InterBase plugin honors the following connection options: + \table + \header \li Attribute \li Possible value + \row + \li ISC_DPB_SQL_ROLE_NAME + \li Specifies the login role name + \endtable + + + \section3 How to Build the QIBASE Plugin \snippet code/doc_src_sql-driver.cpp 24 You need the InterBase/Firebird development headers and libraries diff --git a/src/sql/kernel/qsqldatabase.cpp b/src/sql/kernel/qsqldatabase.cpp index 90ce374c54..a547b1f15b 100644 --- a/src/sql/kernel/qsqldatabase.cpp +++ b/src/sql/kernel/qsqldatabase.cpp @@ -1099,98 +1099,8 @@ QSqlRecord QSqlDatabase::record(const QString& tablename) const The format of the \a options string is a semicolon separated list of option names or option=value pairs. The options depend on the - database client used: - - \table - \header \li ODBC \li MySQL \li PostgreSQL - \row - - \li - \list - \li SQL_ATTR_ACCESS_MODE - \li SQL_ATTR_LOGIN_TIMEOUT - \li SQL_ATTR_CONNECTION_TIMEOUT - \li SQL_ATTR_CURRENT_CATALOG - \li SQL_ATTR_METADATA_ID - \li SQL_ATTR_PACKET_SIZE - \li SQL_ATTR_TRACEFILE - \li SQL_ATTR_TRACE - \li SQL_ATTR_CONNECTION_POOLING - \li SQL_ATTR_ODBC_VERSION - \endlist - - \li - \list - \li CLIENT_COMPRESS - \li CLIENT_FOUND_ROWS - \li CLIENT_IGNORE_SPACE - \li CLIENT_ODBC - \li CLIENT_NO_SCHEMA - \li CLIENT_INTERACTIVE - \li UNIX_SOCKET - \li MYSQL_OPT_RECONNECT - \li MYSQL_OPT_CONNECT_TIMEOUT - \li MYSQL_OPT_READ_TIMEOUT - \li MYSQL_OPT_WRITE_TIMEOUT - \li MYSQL_OPT_LOCAL_INFILE - \li MYSQL_OPT_SSL_KEY - \li MYSQL_OPT_SSL_CERT - \li MYSQL_OPT_SSL_CA - \li MYSQL_OPT_SSL_CAPATH - \li MYSQL_OPT_SSL_CIPHER - \li MYSQL_OPT_SSL_CRL - \li MYSQL_OPT_SSL_CRLPATH - \li SSL_KEY (deprecated, use MYSQL_OPT_SSL_KEY) - \li SSL_CERT (deprecated, use MYSQL_OPT_SSL_CERT) - \li SSL_CA (deprecated, use MYSQL_OPT_SSL_CA) - \li SSL_CAPATH (deprecated, use MYSQL_OPT_SSL_CAPATH) - \li SSL_CIPHER (deprecated, use MYSQL_OPT_SSL_CIPHER) - \endlist - - \li - \list - \li connect_timeout - \li options - \li tty - \li requiressl - \li service - \endlist - - \header \li DB2 \li OCI - \row - - \li - \list - \li SQL_ATTR_ACCESS_MODE - \li SQL_ATTR_LOGIN_TIMEOUT - \endlist - - \li - \list - \li OCI_ATTR_PREFETCH_ROWS - \li OCI_ATTR_PREFETCH_MEMORY - \endlist - - \header \li SQLite \li Interbase - \row - - \li - \list - \li QSQLITE_BUSY_TIMEOUT - \li QSQLITE_OPEN_READONLY - \li QSQLITE_OPEN_URI - \li QSQLITE_ENABLE_SHARED_CACHE - \li QSQLITE_ENABLE_REGEXP - \li QSQLITE_NO_USE_EXTENDED_RESULT_CODES - \endlist - - \li - \list - \li ISC_DPB_LC_CTYPE - \li ISC_DPB_SQL_ROLE_NAME - \endlist - - \endtable + database client used and are described for each plugin in the + \l{sql-driver.html}{SQL Database Drivers} page. Examples: \snippet code/src_sql_kernel_qsqldatabase.cpp 4 -- cgit v1.2.3