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.jdbc2.optional.MysqlDataSource

com.mysql.cj.jdbc.jdbc2.optional.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.DataSourcesetURL() 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
&amp; to separate configuration
parameters, as the ampersand is a reserved character for
XML.

The properties are listed in the following tables.

Authentication.

Properties and Descriptions

user

The user to connect as

Since version: all versions

password

The password to use when connecting

Since version: all versions

Connection.

Properties and Descriptions

connectionAttributes

A comma-delimited list of user-defined key:value pairs
(in addition to standard MySQL-defined key:value
pairs) to be passed to MySQL Server for display as
connection attributes in the
PERFORMANCE_SCHEMA.SESSION_CONNECT_ATTRS table.
Example usage:
connectionAttributes=key1:value1,key2:value2 This
functionality is available for use with MySQL Server
version 5.6 or later only. Earlier versions of MySQL
Server do not support connection attributes, causing
this configuration option to be ignored. Setting
connectionAttributes=none will cause connection
attribute processing to be bypassed, for situations
where Connection creation/initialization speed is
critical.

Since version: 5.1.25

connectionLifecycleInterceptors

A comma-delimited list of classes that implement
"com.mysql.cj.api.jdbc.interceptors.ConnectionLifecycleInterceptor"
that should notified of connection lifecycle events
(creation, destruction, commit, rollback, setCatalog
and setAutoCommit) and potentially alter the execution
of these commands. ConnectionLifecycleInterceptors are
"stackable", more than one interceptor may be
specified via the configuration property as a
comma-delimited list, with the interceptors executed
in order from left to right.

Since version: 5.1.4

useConfigs

Load the comma-delimited list of configuration
properties before parsing the URL or applying
user-specified properties. These configurations are
explained in the 'Configurations' of the
documentation.

Since version: 3.1.5

authenticationPlugins

Comma-delimited list of classes that implement
com.mysql.cj.api.mysqla.authentication.AuthenticationPlugin
and which will be used for authentication unless
disabled by "disabledAuthenticationPlugins" property.

Since version: 5.1.19

createDatabaseIfNotExist

Creates the database given in the URL if it doesn't
yet exist. Assumes the configured user has permissions
to create databases.

Default: false

Since version: 3.1.9

defaultAuthenticationPlugin

Name of a class implementing
com.mysql.cj.api.mysqla.authentication.AuthenticationPlugin
which will be used as the default authentication
plugin (see below). It is an error to use a class
which is not listed in "authenticationPlugins" nor it
is one of the built-in plugins. It is an error to set
as default a plugin which was disabled with
"disabledAuthenticationPlugins" property. It is an
error to set this value to null or the empty string
(i.e. there must be at least a valid default
authentication plugin specified for the connection,
meeting all constraints listed above).

Default:
com.mysql.cj.mysqla.authentication.MysqlNativePasswordPlugin

Since version: 5.1.19

detectCustomCollations

Should the driver detect custom charsets/collations
installed on server (true/false, defaults to 'false').
If this option set to 'true' driver gets actual
charsets/collations from server each time connection
establishes. This could slow down connection
initialization significantly.

Default: false

Since version: 5.1.29

disabledAuthenticationPlugins

Comma-delimited list of classes implementing
com.mysql.cj.api.mysqla.authentication.AuthenticationPlugin
or mechanisms, i.e. "mysql_native_password". The
authentication plugins or mechanisms listed will not
be used for authentication which will fail if it
requires one of them. It is an error to disable the
default authentication plugin (either the one named by
"defaultAuthenticationPlugin" property or the
hard-coded one if "defaultAuthenticationPlugin"
property is not set).

Since version: 5.1.19

disconnectOnExpiredPasswords

If "disconnectOnExpiredPasswords" is set to "false"
and password is expired then server enters "sandbox"
mode and sends ERR(08001, ER_MUST_CHANGE_PASSWORD) for
all commands that are not needed to set a new password
until a new password is set.

Default: true

Since version: 5.1.23

interactiveClient

Set the CLIENT_INTERACTIVE flag, which tells MySQL to
timeout connections based on INTERACTIVE_TIMEOUT
instead of WAIT_TIMEOUT

Default: false

Since version: 3.1.0

passwordCharacterEncoding

What character encoding is used for passwords? Leaving
this set to the default value (null), uses the value
set in "characterEncoding" if there is one, otherwise
uses UTF-8 as default encoding. If the password
contains non-ASCII characters, the password encoding
must match what server encoding was set to when the
password was created. For passwords in other character
encodings, the encoding will have to be specified with
this property (or with "characterEncoding"), as it's
not possible for the driver to auto-detect this.

Since version: 5.1.7

propertiesTransform

An implementation of
com.mysql.cj.api.conf.ConnectionPropertiesTransform
that the driver will use to modify URL properties
passed to the driver before attempting a connection

Since version: 3.1.4

rollbackOnPooledClose

Should the driver issue a rollback() when the logical
connection in a pool is closed?

Default: true

Since version: 3.0.15

useAffectedRows

