Add support for typed null parameters in prepared statements across all drivers

- Introduced `TypedNull` wrapper to specify type information for null parameters.
- Added `bindNull` methods to `Statement` for positional and named parameters.
- Updated SQL rendering logic for MySQL, PostgreSQL, and SQLite to handle `TypedNull`.
- Extended test suite to cover typed null bindings with various SQL column types.

Author: smyrgeorge

sqlx4k-mysql/src/jvmMain/kotlin/io/github/smyrgeorge/sqlx4k/mysql/MySQL.kt

@@ -25,6 +25,7 @@ import io.github.smyrgeorge.sqlx4k.ValueEncoderRegistry
 import io.github.smyrgeorge.sqlx4k.impl.migrate.Migration
 import io.github.smyrgeorge.sqlx4k.impl.migrate.MigrationFile
 import io.github.smyrgeorge.sqlx4k.impl.migrate.Migrator
+import io.github.smyrgeorge.sqlx4k.impl.types.TypedNull
 import io.netty.buffer.ByteBuf
 import io.netty.buffer.ByteBufAllocator
 import io.r2dbc.pool.ConnectionPool as NativeR2dbcConnectionPool
@@ -449,8 +450,7 @@ class MySQL(
             statement: Statement,
             encoders: ValueEncoderRegistry
         ): io.r2dbc.spi.Statement {
-            fun Any?.toR2dbc(): Any? = when (this) {
-                null -> this
+            fun Any.toR2dbc(): Any = when (this) {
                 is Char -> toString()
                 // MySQL DATETIME is timezone-agnostic; convert to UTC LocalDateTime to
                 // avoid session-timezone shifts when the driver binds java.time.Instant.
@@ -469,9 +469,11 @@ class MySQL(
             val query = statement.renderNativeQuery(Dialect.MySQL, encoders)
             val stmt = createStatement(query.sql)
             query.values.forEachIndexed { index, value ->
-                val converted = value?.toR2dbc()
-                if (converted == null) stmt.bindNull(index, Any::class.java)
-                else stmt.bind(index, converted)
+                when (value) {
+                    is TypedNull -> stmt.bindNull(index, value.type.java)
+                    null -> stmt.bindNull(index, Any::class.java)
+                    else -> stmt.bind(index, value.toR2dbc())
+                }
             }
             return stmt
         }

sqlx4k-postgres/src/commonTest/kotlin/io/github/smyrgeorge/sqlx4k/postgres/CommonPostgreSQLPreparedStatementTests.kt

@@ -10,16 +10,19 @@ import assertk.assertions.isNull
 import assertk.assertions.isTrue
 import io.github.smyrgeorge.sqlx4k.Statement
 import io.github.smyrgeorge.sqlx4k.impl.extensions.asBoolean
+import io.github.smyrgeorge.sqlx4k.impl.extensions.asBooleanOrNull
 import io.github.smyrgeorge.sqlx4k.impl.extensions.asDouble
 import io.github.smyrgeorge.sqlx4k.impl.extensions.asFloat
 import io.github.smyrgeorge.sqlx4k.impl.extensions.asInstant
+import io.github.smyrgeorge.sqlx4k.impl.extensions.asInstantOrNull
 import io.github.smyrgeorge.sqlx4k.impl.extensions.asInt
 import io.github.smyrgeorge.sqlx4k.impl.extensions.asLocalDate
 import io.github.smyrgeorge.sqlx4k.impl.extensions.asLocalDateTime
 import io.github.smyrgeorge.sqlx4k.impl.extensions.asLocalTime
 import io.github.smyrgeorge.sqlx4k.impl.extensions.asLong
 import io.github.smyrgeorge.sqlx4k.impl.extensions.asShort
 import io.github.smyrgeorge.sqlx4k.impl.extensions.asUuid
+import io.github.smyrgeorge.sqlx4k.impl.extensions.asUuidOrNull
 import io.github.smyrgeorge.sqlx4k.impl.statement.ExtendedStatement
 import io.github.smyrgeorge.sqlx4k.impl.types.NoWrappingTuple
 import kotlin.random.Random
@@ -141,34 +144,82 @@ class CommonPostgreSQLPreparedStatementTests(
         val table = newTable()
         try {
             db.execute(
-                "create table $table(id serial primary key, v_text text, v_int4 int4)"
+                """
+                create table $table(
+                    id serial primary key,
+                    v_text text,
+                    v_int4 int4,
+                    v_bool bool,
+                    v_uuid uuid,
+                    v_tstz timestamptz
+                )
+                """.trimIndent()
             ).getOrThrow()
 
-            // Positional null
+            // Positional null — text column
             val insertPos = Statement.create("insert into $table(v_text, v_int4) values (?, ?)")
                 .bind(0, null)
                 .bind(1, 1)
             db.execute(insertPos).getOrThrow()
 
-            // Named null
+            // Named null — int4 column
             val insertNamed = Statement.create("insert into $table(v_text, v_int4) values (:text, :int4)")
                 .bind("text", "present")
                 .bind("int4", null)
             db.execute(insertNamed).getOrThrow()
 
-            // Verify positional null
+            // Positional null — uuid column (most likely to break with Any::class.java)
+            val insertUuid = Statement.create("insert into $table(v_int4, v_uuid) values (?, ?)")
+                .bind(0, 3)
+                .bind(1, null)
+            db.execute(insertUuid).getOrThrow()
+
+            // Named null — bool column
+            val insertBool = Statement.create("insert into $table(v_int4, v_bool) values (:id, :flag)")
+                .bind("id", 4)
+                .bind("flag", null)
+            db.execute(insertBool).getOrThrow()
+
+            // Positional null — timestamptz column
+            val insertTstz = Statement.create("insert into $table(v_int4, v_tstz) values (?, ?)")
+                .bind(0, 5)
+                .bind(1, null)
+            db.execute(insertTstz).getOrThrow()
+
+            // Verify positional null (text)
             val row1 = db.fetchAll(
                 Statement.create("select v_text, v_int4 from $table where v_int4 = ?").bind(0, 1)
             ).getOrThrow().first()
             assertThat(row1.get(0).asStringOrNull()).isNull()
             assertThat(row1.get(1).asInt()).isEqualTo(1)
 
-            // Verify named null
+            // Verify named null (int4)
             val row2 = db.fetchAll(
                 Statement.create("select v_text, v_int4 from $table where v_text = :t").bind("t", "present")
             ).getOrThrow().first()
             assertThat(row2.get(0).asString()).isEqualTo("present")
             assertThat(row2.get(1).asStringOrNull()).isNull()
+
+            // Verify positional null (uuid)
+            val row3 = db.fetchAll(
+                Statement.create("select v_int4, v_uuid from $table where v_int4 = ?").bind(0, 3)
+            ).getOrThrow().first()
+            assertThat(row3.get(0).asInt()).isEqualTo(3)
+            assertThat(row3.get(1).asUuidOrNull()).isNull()
+
+            // Verify named null (bool)
+            val row4 = db.fetchAll(
+                Statement.create("select v_int4, v_bool from $table where v_int4 = ?").bind(0, 4)
+            ).getOrThrow().first()
+            assertThat(row4.get(0).asInt()).isEqualTo(4)
+            assertThat(row4.get(1).asBooleanOrNull()).isNull()
+
+            // Verify positional null (timestamptz)
+            val row5 = db.fetchAll(
+                Statement.create("select v_int4, v_tstz from $table where v_int4 = ?").bind(0, 5)
+            ).getOrThrow().first()
+            assertThat(row5.get(0).asInt()).isEqualTo(5)
+            assertThat(row5.get(1).asInstantOrNull()).isNull()
         } finally {
             runCatching { db.execute("drop table if exists $table") }
         }

sqlx4k-postgres/src/jvmMain/kotlin/io/github/smyrgeorge/sqlx4k/postgres/PostgreSQLImpl.kt

@@ -15,6 +15,7 @@ import io.github.smyrgeorge.sqlx4k.ValueEncoderRegistry
 import io.github.smyrgeorge.sqlx4k.impl.migrate.Migration
 import io.github.smyrgeorge.sqlx4k.impl.migrate.MigrationFile
 import io.github.smyrgeorge.sqlx4k.impl.migrate.Migrator
+import io.github.smyrgeorge.sqlx4k.impl.types.TypedNull
 import io.r2dbc.pool.ConnectionPool as NativeR2dbcConnectionPool
 import io.r2dbc.postgresql.PostgresqlConnectionFactory
 import io.r2dbc.postgresql.api.Notification as NativeR2dbcNotification
@@ -502,8 +503,7 @@ class PostgreSQLImpl(
             statement: Statement,
             encoders: ValueEncoderRegistry
         ): io.r2dbc.spi.Statement {
-            fun Any?.toR2dbc(): Any? = when (this) {
-                null -> this
+            fun Any.toR2dbc(): Any = when (this) {
                 is Instant -> toJavaInstant()
                 is LocalDate -> toJavaLocalDate()
                 is LocalTime -> toJavaLocalTime()
@@ -515,9 +515,11 @@ class PostgreSQLImpl(
             val query = statement.renderNativeQuery(Dialect.PostgreSQL, encoders)
             val stmt = createStatement(query.sql)
             query.values.forEachIndexed { index, value ->
-                val converted = value?.toR2dbc()
-                if (converted == null) stmt.bindNull(index, Any::class.java)
-                else stmt.bind(index, converted)
+                when (value) {
+                    is TypedNull -> stmt.bindNull(index, value.type.java)
+                    null -> stmt.bindNull(index, Any::class.java)
+                    else -> stmt.bind(index, value.toR2dbc())
+                }
             }
             return stmt
         }

sqlx4k-sqlite/src/jvmMain/kotlin/io/github/smyrgeorge/sqlx4k/sqlite/SQLite.kt

@@ -19,6 +19,7 @@ import io.github.smyrgeorge.sqlx4k.impl.migrate.Migrator
 import io.github.smyrgeorge.sqlx4k.impl.pool.ConnectionPoolImpl
 import io.github.smyrgeorge.sqlx4k.impl.pool.PooledConnection
 import io.github.smyrgeorge.sqlx4k.impl.pool.PooledTransaction
+import io.github.smyrgeorge.sqlx4k.impl.types.TypedNull
 import java.sql.Connection as NativeJdbcConnection
 import java.sql.DriverManager
 import java.sql.ResultSet as NativeJdbcResultSet
@@ -428,7 +429,11 @@ class SQLite(
             val query = statement.renderNativeQuery(Dialect.SQLite, encoders)
             val stmt = prepareStatement(query.sql)
             query.values.forEachIndexed { index, value ->
-                stmt.setObject(index + 1, value?.toJdbc())
+                when (value) {
+                    is TypedNull -> stmt.setNull(index + 1, java.sql.Types.NULL)
+                    null -> stmt.setNull(index + 1, java.sql.Types.NULL)
+                    else -> stmt.setObject(index + 1, value.toJdbc())
+                }
             }
             return stmt
         }

sqlx4k/src/commonMain/kotlin/io/github/smyrgeorge/sqlx4k/Statement.kt

@@ -1,6 +1,7 @@
 package io.github.smyrgeorge.sqlx4k
 
 import io.github.smyrgeorge.sqlx4k.impl.statement.SimpleStatement
+import kotlin.reflect.KClass
 
 /**
  * Represents a statement that allows binding of positional and named parameters.
@@ -60,6 +61,20 @@ interface Statement {
      */
     fun bind(index: Int, value: Any?): Statement
 
+    /**
+     * Binds a typed null value to a positional parameter in the statement.
+     *
+     * This method is used to explicitly bind a `null` value to a positional parameter
+     * while specifying the intended SQL type. It is particularly useful when interacting
+     * with strongly-typed SQL columns where the type information is required to correctly
+     * handle the `null` value (e.g., `uuid`, `timestamptz`, typed arrays).
+     *
+     * @param index The zero-based index of the positional parameter to bind the null value to.
+     * @param type The Kotlin class corresponding to the intended SQL type of the parameter.
+     * @return The current `Statement` instance to allow for method chaining.
+     */
+    fun bindNull(index: Int, type: KClass<*>): Statement
+
     /**
      * Binds a value to a named parameter in the statement.
      *
@@ -69,6 +84,21 @@ interface Statement {
      */
     fun bind(parameter: String, value: Any?): Statement
 
+    /**
+     * Binds a typed null value to a named parameter in the statement.
+     *
+     * This method is used to explicitly bind a `null` value to a named parameter
+     * while specifying the intended SQL type. It is beneficial in cases where
+     * the type information is required to properly handle the `null` value,
+     * such as in the case of strongly-typed SQL columns (e.g., `uuid`, `timestamptz`,
+     * typed arrays).
+     *
+     * @param parameter The name of the parameter to bind the null value to.
+     * @param type The Kotlin class representing the intended SQL type of the parameter.
+     * @return The current `Statement` instance to allow for method chaining.
+     */
+    fun bindNull(parameter: String, type: KClass<*>): Statement
+
     /**
      * Renders the SQL statement by replacing placeholders for positional and named parameters
      * with their respective bound values.

sqlx4k/src/commonMain/kotlin/io/github/smyrgeorge/sqlx4k/impl/extensions/encode.kt

@@ -4,6 +4,7 @@ package io.github.smyrgeorge.sqlx4k.impl.extensions
 
 import io.github.smyrgeorge.sqlx4k.Dialect
 import io.github.smyrgeorge.sqlx4k.SQLError
+import io.github.smyrgeorge.sqlx4k.impl.types.TypedNull
 import io.github.smyrgeorge.sqlx4k.ValueEncoderRegistry
 import io.github.smyrgeorge.sqlx4k.impl.types.NoWrappingTuple
 import kotlin.time.Instant
@@ -32,6 +33,7 @@ import kotlinx.datetime.toLocalDateTime
 internal fun Any?.encodeValue(encoders: ValueEncoderRegistry): String {
     return when (this) {
         null -> "null"
+        is TypedNull -> "null"
         is String -> {
             // Fast path: if no single quote present, avoid replace allocation
             if (indexOf('\'') < 0) return "'${this}'"
@@ -124,6 +126,7 @@ internal fun Instant.toTimestampString(timeZone: TimeZone = TimeZone.UTC): Strin
 internal fun Any?.resolveNativeValue(encoders: ValueEncoderRegistry): Any? {
     return when (this) {
         null -> null
+        is TypedNull -> this
         is String, is Char, is Boolean, is Byte, is Short, is Int, is Long, is Float, is Double -> this
         is Instant, is LocalDate, is LocalTime, is LocalDateTime -> this
         is Uuid -> this

sqlx4k/src/commonMain/kotlin/io/github/smyrgeorge/sqlx4k/impl/statement/AbstractStatement.kt

@@ -3,7 +3,9 @@ package io.github.smyrgeorge.sqlx4k.impl.statement
 import io.github.smyrgeorge.sqlx4k.Dialect
 import io.github.smyrgeorge.sqlx4k.SQLError
 import io.github.smyrgeorge.sqlx4k.Statement
+import io.github.smyrgeorge.sqlx4k.impl.types.TypedNull
 import io.github.smyrgeorge.sqlx4k.ValueEncoderRegistry
+import kotlin.reflect.KClass
 import io.github.smyrgeorge.sqlx4k.impl.extensions.appendNativeValue
 import io.github.smyrgeorge.sqlx4k.impl.extensions.encodeValue
 import io.github.smyrgeorge.sqlx4k.impl.extensions.isIdentPart
@@ -108,6 +110,44 @@ abstract class AbstractStatement(
         return this
     }
 
+    /**
+     * Binds a typed null to a positional parameter.
+     *
+     * @param index The zero-based index of the positional parameter.
+     * @param type  The Kotlin class of the intended SQL type.
+     * @return The current [Statement] instance to allow for method chaining.
+     * @throws SQLError if the given index is out of bounds.
+     */
+    override fun bindNull(index: Int, type: KClass<*>): AbstractStatement {
+        if (index !in 0..<extractedPositionalParameters) {
+            SQLError(
+                code = SQLError.Code.PositionalParameterOutOfBounds,
+                message = "Index '$index' out of bounds."
+            ).raise()
+        }
+        positionalParametersValues[index] = TypedNull(type)
+        return this
+    }
+
+    /**
+     * Binds a typed null to a named parameter.
+     *
+     * @param parameter The name of the parameter.
+     * @param type      The Kotlin class of the intended SQL type.
+     * @return The current [Statement] instance to allow for method chaining.
+     * @throws SQLError if the specified named parameter is not found.
+     */
+    override fun bindNull(parameter: String, type: KClass<*>): AbstractStatement {
+        if (parameter !in extractedNamedParameters) {
+            SQLError(
+                code = SQLError.Code.NamedParameterNotFound,
+                message = "Parameter '$parameter' not found."
+            ).raise()
+        }
+        namedParametersValues[parameter] = TypedNull(type)
+        return this
+    }
+
     /**
      * Renders the SQL statement by replacing positional and named parameter placeholders
      * with their corresponding bound values using the provided encoder registry.

sqlx4k/src/commonMain/kotlin/io/github/smyrgeorge/sqlx4k/impl/statement/ExtendedStatement.kt

@@ -3,9 +3,11 @@ package io.github.smyrgeorge.sqlx4k.impl.statement
 import io.github.smyrgeorge.sqlx4k.Dialect
 import io.github.smyrgeorge.sqlx4k.SQLError
 import io.github.smyrgeorge.sqlx4k.Statement
+import io.github.smyrgeorge.sqlx4k.impl.types.TypedNull
 import io.github.smyrgeorge.sqlx4k.ValueEncoderRegistry
 import io.github.smyrgeorge.sqlx4k.impl.extensions.encodeValue
 import io.github.smyrgeorge.sqlx4k.impl.extensions.resolveNativeValue
+import kotlin.reflect.KClass
 
 /**
  * The `ExtendedStatement` class provides an implementation that extends the functionality
@@ -57,6 +59,17 @@ class ExtendedStatement(sql: String) : AbstractStatement(sql) {
         return this
     }
 
+    override fun bindNull(index: Int, type: KClass<*>): ExtendedStatement {
+        if (index < 0 || index >= pgParameters.size) {
+            SQLError(
+                code = SQLError.Code.PositionalParameterOutOfBounds,
+                message = "Index '$index' out of bounds."
+            ).raise()
+        }
+        pgParametersValues[index] = TypedNull(type)
+        return this
+    }
+
     /**
      * Renders a native SQL query by resolving positional parameters and encoding their values
      * using the specified encoder registry for the given SQL dialect.

sqlx4k/src/commonMain/kotlin/io/github/smyrgeorge/sqlx4k/impl/types/TypedNull.kt

@@ -0,0 +1,15 @@
+package io.github.smyrgeorge.sqlx4k.impl.types
+
+import kotlin.reflect.KClass
+
+/**
+ * Wraps a null value with type information for use with [io.github.smyrgeorge.sqlx4k.Statement.bindNull].
+ *
+ * When binding a null parameter to a prepared statement, the database driver
+ * typically needs the target SQL type to determine the correct OID or wire format.
+ * This wrapper preserves that type alongside the null so it can be forwarded to the
+ * driver's `bindNull` call.
+ *
+ * @property type The Kotlin class representing the intended parameter type.
+ */
+data class TypedNull(val type: KClass<*>)