# Cygnus On-Premises Database Core

This module executes cloud-supplied, parameterized query definitions against the
on-premises JDBC `DataSource` without creating delimiter strings or `String[][]`
result buffers.

## Query format

The query catalog value retains the operation prefix during incremental migration:

```text
select!C0L!select id, name from operation where operation_type = ? and operated_by = ?
```

Legacy `val0`, `val1`, ... placeholders are rejected by the modern executor. They
remain available through the existing `DBFunctions.FetchRunQuery` path until each
query is migrated.

## Usage

```java
List<Operation> rows = dbFunctions.query(
        600,
        new Object[] { operationType, operatedBy },
        Operation.class);
```

For maximum throughput, use an explicit mapper:

```java
List<Operation> rows = dbFunctions.query(
        600,
        parameters,
        result -> new Operation(result.getLong("id"), result.getString("name")));
```

Large reports can use `stream(...)` so rows are consumed without retaining the
whole result in memory. PostgreSQL cursor fetching is enabled by running reads with
auto-commit disabled and the configured fetch size.

## Dynamic multi-value parameters

Use a typed array parameter with PostgreSQL `ANY` when the number of values is
not known in advance. The cached query remains parameterized:

```sql
select ... where op.description = any(?)
```

```java
dbExecutor.query(
    queryId,
    new Object[] { portfolioId, SqlArrayParameter.text(descriptions) },
    Option.class);
```

Factories are available for text, integer, smallint, bigint, numeric, boolean,
UUID, date, timestamp and timestamp-with-time-zone arrays. Use
`SqlArrayParameter.of(postgresType, values)` for another PostgreSQL scalar or
enum type. An empty collection is valid and causes `= ANY(empty_array)` to
match no rows.