Complete the documents and update Kotlin's version

Author: qiaoyuang

CHANGELOG.md

@@ -2,29 +2,33 @@
 
 - Date format: YYYY-MM-dd
 
-## 2.0.0 / 2025-10-xx
+## 2.0.0 / 2025-10-23
 
 ### All
 
-* Update `Kotlin`'s version to `2.2.20`
+* Update `Kotlin`'s version to `2.2.21`
 * Remove the Desuger configuration
+* Update minimal supported Android version from API 23 to 24
 
 ### sqllin-dsl
 
 * Optimized performance for SQL assembly
-* New API for creating Database: `DSLDBConfiguration`
-* New experimental API: `DatabaseScope#CREATE`
-* New experimental API: `DatabaseScope#DROP`
-* New experimental API: `DatabaseSceop#ALERT`
+* New annotation for marking primary key: `PrimaryKey`
+* New annotation for marking composite primary key: `CompositePrimaryKey`
+* New experimental API for creating Database: `DSLDBConfiguration`
+* New experimental DSL API: `DatabaseScope#CREATE`
+* New experimental DSL API: `DatabaseScope#DROP`
+* New experimental DSL API: `DatabaseSceop#ALERT`
 * Support using ByteArray in DSL, that represents BLOB in SQLite
 
 ### sqllin-driver
 
 * Update the `sqlite-jdbc`'s version to `3.50.3.0`
+* **Breaking change**: The data type of `bindParams` in `DatabaseConnection#query` changed from `Array<out String?>?` to `Array<out Any?>?`
 
 ### sqllin-processor
 
-* Update `KSP`'s version to `2.2.20-2.0.4`
+* Update `KSP`'s version to `2.3.0`
 
 ## 1.4.4 / 2025-07-07
 

gradle/libs.versions.toml

@@ -1,8 +1,8 @@
 [versions]
 
-kotlin = "2.2.20"
+kotlin = "2.2.21"
 agp = "8.12.3"
-ksp = "2.2.20-2.0.4"
+ksp = "2.3.0"
 serialization = "1.9.0"
 coroutines = "1.10.2"
 androidx-annotation = "1.9.1"
@@ -11,7 +11,7 @@ androidx-test-runner = "1.7.0"
 sqlite-jdbc = "3.50.3.0"
 jvm-toolchain = "21"
 android-sdk-compile = "36"
-android-sdk-min = "23"
+android-sdk-min = "24"
 vanniktech-maven-publish = "0.34.0"
 
 [libraries]

sqllin-architecture.png

@@ -14,7 +14,7 @@ plugins {
     id("com.google.devtools.ksp")
 }
 
