packages feed

duckdb-simple-1.0.0.0: src/Database/DuckDB/Simple/V2/Pragma.hs

{-# LANGUAGE BlockArguments #-}

-- |
-- Module      : Database.DuckDB.Simple.V2.Pragma
-- Description : Register PRAGMA functions with callbacks that get native handles.
--
-- The callbacks of this module get the borrowed bind info and context of the
-- call. "Database.DuckDB.Simple.Pragma" has the typed callbacks.
--
-- Use this module to read the arguments of a call as native values, to set the documentation of a pragma,
-- or to register a pragma on an extension target. 'registerPragmaFunctionOn' declares the name and the
-- parameters. 'registerPragmaFunctionWith' gives the native builder to a configuration action. A pragma has
-- one callback: a 'QueryPragma' or an 'ExecPragma'.
--
-- The example uses the imports and the definitions of the module header of
-- "Database.DuckDB.Simple.V2.Registration".
module Database.DuckDB.Simple.V2.Pragma (
  PragmaCallback (..),
  registerPragmaFunctionOn,
  registerPragmaFunctionWith,
) where

import Control.Monad (when)
import Data.Text (Text)
import qualified Data.Text as Text
import Database.DuckDB.Simple.Callback (
  attachOpaque,
  checkTargetThreads,
  guardContext,
  install,
  runCallback,
  withCallbackResources,
  withTarget,
 )
import Database.DuckDB.Simple.Native
import Database.DuckDB.Simple.V2.Registration (
  ContextCallback,
  FunctionParameter,
  FunctionSignature (..),
  RegistrationTarget (..),
  configureFunctionSignature,
  withRegistrationFactory,
 )

-- | A query callback returns SQL to run in place of the PRAGMA statement.
-- An execution callback performs an action and returns no rows. Callback handles
-- are borrowed. Exceptions become SQL errors. DuckDB permits exactly one callback.
data PragmaCallback
  = QueryPragma (DuckDBV2FunctionBindInfoHandle -> DuckDBV2ContextHandle -> IO Text)
  | ExecPragma (ContextCallback DuckDBV2FunctionBindInfoHandle)

-- | Register a pragma on a connection or a loading extension. The name must not
-- be empty and must not contain NUL.
registerPragmaFunctionOn :: RegistrationTarget -> Text -> [FunctionParameter] -> PragmaCallback -> IO ()
registerPragmaFunctionOn target name parameters callback = do
  when (Text.null name || Text.any (== '\0') name) $
    throwInvalidArgument (Text.pack "pragma function name must be nonempty and must not contain NUL")
  withRegistrationFactory target \factory ->
    registerPragmaFunctionWith
      target
      ( \function -> do
          withIdentifier name (checked . c_duckdb_v2_pragma_function_set_name function)
          signature <- output (c_duckdb_v2_pragma_function_get_signature function)
          configureFunctionSignature factory (FunctionSignature parameters Nothing) signature
      )
      callback

-- | Configure a pragma on a connection or a loading extension.
-- The action borrows the builder and can set its name, signature, and documentation.
-- Do not set native callbacks or user data. The library owns the callback pointer.
-- Use Haskell closures to retain registration data.
--
-- The example registers an execution pragma that counts its calls. The configuration action sets the name
-- and the description of the pragma.
--
-- > withConnection ":memory:" \connection -> do
-- >   calls <- newIORef (0 :: Int)
-- >   Pragma.registerPragmaFunctionWith
-- >     (R.ConnectionTarget connection)
-- >     ( \function -> do
-- >         R.withIdentifier "managed_exec" (R.checked . c_duckdb_v2_pragma_function_set_name function)
-- >         docs <- R.output (c_duckdb_v2_pragma_function_get_docs function)
-- >         Docs.setFunctionDocs docs Docs.defaultFunctionDocs{Docs.functionDescription = Just "Count calls."}
-- >     )
-- >     (Pragma.ExecPragma (\_ _ -> modifyIORef' calls (+ 1)))
-- >   _ <- execute_ connection "PRAGMA managed_exec"
-- >   readIORef calls >>= print -- 1
registerPragmaFunctionWith :: RegistrationTarget -> (DuckDBV2PragmaFunctionHandle -> IO ()) -> PragmaCallback -> IO ()
registerPragmaFunctionWith target configure callback =
  withTarget
    target
    c_duckdb_v2_pragma_function_create
    c_duckdb_v2_pragma_function_destroy
    c_duckdb_v2_connection_register_pragma_function
    c_duckdb_v2_extension_register_pragma_function
    \function register ->
      withCallbackResources
        (checkTargetThreads target)
        ( \allocate -> case callback of
            QueryPragma action ->
              install
                allocate
                DuckDBV2PragmaFunctionQueryCallbackFn
                ( DuckDBV2PragmaFunctionQueryCallbackFn_Aux \info result context err ->
                    runCallback err do
                      sql <- action info context
                      withText sql (checked . c_duckdb_v2_pragma_function_query_set_query result)
                )
                (c_duckdb_v2_pragma_function_set_query_callback function)
            ExecPragma action ->
              install
                allocate
                DuckDBV2PragmaFunctionExecCallbackFn
                (DuckDBV2PragmaFunctionExecCallbackFn_Aux (guardContext action))
                (c_duckdb_v2_pragma_function_set_exec_callback function)
        )
        (attachOpaque (c_duckdb_v2_pragma_function_set_user_data function))
        \installCallback -> do
          configure function
          installCallback
          register