driver/io.github.octaviusframework.driver.jdbc/OctaviusDataSource

OctaviusDataSource

Implementation of the standard JDBC DataSource interface for the Octavius driver.

This class serves as a factory for obtaining connections to a PostgreSQL database. It encapsulates the configuration properties required to establish a connection, such as the server URL, credentials, and SSL settings.

Configuration properties can be set either via the url property or individually using the respective accessor properties. Every field of OctaviusProperties has an accessor here, so a pool that configures a DataSource through JavaBean setters - HikariCP's addDataSourceProperty, for one - can reach all of them; anything else goes through setProperty, including server startup parameters.

Constructors

OctaviusDataSource

constructor()

Properties

applicationName

var applicationName: String?

The name this connection reports to the server, visible in pg_stat_activity. Unset, the driver's own name - Octavius Driver - is sent instead.

cancelSignalTimeout

var cancelSignalTimeout: Int

Seconds allowed for a cancel request, covering both its connect and its reads.

channelBinding

var channelBinding: ChannelBinding?

How hard to insist that authentication be bound to the TLS channel. Defaults to ChannelBinding.PREFER.

connection

open override val connection: Connection

databaseName

var databaseName: String?

The name of the database to connect to.

initialParameterWriterCapacity

var initialParameterWriterCapacity: Int

Starting size, in bytes, of the per-connection parameter buffer.

loginTimeout

open override var loginTimeout: Int

logParameterValues

var logParameterValues: Boolean

Whether a traced statement carries the values bound to it, rather than only how many there were. Off unless set, and effective only at trace.

logWriter

open override var logWriter: PrintWriter?

maxCachedRowSize

var maxCachedRowSize: Int

Largest row, in bytes, kept in the reusable row buffer.

maxParameterWriterCapacity

var maxParameterWriterCapacity: Int

Cap for the per-connection parameter buffer; it shrinks back to initialParameterWriterCapacity after a query that exceeded it.

noticeHandler

var noticeHandler: String?

Fully-qualified class name of a NoticeHandler for server notices.

notificationBufferCapacity

var notificationBufferCapacity: Int

Capacity of the LISTEN/NOTIFY buffer.

parentLogger

open override val parentLogger: Logger

password

var password: String?

The password for authenticating with the database.

portNumber

var portNumber: Int

The port number on which the PostgreSQL server is listening. Defaults to 5432.

serverName

var serverName: String?

The hostname or IP address of the PostgreSQL server.

socketTimeout

var socketTimeout: Int

Seconds to wait on a socket read before failing. 0 waits forever.

ssl

var ssl: Boolean?

Shorthand raising the default SSL mode to REQUIRE. Ignored when sslmode is set explicitly.

sslcert

var sslcert: String?

The path to the client certificate file for SSL authentication. Takes effect only together with sslkey; with either missing, no client certificate is presented.

sslkey

var sslkey: String?

The path to the client private key file for SSL authentication. PKCS#8 in PEM form, encrypted or not - sslpassword opens an encrypted one - and RSA or EC alike, the algorithm being read off sslcert rather than assumed.

sslmode

var sslmode: SslMode?

The SSL mode to use (e.g., disable, require, verify-ca, verify-full).

sslpassword

var sslpassword: String?

Decrypts sslkey where that key is encrypted - a PEM file opening on BEGIN ENCRYPTED PRIVATE KEY. An unencrypted key ignores it; an encrypted one without it is refused, naming this property.

sslrootcert

var sslrootcert: String?

The path to the root certificate file for verifying the server's certificate. Optional: left unset, verification under verify-ca and above uses the JVM's default trust store.

url

var url: String

The JDBC URL used to connect to the database. Setting this property will parse the URL and merge the properties.

user

var user: String?

The username for authenticating with the database.

Functions

createConnectionBuilder

open fun createConnectionBuilder(): ConnectionBuilder?

createShardingKeyBuilder

open fun createShardingKeyBuilder(): ShardingKeyBuilder?

getConnection

open override fun getConnection(): Connection

open override fun getConnection(username: String?, pass: String?): Connection

getLoginTimeout

open override fun getLoginTimeout(): Int

getLogWriter

open override fun getLogWriter(): PrintWriter?

getOctaviusSession

fun DataSource.getOctaviusSession(): OctaviusSession

Retrieves a new OctaviusSession from this DataSource.

fun DataSource.getOctaviusSession(username: String, pass: String): OctaviusSession

Retrieves a new OctaviusSession from this DataSource using the specified credentials.

getParentLogger

open override fun getParentLogger(): Logger

isWrapperFor

open override fun isWrapperFor(iface: Class<*>): Boolean

setLoginTimeout

open override fun setLoginTimeout(seconds: Int)

setLogWriter

open override fun setLogWriter(out: PrintWriter?)

setProperty

fun setProperty(name: String, value: String)

Sets any property this class does not expose directly, by the same name a JDBC URL would use. Anything the driver does not recognise is sent to the server as a startup parameter, which is what makes this the programmatic route to search_path, statement_timeout and friends - application_name has applicationName and needs no detour.

unwrap

open override fun <T> unwrap(iface: Class<T>): T

unwrap

inline fun <T> DataSource.unwrap(): T

Unwraps this DataSource to an instance of the specified type T.

unwrapToOctavius

fun DataSource.unwrapToOctavius(): OctaviusDataSource

Unwraps this DataSource to its underlying OctaviusDataSource instance.