-val sqllinVersion = "1.4.4"
+val sqllinVersion = "2.0.0"
 
 kotlin {
     // ......
@@ -122,10 +122,48 @@ val database = Database(
 注意，由于 Android Framework 的限制，`inMemory`、`journalMode`、`lookasideSlotSize`、`lookasideSlotCount` 这些参数仅在 Android 9 及以上版本生效。 并且，由于
 [sqlite-jdbc](https://github.com/xerial/sqlite-jdbc)（SQLlin 在 JVM 上基于它）不支持 `sqlite3_config()`，`lookasideSlotSize` 和 `lookasideSlotCount` 两个属性在 JVM 平台不生效。
 
-当前由于会改变数据库结构的操作暂时还没有 DSL 化支持。因此，你需要在 `create` 和 `update` 参数中使用字符串编写 SQL 语句。
+### 使用 DSLDBConfiguration 进行类型安全的模式管理
+
+除此之外，你还可以使用新的试验性 API `DSLDBConfiguration`，它允许你在 `create` 和 `upgrade` 回调中使用类型安全的 SQL DSL，而不是原始的 SQL 字符串：
+
+```kotlin
+import com.ctrip.sqllin.driver.DSLDBConfiguration
+import com.ctrip.sqllin.dsl.Database
+
+val database = Database(
+    DSLDBConfiguration(
+        name = "Person.db",
+        path = getGlobalDatabasePath(),
+        version = 1,
+        isReadOnly = false,
+        inMemory = false,
+        journalMode = JournalMode.WAL,
+        synchronousMode = SynchronousMode.NORMAL,
+        busyTimeout = 5000,
+        lookasideSlotSize = 0,
+        lookasideSlotCount = 0,
+        create = {
+            // Use type-safe DSL instead of raw SQL
+            CREATE(PersonTable)
+        },
+        upgrade = { oldVersion, newVersion ->
+            when (oldVersion) {
+                1 -> {
+                    // Example: Add a new column in version 2
+                    PersonTable ALERT_ADD_COLUMN PersonTable.email
+                }
+            }
+        }
+    )
+)
+```
+
+通过使用 `DSLDBConfiguration`，你可以直接在回调中使用 CREATE、DROP 和 ALTER 操作，使模式管理更加类型安全和易于维护。这些回调中可用的 DSL 操作与常规 `database { }` 块中可用的操作相同。
 
 通常你只需要在你的组件的生命周期内创建一个 `Database` 对象，所以你需要在组件的生命周期结束时手动关闭数据库：
 
+> 注意: `DSLDBConfiguration` 处于实验性阶段，但当其稳定后会彻底取代 `DatabaseConfiguration`, 也就是说在未来版本中 _sqllin-dsl_ 将不再支持使用 `DatabaseConfiguration` 创建 `Database` 实例。
+
 ```kotlin
 override fun onDestroy() {
     database.close()
@@ -156,6 +194,74 @@ data class Person(
 在 _sqllin-dsl_ 中，对象序列化为 SQL 语句，或者从游标中反序列化依赖 _kotlinx.serialization_，所以你需要在你的 data class
 上添加 `@Serializable` 注解。因此，如果你想在序列化或反序列化以及 `Table` 类生成的时候忽略某些属性，你可以给你的属性添加 `kotlinx.serialization.Transient` 注解。
 
+### 定义主键
+
+SQLlin 提供了用于定义数据库表主键的注解。
+
+#### 使用 @PrimaryKey 定义单一主键
+
+使用 `@PrimaryKey` 标记单个属性作为主键：
+
+```kotlin
+import com.ctrip.sqllin.dsl.annotation.DBRow
+import com.ctrip.sqllin.dsl.annotation.PrimaryKey
+import kotlinx.serialization.Serializable
+
+@DBRow
+@Serializable
+data class Person(
+    @PrimaryKey(autoIncrement = true)
+    val id: Long? = null,  // Auto-incrementing primary key
+    val name: String,
+    val age: Int,
+)
+```
+
+**重要的类型和可空性规则：**
+
+- **对于自增的 `Long` 主键**：属性**必须**声明为可空类型（`Long?`）。这会映射到 SQLite 的 `INTEGER PRIMARY KEY`，它作为内部 `rowid` 的别名。当插入 `id = null` 的新记录时，SQLite 会自动生成 ID。
+
+- **对于其他类型（String、Int 等）**：属性**必须**是非空的。插入时必须提供唯一值：
+
+```kotlin
+@DBRow
+@Serializable
+data class User(
+    @PrimaryKey
+    val username: String,  // Non-nullable, user-provided primary key
+    val email: String,
+)
+```
+
+`autoIncrement` 参数启用更严格的自增行为（使用 `AUTOINCREMENT` 关键字），确保行 ID 永远不会被重用。这仅对 `Long?` 属性有意义。
+
+#### 使用 @CompositePrimaryKey 定义组合主键
+
+当表的主键由多个列组成时，使用 `@CompositePrimaryKey`：
+
+```kotlin
+import com.ctrip.sqllin.dsl.annotation.DBRow
+import com.ctrip.sqllin.dsl.annotation.CompositePrimaryKey
+import kotlinx.serialization.Serializable
+
+@DBRow
+@Serializable
+data class Enrollment(
+    @CompositePrimaryKey
+    val studentId: Long,
+    @CompositePrimaryKey
+    val courseId: Long,
+    val enrollmentDate: String,
+)
+```
+
+**重要规则：**
+
+- 你可以在同一个类中对**多个属性**应用 `@CompositePrimaryKey`
+- 所有带有 `@CompositePrimaryKey` 的属性**必须是非空的**
+- 你**不能**在同一个类中混合使用 `@PrimaryKey` 和 `@CompositePrimaryKey` - 只能使用其中一个
+- 所有 `@CompositePrimaryKey` 属性的组合形成表的组合主键
+
 ## 接下来
 
 你已经学习完了所有的准备工作，现在可以开始学习如何操作数据库了：

sqllin-dsl/doc/getting-start-cn.md

@@ -16,7 +16,7 @@ plugins {
     id("com.google.devtools.ksp")
 }
 
-val sqllinVersion = "1.4.4"
+val sqllinVersion = "2.0.0"
 
 kotlin {
     // ......
@@ -126,15 +126,52 @@ val database = Database(
 )
 ```
 
-Note, because of limitation by Android Framework, the `inMemory`, `busyTimeout`, `lookasideSlotSize`, `lookasideSlotCount` 
+Note, because of limitation by Android Framework, the `inMemory`, `busyTimeout`, `lookasideSlotSize`, `lookasideSlotCount`
 only work on Android 9 and higher. And, because [sqlite-jdbc](https://github.com/xerial/sqlite-jdbc)(SQLlin is based on it on JVM) doesn't support
 `sqlite3_config()`, the `lookasideSlotSize` and `lookasideSlotCount` don't work on JVM target.
 
-Now, the operations that change database structure haven't been supported by DSL yet. So, you need to write these SQL statements by string
-as in `create` and `upgrade` parameters.
+### Using DSLDBConfiguration for Type-Safe Schema Management
+
+Alternatively, you can use `DSLDBConfiguration` which allows you to use the type-safe SQL DSL in the `create` and `upgrade` callbacks instead of raw SQL strings:
+
+```kotlin
+import com.ctrip.sqllin.driver.DSLDBConfiguration
+import com.ctrip.sqllin.dsl.Database
+
+val database = Database(
+    DSLDBConfiguration(
+        name = "Person.db",
+        path = getGlobalDatabasePath(),
+        version = 1,
+        isReadOnly = false,
+        inMemory = false,
+        journalMode = JournalMode.WAL,
+        synchronousMode = SynchronousMode.NORMAL,
+        busyTimeout = 5000,
+        lookasideSlotSize = 0,
+        lookasideSlotCount = 0,
+        create = {
+            // Use type-safe DSL instead of raw SQL
+            CREATE(PersonTable)
+        },
+        upgrade = { oldVersion, newVersion ->
+            when (oldVersion) {
+                1 -> {
+                    // Example: Add a new column in version 2
+                    PersonTable ALERT_ADD_COLUMN PersonTable.email
+                }
+            }
+        }
+    )
+)
+```
+
+With `DSLDBConfiguration`, you can use CREATE, DROP, and ALTER operations directly in the callbacks, making schema management more type-safe and maintainable. The DSL operations available in these callbacks are the same as those available in regular `database { }` blocks.
 
 Usually, you just need to create one `Database` instance in your component lifecycle. So, you need to close database manually when the lifecycle ended:
 
+> Notice: `DSLDBConfiguration` is experimental, but it will completely replace `DatabaseConfiguration` when it is stable. That means _sqllin-dsl_ will not support to use `DatabaseConfiguration` to create `Database` instances in the future versions.
+
 ```kotlin
 override fun onDestroy() {
     database.close()
@@ -167,6 +204,74 @@ name as table name, for example, `Person`'s default table name is "Person".
 In _sqllin-dsl_, objects are serialized to SQL and deserialized from cursor depend on _kotlinx.serialization_. So, you also need to add the `@Serializable` onto your data classes. Therefore, if
 you want to ignore some properties when serialization or deserialization and `Table` classes generation, you can annotate your properties with `kotlinx.serialization.Transient`.
 
+### Defining Primary Keys
+
+SQLlin provides annotations to define primary keys for your database tables.
+
+#### Single Primary Key with @PrimaryKey
+
+Use `@PrimaryKey` to mark a single property as the primary key:
+
+```kotlin
+import com.ctrip.sqllin.dsl.annotation.DBRow
+import com.ctrip.sqllin.dsl.annotation.PrimaryKey
+import kotlinx.serialization.Serializable
+
+@DBRow
+@Serializable
+data class Person(
+    @PrimaryKey(autoIncrement = true)
+    val id: Long? = null,  // Auto-incrementing primary key
+    val name: String,
+    val age: Int,
+)
+```
+
+**Important type and nullability rules:**
+
+- **For `Long` primary keys with auto-increment**: The property **must** be declared as nullable (`Long?`). This maps to SQLite's `INTEGER PRIMARY KEY` which acts as an alias for the internal `rowid`. When inserting a new record with `id = null`, SQLite automatically generates the ID.
+
+- **For other types (String, Int, etc.)**: The property **must** be non-nullable. You must provide a unique value when inserting:
+
+```kotlin
+@DBRow
+@Serializable
+data class User(
+    @PrimaryKey
+    val username: String,  // Non-nullable, user-provided primary key
+    val email: String,
+)
+```
+
+The `autoIncrement` parameter enables stricter auto-incrementing behavior (using `AUTOINCREMENT` keyword), ensuring row IDs are never reused. This is only meaningful for `Long?` properties.
+
+#### Composite Primary Key with @CompositePrimaryKey
+
+Use `@CompositePrimaryKey` when your table's primary key consists of multiple columns:
+
+```kotlin
+import com.ctrip.sqllin.dsl.annotation.DBRow
+import com.ctrip.sqllin.dsl.annotation.CompositePrimaryKey
+import kotlinx.serialization.Serializable
+
+@DBRow
+@Serializable
+data class Enrollment(
+    @CompositePrimaryKey
+    val studentId: Long,
+    @CompositePrimaryKey
+    val courseId: Long,
+    val enrollmentDate: String,
+)
+```
+
+**Important rules:**
+
+- You can apply `@CompositePrimaryKey` to **multiple properties** in the same class
+- All properties with `@CompositePrimaryKey` **must be non-nullable**
+- You **cannot** mix `@PrimaryKey` and `@CompositePrimaryKey` in the same class - use one or the other
+- The combination of all `@CompositePrimaryKey` properties forms the table's composite primary key
+
 ## Next Step
 
 You have learned all the preparations, you can start learn how to operate database now: