Oracle.Query

Definitions

decodeRows : FromRow a => List (List OracleValue) -> Either OracleError (List a)

Totality: total
Visibility: export

queryRaw : Connection -> String -> List BindParameter -> IO (Either OracleError (List (List OracleValue)))

  Execute a SQL query while automatically managing the prepared statement lifetime.
  
  This is the raw query API.
  
  The statement is:
  1. Prepared.
  2. Bound with parameters.
  3. Executed.
  4. Fetched.
  5. Released.
  
  Returned rows contain raw Oracle values.
  

Visibility: export

query_ : FromRow a => Connection -> String -> List BindParameter -> IO (Either OracleError (List a))

  Execute a query and decode every returned row.
  
  The target type must provide a `FromRow` implementation describing how to convert `List OracleValue` into the target value.
  
  Example:
  
  ```idris
  record Employee where
    constructor MkEmployee
    id   : Int64
    name : String
  
  implementation FromRow Employee where
    fromRow [OracleInt id, OracleString name] =
        Right (MkEmployee id name)
    fromRow _ =
        Left invalidRow
  
  employees <- query_ conn
                     "select id,name from employees"
                     []
  ```
  

Visibility: export

queryOne : FromRow a => Connection -> String -> List BindParameter -> IO (Either OracleError (Maybe a))

  Execute a query and decode at most a single row.
  
  Returns:
  - Left OracleError if execution fails.
  - Right Nothing if no rows were returned.
  - Right (Just value) for the first row.
  
  If multiple rows are returned, only the first row is used and the remainder are ignored.
  
  Example:
  
  ```idris
  employee <-
    queryOne
      conn
      "select id,name
         from employees
        where id = :id"
      [ MkBindParameter "id"
          (OracleInt 1)
      ]
  ```
  

Visibility: export

queryExactlyOne : FromRow a => Connection -> String -> List BindParameter -> IO (Either OracleError a)

  Execute a query and require exactly one row.
  
  Returns:
  - Left OracleError if query execution fails.
  - Left OracleError if no rows are returned.
  - Left OracleError if more than one row is returned.
  - Right value if exactly one row is returned.
  
  This function is useful when querying by a primary key or other unique identifier.
  
  Example:
  
  ```idris
  employee <-
    queryExactlyOne
      conn
      "select id,name
         from employees
        where id = :id"
      [ MkBindParameter "id"
          (OracleInt 1)
      ]
  ```
  

Visibility: export

queryAs : FromRow a => Connection -> Query -> IO (Either OracleError (List a))

  Execute a structured Query and decode every returned row.
  
  The SQL statement is constructed using `buildQuerySQL`, which renders each `QueryColumn` in the SELECT projection.
  
  Ordinary columns are rendered unchanged, while `JSONColumn` expressions are wrapped with `JSON_SERIALIZE(... RETURNING CLOB)`.
  
  Each returned row is decoded using the `FromRow` implementation for the requested result type.
  
  If the query returns no rows, this function succeeds with an empty list.
  
  Any Oracle error encountered while preparing, binding, executing, or fetching the query is returned as `Left OracleError`.
  

Visibility: export

queryOneAs : FromRow a => Connection -> Query -> IO (Either OracleError a)

  Execute a structured Query and decode exactly one returned row.
  
  The SQL statement is constructed using `buildQuerySQL`, which renders each `QueryColumn` in the SELECT projection.
  
  Ordinary columns are rendered unchanged, while `JSONColumn` expressions are wrapped with `JSON_SERIALIZE(... RETURNING CLOB)`.
  
  The returned row is decoded using the `FromRow` implementation for the requested result type.
  
  This function succeeds only when the query returns exactly one row.
  
  It returns an `OracleError` if the query returns no rows or more than one row.
  
  Any Oracle error encountered while preparing, binding, executing, or fetching the query is returned as `Left OracleError`.
  

Visibility: export

queryJSON : Connection -> JSONQuery -> IO (Either OracleError String)

  Execute a JSON query and return the serialized JSON document.
  
  The JSONQuery expression is wrapped internally as:
  
    JSON_SERIALIZE(expression RETURNING CLOB)
  
  The query must return exactly one row containing one non-null JSON value.
  
  The returned JSON is represented as a String so that it can be decoded using the Idris2 JSON library.
  
  Example:
  
    queryJSON conn
      (MkJSONQuery
        "payload"
        "documents WHERE id = :id"
        [MkBindParameter "id" (OracleNumber 42)])
  

Visibility: export

queryJSONList : Connection -> JSONQuery -> IO (Either OracleError (List String))

  Execute a JSON query and return all serialized JSON documents.
  
  Each row must contain exactly one non-null JSON value.
  
  This is the multi-row counterpart to queryJSON.
  

Visibility: export

queryJSONAs : FromJSON a => Connection -> JSONQuery -> IO (Either OracleError a)

  Execute a JSON query and decode the resulting JSON document.
  
  The result is decoded using the FromJSON implementation for `a`.
  
  This allows callers to query Oracle JSON directly into an Idris data type with a derived FromJSON implementation.
  

Visibility: export

queryJSONListAs : FromJSON a => Connection -> JSONQuery -> IO (Either OracleError (List a))

  Execute a JSON query and decode all resulting JSON documents.
  
  Each row is decoded using the FromJSON implementation for `a`.
  

Visibility: export

execute_ : Connection -> String -> List BindParameter -> IO (Either OracleError ())

  Execute a statement that does not return rows.
  
  This function is intended for:
  - INSERT
  - UPDATE
  - DELETE
  - MERGE
  - DDL statements
  
  The statement is automatically:
  1. Prepared.
  2. Bound.
  3. Executed.
  4. Released.
  
  Example:
  
  ```idris
  execute_
    conn
    "insert into employees(id,name)
     values (:id,:name)"
    [ MkBindParameter "id"
        (OracleInt 1)
    , MkBindParameter "name"
        (OracleString "Alice")
    ]
  ```
  

Totality: total
Visibility: export