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 <andy.shaw@qt.io>
This commit is contained in:
Christian Ehrlicher
parent
5419faebde
commit
35f9f2bb00
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user