Don't set the CLIENT_FOUND_ROWS flag when connecting
to the server (not JDBC-compliant, will break most
applications that rely on "found" rows vs. "affected
rows" for DML statements), but does cause "correct"
update counts from "INSERT ... ON DUPLICATE KEY
UPDATE" statements to be returned by the server.

Default: false

Since version: 5.1.7

Session.

Properties and Descriptions

characterEncoding

What character encoding should the driver use when
dealing with strings? (defaults is to 'autodetect')

Since version: 1.1g

characterSetResults

Character set to tell the server to return results as.

Since version: 3.0.13

connectionCollation

If set, tells the server to use this collation via
'set collation_connection'

Since version: 3.0.13

sessionVariables

A comma or semicolon separated list of name=value
pairs to be sent as SET [SESSION] ... to the server
when the driver connects.

Since version: 3.1.8

useOldUTF8Behavior

Use the UTF-8 behavior the driver did when
communicating with 4.0 and older servers

Default: false

Since version: 3.1.6

Networking.

Properties and Descriptions

socksProxyHost

Name or IP address of SOCKS host to connect through.

Since version: 5.1.34

socksProxyPort

Port of SOCKS server.

Default: 1080

Since version: 5.1.34

socketFactory

The name of the class that the driver should use for
creating socket connections to the server. This class
must implement the interface
'com.mysql.cj.api.io.SocketFactory' and have public
no-args constructor.

Default: com.mysql.cj.core.io.StandardSocketFactory

Since version: 3.0.3

connectTimeout

Timeout for socket connect (in milliseconds), with 0
being no timeout. Only works on JDK-1.4 or newer.
Defaults to '0'.

Hostname or IP address given to explicitly configure
the interface that the driver will bind the client
side of the TCP/IP connection to when connecting.

Since version: 5.0.5

maxAllowedPacket

Maximum allowed packet size to send to server. If not
set, the value of system variable 'max_allowed_packet'
will be used to initialize this upon connecting. This
value will not take effect if set larger than the
value of 'max_allowed_packet'. Also, due to an
internal dependency with the property
"blobSendChunkSize", this setting has a minimum value
of "8203" if "useServerPrepStmts" is set to "true".

Default: 65535

Since version: 5.1.8

tcpKeepAlive

If connecting using TCP/IP, should the driver set
SO_KEEPALIVE?

Default: true

Since version: 5.0.7

tcpNoDelay

If connecting using TCP/IP, should the driver set
SO_TCP_NODELAY (disabling the Nagle Algorithm)?

Default: true

Since version: 5.0.7

tcpRcvBuf

If connecting using TCP/IP, should the driver set
SO_RCV_BUF to the given value? The default value of
'0', means use the platform default value for this
property)

Default: 0

Since version: 5.0.7

tcpSndBuf

If connecting using TCP/IP, should the driver set
SO_SND_BUF to the given value? The default value of
'0', means use the platform default value for this
property)

Default: 0

Since version: 5.0.7

tcpTrafficClass

If connecting using TCP/IP, should the driver set
traffic class or type-of-service fields ?See the
documentation for java.net.Socket.setTrafficClass()
for more information.

Default: 0

Since version: 5.0.7

useCompression

Use zlib compression when communicating with the
server (true/false)? Defaults to 'false'.

Default: false

Since version: 3.0.17

useUnbufferedInput

Don't use BufferedInputStream for reading data from
the server

Default: true

Since version: 3.0.11

Security.

Properties and Descriptions

allowMultiQueries

Allow the use of ';' to delimit multiple queries
during one statement (true/false), defaults to
'false', and does not affect the addBatch() and
executeBatch() methods, which instead rely on
rewriteBatchStatements.

Default: false

Since version: 3.1.1

useSSL

Use SSL when communicating with the server
(true/false), default is 'true' when connecting to
MySQL 5.5.45+, 5.6.26+ or 5.7.6+, otherwise default is
'false'

Default: false

Since version: 3.0.2

requireSSL

Require server support of SSL connection if
useSSL=true? (defaults to 'false').

Default: false

Since version: 3.1.0

verifyServerCertificate

If "useSSL" is set to "true", should the driver verify
the server's certificate? When using this feature, the
keystore parameters should be specified by the
"clientCertificateKeyStore*" properties, rather than
system properties. Default is 'false' when connecting
to MySQL 5.5.45+, 5.6.26+ or 5.7.6+ and "useSSL" was
not explicitly set to "true". Otherwise default is
'true'

Default: true

Since version: 5.1.6

clientCertificateKeyStoreUrl

URL to the client certificate KeyStore (if not
specified, use defaults)

Since version: 5.1.0

clientCertificateKeyStoreType

