|
| 1 | +package org.jetbrains.kotlinx.dataframe.io |
| 2 | + |
| 3 | +/** |
| 4 | + * Represents the configuration for an internally managed JDBC database connection. |
| 5 | + * |
| 6 | + * This class defines connection parameters used by the library to create a `Connection` |
| 7 | + * when the user does not provide one explicitly. |
| 8 | + * It is designed for safe, read-only access by default. |
| 9 | + * |
| 10 | + * __NOTE:__ Connections created using this configuration are managed entirely by the library. |
| 11 | + * Users do not have access to the underlying `Connection` instance and cannot commit or close it manually. |
| 12 | + * |
| 13 | + * ### Read-Only Mode Behavior: |
| 14 | + * |
| 15 | + * When [readOnly] is `true` (default), the connection operates in read-only mode with: |
| 16 | + * - `Connection.setReadOnly(true)` |
| 17 | + * - `Connection.setAutoCommit(false)` |
| 18 | + * - automatic `rollback()` at the end of execution |
| 19 | + * |
| 20 | + * When [readOnly] is `false`, the connection uses JDBC defaults (usually read-write), |
| 21 | + * but the library still rejects any queries that appear to modify data |
| 22 | + * (e.g. contain `INSERT`, `UPDATE`, `DELETE`, etc.). |
| 23 | + * |
| 24 | + * ### Examples: |
| 25 | + * |
| 26 | + * ```kotlin |
| 27 | + * // Safe read-only connection (default) |
| 28 | + * val config = DbConnectionConfig("jdbc:sqlite::memory:") |
| 29 | + * val df = DataFrame.readSqlQuery(config, "SELECT * FROM books") |
| 30 | + * |
| 31 | + * // Use default JDBC connection settings (still protected against mutations) |
| 32 | + * val config = DbConnectionConfig( |
| 33 | + * url = "jdbc:sqlite::memory:", |
| 34 | + * readOnly = false |
| 35 | + * ) |
| 36 | + * ``` |
| 37 | + * |
| 38 | + * @property [url] The JDBC URL of the database, e.g., `"jdbc:postgresql://localhost:5432/mydb"`. |
| 39 | + * Must follow the standard format: `jdbc:subprotocol:subname`. |
| 40 | + * |
| 41 | + * @property [user] The username used for authentication. |
| 42 | + * Optional, default is an empty string. |
| 43 | + * |
| 44 | + * @property [password] The password used for authentication. |
| 45 | + * Optional, default is an empty string. |
| 46 | + * |
| 47 | + * @property [readOnly] If `true` (default), enables read-only mode. If `false`, uses JDBC defaults |
| 48 | + * but still prevents data-modifying queries. See class documentation for details. |
| 49 | + */ |
| 50 | +public class DbConnectionConfig( |
| 51 | + public val url: String, |
| 52 | + public val user: String = "", |
| 53 | + public val password: String = "", |
| 54 | + public val readOnly: Boolean = true, |
| 55 | +) { |
| 56 | + override fun equals(other: Any?): Boolean { |
| 57 | + if (this === other) return true |
| 58 | + if (other !is DbConnectionConfig) return false |
| 59 | + |
| 60 | + if (url != other.url) return false |
| 61 | + if (user != other.user) return false |
| 62 | + if (password != other.password) return false |
| 63 | + if (readOnly != other.readOnly) return false |
| 64 | + |
| 65 | + return true |
| 66 | + } |
| 67 | + |
| 68 | + override fun hashCode(): Int { |
| 69 | + var result = url.hashCode() |
| 70 | + result = 31 * result + user.hashCode() |
| 71 | + result = 31 * result + password.hashCode() |
| 72 | + result = 31 * result + readOnly.hashCode() |
| 73 | + return result |
| 74 | + } |
| 75 | + |
| 76 | + override fun toString(): String = "DbConnectionConfig(url='$url', user='$user', password='***', readOnly=$readOnly)" |
| 77 | + |
| 78 | + /** |
| 79 | + * Creates a copy of this configuration with the option to override specific properties. |
| 80 | + * |
| 81 | + * @param url The JDBC URL. If not specified, uses the current value. |
| 82 | + * @param user The username. If not specified, uses the current value. |
| 83 | + * @param password The password. If not specified, uses the current value. |
| 84 | + * @param readOnly The read-only flag. If not specified, uses the current value. |
| 85 | + * @return A new [DbConnectionConfig] instance with the specified changes. |
| 86 | + */ |
| 87 | + public fun copy( |
| 88 | + url: String = this.url, |
| 89 | + user: String = this.user, |
| 90 | + password: String = this.password, |
| 91 | + readOnly: Boolean = this.readOnly, |
| 92 | + ): DbConnectionConfig = DbConnectionConfig(url, user, password, readOnly) |
| 93 | +} |
0 commit comments