6.3 Configuration Properties

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
`defaultAuthenticationPlugin`	mysql_native_password	5.1.19
`ociConfigProfile`	DEFAULT	8.0.33
`authenticationFidoCallbackHandler`	-	8.0.29
`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
`maxByteArrayAsHex`	1024	8.0.31
`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