KeyStore type for client certificates (NULL or empty
means use the default, which is "JKS". Standard
keystore types supported by the JVM are "JKS" and
"PKCS12", your environment may have more available
depending on what security products are installed and
available to the JVM.

Default: JKS

Since version: 5.1.0

clientCertificateKeyStorePassword

Password for the client certificates KeyStore

Since version: 5.1.0

trustCertificateKeyStoreUrl

URL to the trusted root certificate KeyStore (if not
specified, use defaults)

Since version: 5.1.0

trustCertificateKeyStoreType

KeyStore type for trusted root certificates (NULL or
empty means use the default, which is "JKS". Standard
keystore types supported by the JVM are "JKS" and
"PKCS12", your environment may have more available
depending on what security products are installed and
available to the JVM.

Default: JKS

Since version: 5.1.0

trustCertificateKeyStorePassword

Password for the trusted root certificates KeyStore

Since version: 5.1.0

enabledSSLCipherSuites

If "useSSL" is set to "true", overrides the cipher
suites enabled for use on the underlying SSL sockets.
This may be required when using external JSSE
providers or to specify cipher suites compatible with
both MySQL server and used JVM.

Since version: 5.1.35

enabledTLSProtocols

If "useSSL" is set to "true", overrides the TLS
protocols enabled for use on the underlying SSL
sockets. This may be used to restrict connections to
specific TLS versions.

Since version: 8.0.8

allowLoadLocalInfile

Should the driver allow use of 'LOAD DATA LOCAL
INFILE...' (defaults to 'true').

Default: true

Since version: 3.0.3

allowUrlInLocalInfile

Should the driver allow URLs in 'LOAD DATA LOCAL
INFILE' statements?

Default: false

Since version: 3.1.4

allowPublicKeyRetrieval

Allows special handshake roundtrip to get server RSA
public key directly from server.

File path to the server RSA public key file for
sha256_password authentication. If not specified, the
public key will be retrieved from the server.

Since version: 5.1.31

Statements.

Properties and Descriptions

continueBatchOnError

Should the driver continue processing batch commands
if one statement fails. The JDBC spec allows either
way (defaults to 'true').

Default: true

Since version: 3.0.3

dontTrackOpenResources

The JDBC specification requires the driver to
automatically track and close resources, however if
your application doesn't do a good job of explicitly
calling close() on statements or result sets, this can
cause memory leakage. Setting this property to true
relaxes this constraint, and can be more memory
efficient for some applications. Also the automatic
closing of the Statement and current ResultSet in
Statement.closeOnCompletion() and
Statement.getMoreResults
([Statement.CLOSE_CURRENT_RESULT |
Statement.CLOSE_ALL_RESULTS]), respectively, ceases to
happen. This property automatically sets
holdResultsOpenOverStatementClose=true.

Default: false

Since version: 3.1.7

queryInterceptors

A comma-delimited list of classes that implement
"com.mysql.cj.api.interceptors.QueryInterceptor" that
should be placed "in between" query execution to
influence the results. QueryInterceptors are
"chainable", the results returned by the "current"
interceptor will be passed on to the next in in the
chain, from left-to-right order, as specified in this
property.

Since version: 8.0.7

queryTimeoutKillsConnection

If the timeout given in Statement.setQueryTimeout()
expires, should the driver forcibly abort the
Connection instead of attempting to abort the query?

Default: false

Since version: 5.1.9

Prepared Statements.

Properties and Descriptions

allowNanAndInf

Should the driver allow NaN or +/- INF values in
PreparedStatement.setDouble()?

Should the driver detect prepared statements that are
not supported by the server, and replace them with
client-side emulated versions?

Default: true

Since version: 3.1.7

generateSimpleParameterMetadata

Should the driver generate simplified parameter
metadata for PreparedStatements when no metadata is
available either because the server couldn't support
preparing the statement, or server-side prepared
statements are disabled?

Default: false

Since version: 5.0.5

processEscapeCodesForPrepStmts

Should the driver process escape codes in queries that
are prepared? Default escape processing behavior in
non-prepared statements must be defined with the
property 'enableEscapeProcessing'.

This will cause a 'streaming' ResultSet to be
automatically closed, and any outstanding data still
streaming from the server to be discarded if another
query is executed before all the data has been read
from the server.

Default: false

Since version: 3.0.9

emptyStringsConvertToZero

Should the driver allow conversions from empty string
fields to numeric values of '0'?

Default: true

Since version: 3.1.8

holdResultsOpenOverStatementClose

Should the driver close result sets on
Statement.close() as required by the JDBC
specification?

Default: false

Since version: 3.1.7

jdbcCompliantTruncation

Should the driver throw java.sql.DataTruncation
exceptions when data is truncated as is required by
the JDBC specification when connected to a server that
supports warnings (MySQL 4.1.0 and newer)? This
property has no effect if the server sql-mode includes
STRICT_TRANS_TABLES.

Default: true

Since version: 3.1.2

maxRows

The maximum number of rows to return (0, the default
means return all rows).

Default: -1

Since version: all versions

netTimeoutForStreamingResults

What value should the driver automatically set the
server setting 'net_write_timeout' to when the
streaming result sets feature is in use? (value has
unit of seconds, the value '0' means the driver will
not try and adjust this value)

Default: 600

Since version: 5.1.0

padCharsWithSpace

If a result set column has the CHAR type and the value
does not fill the amount of characters specified in
the DDL for the column, should the driver pad the
remaining characters with space (for ANSI compliance)?

Default: false

Since version: 5.0.6

populateInsertRowWithDefaultValues

When using ResultSets that are CONCUR_UPDATABLE,
should the driver pre-populate the "insert" row with
default values from the DDL for the table used in the
query so those values are immediately available for
ResultSet accessors? This functionality requires a
call to the database for metadata each time a result
set of this type is created. If disabled (the
default), the default values will be populated by the
an internal call to refreshRow() which pulls back
default values and/or values changed by triggers.

Default: false

Since version: 5.0.5

strictUpdates

Should the driver do strict checking (all primary keys
selected) of updatable result sets (true, false,
defaults to 'true')?

Default: true

Since version: 3.0.4

tinyInt1isBit

Should the driver treat the datatype TINYINT(1) as the
BIT type (because the server silently converts BIT
-> TINYINT(1) when creating tables)?

Default: true

Since version: 3.0.16

transformedBitIsBoolean

If the driver converts TINYINT(1) to a different type,
should it use BOOLEAN instead of BIT for future
compatibility with MySQL-5.0, as MySQL-5.0 has a BIT
type?

Default: false

Since version: 3.1.9

Metadata.

Properties and Descriptions

getProceduresReturnsFunctions

Pre-JDBC4 DatabaseMetaData API has only the
getProcedures() and getProcedureColumns() methods, so
they return metadata info for both stored procedures
and functions. JDBC4 was extended with the
getFunctions() and getFunctionColumns() methods and
the expected behaviours of previous methods are not
well defined. For JDBC4 and higher, default 'true'
value of the option means that calls of
DatabaseMetaData.getProcedures() and
DatabaseMetaData.getProcedureColumns() return metadata
for both procedures and functions as before, keeping
backward compatibility. Setting this property to
'false' decouples Connector/J from its pre-JDBC4
behaviours for DatabaseMetaData.getProcedures() and
DatabaseMetaData.getProcedureColumns(), forcing them
to return metadata for procedures only.

When DatabaseMetadataMethods ask for a 'catalog'
parameter, does the value null mean use the current
catalog?

Default: false

Since version: 3.1.8

useHostsInPrivileges

Add '@hostname' to users in
DatabaseMetaData.getColumn/TablePrivileges()
(true/false), defaults to 'true'.

Default: true

Since version: 3.0.2

useInformationSchema

Should the driver use the INFORMATION_SCHEMA to derive
information used by DatabaseMetaData? Default is
'true' when connecting to MySQL 8.0.3+, otherwise
default is 'false'.

Default: false

Since version: 5.0.0

BLOB/CLOB processing.

Properties and Descriptions

autoDeserialize

Should the driver automatically detect and
de-serialize objects stored in BLOB fields?

Default: false

Since version: 3.1.5

blobSendChunkSize

Chunk size to use when sending BLOB/CLOBs via
ServerPreparedStatements. Note that this value cannot
exceed the value of "maxAllowedPacket" and, if that is
the case, then this value will be corrected
automatically.

Default: 1048576

Since version: 3.1.9

blobsAreStrings

Should the driver always treat BLOBs as Strings -
specifically to work around dubious metadata returned
by the server for GROUP BY clauses?

Default: false

Since version: 5.0.8

clobCharacterEncoding

The character encoding to use for sending and
retrieving TEXT, MEDIUMTEXT and LONGTEXT values
instead of the configured connection characterEncoding

Since version: 5.0.0

emulateLocators

Should the driver emulate java.sql.Blobs with
locators? With this feature enabled, the driver will
delay loading the actual Blob data until the one of
the retrieval methods (getInputStream(), getBytes(),
and so forth) on the blob data stream has been
accessed. For this to work, you must use a column
alias with the value of the column to the actual name
of the Blob. The feature also has the following
restrictions: The SELECT that created the result set
must reference only one table, the table must have a
primary key; the SELECT must alias the original blob
column name, specified as a string, to an alternate
name; the SELECT must cover all columns that make up
the primary key.

Default: false

Since version: 3.1.0

functionsNeverReturnBlobs

Should the driver always treat data from functions
returning BLOBs as Strings - specifically to work
around dubious metadata returned by the server for
GROUP BY clauses?

Default: false

Since version: 5.0.8

locatorFetchBufferSize

If 'emulateLocators' is configured to 'true', what
size buffer should be used when fetching BLOB data for
getBinaryInputStream?

Send fractional part from TIMESTAMP seconds. If set to
false, the nanoseconds value of TIMESTAMP values will
be truncated before sending any data to the server.
This option applies only to prepared statements,
callable statements or updatable result sets.

Default: true

Since version: 5.1.37

serverTimezone

Override detection/mapping of time zone. Used when
time zone from server doesn't map to Java time zone

Since version: 3.0.2

treatUtilDateAsTimestamp

Should the driver treat java.util.Date as a TIMESTAMP
for the purposes of PreparedStatement.setObject()?

Default: true

Since version: 5.0.5

yearIsDateType

Should the JDBC driver treat the MySQL type "YEAR" as
a java.sql.Date, or as a SHORT?

Default: true

Since version: 3.1.9

zeroDateTimeBehavior

What should happen when the driver encounters DATETIME
values that are composed entirely of zeros (used by
MySQL to represent invalid dates)? Valid values are
"EXCEPTION", "ROUND" and "CONVERT_TO_NULL".

Default: EXCEPTION

Since version: 3.1.4

High Availability and Clustering.

Properties and Descriptions

autoReconnect

Should the driver try to re-establish stale and/or
dead connections? If enabled the driver will throw an
exception for a queries issued on a stale or dead
connection, which belong to the current transaction,
but will attempt reconnect before the next query
issued on the connection in a new transaction. The use
of this feature is not recommended, because it has
side effects related to session state and data
consistency when applications don't handle
SQLExceptions properly, and is only designed to be
used when you are unable to configure your application
to handle SQLExceptions resulting from dead and stale
connections properly. Alternatively, as a last option,
investigate setting the MySQL server variable
"wait_timeout" to a high value, rather than the
default of 8 hours.

Default: false

Since version: 1.1

autoReconnectForPools

Use a reconnection strategy appropriate for connection
pools (defaults to 'false')

Default: false

Since version: 3.1.3

failOverReadOnly

When failing over in autoReconnect mode, should the
connection be set to 'read-only'?

Default: true

Since version: 3.0.12

maxReconnects

Maximum number of reconnects to attempt if
autoReconnect is true, default is '3'.

Default: 3

Since version: 1.1

reconnectAtTxEnd

If autoReconnect is set to true, should the driver
attempt reconnections at the end of every transaction?

Default: false

Since version: 3.0.10

retriesAllDown

When using loadbalancing or failover, the number of
times the driver should cycle through available hosts,
attempting to connect. Between cycles, the driver will
pause for 250ms if no servers are available.

Default: 120

Since version: 5.1.6

initialTimeout

If autoReconnect is enabled, the initial time to wait
between re-connect attempts (in seconds, defaults to
'2').

Default: 2

Since version: 1.1

queriesBeforeRetryMaster

Number of queries to issue before falling back to the
primary host when failed over (when using multi-host
failover). Whichever condition is met first,
'queriesBeforeRetryMaster' or
'secondsBeforeRetryMaster' will cause an attempt to be
made to reconnect to the primary host. Setting both
properties to 0 disables the automatic fall back to
the primary host at transaction boundaries. Defaults
to 50.

Default: 50

Since version: 3.0.2

secondsBeforeRetryMaster

How long should the driver wait, when failed over,
before attempting to reconnect to the primary host?
Whichever condition is met first,
'queriesBeforeRetryMaster' or
'secondsBeforeRetryMaster' will cause an attempt to be
made to reconnect to the master. Setting both
properties to 0 disables the automatic fall back to
the primary host at transaction boundaries. Time in
seconds, defaults to 30

Default: 30

Since version: 3.0.2

allowMasterDownConnections

By default, a replication-aware connection will fail
to connect when configured master hosts are all
unavailable at initial connection. Setting this
property to 'true' allows to establish the initial
connection, by failing over to the slave servers, in
read-only state. It won't prevent subsequent failures
when switching back to the master hosts i.e. by
setting the replication connection to read/write
state.

Default: false

Since version: 5.1.27

allowSlaveDownConnections

By default, a replication-aware connection will fail
to connect when configured slave hosts are all
unavailable at initial connection. Setting this
property to 'true' allows to establish the initial
connection. It won't prevent failures when switching
to slaves i.e. by setting the replication connection
to read-only state. The property
'readFromMasterWhenNoSlaves' should be used for this
purpose.

Default: false

Since version: 6.0.2

ha.enableJMX

Enables JMX-based management of load-balanced
connection groups, including live addition/removal of
hosts from load-balancing pool. Enables JMX-based
management of replication connection groups, including
live slave promotion, addition of new slaves and
removal of master or slave hosts from load-balanced
master and slave connection pools.

Default: false

Since version: 5.1.27

loadBalanceHostRemovalGracePeriod

Sets the grace period to wait for a host being removed
from a load-balanced connection, to be released when
it is currently the active host.

Default: 15000

Since version: 6.0.3

readFromMasterWhenNoSlaves

Replication-aware connections distribute load by using
the master hosts when in read/write state and by using
the slave hosts when in read-only state. If, when
setting the connection to read-only state, none of the
slave hosts are available, an SQLExeception is thrown
back. Setting this property to 'true' allows to fail
over to the master hosts, while setting the connection
state to read-only, when no slave hosts are available
at switch instant.

Default: false

Since version: 6.0.2

selfDestructOnPingMaxOperations

If set to a non-zero value, the driver will report
close the connection and report failure when
Connection.ping() or Connection.isValid(int) is called
if the connection's count of commands sent to the
server exceeds this value.

Default: 0

Since version: 5.1.6

selfDestructOnPingSecondsLifetime

If set to a non-zero value, the driver will close the
connection and report failure when Connection.ping()
or Connection.isValid(int) is called if the
connection's lifetime exceeds this value (in
milliseconds).

Default: 0

Since version: 5.1.6

ha.loadBalanceStrategy

If using a load-balanced connection to connect to SQL
nodes in a MySQL Cluster/NDB configuration (by using
the URL prefix "jdbc:mysql:loadbalance://"), which
load balancing algorithm should the driver use: (1)
"random" - the driver will pick a random host for each
request. This tends to work better than round-robin,
as the randomness will somewhat account for spreading
loads where requests vary in response time, while
round-robin can sometimes lead to overloaded nodes if
there are variations in response times across the
workload. (2) "bestResponseTime" - the driver will
route the request to the host that had the best
response time for the previous transaction. (3)
"serverAffinity" - the driver initially attempts to
enforce server affinity while still respecting and
benefiting from the fault tolerance aspects of the
load-balancing implementation. The server affinity
ordered list is provided using the property
'serverAffinityOrder'. If none of the servers listed
in the affinity list is responsive, the driver then
refers to the "random" strategy to proceed with
choosing the next server.

Default: random

Since version: 5.0.6

loadBalanceAutoCommitStatementRegex

When load-balancing is enabled for auto-commit
statements (via
loadBalanceAutoCommitStatementThreshold), the
statement counter will only increment when the SQL
matches the regular expression. By default, every
statement issued matches.

Since version: 5.1.15

loadBalanceAutoCommitStatementThreshold

When auto-commit is enabled, the number of statements
which should be executed before triggering
load-balancing to rebalance. Default value of 0 causes
load-balanced connections to only rebalance when
exceptions are encountered, or auto-commit is disabled
and transactions are explicitly committed or rolled
back.

Default: 0

Since version: 5.1.15

loadBalanceBlacklistTimeout

Time in milliseconds between checks of servers which
are unavailable, by controlling how long a server
lives in the global blacklist.

Default: 0

Since version: 5.1.0

loadBalanceConnectionGroup

Logical group of load-balanced connections within a
classloader, used to manage different groups
independently. If not specified, live management of
load-balanced connections is disabled.

Since version: 5.1.13

loadBalanceExceptionChecker

Fully-qualified class name of custom exception
checker. The class must implement
com.mysql.cj.api.jdbc.ha.LoadBalanceExceptionChecker
interface, and is used to inspect SQLExceptions and
determine whether they should trigger fail-over to
another host in a load-balanced deployment.

Default:
com.mysql.cj.jdbc.ha.StandardLoadBalanceExceptionChecker

Since version: 5.1.13

loadBalancePingTimeout

Time in milliseconds to wait for ping response from
each of load-balanced physical connections when using
load-balanced Connection.

Default: 0

Since version: 5.1.13

loadBalanceSQLExceptionSubclassFailover

Comma-delimited list of classes/interfaces used by
default load-balanced exception checker to determine
whether a given SQLException should trigger failover.
The comparison is done using
Class.isInstance(SQLException) using the thrown
SQLException.

Since version: 5.1.13

loadBalanceSQLStateFailover

Comma-delimited list of SQLState codes used by default
load-balanced exception checker to determine whether a
given SQLException should trigger failover. The
SQLState of a given SQLException is evaluated to
determine whether it begins with any value in the
comma-delimited list.

Since version: 5.1.13

loadBalanceValidateConnectionOnSwapServer

Should the load-balanced Connection explicitly check
whether the connection is live when swapping to a new
physical connection at commit/rollback?

Default: false

Since version: 5.1.13

pinGlobalTxToPhysicalConnection

When using XAConnections, should the driver ensure
that operations on a given XID are always routed to
the same physical connection? This allows the
XAConnection to support "XA START ... JOIN" after "XA
END" has been called

Default: false

Since version: 5.0.1

replicationConnectionGroup

Logical group of replication connections within a
classloader, used to manage different groups
independently. If not specified, live management of
replication connections is disabled.

Since version: 8.0.7

resourceId

A globally unique name that identifies the resource
that this datasource or connection is connected to,
used for XAResource.isSameRM() when the driver can't
determine this value based on hostnames used in the
URL

Since version: 5.0.1

serverAffinityOrder

A comma separated list containing the host/port pairs
that are to be used in load-balancing "serverAffinity"
strategy. Only the sub-set of the hosts enumerated in
the main hosts section in this URL will be used and
they must be identical in case and type, i.e., can't
use an IP address in one place and the corresponding
host name in the other.

Since version: 8.0.8

Performance Extensions.

Properties and Descriptions

callableStmtCacheSize

If 'cacheCallableStmts' is enabled, how many callable
statements should be cached?

Default: 100

Since version: 3.1.2

metadataCacheSize

The number of queries to cache ResultSetMetadata for
if cacheResultSetMetaData is set to 'true' (default
50)

Default: 50

Since version: 3.1.1

useLocalSessionState

Should the driver refer to the internal values of
autocommit and transaction isolation that are set by
Connection.setAutoCommit() and
Connection.setTransactionIsolation() and transaction
state as maintained by the protocol, rather than
querying the database or blindly sending commands to
the database for commit() or rollback() method calls?

Default: false

Since version: 3.1.7

useLocalTransactionState

Should the driver use the in-transaction state
provided by the MySQL protocol to determine if a
commit() or rollback() should actually be sent to the
database?

Default: false

Since version: 5.1.7

prepStmtCacheSize

If prepared statement caching is enabled, how many
prepared statements should be cached?

Default: 25

Since version: 3.0.10

prepStmtCacheSqlLimit

If prepared statement caching is enabled, what's the
largest SQL the driver will cache the parsing for?

Default: 256

Since version: 3.0.10

parseInfoCacheFactory

Name of a class implementing
com.mysql.cj.api.CacheAdapterFactory, which will be
used to create caches for the parsed representation of
client-side prepared statements.

Default: com.mysql.cj.mysqla.PerConnectionLRUFactory

Since version: 5.1.1

serverConfigCacheFactory

Name of a class implementing
com.mysql.cj.api.CacheAdapterFactory<String,
Map<String, String>>, which will be used to
create caches for MySQL server configuration values

Default:
com.mysql.cj.core.util.PerVmServerConfigCacheFactory

Since version: 5.1.1

alwaysSendSetIsolation

Should the driver always communicate with the database
when Connection.setTransactionIsolation() is called?
If set to false, the driver will only communicate with
the database when the requested transaction isolation
is different than the whichever is newer, the last
value that was set via
Connection.setTransactionIsolation(), or the value
that was read from the server when the connection was
established. Note that useLocalSessionState=true will
force the same behavior as
alwaysSendSetIsolation=false, regardless of how
alwaysSendSetIsolation is set.

Default: true

Since version: 3.1.7

maintainTimeStats

Should the driver maintain various internal timers to
enable idle time calculations as well as more verbose
error messages when the connection to the server
fails? Setting this property to false removes at least
two calls to System.getCurrentTimeMillis() per query.

Default: true

Since version: 3.1.9

useCursorFetch

Should the driver use cursor-based fetching to
retrieve rows? If set to "true" and "defaultFetchSize"
> 0 (or setFetchSize() > 0 is called on a
statement) then the cursor-based result set will be
used. Please note that "useServerPrepStmts" is
automatically set to "true" in this case because
cursor functionality is available only for server-side
prepared statements.

Default: false

Since version: 5.0.0

cacheCallableStmts

Should the driver cache the parsing stage of
CallableStatements

Default: false

Since version: 3.1.2

cachePrepStmts

Should the driver cache the parsing stage of
PreparedStatements of client-side prepared statements,
the "check" for suitability of server-side prepared
and server-side prepared statements themselves?

Should the driver cache the results of 'SHOW
VARIABLES' and 'SHOW COLLATION' on a per-URL basis?

Default: false

Since version: 3.1.5

defaultFetchSize

The driver will call setFetchSize(n) with this value
on all newly-created Statements

Default: 0

Since version: 3.1.9

dontCheckOnDuplicateKeyUpdateInSQL

Stops checking if every INSERT statement contains the
"ON DUPLICATE KEY UPDATE" clause. As a side effect,
obtaining the statement's generated keys information
will return a list where normally it wouldn't. Also be
aware that, in this case, the list of generated keys
returned may not be accurate. The effect of this
property is canceled if set simultaneously with
'rewriteBatchedStatements=true'.

Default: false

Since version: 5.1.32

elideSetAutoCommits

If using MySQL-4.1 or newer, should the driver only
issue 'set autocommit=n' queries when the server's
state doesn't match the requested state by
Connection.setAutoCommit(boolean)?

Default: false

Since version: 3.1.3

enableEscapeProcessing

Sets the default escape processing behavior for
Statement objects. The method
Statement.setEscapeProcessing() can be used to specify
the escape processing behavior for an individual
Statement object. Default escape processing behavior
in prepared statements must be defined with the
property 'processEscapeCodesForPrepStmts'.

Default: true

Since version: 6.0.1

enableQueryTimeouts

When enabled, query timeouts set via
Statement.setQueryTimeout() use a shared
java.util.Timer instance for scheduling. Even if the
timeout doesn't expire before the query is processed,
there will be memory used by the TimerTask for the
given timeout which won't be reclaimed until the time
the timeout would have expired if it hadn't been
cancelled by the driver. High-load environments might
want to consider disabling this functionality.

Default: true

Since version: 5.0.6

largeRowSizeThreshold

What size result set row should the JDBC driver
consider "large", and thus use a more memory-efficient
way of representing the row internally?

Default: 2048

Since version: 5.1.1

readOnlyPropagatesToServer

Should the driver issue appropriate statements to
implicitly set the transaction access mode on server
side when Connection.setReadOnly() is called? Setting
this property to 'true' enables InnoDB read-only
potential optimizations but also requires an extra
roundtrip to set the right transaction state. Even if
this property is set to 'false', the driver will do
its best effort to prevent the execution of
database-state-changing queries. Requires minimum of
MySQL 5.6.

Default: true

Since version: 5.1.35

rewriteBatchedStatements

Should the driver use multiqueries (irregardless of
the setting of "allowMultiQueries") as well as
rewriting of prepared statements for INSERT into
multi-value inserts when executeBatch() is called?
Notice that this has the potential for SQL injection
if using plain java.sql.Statements and your code
doesn't sanitize input correctly. Notice that for
prepared statements, server-side prepared statements
can not currently take advantage of this rewrite
option, and that if you don't specify stream lengths
when using PreparedStatement.set*Stream(), the driver
won't be able to determine the optimum number of
parameters per batch and you might receive an error
from the driver that the resultant packet is too
large. Statement.getGeneratedKeys() for these
rewritten statements only works when the entire batch
includes INSERT statements. Please be aware using
rewriteBatchedStatements=true with INSERT .. ON
DUPLICATE KEY UPDATE that for rewritten statement
server returns only one value as sum of all affected
(or found) rows in batch and it isn't possible to map
it correctly to initial statements; in this case
driver returns 0 as a result of each batch statement
if total count was 0, and the
Statement.SUCCESS_NO_INFO as a result of each batch
statement if total count was > 0.

Default: false

Since version: 3.1.13

useReadAheadInput

Use newer, optimized non-blocking, buffered input
stream when reading from the server?

Default: true

Since version: 3.1.5

Debugging/Profiling.

Properties and Descriptions

logger

The name of a class that implements
"com.mysql.cj.api.log.Log" that will be used to log
messages to. (default is
"com.mysql.cj.core.log.StandardLogger", which logs to
STDERR)

Default: com.mysql.cj.core.log.StandardLogger

Since version: 3.1.1

gatherPerfMetrics

Should the driver gather performance metrics, and
report them via the configured logger every
'reportMetricsIntervalMillis' milliseconds?

Default: false

Since version: 3.1.2

profileSQL

Trace queries and their execution/fetch times to the
configured logger (true/false) defaults to 'false'

Default: false

Since version: 3.1.0

reportMetricsIntervalMillis

If 'gatherPerfMetrics' is enabled, how often should
they be logged (in ms)?

Default: 30000

Since version: 3.1.2

maxQuerySizeToLog

Controls the maximum length/size of a query that will
get logged when profiling or tracing

Default: 2048

Since version: 3.1.3

packetDebugBufferSize

The maximum number of packets to retain when
'enablePacketDebug' is true

Default: 20

Since version: 3.1.3

slowQueryThresholdMillis

If 'logSlowQueries' is enabled, how long should a
query (in ms) before it is logged as 'slow'?

Default: 2000

Since version: 3.1.2

slowQueryThresholdNanos

If 'useNanosForElapsedTime' is set to true, and this
property is set to a non-zero value, the driver will
use this threshold (in nanosecond units) to determine
if a query was slow.

Default: 0

Since version: 5.0.7

useUsageAdvisor

Should the driver issue 'usage' warnings advising
proper and efficient usage of JDBC and MySQL
Connector/J to the log (true/false, defaults to
'false')?

Default: false

Since version: 3.1.1

autoGenerateTestcaseScript

Should the driver dump the SQL it is executing,
including server-side prepared statements to STDERR?

Default: false

Since version: 3.1.9

autoSlowLog

Instead of using slowQueryThreshold* to determine if a
query is slow enough to be logged, maintain statistics
that allow the driver to determine queries that are
outside the 99th percentile?

Default: true

Since version: 5.1.4

clientInfoProvider

The name of a class that implements the
com.mysql.cj.api.jdbc.ClientInfoProvider interface in
order to support JDBC-4.0's
Connection.get/setClientInfo() methods

Default: com.mysql.cj.jdbc.CommentClientInfoProvider

Since version: 5.1.0

enablePacketDebug

When enabled, a ring-buffer of 'packetDebugBufferSize'
packets will be kept, and dumped when exceptions are
thrown in key areas in the driver's code

Default: false

Since version: 3.1.3

explainSlowQueries

If 'logSlowQueries' is enabled, should the driver
automatically issue an 'EXPLAIN' on the server and
send the results to the configured log at a WARN
level?

Default: false

Since version: 3.1.2

logSlowQueries

Should queries that take longer than
'slowQueryThresholdMillis' be logged?

Default: false

Since version: 3.1.2

logXaCommands

Should the driver log XA commands sent by
MysqlXaConnection to the server, at the DEBUG level of
logging?

Default: false

Since version: 5.0.5

profilerEventHandler

Name of a class that implements the interface
com.mysql.cj.api.ProfilerEventHandler that will be
used to handle profiling/tracing events.

Default:
com.mysql.cj.core.profiler.LoggingProfilerEventHandler

Since version: 5.1.6

resultSetSizeThreshold

If the usage advisor is enabled, how many rows should
a result set contain before the driver warns that it
is suspiciously large?

Default: 100

Since version: 5.0.5

traceProtocol

Should trace-level network protocol be logged?

Default: false

Since version: 3.1.2

useNanosForElapsedTime

For profiling/debugging functionality that measures
elapsed time, should the driver try to use nanoseconds
resolution if available (JDK >= 1.5)?

Default: false

Since version: 5.0.7

useOnlyServerErrorMessages

Don't prepend 'standard' SQLState error messages to
error messages returned by the server.

Default: true

Since version: 3.0.15

Exceptions/Warnings.

Properties and Descriptions

dumpQueriesOnException

Should the driver dump the contents of the query sent
to the server in the message for SQLExceptions?

Default: false

Since version: 3.1.3

exceptionInterceptors

Comma-delimited list of classes that implement
com.mysql.cj.api.exceptions.ExceptionInterceptor.
These classes will be instantiated one per Connection
instance, and all SQLExceptions thrown by the driver
will be allowed to be intercepted by these
interceptors, in a chained fashion, with the first
class listed as the head of the chain.

Include the output of "SHOW ENGINE INNODB STATUS" in
exception messages when deadlock exceptions are
detected?

Default: false

Since version: 5.0.7

includeThreadDumpInDeadlockExceptions

Include a current Java thread dump in exception
messages when deadlock exceptions are detected?

Default: false

Since version: 5.1.15

includeThreadNamesAsStatementComment

Include the name of the current thread as a comment
visible in "SHOW PROCESSLIST", or in Innodb deadlock
dumps, useful in correlation with
"includeInnodbStatusInDeadlockExceptions=true" and
"includeThreadDumpInDeadlockExceptions=true".

Default: false

Since version: 5.1.15

Tunes for integration with other products.

Properties and Descriptions

overrideSupportsIntegrityEnhancementFacility

Should the driver return "true" for
DatabaseMetaData.supportsIntegrityEnhancementFacility()
even if the database doesn't support it to workaround
applications that require this method to return "true"
to signal support of foreign keys, even though the SQL
specification states that this facility contains much
more than just foreign key support (one such
application being OpenOffice)?

Default: false

Since version: 3.1.12

ultraDevHack

Create PreparedStatements for prepareCall() when
required, because UltraDev is broken and issues a
prepareCall() for _all_ statements? (true/false,
defaults to 'false')

Default: false

Since version: 2.0.3

JDBC compliance.

Properties and Descriptions

useColumnNamesInFindColumn

Prior to JDBC-4.0, the JDBC specification had a bug
related to what could be given as a "column name" to
ResultSet methods like findColumn(), or getters that
took a String property. JDBC-4.0 clarified "column
name" to mean the label, as given in an "AS" clause
and returned by ResultSetMetaData.getColumnLabel(),
and if no AS clause, the column name. Setting this
property to "true" will give behavior that is
congruent to JDBC-3.0 and earlier versions of the JDBC
specification, but which because of the specification
bug could give unexpected results. This property is
preferred over "useOldAliasMetadataBehavior" unless
you need the specific behavior that it provides with
respect to ResultSetMetadata.

Default: false

Since version: 5.1.7

pedantic

Follow the JDBC spec to the letter.

Default: false

Since version: 3.0.0

useOldAliasMetadataBehavior

Should the driver use the legacy behavior for "AS"
clauses on columns and tables, and only return aliases
(if any) for ResultSetMetaData.getColumnName() or
ResultSetMetaData.getTableName() rather than the
original column/table name? In 5.0.x, the default
value was true.

Default: false

Since version: 5.0.4

X Protocol and X DevAPI.

Properties and Descriptions

xdevapi.asyncResponseTimeout

Timeout (in seconds) for getting server response via X
Protocol.

Default: 300

Since version: 8.0.7

xdevapi.auth

Authentication mechanism to use with the X Protocol.
Allowed values are "MYSQL41", "PLAIN", and "EXTERNAL".
Value is case insensitive. If the property is not set,
the mechanism is chosen depending on the connection
type: "PLAIN" is used for TLS connections and
"MYSQL41" is used for unencrypted connections.

Since version: 8.0.8

xdevapi.ssl-mode

By default the network connections in X DevAPI
sessions are SSL encrypted. This property permits to
turn secure connections off or to choose different
levels of security. The following values are allowed:
DISABLED - Establish unencrypted connections; REQUIRED
- (default) Establish secure connections if the server
supports them, fails otherwise; VERIFY_CA - Like
REQUIRED but additionally verify the server TLS
certificate against the configured Certificate
Authority (CA) certificates; VERIFY_IDENTITY - Like
VERIFY_CA, but additionally verify that the server
certificate matches the host to which the connection
is attempted.

Default: REQUIRED

Since version: 8.0.7

xdevapi.ssl-truststore

URL to the trusted CA certificates key store (if not
specified, use defaults)

Since version: 6.0.6

xdevapi.ssl-truststore-password

Password for the trusted CA certificates key store

Since version: 6.0.6

xdevapi.ssl-truststore-type

Type of the trusted CA certificates key store (NULL or
empty means use the default, which is "JKS")

Default: JKS

Since version: 6.0.6

xdevapi.useAsyncProtocol

Use asynchronous variant of X Protocol

Default: true

Since version: 6.0.0

Properties for named pipe connections

Connector/J also supports access to MySQL using named pipes on
Windows platforms with the
NamedPipeSocketFactory as a plugin-sockets
factory. If you do not use a namedPipePath
property, the default of '\\.\pipe\MySQL' is
used. If you use the NamedPipeSocketFactory,
the host name and port number values in the JDBC URL are
ignored. To enable this feature, set the
socketFactory property:

To create your own socket factories, follow the sample code in
com.mysql.cj.core.io.NamedPipeSocketFactory
or
com.mysql.cj.core.io.StandardSocketFactory.

An alternate approach is to use the following two properties in
connection URLs for establishing named pipe connections on
Windows platforms:

(protocol=pipe) for named pipes (default
value for the property is tcp).

(path=path_to_pipe)
for path of named pipes. Default value for the path is
\\.\pipe\MySQL.

The “address-equals” or “key-value”
form of host specification (see
Single host for details)
greatly simplifies the URL for a named pipe connection on
Windows. For example, to use the default named pipe of
“\\.\pipe\MySQL,” just
specify:

jdbc:mysql://address=(protocol=pipe)/test

To use the custom named pipe of
“\\.\pipe\MySQL57” :

jdbc:mysql://address=(protocol=pipe)(path=\\.\pipe\MySQL57)/test

With (protocol=pipe), the
NamedPipeSocketFactory is automatically
selected.

Named pipes only work when connecting to a MySQL server on the
same physical machine where the JDBC driver is running. In
simple performance tests, named pipe access is between 30%-50%
faster than the standard TCP/IP access. However, this varies per
system, and named pipes are slower than TCP/IP in many Windows
configurations.