Add support for read-only mode in DuckDB and SQLite (#1383)

* Add support for read-only mode in database connections This commit introduces `createConnection` methods for `DuckDb` and `Sqlite` to handle read-only mode during connection creation. It also updates test configurations and ensures proper handling of in-memory databases. * Linter * apiDump * Simplify SQLite read-only connection creation and clean up DuckDB handling Streamlined `createConnection` for SQLite using `SQLiteConfig` for read-only mode. Improved `isInMemoryDuckDb` logic for better URL handling. Updated dependencies and tests for consistency. * Linter

Author: zaleslaw

dataframe-jdbc/api/dataframe-jdbc.api

@@ -120,6 +120,7 @@ public abstract class org/jetbrains/kotlinx/dataframe/io/db/DbType {
 public abstract fun buildTableMetadata (Ljava/sql/ResultSet;)Lorg/jetbrains/kotlinx/dataframe/io/TableMetadata;
 public abstract fun convertSqlTypeToColumnSchemaValue (Lorg/jetbrains/kotlinx/dataframe/io/TableColumnMetadata;)Lorg/jetbrains/kotlinx/dataframe/schema/ColumnSchema;
 public abstract fun convertSqlTypeToKType (Lorg/jetbrains/kotlinx/dataframe/io/TableColumnMetadata;)Lkotlin/reflect/KType;
+public fun createConnection (Lorg/jetbrains/kotlinx/dataframe/io/DbConnectionConfig;)Ljava/sql/Connection;
 public final fun getDbTypeInJdbcUrl ()Ljava/lang/String;
 public abstract fun getDriverClassName ()Ljava/lang/String;
 public fun getTableTypes ()Ljava/util/List;
@@ -133,6 +134,7 @@ public final class org/jetbrains/kotlinx/dataframe/io/db/DuckDb : org/jetbrains/
 public fun buildTableMetadata (Ljava/sql/ResultSet;)Lorg/jetbrains/kotlinx/dataframe/io/TableMetadata;
 public fun convertSqlTypeToColumnSchemaValue (Lorg/jetbrains/kotlinx/dataframe/io/TableColumnMetadata;)Lorg/jetbrains/kotlinx/dataframe/schema/ColumnSchema;
 public fun convertSqlTypeToKType (Lorg/jetbrains/kotlinx/dataframe/io/TableColumnMetadata;)Lkotlin/reflect/KType;
+public fun createConnection (Lorg/jetbrains/kotlinx/dataframe/io/DbConnectionConfig;)Ljava/sql/Connection;
 public fun getDriverClassName ()Ljava/lang/String;
 public fun isSystemTable (Lorg/jetbrains/kotlinx/dataframe/io/TableMetadata;)Z
 }
@@ -200,6 +202,7 @@ public final class org/jetbrains/kotlinx/dataframe/io/db/Sqlite : org/jetbrains/
 public fun buildTableMetadata (Ljava/sql/ResultSet;)Lorg/jetbrains/kotlinx/dataframe/io/TableMetadata;
 public fun convertSqlTypeToColumnSchemaValue (Lorg/jetbrains/kotlinx/dataframe/io/TableColumnMetadata;)Lorg/jetbrains/kotlinx/dataframe/schema/ColumnSchema;
 public fun convertSqlTypeToKType (Lorg/jetbrains/kotlinx/dataframe/io/TableColumnMetadata;)Lkotlin/reflect/KType;
+public fun createConnection (Lorg/jetbrains/kotlinx/dataframe/io/DbConnectionConfig;)Ljava/sql/Connection;
 public fun getDriverClassName ()Ljava/lang/String;
 public fun isSystemTable (Lorg/jetbrains/kotlinx/dataframe/io/TableMetadata;)Z
 }

dataframe-jdbc/build.gradle.kts

