packages feed

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

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

-- |
-- Module      : Database.DuckDB.Simple.Catalog
-- Description : Catalog inspection through V2 queries and native table descriptions.
--
-- 'catalogTypeName' and 'lookupCatalogEntry' run SQL on the V2 connection.
-- The SQL reads the @duckdb_*()@ table functions, which are the metadata
-- interface of DuckDB. The C API V2 of DuckDB 2.0.0 has no call that looks up
-- a catalog entry. The V1 C API has such calls, but it has no supported way
-- to use a V2 connection. In a reply of 2026-10-20 to an extension author,
-- DuckDB wrote: "we'll add a catalog access interface eventually"
-- (<https://github.com/duckdb/duckdb/discussions/27525 DuckDB discussion 27525>).
module Database.DuckDB.Simple.Catalog (
  CatalogEntryType (..),
  CatalogEntry (..),
  catalogTypeName,
  lookupCatalogEntry,
  TableDescription (..),
  ColumnDescription (..),
  describeTable,
) where

import Control.Exception (bracket)
import Control.Monad (forM, when)
import Data.Text (Text)
import qualified Data.Text as Text
import Database.DuckDB.Simple (Only (..), query)
import Database.DuckDB.Simple.Internal (Connection, withConnectionHandle)
import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep)
import Database.DuckDB.Simple.Native
import Database.DuckDB.Simple.V2.LogicalRep (logicalTypeToRep)

-- | Entry kinds that DuckDB exposes through catalog metadata. There is no
-- collation kind: @pragma_collations()@ gives the name of each collation, but
-- not its catalog and its schema.
data CatalogEntryType = CatalogTable | CatalogView | CatalogIndex | CatalogSequence | CatalogType
  deriving (Eq, Ord, Show, Read)

-- | A copied catalog entry name and kind.
data CatalogEntry = CatalogEntry
  { catalogEntryName :: Text
  , catalogEntryType :: CatalogEntryType
  }
  deriving (Eq, Show)

-- | A table's qualified name, access mode, and columns.
data TableDescription = TableDescription
  { tableDescriptionName :: [Text]
  , tableDescriptionReadonly :: Bool
  , tableDescriptionColumns :: [ColumnDescription]
  }
  deriving (Eq, Show)

-- | A copied column description. Native handles remain inside the call. The
-- column type keeps the alias of DuckDB at each depth, for example JSON. See
-- Note [Type aliases] in "Database.DuckDB.Simple.LogicalRep".
data ColumnDescription = ColumnDescription
  { columnDescriptionName :: Text
  , columnDescriptionType :: LogicalTypeRep
  , columnDescriptionHasDefault :: Bool
  , columnDescriptionGenerated :: Bool
  }
  deriving (Eq, Show)

-- | Read the backend type of an attached database, for example @duckdb@.
-- DuckDB gives a type for each attached database, so the result is 'Nothing'
-- only for a name that no attached database has.
catalogTypeName :: Connection -> Text -> IO (Maybe Text)
catalogTypeName conn name = do
  validateNames [name]
  -- See Note [SQL text of the library] in "Database.DuckDB.Simple.Native".
  rows <-
    query conn (Query ("SELECT type::VARCHAR FROM system.main.duckdb_databases() WHERE " <> identifierMatches "database_name")) (Only name)
  pure (case rows of Only value : _ -> Just value; [] -> Nothing)

-- | Look up an entry in a top-level schema. Names use DuckDB's identifier rules.
lookupCatalogEntry :: Connection -> Text -> Text -> Text -> CatalogEntryType -> IO (Maybe CatalogEntry)
lookupCatalogEntry conn catalog schema name kind = do
  validateNames [catalog, schema, name]
  (functionName, columnName) <- case kind of
    CatalogTable -> pure ("duckdb_tables()", "table_name")
    CatalogView -> pure ("duckdb_views()", "view_name")
    CatalogIndex -> pure ("duckdb_indexes()", "index_name")
    CatalogSequence -> pure ("duckdb_sequences()", "sequence_name")
    CatalogType -> pure ("duckdb_types()", "type_name")
  -- See Note [SQL text of the library] in "Database.DuckDB.Simple.Native".
  let sql =
        Query
          ( "SELECT e."
              <> columnName
              <> "::VARCHAR FROM system.main."
              <> functionName
              <> " e"
              <> " JOIN system.main.duckdb_schemas() s ON e.database_oid = s.database_oid AND e.schema_oid = s.oid"
              <> " WHERE s.parent_schema_oid IS NULL AND "
              <> identifierMatches "e.database_name"
              <> " AND "
              <> identifierMatches "e.schema_name"
              <> " AND "
              <> identifierMatches ("e." <> columnName)
              <> " LIMIT 1"
          )
  rows <- query conn sql (catalog, schema, name)
  pure (case rows of Only value : _ -> Just (CatalogEntry value kind); [] -> Nothing)

-- | Compare a trusted column with a parameter using ASCII case folding.
-- Binary comparison keeps the result independent of the SQL collation.
identifierMatches :: Text -> Text
identifierMatches column = normalize column <> " = " <> normalize "?"
  where
    normalize expression = "system.main.encode(system.main.translate(" <> expression <> ", 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz'))"

-- | Copy a native base-table description using a parsed qualified name.
describeTable :: Connection -> Text -> IO TableDescription
describeTable conn name = withConnectionHandle conn $ \handle -> withConnectionFactory handle $ \factory ->
  withText name $ \text -> bracket (output (c_duckdb_v2_qname_parse text)) (destroy c_duckdb_v2_qname_destroy) $ \qname ->
    bracket (output (c_duckdb_v2_connection_describe_table handle qname)) (destroy c_duckdb_v2_table_description_destroy) $ \table -> do
      copiedName <- bracket (output (c_duckdb_v2_table_description_get_qname table)) (destroy c_duckdb_v2_qname_destroy) $ \resolved -> do
        parts <- output (c_duckdb_v2_qname_get_part_count resolved)
        forM (indices parts) $ \index -> output (c_duckdb_v2_qname_get_part resolved index) >>= readIdentifier
      readonly <- output (c_duckdb_v2_table_description_is_readonly table)
      count <- output (c_duckdb_v2_table_description_get_column_count table)
      columns <- forM (indices count) $ \index ->
        bracket (output (c_duckdb_v2_table_description_get_column table index)) (destroy c_duckdb_v2_column_description_destroy) $ \column -> do
          columnName <- output (c_duckdb_v2_column_description_get_name column) >>= readIdentifier
          columnType <- output (c_duckdb_v2_column_description_get_type column) >>= logicalTypeToRep factory
          defaultValue <- output (c_duckdb_v2_column_description_has_default column)
          generated <- output (c_duckdb_v2_column_description_has_generated column)
          pure (ColumnDescription columnName columnType (defaultValue /= 0) (generated /= 0))
      pure (TableDescription copiedName (readonly /= 0) columns)

-- | Reject names that contain NUL.
validateNames :: [Text] -> IO ()
validateNames names = when (any (Text.any (== '\0')) names) $ throwInvalidArgument "catalog lookup name contains NUL"