Skip to content
/ hucpa Public

JRuby wrapper to HikariCP JDBC connection pool

License

Notifications You must be signed in to change notification settings

tomekw/hucpa

Repository files navigation

Hucpa

Code Climate Gem Version CircleCI

A JRuby wrapper to HikariCP - "zero-overhead" production ready JDBC connection pool. This is / will be a part of a bigger effort, like a dedicated library to use SQL and / or ActiveRecord integration.

Please note the project support only JRuby (tested with 9.1.8.0+) on Java 8.

The public API is subject to change before version 1.0.0.

Installation

Add this line to your application's Gemfile:

gem "hucpa"

And then execute:

$ bundle

Or install it yourself as:

$ gem install hucpa

Configuration options

See HikariCP Documentation for a detailed description. Not all HikariCP-defined configuration options are currently supported. To add support for infrequently used options please raise an issue or file a pull request.

Option Required Default value Notes
adapter Yes(1) - Symbol
auto_commit No true Boolean
connection_test_query No - String
connection_timeout No 30_000 Integer, greater than or equal to 250, in miliseconds
database_name No - String
idle_timeout No 600_000 Integer, 0 (disabled) or greater than or equal to 10000, in miliseconds
jdbc_url Yes(1) - String
max_lifetime No 1_800_000 Integer, 0 (disabled) or greater than or equal to 30000, in miliseconds
maximum_pool_size No 10 Integer, greater than or equal to 1
minimum_idle No 10 Integer, greater than or equal to 1
password Yes - String
pool_name No - String
server_name No - String
username Yes - String

(1) - either adapter or jdbc_url has to be provided.

Supported adapters and corresponding datasource class names

Adapter Datasource class name
db2 com.ibm.db2.jcc.DB2SimpleDataSource
derby org.apache.derby.jdbc.ClientDataSource
fdbsql com.foundationdb.sql.jdbc.ds.FDBSimpleDataSource
firebird org.firebirdsql.pool.FBSimpleDataSource
h2 org.h2.jdbcx.JdbcDataSource
hsqldb org.hsqldb.jdbc.JDBCDataSource
mariadb org.mariadb.jdbc.MySQLDataSource
mysql com.mysql.jdbc.jdbc2.optional.MysqlDataSource
oracle oracle.jdbc.pool.OracleDataSource
pgjdbc_ng com.impossibl.postgres.jdbc.PGDataSource
postgresql org.postgresql.ds.PGSimpleDataSource
sqlite org.sqlite.JDBC
sqlserver_jtds net.sourceforge.jtds.jdbcx.JtdsDataSource
sqlserver com.microsoft.sqlserver.jdbc.SQLServerDataSource
sybase com.sybase.jdbcx.SybDataSource

Usage

Install the database driver, for PostgreSQL:

gem "jdbc-postgres"

Load the the database driver if needed, for PostgreSQL:

require "jdbc/postgres"
Jdbc::Postgres.load_driver

Configure the connection pool:

# Using the adapter option
options = {
  adapter: :postgresql,
  database_name: "hucpa",
  password: "hucpa",
  server_name: "postgres",
  username: "hucpa"
}

# Using the jdbc_url option
options = {
  jdbc_url: "jdbc:postgresql://postgres/hucpa",
  password: "hucpa",
  username: "hucpa"
}

connection_pool = Hucpa::ConnectionPool.new(options)

Use the connection pool with the with_connection API:

answer = connection_pool.with_connection do |connection|
  result_set =
    connection
      .create_statement
      .execute_query("SELECT 42 AS answer")

  result_set.next and result_set.get_int("answer")
end

answer
=> 42

Or use the connection pool with the "classic" API:

datasource = connection_pool.open

# Explicitly obtain the DB connection
connection = datasource.connection

result_set =
  connection
    .create_statement
    .execute_query("SELECT 42 AS answer")

answer = result_set.next and result_set.get_int("answer")

# Explicitly release the DB connection
connection.close

answer
=> 42

Close the connection pool:

connection_pool.close

Development

Build the Docker image:

$ docker-compose build

Create services:

$ docker-compose create

Run specs:

$ docker-compose run --rm app rspec spec

Run console:

$ docker-compose run --rm app irb

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/tomekw/hucpa. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.