SQLiteConn: Add 'Raw' method to give access to underlying sqlite3 context structure

This is necessary, for instance, to allow users of the package to make
their own CGo callbacks, and have the underlying sqlite3 library call
those C functions directly.

Note that the intention from the sqlite3 library seems to be that
there should be a measure of binary compatibility between versions:
even extensions compiled against an older different version of sqlite3
should be able to call sqlite3_create_function with no problems. So
this should work even if users of the package have a slightly
different version of the sqlite3.h header.

Note that the code itself was written by @rittneje.  I tested it and
wrote the comments.

Signed-off-by: George Dunlap <[email protected]>

v2:
Just copy @rittneje's code exactly:
- Grab the lock while the function is running
- Replace the error code with our own if it's of type ErrNo

Author: gwd

doc.go

@@ -130,5 +130,12 @@ You can then use the custom driver by passing its name to sql.Open.
 	}
 
 See the documentation of RegisterFunc for more details.
+
+# Cgo SQLite3 Extensions
+
+Go callbacks are convenient, but the runtime overhead of reflecting
+incoming types can be significant.  For performance-critical
+functions, Cgo functions can also be defined.  See SQLiteConn's Raw
+method for an example.
 */
 package sqlite3

sqlite3.go

@@ -809,6 +809,53 @@ func (c *SQLiteConn) RegisterAggregator(name string, impl any, pure bool) error
 	return nil
 }
 
+// Raw provides access to the underlying raw C sqlite context pointer
+// by casting the `raw` argument from `unsafe.Pointer` to
+// `*C.sqlite3`.  This is can be used, for example, to add your own C
+// functions directly (which, due to fewer runtime reflection checks,
+// typically run an order of magnitude faster).  For example:
+//
+//    /*
+//    #include <sqlite3.h>
+//    ...
+//    void myFunc(sqlite3_context *context, int argc, sqlite3_value **argv) {
+//        // Function definition
+//    }
+//
+//    int myfunc_setup(sqlite3 *db) {
+//        return sqlite3_create_function(db, "myFunc", ...);
+//    }
+//    */
+//    import "C"
+//
+//    d := &sqlite3.SQLiteDriver{
+//        ConnectHook: func(c *SQLiteConn) error {
+//            return c.Raw(func(raw unsafe.Pointer) error {
+//                db := (*C.sqlite3)(raw)
+//                if rv := C.myfunc_setup(db); rv != C.SQLITE_OK {
+//                    return sqlite3.ErrNo(rv)
+//                }
+//                return nil
+//            }
+//         },
+//    }
+//
+// Note that as of 1.13, go doesn't correctly handle passing C
+// function pointers back to C functions, so C.sqlite3_create_function
+// can't be called from Go directly.  See
+// https://github.com/golang/go/issues/19835 for more details.
+func (c *SQLiteConn) Raw(f func(unsafe.Pointer) error) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if err := f(unsafe.Pointer(c.db)); err != nil {
+		if _, ok := err.(ErrNo); ok {
+			return c.lastError()
+		}
+		return err
+	}
+	return nil
+}
+
 // AutoCommit return which currently auto commit or not.
 func (c *SQLiteConn) AutoCommit() bool {
 	c.mu.Lock()