Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
279 lines (187 sloc) 8.11 KB

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: :::scala 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: :::scala 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:

    • :::scala StmtCacheConfig.Disabled — disables caching

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

      • capacity
       Specifies maximum prepared statements that can be cached.
      

    Default value: :::scala Enabled(capacity = 100).


  • writeTimeout

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

    Default value: :::scala Timeout(10.seconds).


  • ec

    Execution context used by the connection to execute Future callbacks.

    Default value: :::scala 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: :::scala 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: :::scala Vector.empty.


  • typeCodecs

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

    Codecs specified here supplement built-in codecs.

    Default value: :::scala 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: :::scala 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: :::scala 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: :::scala 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
      )
    )
  )
}