@@ -17,6 +17,7 @@ repositories {
 dependencies {
  api(projects.core)
  compileOnly(libs.duckdb.jdbc)
+ compileOnly(libs.sqlite)
  implementation(libs.kotlinLogging)
  testImplementation(libs.mariadb)
  testImplementation(libs.sqlite)

dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/db/DbType.kt

@@ -1,11 +1,14 @@
 package org.jetbrains.kotlinx.dataframe.io.db
 
+import org.jetbrains.kotlinx.dataframe.io.DbConnectionConfig
 import org.jetbrains.kotlinx.dataframe.io.TableColumnMetadata
 import org.jetbrains.kotlinx.dataframe.io.TableMetadata
 import org.jetbrains.kotlinx.dataframe.io.getSchemaForAllSqlTables
 import org.jetbrains.kotlinx.dataframe.io.readAllSqlTables
 import org.jetbrains.kotlinx.dataframe.schema.ColumnSchema
+import java.sql.Connection
 import java.sql.DatabaseMetaData
+import java.sql.DriverManager
 import java.sql.ResultSet
 import kotlin.reflect.KType
 
@@ -75,4 +78,22 @@ public abstract class DbType(public val dbTypeInJdbcUrl: String) {
  * @return A new SQL query with the limit clause added.
  */
  public open fun sqlQueryLimit(sqlQuery: String, limit: Int = 1): String = "$sqlQuery LIMIT $limit"
+
+ /**
+ * Creates a database connection using the provided configuration.
+ * This method is only called when working with [DbConnectionConfig] (internally managed connections).
+ *
+ * Some databases (like [Sqlite]) require read-only mode to be set during connection creation
+ * rather than after the connection is established.
+ *
+ * @param [dbConfig] The database configuration containing URL, credentials, and read-only flag.
+ * @return A configured [Connection] instance.
+ */
+ public open fun createConnection(dbConfig: DbConnectionConfig): Connection {
+ val connection = DriverManager.getConnection(dbConfig.url, dbConfig.user, dbConfig.password)
+ if (dbConfig.readOnly) {
+ connection.isReadOnly = true
+ }
+ return connection
+ }
 }

dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/db/DuckDb.kt

@@ -1,5 +1,6 @@
 package org.jetbrains.kotlinx.dataframe.io.db
 
+import io.github.oshai.kotlinlogging.KotlinLogging
 import org.duckdb.DuckDBColumnType
 import org.duckdb.DuckDBColumnType.ARRAY
 import org.duckdb.DuckDBColumnType.BIGINT
@@ -39,6 +40,7 @@ import org.duckdb.DuckDBColumnType.VARCHAR
 import org.duckdb.DuckDBResultSetMetaData
 import org.duckdb.JsonNode
 import org.jetbrains.kotlinx.dataframe.DataFrame
+import org.jetbrains.kotlinx.dataframe.io.DbConnectionConfig
 import org.jetbrains.kotlinx.dataframe.io.TableColumnMetadata
 import org.jetbrains.kotlinx.dataframe.io.TableMetadata
 import org.jetbrains.kotlinx.dataframe.io.db.DuckDb.convertSqlTypeToKType
@@ -49,21 +51,26 @@ import java.math.BigDecimal
 import java.math.BigInteger
 import java.sql.Array
 import java.sql.Blob
+import java.sql.Connection
 import java.sql.DatabaseMetaData
+import java.sql.DriverManager
 import java.sql.ResultSet
 import java.sql.Struct
 import java.sql.Timestamp
 import java.time.LocalDate
 import java.time.LocalTime
 import java.time.OffsetDateTime
 import java.time.OffsetTime
+import java.util.Properties
 import java.util.UUID
 import kotlin.reflect.KType
 import kotlin.reflect.KTypeProjection
 import kotlin.reflect.full.createType
 import kotlin.reflect.full.withNullability
 import kotlin.reflect.typeOf
 
+private val logger = KotlinLogging.logger {}
+
 /**
  * Represents the [DuckDB](http://duckdb.org/) database type.
  *
@@ -216,4 +223,39 @@ public object DuckDb : DbType("duckdb") {
  tables.getString("TABLE_SCHEM"),
  tables.getString("TABLE_CAT"),
  )
+
+ /**
+ * Creates a database connection using the provided configuration.
+ *
+ * DuckDB does not support changing read-only status after connection creation,
+ * but supports read-only mode through connection parameters.
+ *
+ * @param [dbConfig] The database configuration containing URL, credentials, and read-only flag.
+ * @return A configured [java.sql.Connection] instance.
+ */
+ override fun createConnection(dbConfig: DbConnectionConfig): Connection {
+ val properties = Properties().apply {
+ dbConfig.user.takeIf { it.isNotEmpty() }?.let { setProperty("user", it) }
+ dbConfig.password.takeIf { it.isNotEmpty() }?.let { setProperty("password", it) }
+
+ // Handle DuckDB limitation: in-memory databases cannot be opened in read-only mode
+ if (dbConfig.readOnly && !dbConfig.url.isInMemoryDuckDb()) {
+ setProperty("access_mode", "read_only")
+ } else if (dbConfig.readOnly) {
+ logger.warn {
+ "Cannot create read-only in-memory DuckDB database (url=${dbConfig.url}). " +
+ "In-memory databases require write access for initialization. Connection will be created without read-only mode."
+ }
+ }
+ }
+
+ return DriverManager.getConnection(dbConfig.url, properties)
+ }
+
+ /**
+ * Checks if the DuckDB URL represents an in-memory database.
+ * In-memory DuckDB URLs are either "jdbc:duckdb:" or "jdbc:duckdb:" followed only by whitespace.
+ */
+ private fun String.isInMemoryDuckDb(): Boolean =
+ this.trim() == "jdbc:duckdb:" || matches("jdbc:duckdb:\\s*$".toRegex())
 }

dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/db/Sqlite.kt

@@ -1,8 +1,12 @@
 package org.jetbrains.kotlinx.dataframe.io.db
 
+import org.jetbrains.kotlinx.dataframe.io.DbConnectionConfig
 import org.jetbrains.kotlinx.dataframe.io.TableColumnMetadata
 import org.jetbrains.kotlinx.dataframe.io.TableMetadata
 import org.jetbrains.kotlinx.dataframe.schema.ColumnSchema
+import org.sqlite.SQLiteConfig
+import java.sql.Connection
+import java.sql.DriverManager
 import java.sql.ResultSet
 import kotlin.reflect.KType
 
@@ -28,4 +32,13 @@ public object Sqlite : DbType("sqlite") {
  )
 
  override fun convertSqlTypeToKType(tableColumnMetadata: TableColumnMetadata): KType? = null
+
+ override fun createConnection(dbConfig: DbConnectionConfig): Connection =
+ if (dbConfig.readOnly) {
+ val config = SQLiteConfig()
+ config.setReadOnly(true)
+ config.createConnection(dbConfig.url)
+ } else {
+ DriverManager.getConnection(dbConfig.url, dbConfig.user, dbConfig.password)
+ }
 }

dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/readJdbc.kt

@@ -9,6 +9,7 @@ import org.jetbrains.kotlinx.dataframe.api.toDataFrame
 import org.jetbrains.kotlinx.dataframe.impl.schema.DataFrameSchemaImpl
 import org.jetbrains.kotlinx.dataframe.io.db.DbType
 import org.jetbrains.kotlinx.dataframe.io.db.extractDBTypeFromConnection
+import org.jetbrains.kotlinx.dataframe.io.db.extractDBTypeFromUrl
 import org.jetbrains.kotlinx.dataframe.schema.ColumnSchema
 import org.jetbrains.kotlinx.dataframe.schema.DataFrameSchema
 import java.math.BigDecimal
@@ -174,16 +175,13 @@ internal inline fun <T> withReadOnlyConnection(
  dbType: DbType? = null,
  block: (Connection) -> T,
 ): T {
- val connection = DriverManager.getConnection(dbConfig.url, dbConfig.user, dbConfig.password)
-
- val originalAutoCommit = connection.autoCommit
- val originalReadOnly = connection.isReadOnly
+ val actualDbType = dbType ?: extractDBTypeFromUrl(dbConfig.url)
+ val connection = actualDbType.createConnection(dbConfig)
 
  return connection.use { conn ->
  try {
  if (dbConfig.readOnly) {
  conn.autoCommit = false
- conn.isReadOnly = true
  }
 
  block(conn)
@@ -197,10 +195,6 @@ internal inline fun <T> withReadOnlyConnection(
  }
  }
  }
-
- // Restore original settings (relevant in pooled environments)
- conn.autoCommit = originalAutoCommit
- conn.isReadOnly = originalReadOnly
  }
  }
 }

dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/h2/h2Test.kt

@@ -1173,7 +1173,7 @@ class JdbcTest {
 
  @Test
  fun `withReadOnlyConnection sets readOnly and rolls back after execution`() {
- val config = DbConnectionConfig("jdbc:h2:mem:test;DB_CLOSE_DELAY=-1", readOnly = true)
+ val config = DbConnectionConfig("jdbc:h2:mem:test;MODE=MySQL;DB_CLOSE_DELAY=-1", readOnly = true)
 
  var wasExecuted = false
  val result = withReadOnlyConnection(config) { conn ->

dataframe-jdbc/src/test/kotlin/org/jetbrains/kotlinx/dataframe/io/local/duckDbTest.kt

@@ -31,18 +31,19 @@ import org.jetbrains.kotlinx.dataframe.io.readResultSet
 import org.jetbrains.kotlinx.dataframe.io.readSqlQuery
 import org.jetbrains.kotlinx.dataframe.io.readSqlTable
 import org.jetbrains.kotlinx.dataframe.schema.DataFrameSchema
-import org.junit.Ignore
 import org.junit.Test
 import java.math.BigDecimal
 import java.math.BigInteger
 import java.nio.ByteBuffer
+import java.nio.file.Files
 import java.sql.Blob
 import java.sql.DriverManager
 import java.sql.Timestamp
 import java.time.LocalDate
 import java.time.LocalTime
 import java.time.OffsetDateTime
 import java.util.UUID
+import kotlin.io.path.createTempDirectory
 
 private const val URL = "jdbc:duckdb:"
 
@@ -624,12 +625,35 @@ class DuckDbTest {
  }
  }
 
- // TODO Issue #1365
- @Ignore
  @Test
  fun `change read mode`() {
- val config = DbConnectionConfig("jdbc:duckdb:", readOnly = true)
+ // Test in-memory database (cannot be read-only)
+ val config = DbConnectionConfig("jdbc:duckdb:")
  val df = config.readDataFrame("SELECT 1, 2, 3")
  df.values().toList() shouldBe listOf(1, 2, 3)
  }
+
+ @Test
+ fun `change read mode with persistent database`() {
+ // Test read-only mode with a temporary file
+ val tempDir = createTempDirectory("duckdb-test-")
+ val dbPath = tempDir.resolve("test.duckdb")
+ try {
+ // First, create the database with actual data using plain JDBC to allow DDL/DML
+ DriverManager.getConnection("jdbc:duckdb:${dbPath.toAbsolutePath()}").use { connection ->
+ connection.createStatement().use { st ->
+ st.executeUpdate("CREATE TABLE test_data(col1 INTEGER, col2 INTEGER, col3 INTEGER)")
+ st.executeUpdate("INSERT INTO test_data VALUES (1, 2, 3)")
+ }
+ }
+
+ // Now test read-only access via our API
+ val config = DbConnectionConfig("jdbc:duckdb:${dbPath.toAbsolutePath()}", readOnly = true)
+ val df = config.readDataFrame("SELECT col1, col2, col3 FROM test_data")
+ df.values().toList() shouldBe listOf(1, 2, 3)
+ } finally {
+ Files.deleteIfExists(dbPath)
+ Files.deleteIfExists(tempDir)
+ }
+ }
 }