io.vertx.sqlclient

## Interface Pool

- All Superinterfaces:
    SqlClient
  All Known Subinterfaces:
    DB2Pool, JDBCPool, MSSQLPool, MySQLPool, PgPool

      public interface Pool
      extends SqlClient

  A connection pool which reuses a number of SQL connections.
  Author:
    Julien Viet

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close(Handler<AsyncResult<Void>> handler)` Close the pool and release the associated resources.
    `Pool` | `connectHandler(Handler<SqlConnection> handler)` Set an handler called when the pool has established a connection to the database.
    `Pool` | `connectionProvider(java.util.function.Function<Context,Future<SqlConnection>> provider)` Replace the default pool connection provider, the new `provider` returns a future connection for a given `Context`.
    `Future<SqlConnection>` | `getConnection()` Like `getConnection(Handler)` but returns a `Future` of the asynchronous result
    `void` | `getConnection(Handler<AsyncResult<SqlConnection>> handler)` Get a connection from the pool.
    `static Pool` | `pool(SqlConnectOptions connectOptions)` Like `pool(SqlConnectOptions, PoolOptions)` with default options.
    `static Pool` | `pool(SqlConnectOptions database, PoolOptions options)` Like `pool(Vertx, SqlConnectOptions, PoolOptions)` with a Vert.x instance created automatically.
    `static Pool` | `pool(Vertx vertx, SqlConnectOptions database, PoolOptions options)` Create a connection pool to the `database` with the given `options`.
    `PreparedQuery<RowSet<Row>>` | `preparedQuery(String sql)` Create a prepared query, one of the `PreparedQuery.execute(io.vertx.sqlclient.Tuple, io.vertx.core.Handler<io.vertx.core.AsyncResult<T>>)` or `PreparedQuery.executeBatch(java.util.List<io.vertx.sqlclient.Tuple>, io.vertx.core.Handler<io.vertx.core.AsyncResult<T>>)` methods must be called to execute the query.
    `Query<RowSet<Row>>` | `query(String sql)` Create a query, the `Query.execute(io.vertx.core.Handler<io.vertx.core.AsyncResult<T>>)` method must be called to execute the query.
    `int` | `size()`
    `default <T> Future<T>` | `withConnection(java.util.function.Function<SqlConnection,Future<T>> function)` Like `withConnection(Function, Handler)` but returns a `Future` of the asynchronous result
    `default <T> void` | `withConnection(java.util.function.Function<SqlConnection,Future<T>> function, Handler<AsyncResult<T>> handler)` Get a connection from the pool and execute the given `function`.
    `default <T> Future<T>` | `withTransaction(java.util.function.Function<SqlConnection,Future<T>> function)` Like `withTransaction(Function, Handler)` but returns a `Future` of the asynchronous result.
    `default <T> void` | `withTransaction(java.util.function.Function<SqlConnection,Future<T>> function, Handler<AsyncResult<T>> handler)` Execute the given `function` within a transaction.
    `default <T> Future<T>` | `withTransaction(TransactionPropagation txPropagation, java.util.function.Function<SqlConnection,Future<T>> function)` Like `withTransaction(Function)` but allows for setting the mode, defining how the acquired connection is managed during the execution of the function.
    `default <T> void` | `withTransaction(TransactionPropagation txPropagation, java.util.function.Function<SqlConnection,Future<T>> function, Handler<AsyncResult<T>> handler)` Like `withTransaction(Function, Handler)` but allows for setting the mode, defining how the acquired connection is managed during the execution of the function.

    - ### Methods inherited from interface io.vertx.sqlclient.SqlClient

      `close, preparedQuery`

- - ### Method Detail

    - #### pool

          static Pool pool(SqlConnectOptions connectOptions)

      Like `pool(SqlConnectOptions, PoolOptions)` with default options.

    - #### pool

          static Pool pool(SqlConnectOptions database,
                           PoolOptions options)

      Like `pool(Vertx, SqlConnectOptions, PoolOptions)` with a Vert.x instance created automatically.

    - #### pool

          static Pool pool(Vertx vertx,
                           SqlConnectOptions database,
                           PoolOptions options)

      Create a connection pool to the `database` with the given `options`.

      A `Driver` will be selected among the drivers found on the classpath returning `true` when `Driver.acceptsOptions(SqlConnectOptions)` applied to the first options of the list.

      Parameters:
        `vertx` - the Vertx instance to be used with the connection pool
        `database` - the options used to create the connection pool, such as database hostname
        `options` - the options for creating the pool
      Returns:
        the connection pool
      Throws:
        `ServiceConfigurationError` - if no compatible drivers are found, or if multiple compatible drivers are found

    - #### getConnection

          void getConnection(Handler<AsyncResult<SqlConnection>> handler)

      Get a connection from the pool.
      Parameters:
        `handler` - the handler that will get the connection result

    - #### getConnection

          Future<SqlConnection> getConnection()

      Like `getConnection(Handler)` but returns a `Future` of the asynchronous result

    - #### query

          Query<RowSet<Row>> query(String sql)

      Create a query, the `Query.execute(io.vertx.core.Handler<io.vertx.core.AsyncResult<T>>)` method must be called to execute the query. A connection is borrowed from the connection pool when the query is executed and then immediately returned to the pool after it completes.
      Specified by:
        `query` in interface `SqlClient`
      Returns:
        the query

    - #### preparedQuery

          PreparedQuery<RowSet<Row>> preparedQuery(String sql)

      Create a prepared query, one of the `PreparedQuery.execute(io.vertx.sqlclient.Tuple, io.vertx.core.Handler<io.vertx.core.AsyncResult<T>>)` or `PreparedQuery.executeBatch(java.util.List<io.vertx.sqlclient.Tuple>, io.vertx.core.Handler<io.vertx.core.AsyncResult<T>>)` methods must be called to execute the query. A connection is borrowed from the connection pool when the query is executed and then immediately returned to the pool after it completes.
      Specified by:
        `preparedQuery` in interface `SqlClient`
      Returns:
        the prepared query

    - #### withTransaction

          default <T> void withTransaction(java.util.function.Function<SqlConnection,Future<T>> function,
                                           Handler<AsyncResult<T>> handler)

      Execute the given `function` within a transaction.

      The `function` is passed a client executing all operations within a transaction. When the future returned by the function

      - succeeds the transaction commits
      - fails the transaction rollbacks

      The `handler` is given a success result when the function returns a succeeded futures and the transaction commits. Otherwise it is given a failure result.

      Parameters:
        `function` - the code to execute
        `handler` - the result handler

    - #### withTransaction

          default <T> Future<T> withTransaction(java.util.function.Function<SqlConnection,Future<T>> function)

      Like `withTransaction(Function, Handler)` but returns a `Future` of the asynchronous result.

    - #### withTransaction

          default <T> void withTransaction(TransactionPropagation txPropagation,
                                           java.util.function.Function<SqlConnection,Future<T>> function,
                                           Handler<AsyncResult<T>> handler)

      Like `withTransaction(Function, Handler)` but allows for setting the mode, defining how the acquired connection is managed during the execution of the function.

    - #### withTransaction

          default <T> Future<T> withTransaction(TransactionPropagation txPropagation,
                                                java.util.function.Function<SqlConnection,Future<T>> function)

      Like `withTransaction(Function)` but allows for setting the mode, defining how the acquired connection is managed during the execution of the function.

    - #### withConnection

          default <T> void withConnection(java.util.function.Function<SqlConnection,Future<T>> function,
                                          Handler<AsyncResult<T>> handler)

      Get a connection from the pool and execute the given `function`.

      When the future returned by the `function` completes, the connection is returned to the pool.

      The `handler` is given a success result when the function returns a succeeded futures. Otherwise it is given a failure result.

      Parameters:
        `function` - the code to execute
        `handler` - the result handler

    - #### withConnection

          default <T> Future<T> withConnection(java.util.function.Function<SqlConnection,Future<T>> function)

      Like `withConnection(Function, Handler)` but returns a `Future` of the asynchronous result

    - #### close

          void close(Handler<AsyncResult<Void>> handler)

      Close the pool and release the associated resources.
      Specified by:
        `close` in interface `SqlClient`
      Parameters:
        `handler` - the completion handler

    - #### connectHandler

          Pool connectHandler(Handler<SqlConnection> handler)

      Set an handler called when the pool has established a connection to the database.

      This handler allows interactions with the database before the connection is added to the pool.

      When the handler has finished, it must call `SqlClient.close()` to release the connection to the pool.

      Parameters:
        `handler` - the handler
      Returns:
        a reference to this, so the API can be used fluently

    - #### connectionProvider

          Pool connectionProvider(java.util.function.Function<Context,Future<SqlConnection>> provider)

      Replace the default pool connection provider, the new `provider` returns a future connection for a given `Context`.

      A `ConnectionFactory` can be used as connection provider.

      Parameters:
        `provider` - the new connection provider
      Returns:
        a reference to this, so the API can be used fluently

    - #### size

          int size()

      Returns:
        the current pool size approximation

Copyright © 2023 Eclipse. All rights reserved.