packages feed

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

{-# LANGUAGE BlockArguments #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE StrictData #-}

-- |
-- Module      : Database.DuckDB.Simple.Config
-- Description : V2 configuration values, declared scopes, defaults, and aliases.
module Database.DuckDB.Simple.Config (
  ConfigFlag (..),
  ConfigValue (..),
  ConfigOption (..),
  SettingScope (..),
  listConfigFlags,
  listConfigOptions,
  listInstanceOptions,
  getConfigOption,
  setConfigOption,
  getConfigValue,
  getConfigDefaultValue,
  setConfigValue,
  CustomOption (..),
  customOption,
  registerCustomOption,
) where

import Control.Exception (bracket, catch, throwIO)
import Control.Monad (filterM, forM, when)
import Data.Text (Text)
import qualified Data.Text as Text
import Database.DuckDB.Simple.Config.Internal (CustomOption (..), registerCustomOptionOn)
import Database.DuckDB.Simple.FromField (FieldValue)
import Database.DuckDB.Simple.Internal (
  Connection,
  Instance,
  connectionInstance,
  instanceCastFactory,
  readConnectionVariant,
  withConnectionHandle,
  withInstanceHandle,
 )
import Database.DuckDB.Simple.Materialize (ReadFactory (..), materializeValue)
import Database.DuckDB.Simple.Native
import Database.DuckDB.Simple.ToField (ToDuckValue (..))
import Database.DuckDB.Simple.V2.Registration (RegistrationTarget (..), TypeDeclaration)
import Foreign.Marshal.Alloc (alloca)
import Foreign.Storable (peek)

-- | The canonical name and description of a configuration option.
data ConfigFlag = ConfigFlag
  { configFlagName :: Text
  , configFlagDescription :: Text
  }
  deriving (Eq, Show)

-- | An effective option value and the scope that supplied it.
-- 'configValueText' is 'Nothing' for a NULL value, as 'configOptionSetting'.
data ConfigValue = ConfigValue
  { configValueText :: Maybe Text
  , configValueScope :: SettingScope
  }
  deriving (Eq, Show)

-- | A copied option descriptor. The list of aliases can be empty.
-- 'configOptionSetting' is the effective value. 'Nothing' means a NULL value,
-- which the @value@ column of @duckdb_settings()@ also gives as NULL.
-- 'configOptionDefault' is the static default of the declaration. 'Nothing'
-- means that the declaration has no default. The value after @RESET@ can
-- differ from the static default: @progress_bar_time@ has no static default,
-- and DuckDB 2.0.0 gives 2000 after @RESET@.
data ConfigOption = ConfigOption
  { configOptionName :: Text
  , configOptionDescription :: Text
  , configOptionSetting :: Maybe Text
  , configOptionDefault :: Maybe Text
  , configOptionScope :: SettingScope
  , configOptionScopes :: [SettingScope]
  , configOptionAliases :: [Text]
  }
  deriving (Eq, Show)

-- | Declare a global option without a default value or an update function.
customOption :: Text -> TypeDeclaration -> CustomOption
customOption name dtype = CustomOption name dtype Nothing "" SettingScopeGlobal [SettingScopeGlobal] Nothing

-- | Register a typed custom option on the connection's database.
-- The update function must not write options.
registerCustomOption :: Connection -> CustomOption -> IO ()
registerCustomOption conn = registerCustomOptionOn (ConnectionTarget conn)

-- | List the name and the description of each option of the database of the
-- connection, for example a custom option of the database.
-- 'listConfigOptions' gives the same options with their values.
listConfigFlags :: Connection -> IO [ConfigFlag]
listConfigFlags conn = withConnectionHandle conn \handle -> do
  config <- output (c_duckdb_v2_connection_get_config handle)
  copyOptions config copyFlag

-- | List options with effective values from a live connection.
listConfigOptions :: Connection -> IO [ConfigOption]
listConfigOptions conn = withConnectionHandle conn \handle -> do
  config <- output (c_duckdb_v2_connection_get_config handle)
  copyOptions config (copyOption config)

-- | List options and global values from an instance.
listInstanceOptions :: Instance -> IO [ConfigOption]
listInstanceOptions instance_ = withInstanceHandle instance_ \handle -> do
  config <- output (c_duckdb_v2_instance_get_config handle)
  copyOptions config (copyOption config)

-- | Read an effective option by its canonical name or an alias.
getConfigOption :: Connection -> Text -> IO (Maybe ConfigValue)
getConfigOption conn name = do
  checkOptionName name
  (withConfigOptionValue conn name \value scope -> Just . (`ConfigValue` scope) <$> nullableText value)
    `catch` \err ->
      if sqlErrorType err == Just ErrorInputInvalid
        then pure Nothing
        else throwIO err

-- | Write an option at its default, global, or session scope.
setConfigOption :: Connection -> SettingScope -> Text -> Text -> IO ()
setConfigOption conn scope name value = do
  checkOptionName name
  withConnectionHandle conn \handle -> do
    config <- output (c_duckdb_v2_connection_get_config handle)
    withIdentifier name \key -> withText value \setting ->
      checked (c_duckdb_v2_config_set_option_text config key setting (settingScopeToNative scope))

-- | Read a typed option value during one action. The action borrows the value.
withConfigOptionValue :: Connection -> Text -> (DuckDBV2ValueHandle -> SettingScope -> IO a) -> IO a
withConfigOptionValue conn name action = withConnectionHandle conn \handle -> do
  config <- output (c_duckdb_v2_connection_get_config handle)
  withOptionValue config name action

-- | Copy the effective typed value of an option and the scope of that value.
-- An unknown option name raises t'SQLError'. A VARIANT value gives the value
-- that it holds, as in a result. A GEOMETRY value reads with the factory of the
-- instance. See Note [User casts and the casts of the library] in
-- <src/Database.DuckDB.Simple.Materialize.html Database.DuckDB.Simple.Materialize>. The function releases all native
-- handles before it returns.
getConfigValue :: Connection -> Text -> IO (FieldValue, SettingScope)
getConfigValue conn name = do
  checkOptionName name
  withConnectionHandle conn \handle -> do
    config <- output (c_duckdb_v2_connection_get_config handle)
    casts <- instanceCastFactory (connectionInstance conn)
    withOptionValue config name \value scope -> do
      copied <- materializeValue (readConnectionVariant conn) (InstanceFactory casts) value
      pure (copied, scope)

-- | Copy the typed static default of an option. An unknown option name raises
-- t'SQLError'. A VARIANT value gives the value that it holds, as in a result. A
-- GEOMETRY value reads as 'getConfigValue' reads it. The function releases all
-- native handles before it returns.
getConfigDefaultValue :: Connection -> Text -> IO FieldValue
getConfigDefaultValue conn name = do
  checkOptionName name
  withConnectionHandle conn \handle -> do
    config <- output (c_duckdb_v2_connection_get_config handle)
    casts <- instanceCastFactory (connectionInstance conn)
    withIdentifier name \key ->
      bracket (output (c_duckdb_v2_config_get_option_by_name config key)) (destroy c_duckdb_v2_option_destroy) \option ->
        bracket
          (output (c_duckdb_v2_option_get_default_value option))
          (destroy c_duckdb_v2_value_destroy)
          (materializeValue (readConnectionVariant conn) (InstanceFactory casts))

-- | Set an option from a typed Haskell value. Native code casts it to the option type.
setConfigValue :: (ToDuckValue a) => Connection -> SettingScope -> Text -> a -> IO ()
setConfigValue conn scope name value = do
  checkOptionName name
  withConnectionHandle conn \handle -> do
    config <- output (c_duckdb_v2_connection_get_config handle)
    withConnectionFactory handle \factory ->
      bracket (toDuckValue factory value) (destroy c_duckdb_v2_value_destroy) \native ->
        withIdentifier name \key -> checked (c_duckdb_v2_config_set_option_value config key native (settingScopeToNative scope))

-- | Reject an option name that contains NUL, before a native call. Each
-- function of this module that takes an option name calls it first.
checkOptionName :: Text -> IO ()
checkOptionName name = when (Text.any (== '\0') name) $ throwInvalidArgument "config option name contains NUL"

-- | Copy the options visible through a borrowed config.
copyOptions :: DuckDBV2ConfigHandle -> (DuckDBV2OptionHandle -> IO a) -> IO [a]
copyOptions config copy = do
  count <- output (c_duckdb_v2_config_get_option_count config)
  forM (indices count) \index ->
    bracket (output (c_duckdb_v2_config_get_option_by_index config index)) (destroy c_duckdb_v2_option_destroy) copy

-- | Copy the name and description without reading the option value.
copyFlag :: DuckDBV2OptionHandle -> IO ConfigFlag
copyFlag handle =
  ConfigFlag
    <$> (output (c_duckdb_v2_option_get_name handle) >>= readIdentifier)
    <*> (output (c_duckdb_v2_option_get_description handle) >>= readText)

-- | Copy a descriptor while its native strings are alive.
copyOption :: DuckDBV2ConfigHandle -> DuckDBV2OptionHandle -> IO ConfigOption
copyOption config handle = do
  ConfigFlag name description <- copyFlag handle
  setting <- withOptionValue config name \value _ -> nullableText value
  defaultSetting <- bracket (output (c_duckdb_v2_option_get_default_value handle)) (destroy c_duckdb_v2_value_destroy) nullableText
  scope <- output (c_duckdb_v2_option_get_default_scope handle) >>= settingScopeFromNative
  scopes <-
    filterM
      (\candidate -> (/= 0) <$> output (c_duckdb_v2_option_supports_scope handle (settingScopeToNative candidate)))
      [SettingScopeGlobal, SettingScopeSession]
  count <- output (c_duckdb_v2_option_get_alias_count handle)
  aliases <- forM (indices count) \index -> output (c_duckdb_v2_option_get_alias handle index) >>= readIdentifier
  pure (ConfigOption name description setting defaultSetting scope scopes aliases)

-- | Copy the text of a value, or 'Nothing' for a NULL value.
nullableText :: DuckDBV2ValueHandle -> IO (Maybe Text)
nullableText value = do
  isNull <- output (c_duckdb_v2_value_is_null value)
  if isNull /= 0 then pure Nothing else Just <$> valueText value

-- | Release each owned option value after its action.
withOptionValue :: DuckDBV2ConfigHandle -> Text -> (DuckDBV2ValueHandle -> SettingScope -> IO a) -> IO a
withOptionValue config name action = withIdentifier name \key -> alloca \scope ->
  bracket
    (output (\value -> c_duckdb_v2_config_get_option_value config key value scope))
    (destroy c_duckdb_v2_value_destroy)
    \value -> peek scope >>= settingScopeFromNative >>= action value