6.3 Configuration Properties

6.3.1 Authentication

6.3.2 Connection

6.3.3 Session

6.3.4 Networking

6.3.5 Security

6.3.6 Statements

6.3.7 Prepared Statements

6.3.8 Result Sets

6.3.9 Metadata

6.3.10 BLOB/CLOB processing

6.3.11 Datetime types processing

6.3.12 High Availability and Clustering

6.3.13 Performance Extensions

6.3.14 Debugging/Profiling

6.3.15 Exceptions/Warnings

6.3.16 Tunes for integration with other products

6.3.17 JDBC compliance

6.3.18 X Protocol and X DevAPI

Configuration properties define how Connector/J will make a connection to a MySQL server. Unless otherwise noted, properties can be set for a DataSource object or for a Connection object.

Configuration properties can be set in one of the following ways:

• Using the set*() methods on MySQL implementations of java.sql.DataSource (which is the preferred method when using implementations of java.sql.DataSource):

  • com.mysql.cj.jdbc.MysqlDataSource

  • com.mysql.cj.jdbc.MysqlConnectionPoolDataSource

• As a key-value pair in the java.util.Properties instance passed to DriverManager.getConnection() or Driver.connect()

• As a JDBC URL parameter in the URL given to java.sql.DriverManager.getConnection(), java.sql.Driver.connect() or the MySQL implementations of the javax.sql.DataSource setURL() method. If you specify a configuration property in the URL without providing a value for it, nothing will be set; for example, adding useServerPrepStmts alone to the URL does not make Connector/J use server-side prepared statements; you need to add useServerPrepStmts=true.

  Note

  If the mechanism you use to configure a JDBC URL is XML-based, use the XML character literal & to separate configuration parameters, as the ampersand is a reserved character for XML.

The properties are listed by categories in the following tables and then in the subsections that follow. Click on a property name in the tables to see its full description in the subsections.

Table 6.1 Authentication Properties

Name	Default Value	Since Version
user	-	all versions
password	-	all versions
password1	-	8.0.28
password2	-	8.0.28
password3	-	8.0.28
authenticationPlugins	-	5.1.19
disabledAuthenticationPlugins	-	5.1.19
ociConfigFile	-	8.0.27
authenticationFidoCallbackHandler	-	8.0.29
defaultAuthenticationPlugin	mysql_native_password	5.1.19
ldapServerHostname	-	8.0.23

Table 6.2 Connection Properties

Name	Default Value	Since Version
connectionAttributes	-	5.1.25
connectionLifecycleInterceptors	-	5.1.4
useConfigs	-	3.1.5
clientInfoProvider	com.mysql.cj.jdbc.CommentClientInfoProvider	5.1.0
createDatabaseIfNotExist	false	3.1.9
databaseTerm	CATALOG	8.0.17
detectCustomCollations	false	5.1.29
disconnectOnExpiredPasswords	true	5.1.23
interactiveClient	false	3.1.0
passwordCharacterEncoding	-	5.1.7
propertiesTransform	-	3.1.4
rollbackOnPooledClose	true	3.0.15
useAffectedRows	false	5.1.7

Table 6.3 Session Properties

Name	Default Value	Since Version
sessionVariables	-	3.1.8
characterEncoding	-	1.1g
characterSetResults	-	3.0.13
connectionCollation	-	3.0.13
customCharsetMapping	-	8.0.26
trackSessionState	false	8.0.26

Table 6.4 Networking Properties

Name	Default Value	Since Version
socksProxyHost	-	5.1.34
socksProxyPort	1080	5.1.34
socketFactory	com.mysql.cj.protocol.StandardSocketFactory	3.0.3
connectTimeout	0	3.0.1
socketTimeout	0	3.0.1
dnsSrv	false	8.0.19
localSocketAddress	-	5.0.5
maxAllowedPacket	65535	5.1.8
socksProxyRemoteDns	false	8.0.29
tcpKeepAlive	true	5.0.7
tcpNoDelay	true	5.0.7
tcpRcvBuf	0	5.0.7
tcpSndBuf	0	5.0.7
tcpTrafficClass	0	5.0.7
useCompression	false	3.0.17
useUnbufferedInput	true	3.0.11

Table 6.5 Security Properties

Name	Default Value	Since Version
paranoid	false	3.0.1
serverRSAPublicKeyFile	-	5.1.31
allowPublicKeyRetrieval	false	5.1.31
sslMode	PREFERRED	8.0.13
trustCertificateKeyStoreUrl	-	5.1.0
trustCertificateKeyStoreType	JKS	5.1.0
trustCertificateKeyStorePassword	-	5.1.0
fallbackToSystemTrustStore	true	8.0.22
clientCertificateKeyStoreUrl	-	5.1.0
clientCertificateKeyStoreType	JKS	5.1.0
clientCertificateKeyStorePassword	-	5.1.0
fallbackToSystemKeyStore	true	8.0.22
tlsCiphersuites	-	5.1.35
tlsVersions	-	8.0.8
allowLoadLocalInfile	false	3.0.3
allowLoadLocalInfileInPath	-	8.0.22
allowMultiQueries	false	3.1.1
allowUrlInLocalInfile	false	3.1.4
requireSSL	false	3.1.0
useSSL	true	3.0.2
verifyServerCertificate	false	5.1.6

