Specifying a data source name

If different clients are created using the same Vert.x instance and specifying the same data source name, they will
share the same data source.

The first call to JDBCClient.createShared
will actually create the data source, and the specified config will be used.

Subsequent calls will return a new client instance that uses the same data source, so the configuration won’t be used.

Use this way of creating if you wish different groups of clients to have different data sources, e.g. they’re
interacting with different databases.

Creating a client with a non shared data source

In most cases you will want to share a data source between different client instances.
However, it’s possible you want to create a client instance that doesn’t share its data source with any other client.

Configuration

Configuration is passed to the client when creating or deploying it.

The following configuration properties generally apply:

provider_class

The class name of the class actually used to manage the database connections. By default this is
`io.vertx.ext.jdbc.spi.impl.C3P0DataSourceProvider`but if you want to use a different provider you can override
this property and provide your implementation.

Assuming the C3P0 implementation is being used (the default), the following extra configuration properties apply:

url

the JDBC connection URL for the database

driver_class

the class of the JDBC driver

user

the username for the database

password

the password for the database

max_pool_size

the maximum number of connections to pool - default is 15

initial_pool_size

the number of connections to initialise the pool with - default is 3

min_pool_size

the minimum number of connections to pool

max_statements

the maximum number of prepared statements to cache - default is 0.

max_statements_per_connection

the maximum number of prepared statements to cache per connection - default is 0.

max_idle_time

number of seconds after which an idle connection will be closed - default is 0 (never expire).

Other Connection Pool providers are:

BoneCP

Hikari

Similar to C3P0 they can be configured by passing the configuration values on the JSON config object. For the special
case where you do not want to deploy your app as a fat jar but run with a vert.x distribution, then it is recommented
to use BoneCP if you have no write permissions to add the JDBC driver to the vert.x lib directory and are passing it
using the -cp command line flag.

If you want to configure any other C3P0 properties, you can add a file c3p0.properties to the classpath.

JDBC Drivers

If you are using the default DataSourceProvider (relying on c3p0), you would need to copy the JDBC driver class
in your classpath.

If your application is packaged as a fat jar, be sure to embed the jdbc driver. If your application is launched
with the vertx command line, copy the JDBC driver to ${VERTX_HOME}/lib.

The behavior may be different when using a different connection pool.

Data types

Due to the fact that Vert.x uses JSON as its standard message format there will be many limitations to the data types
accepted by the client. You will get out of the box the standard:

null

boolean

number

string

There is also an optimistic cast for temporal types (TIME, DATE, TIMESTAMP) and optionally disabled for UUID. UUIDs
are supported by many databases but not all. For example MySQL does not support it so the recommended way is to use
a VARCHAR(36) column. For other engines UUID optimistic casting can be enabled using the client config json as:

{ "UUIDCast": true }

When this config is present UUIDs will be handled as a native type.

Use as OSGi bundle

Vert.x JDBC client can be used as an OSGi bundle. However notice that you would need to deploy all dependencies
first. Some connection pool requires the JDBC driver to be loaded from the classpath, and so cannot be packaged /
deployed as bundle.