Add per-query SQL syntax validation toggle (@Query(checkSyntax)), update README with usage examples, and refactor validation mechanism in RepositoryProcessor.

Author: smyrgeorge

README.md

@@ -368,7 +368,8 @@ For more details take a look at the [examples](./examples).
 - When it runs: at KSP processing time, before your code is compiled/run.
 - Dialect notes: validation is dialect-agnostic and aims for an ANSI/portable subset. Some vendor-specific features
   (e.g., certain MySQL or PostgreSQL extensions) may not be recognized. If you hit a false positive, you can disable
-  validation per module with ksp arg validate-sql-syntax=false.
+  validation per module with ksp arg validate-sql-syntax=false, or disable it per query with
+  `@Query(checkSyntax = false)`.
 - Most reliable with: SELECT, INSERT, UPDATE, DELETE statements. DDL or very advanced constructs may not be fully
   supported.
 
@@ -380,12 +381,24 @@ Invalid SQL in function findAllBy: Encountered "FROMM" at line 1, column 15
 ```
 
 Tip: keep it enabled to catch typos early; if you rely heavily on vendor-specific syntax not yet supported by the
-parser, turn it off with:
+parser, turn it off either globally or just for a specific method:
+
+- Globally (module-wide):
 
 ```kotlin
 ksp { arg("validate-sql-syntax", "false") }
 ```
 
+- Per query:
+
+```kotlin
+@Repository(mapper = UserMapper::class)
+interface UserRepository {
+    @Query("select * from users where id = :id", checkSyntax = false)
+    suspend fun findOneById(context: QueryExecutor, id: Int): Result<User?>
+}
+```
+
 ### Database Migrations
 
 Run any pending migrations against the database; and validate previously applied migrations against the current

sqlx4k-codegen/src/jvmMain/kotlin/io/github/smyrgeorge/sqlx4k/processor/RepositoryProcessor.kt

@@ -32,8 +32,8 @@ class RepositoryProcessor(
             ?: error("Missing ${TableProcessor.PACKAGE_OPTION} option")
         logger.info("[RepositoryProcessor] Output package: $outputPackage")
 
-        val validateSqlSyntax = options[VALIDATE_SQL_SYNTAX_OPTION]?.toBoolean() ?: true
-        logger.info("[RepositoryProcessor] Validate SQL syntax: $validateSqlSyntax")
+        val globalCheckSqlSyntax = options[VALIDATE_SQL_SYNTAX_OPTION]?.toBoolean() ?: true
+        logger.info("[RepositoryProcessor] Validate SQL syntax: $globalCheckSqlSyntax")
 
         val outputFilename = "GeneratedRepositories"
 
@@ -72,7 +72,14 @@ class RepositoryProcessor(
             // findAll/findAllBy/findOneBy/deleteBy/countBy/execute and also *All variants
             fnsAll
                 .filter { fn -> fn.annotations.any { it.qualifiedName() == TypeNames.QUERY_ANNOTATION } }
-                .forEach { fn -> emitQueryMethod(file, fn, validateSqlSyntax, mapperTypeName, domainDecl) }
+                .forEach { fn ->
+                    val queryAnn = fn.annotations.first { it.qualifiedName() == TypeNames.QUERY_ANNOTATION }
+                    val localCheckSqlSyntax = queryAnn.arguments
+                        .firstOrNull { it.name?.asString() == "checkSyntax" }
+                        ?.value as? Boolean ?: true
+                    val doCheckSyntax = globalCheckSqlSyntax && localCheckSqlSyntax
+                    emitQueryMethod(file, fn, doCheckSyntax, mapperTypeName, domainDecl)
+                }
 
             // Generate CRUD methods: insert/update/delete;
             // Interface must implement CrudRepository<Domain> which we already validated.

sqlx4k/src/commonMain/kotlin/io/github/smyrgeorge/sqlx4k/annotation/Query.kt

@@ -1,12 +1,21 @@
 package io.github.smyrgeorge.sqlx4k.annotation
 
 /**
- * Annotation used to specify a query string for a database operation.
- * This annotation is applied to functions to indicate the query
- * that should be executed when the function is called.
+ * Annotates a repository function with an inline SQL query to execute.
  *
- * @property value The query string to be executed.
+ * This is consumed by the KSP code generator to produce the implementation
+ * and (optionally) validate the SQL syntax at compile time.
+ *
+ * Properties:
+ * - value: the SQL string to execute. Named parameters are supported using :name.
+ * - checkSyntax: when true (default), the processor will validate the SQL syntax
+ *   at compile time using JSqlParser, subject to the module-wide setting
+ *   `ksp { arg("validate-sql-syntax", "true|false") }`. Set to false to skip
+ *   validation for this specific query while leaving global validation enabled.
  */
 @Target(AnnotationTarget.FUNCTION)
 @Retention(AnnotationRetention.SOURCE)
-annotation class Query(val value: String)
+annotation class Query(
+    val value: String,
+    val checkSyntax: Boolean = true,
+)