Refactored DataFrame JDBC API plus DataSource handling (#1487)

* Refactored DataFrame JDBC API for enhanced DataSource handling

This commit introduces new DataFrame JDBC extension functions with `DataSource` support, removing redundant duplicate utilities. It includes revisions to streamline table/schema reading and validation features, delegating reusable connection-handling logic to a dedicated utility class. Also refactor file structure for better organization of DB-related code.

* Refactored schema extraction to use `readSqlTable` and `readSqlQuery` for consistency and improved readability.

* Refactored and modularized schema extraction utilities into a dedicated file `readDataFrameSchema.kt`, improving organization and code clarity. Converted several helper functions to `internal` visibility for encapsulation.

* Refactor: Replace `DataFrame` with `DataFrameSchema` for schema-related methods in tests and main codebase

* Update logging levels in validation utilities to debug and minor schema interface cleanup

* Refactor: support custom `PreparedStatement` configuration, unify query limits, and standardize identifier quoting for various database dialects

* Refactor: enhance `DbType` with batch size and query timeout properties, improve result set processing, and streamline table metadata handling

* Refactor: centralize `makeCommonSqlToKTypeMapping` in `DbType`, streamline SQL type handling and improve readability

* Refactored query execution logic by introducing `readDataFrameFromDatabase` utility for improved code reuse and clarity.

* Refactored ResultSet-processing utilities to use mutable lists for improved post-processing efficiency and reduced copying. Adjusted related functions to accept mutable lists accordingly.

* Add `configureStatement` missed parameters

* Refactored JDBC utilities: added comprehensive error handling in `readDataFrameFromDatabase`, converted data classes to classes with equality and hashCode implementations, added validation for database interaction methods.

* Update the exception type in the ` read from non-existing table` test for accuracy

* Renamed schema extraction functions from `getSchemaFor*` to `from*` for consistency and clarity across the DataFrame JDBC API. Updated all usages and tests accordingly.

* Rename `fromSqlTable` and `fromSqlQuery` to `readSqlTable` and `readSqlQuery` for consistency with updated naming conventions.

* Update `GenerateDataSchemaTask` to use `DataFrameSchema` methods for SQL table and query schema generation

* Refactor: improve code consistency, update parameter documentation, streamline SQL query-related methods, and enhance table schema handling

* Replace `DEFAULT_LIMIT` with nullable `limit` parameter, defaulting to `null` for unlimited row fetching. Updated all related methods and documentation for clarity.

* Add `validateLimit` utility to ensure limit parameter is null or positive; removed redundant exception handling and updated query-building logic.

* Add `validateLimit` calls across all JDBC read methods to enforce limit validation.

* Clarify "limit" parameter documentation and rename `readDataFrameFromDatabase` to `executeQueryAndBuildDataFrame` across JDBC methods for improved readability and consistency.

* Refactor JDBC data handling: relocate and centralize `buildSchemaByTableColumns` and `buildDataColumn` functions, streamline column post-processing logic, and enhance modularity across schema and SQL utilities.

* Ktlint with Junie

* Linter with Junie, part 2

* Refactor and enhance JDBC: update references for improved consistency, streamline `TableMetadata` class with compact constructor and copy method, and remove unused `columnMetadata` parameter from `buildDataColumn`.

* Add `DataFrameSchema.Companion` class to core API

Author: zaleslaw

core/api/core.api

@@ -6810,11 +6810,15 @@ public final class org/jetbrains/kotlinx/dataframe/schema/ComparisonMode : java/
 }
 
 public abstract interface class org/jetbrains/kotlinx/dataframe/schema/DataFrameSchema {
+	public static final field Companion Lorg/jetbrains/kotlinx/dataframe/schema/DataFrameSchema$Companion;
 	public abstract fun compare (Lorg/jetbrains/kotlinx/dataframe/schema/DataFrameSchema;Lorg/jetbrains/kotlinx/dataframe/schema/ComparisonMode;)Lorg/jetbrains/kotlinx/dataframe/schema/CompareResult;
 	public static synthetic fun compare$default (Lorg/jetbrains/kotlinx/dataframe/schema/DataFrameSchema;Lorg/jetbrains/kotlinx/dataframe/schema/DataFrameSchema;Lorg/jetbrains/kotlinx/dataframe/schema/ComparisonMode;ILjava/lang/Object;)Lorg/jetbrains/kotlinx/dataframe/schema/CompareResult;
 	public abstract fun getColumns ()Ljava/util/Map;
 }
 
+public final class org/jetbrains/kotlinx/dataframe/schema/DataFrameSchema$Companion {
+}
+
 public final class org/jetbrains/kotlinx/dataframe/util/DeprecationMessagesKt {
 	public static final field DF_READ_EXCEL Ljava/lang/String;
 }

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/schema/DataFrameSchema.kt

@@ -1,6 +1,7 @@
 package org.jetbrains.kotlinx.dataframe.schema
 
 public interface DataFrameSchema {
+    public companion object;
 
     public val columns: Map<String, ColumnSchema>
 

dataframe-jdbc/api/dataframe-jdbc.api

@@ -0,0 +1,93 @@
+package org.jetbrains.kotlinx.dataframe.io
+
+/**
+ * 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:
+ *
+ * ```kotlin
+ * // 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
+ * )
+ * ```
+ *
+ * @property [url] The JDBC URL of the database, e.g., `"jdbc:postgresql://localhost:5432/mydb"`.
+ *               Must follow the standard format: `jdbc:subprotocol:subname`.
+ *
+ * @property [user] The username used for authentication.
+ *                Optional, default is an empty string.
+ *
+ * @property [password] The password used for authentication.
+ *                    Optional, default is an empty string.
+ *
+ * @property [readOnly] If `true` (default), enables read-only mode. If `false`, uses JDBC defaults
+ *                      but still prevents data-modifying queries. See class documentation for details.
+ */
+public class DbConnectionConfig(
+    public val url: String,
+    public val user: String = "",
+    public val password: String = "",
+    public val readOnly: Boolean = true,
+) {
+    override fun equals(other: Any?): Boolean {
+        if (this === other) return true
+        if (other !is DbConnectionConfig) return false
+
+        if (url != other.url) return false
+        if (user != other.user) return false
+        if (password != other.password) return false
+        if (readOnly != other.readOnly) return false
+
+        return true
+    }
+
+    override fun hashCode(): Int {
+        var result = url.hashCode()
+        result = 31 * result + user.hashCode()
+        result = 31 * result + password.hashCode()
+        result = 31 * result + readOnly.hashCode()
+        return result
+    }
+
+    override fun toString(): String = "DbConnectionConfig(url='$url', user='$user', password='***', readOnly=$readOnly)"
+
+    /**
+     * Creates a copy of this configuration with the option to override specific properties.
+     *
+     * @param url The JDBC URL. If not specified, uses the current value.
+     * @param user The username. If not specified, uses the current value.
+     * @param password The password. If not specified, uses the current value.
+     * @param readOnly The read-only flag. If not specified, uses the current value.
+     * @return A new [DbConnectionConfig] instance with the specified changes.
+     */
+    public fun copy(
+        url: String = this.url,
+        user: String = this.user,
+        password: String = this.password,
+        readOnly: Boolean = this.readOnly,
+    ): DbConnectionConfig = DbConnectionConfig(url, user, password, readOnly)
+}