Table 6.6 Statements Properties

Name	Default Value	Since Version
cacheDefaultTimeZone	true	8.0.20
continueBatchOnError	true	3.0.3
dontTrackOpenResources	false	3.1.7
queryInterceptors	-	8.0.7
queryTimeoutKillsConnection	false	5.1.9

Table 6.7 Prepared Statements Properties

Name	Default Value	Since Version
allowNanAndInf	false	3.1.5
autoClosePStmtStreams	false	3.1.12
compensateOnDuplicateKeyUpdateCounts	false	5.1.7
emulateUnsupportedPstmts	true	3.1.7
generateSimpleParameterMetadata	false	5.0.5
processEscapeCodesForPrepStmts	true	3.1.12
useServerPrepStmts	false	3.1.0
useStreamLengthsInPrepStmts	true	3.0.2

Table 6.8 Result Sets Properties

Name	Default Value	Since Version
clobberStreamingResults	false	3.0.9
emptyStringsConvertToZero	true	3.1.8
holdResultsOpenOverStatementClose	false	3.1.7
jdbcCompliantTruncation	true	3.1.2
maxRows	-1	all versions
netTimeoutForStreamingResults	600	5.1.0
padCharsWithSpace	false	5.0.6
populateInsertRowWithDefaultValues	false	5.0.5
scrollTolerantForwardOnly	false	8.0.24
strictUpdates	true	3.0.4
tinyInt1isBit	true	3.0.16
transformedBitIsBoolean	false	3.1.9

Table 6.9 Metadata Properties

Name	Default Value	Since Version
getProceduresReturnsFunctions	true	5.1.26
noAccessToProcedureBodies	false	5.0.3
nullDatabaseMeansCurrent	false	3.1.8
useHostsInPrivileges	true	3.0.2
useInformationSchema	false	5.0.0

Table 6.10 BLOB/CLOB processing Properties

Name	Default Value	Since Version
autoDeserialize	false	3.1.5
blobSendChunkSize	1048576	3.1.9
blobsAreStrings	false	5.0.8
clobCharacterEncoding	-	5.0.0
emulateLocators	false	3.1.0
functionsNeverReturnBlobs	false	5.0.8
locatorFetchBufferSize	1048576	3.2.1

Table 6.11 Datetime types processing Properties

Name	Default Value	Since Version
connectionTimeZone	-	3.0.2
forceConnectionTimeZoneToSession	false	8.0.23
noDatetimeStringSync	false	3.1.7
preserveInstants	true	8.0.23
sendFractionalSeconds	true	5.1.37
sendFractionalSecondsForTime	true	8.0.23
treatUtilDateAsTimestamp	true	5.0.5
yearIsDateType	true	3.1.9
zeroDateTimeBehavior	EXCEPTION	3.1.4

Table 6.12 High Availability and Clustering Properties

Name	Default Value	Since Version
autoReconnect	false	1.1
autoReconnectForPools	false	3.1.3
failOverReadOnly	true	3.0.12
maxReconnects	3	1.1
reconnectAtTxEnd	false	3.0.10
retriesAllDown	120	5.1.6
initialTimeout	2	1.1
queriesBeforeRetrySource	50	3.0.2
secondsBeforeRetrySource	30	3.0.2
allowReplicaDownConnections	false	6.0.2
allowSourceDownConnections	false	5.1.27
ha.enableJMX	false	5.1.27
loadBalanceHostRemovalGracePeriod	15000	6.0.3
readFromSourceWhenNoReplicas	false	6.0.2
selfDestructOnPingMaxOperations	0	5.1.6
selfDestructOnPingSecondsLifetime	0	5.1.6
ha.loadBalanceStrategy	random	5.0.6
loadBalanceAutoCommitStatementRegex	-	5.1.15
loadBalanceAutoCommitStatementThreshold	0	5.1.15
loadBalanceBlocklistTimeout	0	5.1.0
loadBalanceConnectionGroup	-	5.1.13
loadBalanceExceptionChecker	com.mysql.cj.jdbc.ha.StandardLoadBalanceExceptionChecker	5.1.13
loadBalancePingTimeout	0	5.1.13
loadBalanceSQLExceptionSubclassFailover	-	5.1.13
loadBalanceSQLStateFailover	-	5.1.13
loadBalanceValidateConnectionOnSwapServer	false	5.1.13
pinGlobalTxToPhysicalConnection	false	5.0.1
replicationConnectionGroup	-	8.0.7
resourceId	-	5.0.1
serverAffinityOrder	-	8.0.8

