packages feed

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

{-# LANGUAGE BlockArguments #-}
{-# LANGUAGE LambdaCase #-}
{-# LANGUAGE NamedFieldPuns #-}
{-# LANGUAGE TupleSections #-}

-- |
-- Module      : Database.DuckDB.Simple
-- Description : High-level DuckDB API in the duckdb-simple style.
--
-- The API mirrors the ergonomics of @sqlite-simple@ while being backed by the
-- DuckDB C API. It supports connection management, parameter binding, execution,
-- and typed result decoding. See @README.md@ for usage examples.
module Database.DuckDB.Simple (
  -- * Connections
  Environment,
  createEnvironment,
  closeEnvironment,
  withEnvironment,
  Instance,
  createInstance,
  closeInstance,
  withInstance,
  attachDatabase,
  detachDatabase,
  setDefaultDatabase,
  connect,
  connectWithOptions,
  withConnectionOn,
  Connection,
  open,
  openWithConfig,
  ConnectionOptions (..),
  defaultConnectionOptions,
  defaultCallbackLockWait,
  defaultAggregateStripes,
  defaultArrowBatchSize,
  openWithOptions,
  close,
  withConnection,
  withConnectionWithConfig,
  withConnectionWithOptions,

  -- * Queries and statements
  Query (..),
  Statement,
  openStatement,
  closeStatement,
  withStatement,
  clearStatementBindings,
  namedParameterIndex,
  columnCount,
  columnName,
  executeStatement,
  execute,
  executeMany,
  execute_,
  bind,
  bindNamed,
  executeNamed,
  queryNamed,
  fold,
  fold_,
  foldNamed,
  withTransaction,
  query,
  queryWith,
  query_,
  queryWith_,
  nextRow,
  nextRowWith,

  -- * Errors and conversions
  SQLError (..),
  ErrorType (..),
  FormatError (..),
  ResultError (..),
  FieldParser,
  FromField (..),
  Conversion,
  runConversion,
  liftConversion,
  FromRow (..),
  RowParser,
  field,
  fieldWith,
  numFieldsRemaining,
  -- Re-export parameter helper types.
  ToField (..),
  ToRow (..),
  FieldBinding,
  NamedParam (..),
  DuckDBColumnType (..),
  duckdbColumnType,
  SizedArray,
  sizedArray,
  sizedArrayFromList,
  sizedArrayToArray,
  Null (..),
  Only (..),
  (:.) (..),

  -- * User-defined scalar functions
  Function (..),
  LogicalTypeId (..),
  createFunction,
  createFunctionWithState,
  deleteFunction,

  -- * User-defined table functions
  TypedRow,
  createTableFunction,

  -- * User-defined aggregate functions
  Aggregate (..),
  createAggregate,
) where

import Control.Exception (SomeException, bracket, evaluate, finally, mask, mask_, onException, throwIO, try)
import Control.Monad (foldM, forM_, void, when, zipWithM_)
import Data.Array (elems)
import Data.IORef (atomicModifyIORef', newIORef, readIORef, writeIORef)
import qualified Data.IntMap.Strict as IntMap
import Data.List (findIndex)
import qualified Data.Map.Strict as Map
import qualified Data.Set as Set
import Data.Text (Text)
import qualified Data.Text as Text
import Database.DuckDB.Simple.Conversion (Conversion, liftConversion, runConversion)
import Database.DuckDB.Simple.FromField (
  Field (..),
  FieldParser,
  FromField (..),
  ResultError (..),
  SizedArray,
  sizedArray,
  sizedArrayFromList,
  sizedArrayToArray,
 )
import Database.DuckDB.Simple.FromRow (FromRow (..), RowParser, field, fieldWith, numFieldsRemaining, parseRow, rowErrorsToSqlError)
import Database.DuckDB.Simple.Function (
  Aggregate (..),
  Function (..),
  TypedRow,
  createAggregate,
  createFunction,
  createFunctionWithState,
  createTableFunction,
  deleteFunction,
 )
import Database.DuckDB.Simple.Internal
import Database.DuckDB.Simple.Ok (Ok (..))
import Database.DuckDB.Simple.Result (resetStatementStream, withRows)
import qualified Database.DuckDB.Simple.Result as Result
import Database.DuckDB.Simple.ToField (
  DuckDBColumnType (..),
  FieldBinding,
  NamedParam (..),
  ToField (..),
  bindFieldBinding,
  duckdbColumnType,
  renderFieldBinding,
 )
import Database.DuckDB.Simple.ToRow (ToRow (..))
import Database.DuckDB.Simple.Types (FormatError (..), Null (..), Only (..), (:.) (..))
import Foreign.Marshal.Alloc (alloca)
import Foreign.Storable (peek)

-- | Run an action with a shared native environment.
withEnvironment :: (Environment -> IO a) -> IO a
withEnvironment = bracket createEnvironment closeEnvironment

-- | Run an action with a configured instance in a shared environment.
withInstance :: Environment -> [(Text, Text)] -> (Instance -> IO a) -> IO a
withInstance environment settings = bracket (createInstance environment settings) closeInstance

-- | Attach a catalog. Use 'setDefaultDatabase' to select it for new connections.
attachDatabase :: Instance -> FilePath -> Text -> [(Text, Text)] -> IO ()
attachDatabase instance_ path alias settings = attachCatalog instance_ path alias settings False

-- | Attach a catalog and optionally select it in the same native call.
attachCatalog :: Instance -> FilePath -> Text -> [(Text, Text)] -> Bool -> IO ()
attachCatalog instance_ path alias settings makeDefault = withInstanceHandle instance_ \raw -> do
  when ('\0' `elem` path || Text.any (== '\0') alias) $
    throwInvalidArgument (Text.pack "database path or alias contains NUL")
  when (any (\(key, value) -> Text.any (== '\0') key || Text.any (== '\0') value) settings) $
    throwInvalidArgument (Text.pack "attach option contains NUL")
  bracket (output (c_duckdb_v2_attach_options_create raw)) (destroy c_duckdb_v2_attach_options_destroy) \options -> do
    forM_ settings \(key, value) -> withIdentifier key \name -> withText value \text ->
      checked (c_duckdb_v2_attach_options_set options name text)
    withText (Text.pack path) \file -> withIdentifier alias \name ->
      checked (c_duckdb_v2_instance_attach raw name file options (if makeDefault then 1 else 0))

-- | Detach a catalog from an instance.
detachDatabase :: Instance -> Text -> IO ()
detachDatabase instance_ alias = withInstanceHandle instance_ \raw -> do
  when (Text.any (== '\0') alias) $
    throwInvalidArgument (Text.pack "database alias contains NUL")
  withIdentifier alias \name -> checked (c_duckdb_v2_instance_detach raw name)

-- | Select the default catalog for new connections to an instance.
setDefaultDatabase :: Instance -> Text -> IO ()
setDefaultDatabase instance_ alias = withInstanceHandle instance_ \raw -> do
  when (Text.any (== '\0') alias) $
    throwInvalidArgument (Text.pack "database alias contains NUL")
  withIdentifier alias \name -> checked (c_duckdb_v2_instance_set_default raw name)

-- | Open a connection to a shared instance.
connect :: Instance -> IO Connection
connect instance_ = connectWithOptions instance_ defaultConnectionOptions

-- | Open a connection with options. The function writes each option with its
-- default scope, as a bare SQL @SET@ does. An option whose default scope is
-- GLOBAL thus changes the instance. This change applies to all connections of
-- the instance.
connectWithOptions :: Instance -> ConnectionOptions -> IO Connection
connectWithOptions instance_ options@ConnectionOptions{connectionConfig} = mask_ do
  when (any (\(name, value) -> Text.any (== '\0') name || Text.any (== '\0') value) connectionConfig) $
    throwInvalidArgument (Text.pack "configuration contains NUL")
  checked' <- checkConnectionOptions options
  conn <- createConnection instance_ checked' (pure ())
  flip onException (close conn) do
    withConnectionHandle conn \raw -> do
      config <- output (c_duckdb_v2_connection_get_config raw)
      forM_ connectionConfig \(key, value) ->
        withIdentifier key \name -> withText value \text ->
          checked (c_duckdb_v2_config_set_option_text config name text DuckDBV2SettingScopeDefault)
    pure conn

-- | Run an action with a connection to a shared instance.
withConnectionOn :: Instance -> (Connection -> IO a) -> IO a
withConnectionOn instance_ = bracket (connect instance_) close

-- | Open a DuckDB database located at the supplied path.
open :: FilePath -> IO Connection
open path = openWithConfig path []

-- | Open a DuckDB database with configuration flags applied before startup.
openWithConfig :: FilePath -> [(Text, Text)] -> IO Connection
openWithConfig path settings = openWithOptions path defaultConnectionOptions{connectionConfig = settings}

-- | Check the option bounds before an open creates a native handle.
-- Return the record with the checked values.
checkConnectionOptions :: ConnectionOptions -> IO ConnectionOptions
checkConnectionOptions options@ConnectionOptions{connectionCallbackLockWait, connectionAggregateStripes, connectionArrowBatchSize} = do
  callbackLockWait <- checkCallbackLockWait connectionCallbackLockWait
  stripes <- checkAggregateStripes connectionAggregateStripes
  arrowBatch <- checkArrowBatchSize connectionArrowBatchSize
  pure
    options
      { connectionCallbackLockWait = callbackLockWait
      , connectionAggregateStripes = stripes
      , connectionArrowBatchSize = arrowBatch
      }

-- | Evaluate the bound of 'connectionCallbackLockWait' and reject a negative
-- bound before an open creates a native handle.
checkCallbackLockWait :: Maybe Int -> IO (Maybe Int)
checkCallbackLockWait bound = case bound of
  Just micros
    | micros < 0 -> throwInvalidArgument (Text.pack "connectionCallbackLockWait is negative")
  _ -> evaluate bound

-- | Reject a number of 'connectionAggregateStripes' that is not positive. The
-- check evaluates the field, so an error in the field occurs here and not in a
-- later registration.
checkAggregateStripes :: Int -> IO Int
checkAggregateStripes stripes
  | stripes <= 0 = throwInvalidArgument (Text.pack "connectionAggregateStripes is not positive")
  | otherwise = pure stripes

-- | Reject a 'connectionArrowBatchSize' that is not positive. The check
-- evaluates the field, so an error in the field occurs here and not in a later
-- fold.
checkArrowBatchSize :: Int -> IO Int
checkArrowBatchSize size
  | size <= 0 = throwInvalidArgument (Text.pack "connectionArrowBatchSize is not positive")
  | otherwise = pure size

-- | Open a database with a private environment and instance.
openWithOptions :: FilePath -> ConnectionOptions -> IO Connection
openWithOptions path options = mask_ do
  checked' <- checkConnectionOptions options
  environment <- createEnvironment
  instance_ <- createInstance environment (connectionConfig checked') `onException` closeEnvironment environment
  -- See Note [Native handle ownership] in "Database.DuckDB.Simple.Internal".
  let release = closeInstance instance_ `finally` closeEnvironment environment
  flip onException release do
    -- An empty alias lets DuckDB derive the catalog name from the path.
    attachCatalog instance_ (if null path then ":memory:" else path) Text.empty [] True
    createConnection instance_ checked' release

-- | Close a connection and its statements. The operation is idempotent.
close :: Connection -> IO ()
close = closeConnection

-- | Run an action with a freshly opened connection, closing it afterwards.
withConnection :: FilePath -> (Connection -> IO a) -> IO a
withConnection path = bracket (open path) close

-- | Run an action with a freshly opened configured connection, closing it afterwards.
withConnectionWithConfig :: FilePath -> [(Text, Text)] -> (Connection -> IO a) -> IO a
withConnectionWithConfig path settings = bracket (openWithConfig path settings) close

-- | Run an action with a connection opened with options, closing it afterwards.
withConnectionWithOptions :: FilePath -> ConnectionOptions -> (Connection -> IO a) -> IO a
withConnectionWithOptions path options = bracket (openWithOptions path options) close

-- | Prepare a SQL statement for execution.
openStatement :: Connection -> Query -> IO Statement
openStatement conn queryText = createStatementWithCollections conn queryText []

-- | Finalize a prepared statement. The operation is idempotent.
closeStatement :: Statement -> IO ()
closeStatement = closeStatementState

-- | Run an action with a prepared statement, closing it afterwards.
withStatement :: Connection -> Query -> (Statement -> IO a) -> IO a
withStatement conn sql = bracket (openStatement conn sql) closeStatement

-- | Bind positional parameters to a prepared statement, replacing any previous bindings.
-- The call resets the cursor. If validation or value conversion fails, the
-- previous set of bindings remains.
bind :: Statement -> [FieldBinding] -> IO ()
bind stmt fields = do
  resetStatementStream stmt
  withStatementHandle stmt \_ -> do
    -- The handle is not used. withStatementHandle raises the error for a closed statement or connection.
    let actual = length fields
        expected = length (statementParameterNames stmt)
    when (actual /= expected) $
      throwFormatErrorBindings stmt (parameterCountMessage expected actual) fields
    when (hasNamedParameters stmt) $
      throwFormatErrorBindings stmt (Text.pack "duckdb-simple: statement defines named parameters; use executeNamed or bindNamed") fields
  replaceStatementBindings stmt \staged ->
    zipWithM_ (\idx -> bindFieldBinding staged (fromIntegral idx)) [1 :: Int ..] fields
  where
    parameterCountMessage expected actual =
      Text.pack $
        "duckdb-simple: SQL query contains "
          <> show expected
          <> " parameter(s), but "
          <> show actual
          <> " argument(s) were supplied"

-- | Bind named parameters to a prepared statement.
-- The cursor reset and failure guarantees of 'bind' also apply.
-- A binding name can start with one optional @$@, @:@, or @\@@ prefix. To bind
-- the SQL parameter @$"$foo"@, supply @"$$foo"@.
-- A successful call replaces the explicit bindings. Current session variables
-- can supply omitted parameters when the statement executes.
bindNamed :: Statement -> [NamedParam] -> IO ()
bindNamed stmt params =
  let bindings = fmap (\(name := value) -> (name, toField value)) params
      parameterCountMessage expected actual =
        Text.pack $
          "duckdb-simple: SQL query contains "
            <> show expected
            <> " named parameter(s), but "
            <> show actual
            <> " argument(s) were supplied"
      unknownNameMessage name =
        Text.concat
          [ Text.pack "duckdb-simple: unknown named parameter "
          , name
          ]
      -- One lookup table serves all bindings of this call.
      positions = Map.fromList (zip (map foldIdentifier (elems (statementParameterNames stmt))) [1 :: Int ..])
      apply target (name, binding) = do
        when (Text.any (== '\0') name) $
          withQueryError (statementQuery stmt) (throwInvalidArgument (Text.pack "parameter name contains NUL"))
        case Map.lookup (bindingName name) positions of
          Nothing ->
            throwFormatErrorNamed stmt (unknownNameMessage name) bindings
          Just idx -> bindFieldBinding target (fromIntegral idx :: DuckDBIdx) binding
  in  do
        resetStatementStream stmt
        let names = map (bindingName . fst) bindings
        when (Set.size (Set.fromList names) /= length names) $
          throwFormatErrorNamed stmt (Text.pack "duckdb-simple: duplicate named parameter") bindings
        withStatementHandle stmt \_ -> do
          -- The handle is not used. withStatementHandle raises the error for a closed statement or connection.
          let actual = length bindings
              expected = length (statementParameterNames stmt)
          when (actual > expected) $
            throwFormatErrorNamed stmt (parameterCountMessage expected actual) bindings
          when (expected > 0 && not (hasNamedParameters stmt)) $
            throwFormatErrorNamed
              stmt
              (Text.pack "duckdb-simple: statement does not define named parameters; use positional bindings or adjust the SQL")
              bindings
        replaceStatementBindings stmt \staged -> mapM_ (apply staged) bindings

{- Note [Atomic parameter bindings]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A statement owns its parameter values in a Haskell map. A bind constructs the
replacement map separately. A failed bind releases only the new values.
A successful bind transfers the complete map and moves the old values into the
temporary map. The same cleanup releases that map after success or failure.
Binding resets the cursor before it validates the new parameters.
-}

-- | Replace all bindings after the action constructs every value successfully.
-- See Note [Atomic parameter bindings].
replaceStatementBindings :: Statement -> (Statement -> IO ()) -> IO ()
replaceStatementBindings stmt action =
  bracket (newIORef IntMap.empty) clearBoundValues \staged -> do
    action stmt{statementBindings = staged}
    mask_ do
      replacement <- readIORef staged
      previous <- atomicModifyIORef' (statementBindings stmt) (\values -> (replacement, values))
      writeIORef staged previous

-- | Dense numeric keys in binding order are positional parameters.
hasNamedParameters :: Statement -> Bool
hasNamedParameters stmt =
  or (zipWith (\idx name -> name /= Text.pack (show idx)) [1 :: Int ..] (elems (statementParameterNames stmt)))

-- | Remove all parameter bindings and release an active result.
clearStatementBindings :: Statement -> IO ()
clearStatementBindings stmt = withStatementHandle stmt \_ -> do
  -- The handle is not used. withStatementHandle raises the error for a closed statement or connection.
  resetStatementStream stmt
  clearBoundValues (statementBindings stmt)

-- | Look up the 1-based index of a named placeholder.
namedParameterIndex :: Statement -> Text -> IO (Maybe Int)
namedParameterIndex stmt name = withStatementHandle stmt \_ -> do
  -- The handle is not used. withStatementHandle raises the error for a closed statement or connection.
  when (Text.any (== '\0') name) $
    withQueryError (statementQuery stmt) (throwInvalidArgument (Text.pack "parameter name contains NUL"))
  pure ((+ 1) <$> findIndex ((== bindingName name) . foldIdentifier) (elems (statementParameterNames stmt)))

-- | Retrieve the number of columns produced by the supplied prepared statement.
columnCount :: Statement -> IO Int
columnCount stmt = withStatementSchemas stmt \schema _ ->
  fromIntegral <$> output (c_duckdb_v2_schema_get_count schema)

-- | Look up the zero-based column name of a prepared statement result.
columnName :: Statement -> Int -> IO Text
columnName stmt columnIndex
  | columnIndex < 0 = columnIndexError stmt columnIndex Nothing
  | otherwise = do
      total <- columnCount stmt
      when (columnIndex >= total) $ columnIndexError stmt columnIndex (Just total)
      withStatementSchemas stmt \schema _ -> alloca \name -> do
        _ <- output (c_duckdb_v2_schema_get_field schema (fromIntegral columnIndex) name)
        peek name >>= readIdentifier

-- | Execute a prepared statement and return the number of affected rows.
--   Resets any active result stream before running and raises an @SQLError@
--   if DuckDB reports a failure.
executeStatement :: Statement -> IO Int
executeStatement stmt = do
  resetStatementStream stmt
  -- See Note [Result window] in "Database.DuckDB.Simple.Internal".
  withQueryError (statementQuery stmt) . withResultWindow (statementConnection stmt) (const (pure ())) $ withResult stmt \result ->
    fromIntegral <$> runInterruptibleQuery (statementConnection stmt) (output (c_duckdb_v2_result_drain result))

-- | Execute a query with positional parameters and return the affected row count.
execute :: (ToRow q) => Connection -> Query -> q -> IO Int
execute conn queryText params =
  withStatement conn queryText \stmt -> do
    bind stmt (toRow params)
    executeStatement stmt

-- | Execute the same query multiple times with different parameter sets.
-- The call reads the parameter types one time, for the first row that needs
-- them. A column type that changes during the call does not change how the
-- later rows bind. See Note [Statement schemas] in
-- "Database.DuckDB.Simple.Internal".
executeMany :: (ToRow q) => Connection -> Query -> [q] -> IO Int
executeMany conn queryText rows =
  withStatement conn queryText \stmt -> withKeptParameterTypes stmt do
    foldM
      ( \total row -> do
          bind stmt (toRow row)
          affected <- executeStatement stmt
          pure $! total + affected
      )
      0
      rows

-- | Execute an ad-hoc query without parameters and return the affected row count.
execute_ :: Connection -> Query -> IO Int
execute_ conn queryText = withAdHocStatement conn queryText (executeParsedStatement conn queryText) (pure 0)

-- | Execute a query that uses named parameters.
executeNamed :: Connection -> Query -> [NamedParam] -> IO Int
executeNamed conn queryText params =
  withStatement conn queryText \stmt -> do
    bindNamed stmt params
    executeStatement stmt

-- | Run a parameterised query and decode every resulting row eagerly.
-- An INSERT, UPDATE, or DELETE without RETURNING gives one row with one BIGINT
-- column: the number of changed rows.
query :: (ToRow q, FromRow r) => Connection -> Query -> q -> IO [r]
query = queryWith fromRow

-- | Run a parameterised query with a custom row parser.
queryWith :: (ToRow q) => RowParser r -> Connection -> Query -> q -> IO [r]
queryWith parser conn queryText params =
  withStatement conn queryText \stmt -> do
    bind stmt (toRow params)
    withRows stmt (convertRowsWith parser queryText)

-- | Run a query that uses named parameters and decode all rows eagerly.
queryNamed :: (FromRow r) => Connection -> Query -> [NamedParam] -> IO [r]
queryNamed conn queryText params =
  withStatement conn queryText \stmt -> do
    bindNamed stmt params
    withRows stmt (convertRows queryText)

-- | Run a query without supplying parameters and decode all rows eagerly.
query_ :: (FromRow r) => Connection -> Query -> IO [r]
query_ = queryWith_ fromRow

-- | Run a query without parameters using a custom row parser.
queryWith_ :: RowParser r -> Connection -> Query -> IO [r]
queryWith_ parser conn queryText =
  withAdHocStatement
    conn
    queryText
    (\parsed -> Result.withParsedRows conn queryText parsed (convertRowsWith parser queryText))
    (pure [])

-- | Execute preceding statements before returning the final statement's result.
withAdHocStatement :: Connection -> Query -> (DuckDBV2SqlStatementHandle -> IO a) -> IO a -> IO a
withAdHocStatement conn queryText action empty = withParsedStatements conn queryText \statements ->
  let run [] = empty
      run [parsed] = action parsed
      run (parsed : rest) = do
        void (executeParsedStatement conn queryText parsed)
        run rest
  in  run statements

-- Cursors and folds ---------------------------------------------------------

-- | Fold a parameterised result without constructing a complete Haskell row list.
--   The fold collects all owned native chunks before decoding starts. Native
--   memory use depends on the result size. The step function controls Haskell memory use.
--   An INSERT, UPDATE, or DELETE without RETURNING gives one row with one BIGINT
--   column: the number of changed rows.
fold :: (FromRow row, ToRow params) => Connection -> Query -> params -> a -> (a -> row -> IO a) -> IO a
fold conn queryText params initial step =
  withStatement conn queryText \stmt -> do
    bind stmt (toRow params)
    Result.foldStatementWith MaterializedResult fromRow stmt initial step

-- | Fold a parameterless result. Native materialization follows 'fold'.
fold_ :: (FromRow row) => Connection -> Query -> a -> (a -> row -> IO a) -> IO a
fold_ conn queryText initial step =
  withStatement conn queryText \stmt ->
    Result.foldStatementWith MaterializedResult fromRow stmt initial step

-- | Fold a result with named parameters. Native materialization follows 'fold'.
foldNamed :: (FromRow row) => Connection -> Query -> [NamedParam] -> a -> (a -> row -> IO a) -> IO a
foldNamed conn queryText params initial step =
  withStatement conn queryText \stmt -> do
    bindNamed stmt params
    Result.foldStatementWith MaterializedResult fromRow stmt initial step

-- | Fetch the next row. The first call collects all owned native chunks.
-- An INSERT, UPDATE, or DELETE without RETURNING gives one row with one BIGINT
-- column: the number of changed rows.
nextRow :: (FromRow r) => Statement -> IO (Maybe r)
nextRow = nextRowWith fromRow

-- | Fetch the next row using a custom parser, returning @Nothing@ once exhausted.
nextRowWith :: RowParser r -> Statement -> IO (Maybe r)
nextRowWith = Result.nextRowWith MaterializedResult

-- | Run an action inside a transaction.
withTransaction :: Connection -> IO a -> IO a
withTransaction conn action =
  mask \restore -> do
    void (execute_ conn begin)
    let rollbackAction = void (try (execute_ conn rollback) :: IO (Either SomeException Int))
    result <- restore action `onException` rollbackAction
    void (execute_ conn commit) `onException` rollbackAction
    pure result
  where
    -- See Note [SQL text of the library] in "Database.DuckDB.Simple.Native".
    begin = Query (Text.pack "BEGIN TRANSACTION")
    commit = Query (Text.pack "COMMIT")
    rollback = Query (Text.pack "ROLLBACK")

-- Internal helpers -----------------------------------------------------------

throwFormatError :: Statement -> Text -> [String] -> IO a
throwFormatError Statement{statementQuery} message params =
  throwIO
    FormatError
      { formatErrorMessage = message
      , formatErrorQuery = statementQuery
      , formatErrorParams = params
      }

throwFormatErrorBindings :: Statement -> Text -> [FieldBinding] -> IO a
throwFormatErrorBindings stmt message bindings =
  throwFormatError stmt message (map renderFieldBinding bindings)

throwFormatErrorNamed :: Statement -> Text -> [(Text, FieldBinding)] -> IO a
throwFormatErrorNamed stmt message bindings =
  throwFormatError stmt message (map renderNamed bindings)
  where
    renderNamed (name, binding) =
      Text.unpack name <> " := " <> renderFieldBinding binding

-- | Raise the error for a column index out of bounds, with the query of the
-- statement.
columnIndexError :: Statement -> Int -> Maybe Int -> IO a
columnIndexError stmt idx total =
  let base =
        Text.concat
          [ Text.pack "column index "
          , Text.pack (show idx)
          , Text.pack " out of bounds"
          ]
      message =
        case total of
          Nothing -> base
          Just count ->
            Text.concat
              [ base
              , Text.pack " (column count: "
              , Text.pack (show count)
              , Text.pack ")"
              ]
  in  withQueryError (statementQuery stmt) (throwInvalidArgument message)

-- | Strip one optional prefix from a supplied binding and fold ASCII case.
bindingName :: Text -> Text
bindingName name =
  foldIdentifier $
    case Text.uncons name of
      Just (prefix, rest)
        | prefix == ':' || prefix == '$' || prefix == '@' -> rest
      _ -> name

convertRows :: (FromRow r) => Query -> [[Field]] -> IO [r]
convertRows = convertRowsWith fromRow

convertRowsWith :: RowParser r -> Query -> [[Field]] -> IO [r]
convertRowsWith parser queryText rows =
  runConversion (traverse (parseRow parser) rows) >>= \case
    Errors err -> throwIO (rowErrorsToSqlError queryText err)
    Ok ok -> pure ok