Provide access to the Sqlite3 connection handle.

Solves #56.

caqti-driver-mariadb/lib/caqti_driver_mariadb.ml

@@ -574,6 +574,7 @@ module Connect_functor (System : Caqti_driver_sig.System_unix) = struct
         in
         let module C = struct
           let driver_info = driver_info
+          let driver_connection = None
           include B
           include Caqti_connection.Make_convenience (System) (B)
           include Caqti_connection.Make_populate (System) (B)

caqti-driver-postgresql/lib/caqti_driver_postgresql.ml

@@ -986,6 +986,7 @@ module Connect_functor (System : Caqti_driver_sig.System_unix) = struct
                 in
                 let module Connection = struct
                   let driver_info = driver_info
+                  let driver_connection = None
                   include B
                   include Caqti_connection.Make_convenience (System) (B)
                 end in

caqti-driver-sqlite3/lib/caqti_driver_sqlite3.ml

@@ -31,6 +31,8 @@ let driver_info =
     ~describe_has_typed_fields:true
     ()
 
+type Caqti_connection_sig.driver_connection += Driver_connection of Sqlite3.db
+
 let get_uri_bool uri name =
   (match Uri.get_query_param uri name with
    | Some ("true" | "yes") -> Some true
@@ -583,6 +585,7 @@ module Connect_functor (System : Caqti_driver_sig.System_unix) = struct
       let module Connection_base = Make_connection_base (Arg) in
       let module Connection = struct
         let driver_info = driver_info
+        let driver_connection = Some (Driver_connection db)
         include Connection_base
         include Caqti_connection.Make_convenience (System) (Connection_base)
         include Caqti_connection.Make_populate (System) (Connection_base)

caqti-driver-sqlite3/lib/caqti_driver_sqlite3.mli

@@ -41,3 +41,7 @@ type Caqti_error.msg += Error_msg of {
   errmsg: string option;
     (** The error message reportedy by [sqlite3_errmsg]. *)
 }
+
+(** {1 Access to Raw Connection Handle} *)
+
+type Caqti_connection_sig.driver_connection += Driver_connection of Sqlite3.db

caqti-driver-sqlite3/test/test_sqlite3.ml

@@ -41,8 +41,23 @@ let test_error (module C : Caqti_blocking.CONNECTION) =
    | Error err ->
       Alcotest.failf "unexpected error from bad_insert: %a" Caqti_error.pp err)
 
+let trim_req =
+  Req.(string -->! string @:- "SELECT trim(?)")
+
+let test_fun (module C : Caqti_blocking.CONNECTION) =
+  (match C.driver_connection with
+   | Some Caqti_driver_sqlite3.Driver_connection db ->
+      Sqlite3.create_fun1 db "trim" begin function
+       | TEXT s -> TEXT (String.trim s)
+       | x -> x
+      end;
+      assert (C.find trim_req "  . " = Ok ".")
+   | Some _ -> assert false
+   | None -> assert false)
+
 let test_cases_on_connection = [
   "test_error", `Quick, test_error;
+  "test_fun", `Quick, test_fun;
 ]
 
 let mk_test (name, pool) =

caqti/lib/caqti_connection_sig.mli

@@ -48,6 +48,9 @@
     functions {!Caqti_request.create} and {!S.fold} can construct and process
     any supported SQL query. *)
 
+type driver_connection = ..
+(** This type is only to be extended by drivers. *)
+
 (** Essential connection signature implemented by drivers. *)
 module type Base = sig
   type +'a future
@@ -223,6 +226,12 @@ module type S = sig
   val driver_info : Caqti_driver_info.t
   (** Information about the driver providing this connection module. *)
 
+  val driver_connection : driver_connection option
+  (** The underlying connection object of the driver if available.  The open
+      variant constructor is defined in the driver library.  This is currently
+      only implemented for caqti-driver-sqlite3 for the purpose of defining
+      custom functions. *)
+
   include Base
   include Convenience with type 'a future := 'a future
   include Populate