Mark the new APIs as ExperimentalDSLDatabaseAPI.kt

Author: qiaoyuang

sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/DSLDBConfiguration.kt

@@ -20,6 +20,7 @@ import com.ctrip.sqllin.driver.DatabaseConfiguration
 import com.ctrip.sqllin.driver.DatabasePath
 import com.ctrip.sqllin.driver.JournalMode
 import com.ctrip.sqllin.driver.SynchronousMode
+import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI
 
 /**
  * DSL-level database configuration with [DatabaseScope] callbacks.
@@ -42,6 +43,7 @@ import com.ctrip.sqllin.driver.SynchronousMode
  *
  * @author Yuang Qiao
  */
+@ExperimentalDSLDatabaseAPI
 public data class DSLDBConfiguration(
     val name: String,
     val path: DatabasePath,

sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/DatabaseCreators.kt

@@ -19,6 +19,7 @@ package com.ctrip.sqllin.dsl
 import com.ctrip.sqllin.driver.DatabaseConfiguration
 import com.ctrip.sqllin.driver.DatabasePath
 import com.ctrip.sqllin.driver.openDatabase
+import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI
 
 /**
  * Factory functions for creating [Database] instances.
@@ -73,6 +74,7 @@ public fun Database(
  * @param enableSimpleSQLLog Whether to enable simple SQL logging for debugging
  * @return A new database instance
  */
+@ExperimentalDSLDatabaseAPI
 public fun Database(
     dsldbConfiguration: DSLDBConfiguration,
     enableSimpleSQLLog: Boolean = false,

sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/DatabaseScope.kt

@@ -18,6 +18,7 @@ package com.ctrip.sqllin.dsl
 
 import com.ctrip.sqllin.driver.DatabaseConnection
 import com.ctrip.sqllin.dsl.annotation.AdvancedInsertAPI
+import com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI
 import com.ctrip.sqllin.dsl.annotation.StatementDslMaker
 import com.ctrip.sqllin.dsl.sql.Table
 import com.ctrip.sqllin.dsl.sql.X
@@ -544,6 +545,7 @@ public class DatabaseScope internal constructor(
      * PersonTable.CREATE()
      * ```
      */
+    @ExperimentalDSLDatabaseAPI
     @StatementDslMaker
     public infix fun <T> CREATE(table: Table<T>) {
         val statement = Create.create(table, databaseConnection)
@@ -553,6 +555,7 @@ public class DatabaseScope internal constructor(
     /**
      * Creates this table from its definition (extension function variant).
      */
+    @ExperimentalDSLDatabaseAPI
     @StatementDslMaker
     @JvmName("create")
     public fun <T> Table<T>.CREATE(): Unit = CREATE(this)

sqllin-dsl/src/commonMain/kotlin/com/ctrip/sqllin/dsl/annotation/ExperimentalDSLDatabaseAPI.kt

@@ -0,0 +1,46 @@
+/*
+ * Copyright (C) 2025 Ctrip.com.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.ctrip.sqllin.dsl.annotation
+
+/**
+ * Marks declarations that are **experimental** in SQLlin DSL database API.
+ *
+ * This annotation indicates that the API is still being refined and may undergo changes
+ * in future releases. These APIs include experimental features that provide additional
+ * functionality but may not be as stable as the core APIs.
+ *
+ * Any usage of a declaration annotated with `@ExperimentalDSLDatabaseAPI` must be accepted either by
+ * annotating that usage with the [OptIn] annotation, e.g. `@OptIn(ExperimentalDSLDatabaseAPI::class)`,
+ * or by using the compiler argument `-opt-in=com.ctrip.sqllin.dsl.annotation.ExperimentalDSLDatabaseAPI`.
+ *
+ * @see OptIn
+ * @see RequiresOptIn
+ */
+@RequiresOptIn(
+    message = "This is an experimental API for SQLlin DSL database operations. " +
+            "It may be changed or removed in future releases. " +
+            "Use with caution and be prepared for potential breaking changes.",
+    level = RequiresOptIn.Level.WARNING
+)
+@Target(
+    AnnotationTarget.CLASS,
+    AnnotationTarget.FUNCTION,
+    AnnotationTarget.PROPERTY,
+    AnnotationTarget.TYPEALIAS
+)
+@Retention(AnnotationRetention.BINARY)
+public annotation class ExperimentalDSLDatabaseAPI