updating jdbc docs with DuckDB examples (using korro) as well as fixing some grammar issues

Author: Jolanrensen

docs/StardustDocs/d.tree

@@ -202,6 +202,7 @@
             <toc-element topic="SQLite.md"/>
             <toc-element topic="H2.md"/>
             <toc-element topic="MariaDB.md"/>
+            <toc-element topic="DuckDB.md"/>
             <toc-element topic="Custom-SQL-Source.md"/>
         </toc-element>
         <toc-element topic="Integrations.md"/>

docs/StardustDocs/topics/dataSources/Data-Sources.md

@@ -28,6 +28,7 @@ Below you'll find a list of supported sources along with instructions on how to
     - [SQLite](SQLite.md)
     - [H2](H2.md)
     - [MariaDB](MariaDB.md)
+    - [DuckDB](DuckDB.md)
     - [Custom SQL Source](Custom-SQL-Source.md)
 - [Custom integrations with unsupported data sources](Integrations.md)
 

docs/StardustDocs/topics/dataSources/sql/DuckDB.md

@@ -0,0 +1,107 @@
+# DuckDB
+
+<web-summary>
+Work with DuckDB databases in Kotlin — read tables and queries into DataFrames using JDBC.
+</web-summary>
+
+<card-summary>
+Use Kotlin DataFrame to query and transform DuckDB data directly via JDBC.
+</card-summary>
+
+<link-summary>
+Read DuckDB data into Kotlin DataFrame with JDBC support.
+</link-summary>
+
+<!---IMPORT org.jetbrains.kotlinx.dataframe.samples.io.DuckDb-->
+
+Kotlin DataFrame supports reading from [DuckDB](https://duckdb.org/) databases using JDBC.
+
+This requires the [`dataframe-jdbc` module](Modules.md#dataframe-jdbc),
+which is included by default in the general [`dataframe` artifact](Modules.md#dataframe-general)
+and in [`%use dataframe`](SetupKotlinNotebook.md#integrate-kotlin-dataframe) for Kotlin Notebook.
+
+You’ll also need [the official DuckDB JDBC driver](https://duckdb.org/docs/stable/clients/java):
+
+<tabs>
+<tab title="Gradle project">
+
+```kotlin
+dependencies {
+    implementation("org.duckdb:duckdb_jdbc:$version")
+}
+```
+
+</tab>
+<tab title="Kotlin Notebook">
+
+```kotlin
+USE {
+    dependencies("org.duckdb:duckdb_jdbc:$version")
+}
+```
+
+</tab>
+</tabs>
+
+The actual Maven Central driver version can be found
+[here](https://mvnrepository.com/artifact/org.duckdb/duckdb_jdbc).
+
+## Read
+
+A [`DataFrame`](DataFrame.md) instance can be loaded from a database in several ways:  
+a user can read data from a SQL table by a given name ([`readSqlTable`](readSqlDatabases.md)),  
+as the result of a user-defined SQL query ([`readSqlQuery`](readSqlDatabases.md)),  
+or from a given `ResultSet` ([`readResultSet`](readSqlDatabases.md)).  
+It is also possible to load all data from non-system tables, each into a separate `DataFrame` ([
+`readAllSqlTables`](readSqlDatabases.md)).
+
+See [](readSqlDatabases.md) for more details.
+
+<!---FUN readSqlTable-->
+
+```kotlin
+val url = "jdbc:duckdb:/testDatabase"
+val username = "duckdb"
+val password = "password"
+
+val dbConfig = DbConnectionConfig(url, username, password)
+
+val tableName = "Customer"
+
+val df = DataFrame.readSqlTable(dbConfig, tableName)
+```
+
+<!---END-->
+
+### Extensions
+
+DuckDB has a special trick up its sleeve: it has support
+for [extensions](https://duckdb.org/docs/stable/extensions/overview).
+These can be installed, loaded, and used to connect to a different database via DuckDB.
+See [Core Extensions](https://duckdb.org/docs/stable/core_extensions/overview) for a list of available extensions.
+
+For example, let's load a dataframe
+from [Apache Iceberg via DuckDB](https://duckdb.org/docs/stable/core_extensions/iceberg/overview.html),
+as Iceberg is an unsupported data source in DataFrame at the moment:
+
+<!---FUN readIcebergExtension-->
+
+```kotlin
+// Creating an in-memory DuckDB database
+val connection = DriverManager.getConnection("jdbc:duckdb:")
+val df = connection.use { connection ->
+    // install and load Iceberg
+    connection.createStatement().execute("INSTALL iceberg; LOAD iceberg;")
+
+    // query a table from Iceberg using a specific SQL query
+    DataFrame.readSqlQuery(
+        connection = connection,
+        sqlQuery = "SELECT * FROM iceberg_scan('data/iceberg/lineitem_iceberg', allow_moved_paths = true);",
+    )
+}
+```
+
+<!---END-->
+
+As you can see, the process is very similar to reading from any other JDBC database,
+just without needing explicit DataFrame support.

docs/StardustDocs/topics/dataSources/sql/SQL.md

@@ -29,6 +29,7 @@ Kotlin DataFrame provides out-of-the-box support for the most common SQL databas
 - [SQLite](SQLite.md)
 - [H2](H2.md)
 - [MariaDB](MariaDB.md)
+- [DuckDB](DuckDB.md)
 
 You can also define a [Custom SQL Source](Custom-SQL-Source.md)
 to work with any other JDBC-compatible database.

docs/StardustDocs/topics/readSqlDatabases.md

@@ -44,71 +44,79 @@ Also, there are a few **extension functions** available on `Connection`,
 
 
 **NOTE:** This is an experimental module, and for now, 
-we only support four databases: MS SQL, MariaDB, MySQL, PostgreSQL, and SQLite. 
+we only support these databases: MS SQL, MariaDB, MySQL, PostgreSQL, SQLite, and DuckDB. 
 
 Moreover, since release 0.15 we support the possibility to register custom SQL database, read more in our [guide](readSqlFromCustomDatabase.md).
 
 Additionally, support for JSON and date-time types is limited. 
 Please take this into consideration when using these functions.
 
-## Getting started with reading from SQL database in Gradle Project
+## Getting started with reading from SQL database in a Gradle Project
 
-In the first, you need to add a dependency
+First, you need to add a dependency
 
 ```kotlin
 implementation("org.jetbrains.kotlinx:dataframe-jdbc:$dataframe_version")
 ```
 
-after that, you need to add a dependency for a JDBC driver for the used database, for example
+after that, you need to add the dependency for the database's JDBC driver, for example
 
 For **MariaDB**:
 
 ```kotlin
 implementation("org.mariadb.jdbc:mariadb-java-client:$version")
 ```
 
-Maven Central version could be found [here](https://mvnrepository.com/artifact/org.mariadb.jdbc/mariadb-java-client).
+The Maven Central version can be found [here](https://mvnrepository.com/artifact/org.mariadb.jdbc/mariadb-java-client).
 
 For **PostgreSQL**:
 
 ```kotlin
 implementation("org.postgresql:postgresql:$version")
 ```
 
-Maven Central version could be found [here](https://mvnrepository.com/artifact/org.postgresql/postgresql).
+The Maven Central version can be found [here](https://mvnrepository.com/artifact/org.postgresql/postgresql).
 
 For **MySQL**:
 
 ```kotlin
 implementation("com.mysql:mysql-connector-j:$version")
 ```
 
-Maven Central version could be found [here](https://mvnrepository.com/artifact/com.mysql/mysql-connector-j).
+The Maven Central version can be found [here](https://mvnrepository.com/artifact/com.mysql/mysql-connector-j).
 
 For **SQLite**:
 
 ```kotlin
 implementation("org.xerial:sqlite-jdbc:$version")
 ```
 
-Maven Central version could be found [here](https://mvnrepository.com/artifact/org.xerial/sqlite-jdbc).
+The Maven Central version can be found [here](https://mvnrepository.com/artifact/org.xerial/sqlite-jdbc).
 
 For **MS SQL**:
 
 ```kotlin
 implementation("com.microsoft.sqlserver:mssql-jdbc:$version")
 ```
 
-Maven Central version could be found [here](https://mvnrepository.com/artifact/com.microsoft.sqlserver/mssql-jdbc).
+The Maven Central version can be found [here](https://mvnrepository.com/artifact/com.microsoft.sqlserver/mssql-jdbc).
 
-In the second, be sure that you can establish a connection to the database.
+For **DuckDB**:
 
-For this, usually, you need to have three things: a URL to a database, a username, and a password.
+```kotlin
+implementation("org.duckdb:duckdb_jdbc:$version")
+```
+
+The Maven Central version can be found [here](https://mvnrepository.com/artifact/org.duckdb/duckdb_jdbc).
+
+Next, be sure that you can establish a connection to the database.
+
+For this, usually, you need to have three things: a URL to the database, a username, and a password.
 
-Call one of the following functions to collect data from a database and transform it to the dataframe.
+Call one of the following functions to collect data from the database and transform it to a dataframe.
 
-For example, if you have a local PostgreSQL database named as `testDatabase` with table `Customer`,
-you could read first 100 rows and print the data just copying the code below:
+For example, if you have a local PostgreSQL database named `testDatabase` with a table `Customer`,
+you can read the first 100 rows and print the data by just copying the code below:
 
 ```kotlin
 import org.jetbrains.kotlinx.dataframe.io.DbConnectionConfig
@@ -127,7 +135,7 @@ val df = DataFrame.readSqlTable(dbConfig, tableName, 100)
 df.print()
 ```
 
-Find a full example project [here](https://github.com/zaleslaw/KotlinDataFrame-SQL-Examples/).
+You can find a full example project [here](https://github.com/zaleslaw/KotlinDataFrame-SQL-Examples/).
 
 ## Getting Started with Notebooks
 
@@ -317,7 +325,7 @@ Note that reading from the `ResultSet` could potentially change its state.
 
 The `dbType: DbType` parameter specifies the type of our database (e.g., PostgreSQL, MySQL, etc.), 
 supported by a library. 
-Currently, the following classes are available: `H2, MsSql, MariaDb, MySql, PostgreSql, Sqlite`.
+Currently, the following classes are available: `H2, MsSql, MariaDb, MySql, PostgreSql, Sqlite, DuckDb`.
 
 Also, users have an ability to pass objects, describing their custom databases, more information in [guide](readSqlFromCustomDatabase.md).
 
@@ -525,7 +533,7 @@ This function reads the schema from a `ResultSet` object provided by the user.
 
 The `dbType: DbType` parameter specifies the type of our database (e.g., PostgreSQL, MySQL, etc.),
 supported by a library.
-Currently, the following classes are available: `H2, MariaDb, MySql, PostgreSql, Sqlite`.
+Currently, the following classes are available: `H2, MsSql, MariaDb, MySql, PostgreSql, Sqlite, DuckDB`.
 
 Also, users have an ability to pass objects, describing their custom databases, more information in [guide](readSqlFromCustomDatabase.md).
 

docs/StardustDocs/topics/schemas/gradle/Gradle-Plugin.md

@@ -184,7 +184,7 @@ dataframes {
 Find full example code [here](https://github.com/zaleslaw/KotlinDataFrame-SQL-Examples/blob/master/src/main/kotlin/Example_3_Import_schema_via_Gradle.kt).
 
 **NOTE:** This is an experimental functionality and, for now,
-we only support four databases: MariaDB, MySQL, PostgreSQL, and SQLite.
+we only support these databases: MariaDB, MySQL, PostgreSQL, SQLite, MS SQL, and DuckDB.
 
 Additionally, support for JSON and date-time types is limited.
 Please take this into consideration when using these functions.

tests/build.gradle.kts

@@ -66,12 +66,14 @@ korro {
         include("docs/StardustDocs/topics/write.md")
         include("docs/StardustDocs/topics/rename.md")
         include("docs/StardustDocs/topics/guides/*.md")
+        include("docs/StardustDocs/topics/dataSources/sql/*.md")
     }
 
     samples = fileTree(project.projectDir) {
         include("src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/*.kt")
         include("src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/*.kt")
         include("src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/guides/*.kt")
+        include("src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/io/*.kt")
     }
 
     groupSamples {

tests/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/io/DuckDb.kt

@@ -0,0 +1,48 @@
+package org.jetbrains.kotlinx.dataframe.samples.io
+
+import org.jetbrains.kotlinx.dataframe.DataFrame
+import org.jetbrains.kotlinx.dataframe.io.DbConnectionConfig
+import org.jetbrains.kotlinx.dataframe.io.readSqlQuery
+import org.jetbrains.kotlinx.dataframe.io.readSqlTable
+import org.junit.Ignore
+import org.junit.Test
+import java.sql.DriverManager
+
+class DuckDb {
+
+    @Ignore
+    @Test
+    fun readSqlTable() {
+        // SampleStart
+        val url = "jdbc:duckdb:/testDatabase"
+        val username = "duckdb"
+        val password = "password"
+
+        val dbConfig = DbConnectionConfig(url, username, password)
+
+        val tableName = "Customer"
+
+        val df = DataFrame.readSqlTable(dbConfig, tableName)
+        // SampleEnd
+    }
+
+    // source: https://duckdb.org/docs/stable/core_extensions/iceberg/overview.html
+    @Ignore
+    @Test
+    fun readIcebergExtension() {
+        // SampleStart
+        // Creating an in-memory DuckDB database
+        val connection = DriverManager.getConnection("jdbc:duckdb:")
+        val df = connection.use { connection ->
+            // install and load Iceberg
+            connection.createStatement().execute("INSTALL iceberg; LOAD iceberg;")
+
+            // query a table from Iceberg using a specific SQL query
+            DataFrame.readSqlQuery(
+                connection = connection,
+                sqlQuery = "SELECT * FROM iceberg_scan('data/iceberg/lineitem_iceberg', allow_moved_paths = true);",
+            )
+        }
+        // SampleEnd
+    }
+}