Skip to content

Constructing connection factory

As rdbc documentation mentions, to use the API you need to construct a driver specific ConnectionFactory implementation. In rdbc-pgsql case, it's going to be NettyPgConnectionFactory.

To instantiate NettyPgConnectionFactory use its companion object's apply method. This factory method accepts a configuration object — NettyPgConnFactory#Config instance. Chapters below focus on providing the configuration.

Simple scenario

To create a configuration instance with default configuration options use NettyPgConnFactory#Config's apply method with host, port and authenticator parameters:

import io.rdbc.pgsql.transport.netty.NettyPgConnectionFactory
import io.rdbc.pgsql.transport.netty.NettyPgConnectionFactory.Config
import io.rdbc.pgsql.core.auth.Auth

val cf = NettyPgConnectionFactory(
  Config(
    host = "localhost",
    port = 5432,
    authenticator = Auth.password("user", "pass")
  )
)

If you want to tweak some configuration options (and most likely you do) read the paragraph below.

Configuration options

If you want to override some of default option values use named parameters of Config.apply method. In the example below dbName option is changed from default None to Some("db").

import io.rdbc.pgsql.transport.netty.NettyPgConnectionFactory
import io.rdbc.pgsql.transport.netty.NettyPgConnectionFactory.Config
import io.rdbc.pgsql.core.auth.Auth

val cf = NettyPgConnectionFactory(Config(
  host = "localhost",
  port = 5432,
  authenticator = Auth.password("user", "pass"),
  dbName = Some("db")
))

For other examples see examples paragraph.

The paragraphs below list available configuration options.

Non-transport specific options

The driver is designed to support multiple transport libraries. This paragraph lists options non-specific to any transport library.

Frequently used

  • host

    Host name or IP address the database listens on.

    Default value: no default value.


  • port

    TCP port the database listens on.

    Default value: no default value.


  • authenticator

    Authenticator instance performing authentication. See authentication chapter for details.

    Default value: no default value.


  • dbName

    The database name. if None is provided database name will be assumed to be the same as user name provide by the authenticator.

    Default value: None.


  • subscriberBufferCapacity

    When streaming data from client to the database the driver can accumulate statements into batches for optimized execution. This parameter sets maximum number of statements that will be accumulated.

    Default value: 100.


  • stmtCacheConfig

    Connection can cache prepared statements so that they can be reused when executed later on with different parameters. This paramaeter configures caching mechanism.

    Possible values:

    • StmtCacheConfig.Disabled — disables caching
    • StmtCacheConfig.Enabled — enables caching. Enabled case class has following fields:

      • capacity

        Specifies maximum prepared statements that can be cached.

    Default value: Enabled(capacity = 100).


  • writeTimeout

    If socket write operation takes longer than this value, timeout error will be reported.

    Default value: Timeout(10.seconds).


  • ec

    Execution context used by the connection to execute Future callbacks.

    Default value: scala.concurrent.ExecutionContext.global.

Other

  • typeConverters

    Column values and statement arguments have some nominal Scala types that directly correspond to PostgreSQL types. Converters specified here will convert between the nominal type and the type specified by the client. For example, int4 column is nominally represented by PgInt4 class but because there is a converter that can convert between PgInt4 and Int whenever a PgInt4 is expected client can supply an Int.

    Converters specified here supplement built-in converters.

    Default value: Vector.empty.


  • typeMappings

    Statement arguments have some nominal types that directly correspond to PostgreSQL types. If non-nominal type is used as a statement argument there has to be a mapping between this type and a nominal type. For instance, String maps to PgText type.

    Type mappings specified there supplement built-in mappings.

    Default value: Vector.empty.

  • typeCodecs

    Codecs for PostgreSQL types not supported by default by the driver.

    Codecs specified here supplement built-in codecs.

    Default value: Vector.empty.


  • subscriberMinDemandRequestSize

    When streaming data from a client to a database the driver requests statement argument sets from the client. This parameter defines minimum number of argument sets that the driver will request, each time the driver decides that it needs more argument sets.

    Default value: 10.

Netty transport specific options

  • channelFactory

    Netty ChannelFactory that will be used to create a channel.

    By default JDK NIO will be used which is supported on all platforms. Consider using platform specific native netty transport if your platform supports any. See this page for details.

    Default value: new NioChannelFactory


  • eventLoopGroup

    Netty EventLoopGroup which will be used to handle events for the channel.

    By default JDK NIO will be used which is supported on all platforms. Consider using platform specific native netty transport if your platform supports any. See this page for details.

    Default value: new NioEventLoopGroup.


  • channelOptions

    Netty channel options.

    CONNECT_TIMEOUT_MILLIS is always ignored because it's overridden by timeout value passed to factory's connection() method. Other than that, you can set any netty channel option here.

    Default values:

    • SO_KEEPALIVE = true

Examples

Code in the snippet below creates a connection factory setting transport independent writeTimeout and subscriberBufferCapacity options and also setting netty-specific channelOptions option.

import io.rdbc.pgsql.transport.netty.ChannelOptions._
import io.rdbc.pgsql.transport.netty.NettyPgConnectionFactory
import io.rdbc.pgsql.transport.netty.NettyPgConnectionFactory.Config
import io.rdbc.pgsql.core.auth.Auth
import io.rdbc.sapi.Timeout
import io.netty.channel.ChannelOption._
import scala.concurrent.duration._

val cf = {
  NettyPgConnectionFactory(
    Config(
      host = "pg.example.com",
      port = 5432,
      authenticator = Auth.password("user", "pass"),
      writeTimeout = Timeout(5.seconds),
      subscriberBufferCapacity = 1000,
      channelOptions = Vector(
        SO_KEEPALIVE -> true,
        WRITE_SPIN_COUNT -> 3
      )
    )
  )
}