1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

SQL: rework the connection options documentation

Browse Source 
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 <andy.shaw@qt.io>
This commit is contained in:
Christian Ehrlicher 2022-12-19 20:20:35 +01:00
parent 5419faebde
commit 35f9f2bb00
2 changed files with 199 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

197
src/sql/doc/src/sql-driver.qdoc
View File

@ -154,6 +154,74 @@
Please refer to the MySQL documentation, chapter "libmysqld, the Embedded Please refer to the MySQL documentation, chapter "libmysqld, the Embedded
MySQL Server Library" for more information about the MySQL embedded server. 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 \section3 How to Build the QMYSQL Plugin on Unix and \macos
You need the MySQL / MariaDB header files, as well as the shared library 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 BLOBs are bound to placeholders or QSqlTableModel, which uses a prepared
query to do this internally. 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 \section3 How to Build the OCI Plugin on Unix and \macos
All you need is the " - Basic" and "Instant Client All you need is the " - Basic" and "Instant Client
@ -355,6 +439,56 @@
"SQL_WCHAR support" in the ODBC driver manager otherwise Oracle "SQL_WCHAR support" in the ODBC driver manager otherwise Oracle
will convert all Unicode strings to local 8-bit. 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 \section3 How to Build the ODBC Plugin on Unix and \macos
It is recommended that you use unixODBC. You can find the latest It is recommended that you use unixODBC. You can find the latest
@ -452,6 +586,11 @@
\snippet code/doc_src_sql-driver.qdoc 38 \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 \section3 How to Build the QPSQL Plugin on Unix and \macos
You need the PostgreSQL client library and headers installed. You need the PostgreSQL client library and headers installed.
@ -491,6 +630,20 @@
We suggest using a forward-only query when calling stored procedures We suggest using a forward-only query when calling stored procedures
in DB2 (see QSqlQuery::setForwardOnly()). 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 \section3 How to Build the QDB2 Plugin on Unix and \macos
\snippet code/doc_src_sql-driver.qdoc 18 \snippet code/doc_src_sql-driver.qdoc 18
@ -536,6 +689,39 @@
You can find information about SQLite on \l{http://www.sqlite.org}. 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 \section3 How to Build the QSQLITE Plugin
SQLite version 3 is included as a third-party library within Qt. 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 database file, no matter whether it is stored locally or on another
server. 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 \snippet code/doc_src_sql-driver.cpp 24
You need the InterBase/Firebird development headers and libraries You need the InterBase/Firebird development headers and libraries

94
src/sql/kernel/qsqldatabase.cpp
View File

@ -1099,98 +1099,8 @@ QSqlRecord QSqlDatabase::record(const QString& tablename) const
The format of the \a options string is a semicolon separated list The format of the \a options string is a semicolon separated list
of option names or option=value pairs. The options depend on the of option names or option=value pairs. The options depend on the
database client used: database client used and are described for each plugin in the
\l{sql-driver.html}{SQL Database Drivers} page.
\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
Examples: Examples:
\snippet code/src_sql_kernel_qsqldatabase.cpp 4 \snippet code/src_sql_kernel_qsqldatabase.cpp 4