dataframe-jdbc/org.jetbrains.kotlinx.dataframe.io/DbConnectionConfig

DbConnectionConfig

class DbConnectionConfig(val url: String, val user: String = "", val password: String = "", val readOnly: Boolean = true)

Represents the configuration for an internally managed JDBC database connection.

This class defines connection parameters used by the library to create a Connection when the user does not provide one explicitly. It is designed for safe, read-only access by default.

NOTE: Connections created using this configuration are managed entirely by the library. Users do not have access to the underlying Connection instance and cannot commit or close it manually.

Read-Only Mode Behavior:

When readOnly is true (default), the connection operates in read-only mode with:

Connection.setReadOnly(true)
Connection.setAutoCommit(false)
automatic rollback() at the end of execution

When readOnly is false, the connection uses JDBC defaults (usually read-write), but the library still rejects any queries that appear to modify data (e.g. contain INSERT, UPDATE, DELETE, etc.).

Examples:

// Safe read-only connection (default)
val config = DbConnectionConfig("jdbc:sqlite::memory:")
val df = DataFrame.readSqlQuery(config, "SELECT * FROM books")

// Use default JDBC connection settings (still protected against mutations)
val config = DbConnectionConfig(
    url = "jdbc:sqlite::memory:",
    readOnly = false
)

Constructors

DbConnectionConfig

constructor(url: String, user: String = "", password: String = "", readOnly: Boolean = true)

Properties

password

val password: String

The password used for authentication. Optional, default is an empty string.

readOnly

val readOnly: Boolean

If true (default), enables read-only mode. If false, uses JDBC defaults but still prevents data-modifying queries. See class documentation for details.

url

val url: String

The JDBC URL of the database, e.g., "jdbc:postgresql://localhost:5432/mydb". Must follow the standard format: jdbc:subprotocol:subname.

user

val user: String

The username used for authentication. Optional, default is an empty string.

Functions

copy

fun copy(url: String = this.url, user: String = this.user, password: String = this.password, readOnly: Boolean = this.readOnly): DbConnectionConfig

Creates a copy of this configuration with the option to override specific properties.

equals

open operator override fun equals(other: Any?): Boolean

hashCode

open override fun hashCode(): Int

readDataFrame

fun DbConnectionConfig.readDataFrame(sqlQueryOrTableName: String, limit: Int? = null, inferNullability: Boolean = true, dbType: DbType? = null, validation: SqlValidation = SqlValidation.None, configureStatement: (PreparedStatement) -> Unit = {}): AnyFrame

Converts the result of an SQL query or SQL table (by name) to the DataFrame.

readDataFrameSchema

fun DbConnectionConfig.readDataFrameSchema(sqlQueryOrTableName: String, dbType: DbType? = null): DataFrameSchema

Retrieves the schema of an SQL query result or the SQL table using the provided database configuration.

toString

open override fun toString(): String