Table 6.13 Performance Extensions Properties

Name	Default Value	Since Version
callableStmtCacheSize	100	3.1.2
metadataCacheSize	50	3.1.1
useLocalSessionState	false	3.1.7
useLocalTransactionState	false	5.1.7
prepStmtCacheSize	25	3.0.10
prepStmtCacheSqlLimit	256	3.0.10
queryInfoCacheFactory	com.mysql.cj.PerConnectionLRUFactory	5.1.1
serverConfigCacheFactory	com.mysql.cj.util.PerVmServerConfigCacheFactory	5.1.1
alwaysSendSetIsolation	true	3.1.7
maintainTimeStats	true	3.1.9
useCursorFetch	false	5.0.0
cacheCallableStmts	false	3.1.2
cachePrepStmts	false	3.0.10
cacheResultSetMetadata	false	3.1.1
cacheServerConfiguration	false	3.1.5
defaultFetchSize	0	3.1.9
dontCheckOnDuplicateKeyUpdateInSQL	false	5.1.32
elideSetAutoCommits	false	3.1.3
enableEscapeProcessing	true	6.0.1
enableQueryTimeouts	true	5.0.6
largeRowSizeThreshold	2048	5.1.1
readOnlyPropagatesToServer	true	5.1.35
rewriteBatchedStatements	false	3.1.13
useReadAheadInput	true	3.1.5

Table 6.14 Debugging/Profiling Properties

Name	Default Value	Since Version
logger	com.mysql.cj.log.StandardLogger	3.1.1
profilerEventHandler	com.mysql.cj.log.LoggingProfilerEventHandler	5.1.6
useNanosForElapsedTime	false	5.0.7
maxQuerySizeToLog	2048	3.1.3
profileSQL	false	3.1.0
logSlowQueries	false	3.1.2
slowQueryThresholdMillis	2000	3.1.2
slowQueryThresholdNanos	0	5.0.7
autoSlowLog	true	5.1.4
explainSlowQueries	false	3.1.2
gatherPerfMetrics	false	3.1.2
reportMetricsIntervalMillis	30000	3.1.2
logXaCommands	false	5.0.5
traceProtocol	false	3.1.2
enablePacketDebug	false	3.1.3
packetDebugBufferSize	20	3.1.3
useUsageAdvisor	false	3.1.1
resultSetSizeThreshold	100	5.0.5
autoGenerateTestcaseScript	false	3.1.9

Table 6.15 Exceptions/Warnings Properties

Name	Default Value	Since Version
dumpQueriesOnException	false	3.1.3
exceptionInterceptors	-	5.1.8
ignoreNonTxTables	false	3.0.9
includeInnodbStatusInDeadlockExceptions	false	5.0.7
includeThreadDumpInDeadlockExceptions	false	5.1.15
includeThreadNamesAsStatementComment	false	5.1.15
useOnlyServerErrorMessages	true	3.0.15

Table 6.16 Tunes for integration with other products Properties

Name	Default Value	Since Version
overrideSupportsIntegrityEnhancementFacility	false	3.1.12
ultraDevHack	false	2.0.3

Table 6.17 JDBC compliance Properties

Name	Default Value	Since Version
useColumnNamesInFindColumn	false	5.1.7
pedantic	false	3.0.0
useOldAliasMetadataBehavior	false	5.0.4

Table 6.18 X Protocol and X DevAPI Properties

Name	Default Value	Since Version
xdevapi.auth	PLAIN	8.0.8
xdevapi.compression	PREFERRED	8.0.20
xdevapi.compression-algorithms	zstd_stream,lz4_message,deflate_stream	8.0.22
xdevapi.compression-extensions	-	8.0.22
xdevapi.connect-timeout	10000	8.0.13
xdevapi.connection-attributes	-	8.0.16
xdevapi.dns-srv	false	8.0.19
xdevapi.fallback-to-system-keystore	true	8.0.22
xdevapi.fallback-to-system-truststore	true	8.0.22
xdevapi.ssl-keystore	-	8.0.22
xdevapi.ssl-keystore-password	-	8.0.22
xdevapi.ssl-keystore-type	JKS	8.0.22
xdevapi.ssl-mode	REQUIRED	8.0.7
xdevapi.ssl-truststore	-	6.0.6
xdevapi.ssl-truststore-password	-	6.0.6
xdevapi.ssl-truststore-type	JKS	6.0.6
xdevapi.tls-ciphersuites	-	8.0.19
xdevapi.tls-versions	-	8.0.19