diff --git a/CHANGELOG.md b/CHANGELOG.md
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,597 @@
 # Changelog
 
+See [MIGRATION.md](https://github.com/Tritlo/duckdb-haskell/blob/main/MIGRATION.md)
+for the upgrade instructions.
+
+## 1.0.0.0
+
+- Target DuckDB 2.0 with `duckdb-ffi` 2.0.0.x. The backend uses the
+  generated V2 C API. Upstream marks the V2 API as unstable ("The C API v2 is
+  not yet stable. Its interface may change in upcoming releases."), so this
+  release requires exactly DuckDB 2.0.0. The dependency bound excludes a
+  `duckdb-ffi` release for a later DuckDB version. Creating an
+  environment raises `SQLError` for another library version. Use the earlier
+  release with DuckDB 1.5.
+- Require `base` 4.18 or later, that is GHC 9.6 or later. Version 0.3 accepted
+  `base` 4.14.
+- Raw handles, callback handles, and the error codes of raw calls use V2
+  types. `sqlErrorType` is `Maybe ErrorType`. See MIGRATION.md.
+- Add `Database.DuckDB.Simple.Extension` for loadable Haskell extensions.
+  Enable the `extension` flags of both packages. See `dev/extensions/`.
+- `SQLError` has a fourth field, `sqlErrorBody`: the text of a native error
+  without the prefix of its type, and `Nothing` for an error of the library.
+  Code that builds or matches an `SQLError` by position does not compile. See
+  MIGRATION.md.
+- An `SQLError` with a type keeps that type when it leaves a Haskell callback.
+  The outer statement fails with that type, and its text has one prefix, for example
+  `Conversion Error: ...` for a failed query in a scalar function. A failed cast
+  gives `ErrorTypeMismatch`. Sixteen types give `ErrorInputInvalid` and the text
+  `Invalid Input Error: ` followed by the exception message. An `SQLError`
+  with no type and each other exception give the same result. The "Errors"
+  section of README.md lists those types and the reasons. When a callback error
+  fails a statement in an explicit transaction, DuckDB invalidates that transaction, and
+  COMMIT then stores none of its rows, also under the DuckDB setting
+  `SYNTACTIC_ERRORS_DO_NOT_INVALIDATE`.
+- Add shared environments and instances, attachment management, option
+  discovery, table descriptions, SQL tokenization, and positioned file I/O.
+- `listConfigFlags` takes a `Connection`. It lists that connection's database
+  options, including custom options. See MIGRATION.md.
+- `deleteFunction` reads the name with the rules of DuckDB for a qualified
+  name, so a part in double quotes can contain a dot. See MIGRATION.md.
+- `ConfigValue.configValueText` is `Maybe Text`, and `Nothing` for an option
+  with a NULL value. Version 0.3 stopped the process for such an option. See
+  MIGRATION.md.
+- A `Day` outside the range of DuckDB, from -5877641-06-25 to 5881580-07-10, and
+  a `LocalTime` or a `UTCTime` outside the range from -290308-12-22 00:00:00 to
+  294247-01-10 04:00:54.775806, in the notation of `Data.Time`, raise an
+  `SQLError` of the type `ErrorTypeConversion` when they bind. For a target of
+  the type TIMESTAMP_NS or TIMESTAMPTZ_NS, a value outside the smaller range of
+  that type gets the same type, from the library or from DuckDB by its position.
+  Version 0.3 bound some of these values and raised an `IOException` for the
+  others. See MIGRATION.md.
+- Add typed configuration values and defaults, managed log sinks, macro
+  registration, function documentation, query metrics, and file path
+  operations. Expose table bind metadata for multi-file readers.
+- Add typed registrations. Their signatures have no native handle.
+  `Database.DuckDB.Simple.Function` has `createAggregate`,
+  `createTableFunction`, and the row class `TypedRow`. `Database.DuckDB.Simple`
+  exports the two functions, `Aggregate`, and `TypedRow`. There is no typed
+  cast: the README section "Typed registration" tells why.
+- A cast that `registerCast` registers does not change a value that the
+  library reads or binds, on a connection and in the callbacks of an extension
+  (see the README). An exception in the callback of `registerCast` gives an
+  `SQLError` of the type `ErrorTypeMismatch`, and `TRY(CAST(...))` raises the
+  error. The section Errors of the README tells why.
+- `createAggregate` registers a Haskell fold with initial state, step,
+  combine, and result functions. Its result needs a static SQL declaration
+  and a `ToDuckValue` encoder that works with an instance factory. Examples
+  include nullable GEOMETRY, VARIANT, and records through `ViaDuckDB`.
+- `V2.Registration.registerAggregateFunctionWithCleanup` runs a cleanup
+  action when DuckDB releases the last reference to the aggregate's callbacks.
+- `createTableFunction` registers a Haskell function that gives the rows of a
+  table function as a list. DuckDB reads the list one chunk at a time. It reads
+  only the columns that the query uses, and the first column for a query such
+  as `SELECT count(*)`. The library does not evaluate the other columns of a
+  row, but it evaluates each strict field of each row that it writes.
+- `DuckDBColumnType` has the method `duckdbTypeDeclaration`. It gives the SQL
+  type that a typed table function and a typed aggregate function declare. A
+  record or a sum type gets `ToDuckValue` and a STRUCT or UNION declaration
+  through `ViaDuckDB`. `StructValue`, `TupleValue`, and `UnionValue` have no
+  declaration, and the registration raises an error for them. A
+  `SizedArray n a` declares the ARRAY of size `n`. DuckDB casts a LIST of the
+  same length to it with no error.
+  `Database.DuckDB.Simple.LogicalRep` exports `TypeDeclaration`.
+- `SizedArray n a` is new, and it replaces the instances of `Array Int a`: an
+  `Array Int a` of exactly `n` values, with the bounds `(0, n - 1)`.
+  `sizedArray` makes one from an `Array` with any bounds, `sizedArrayFromList`
+  from a list, and `sizedArrayToArray` gives the `Array`. It binds as an ARRAY
+  of size `n`, a typed registration declares that type, also for a field of a
+  record through `ViaDuckDB`, and it reads an ARRAY and a LIST of `n` elements.
+  A value of another length gives an `Incompatible` conversion error,
+  reported as `SQLError` by the query APIs. `Array Int a` has no
+  `ToField`, `FromField`, `DuckDBColumnType`, `ToDuckValue`, or `DuckValue`
+  instance. A list reads an ARRAY of each size, and a `FieldArray` is an ARRAY
+  value that a program builds at run time. See MIGRATION.md.
+- An ARRAY parameter with more than 100000 elements, the largest ARRAY of
+  DuckDB, raises an `SQLError` of the type `ErrorInputInvalid`, as an empty
+  ARRAY parameter does.
+- An argument of `createFunction` can have each type with `FromField` and
+  `DuckDBColumnType`, for example a record through `ViaDuckDB`, a list, a `Map`,
+  or a newtype with its own column type name. `FunctionArg` is gone.
+  Arguments use the same conversion as query results, including nested values.
+- A result of `createFunction` can have each type with `ToDuckValue`. Its SQL
+  type is the `duckdbTypeDeclaration` of the type: an `Int16` result is
+  SMALLINT, a `Word16` result is USMALLINT, and a `Float` result is FLOAT, in
+  place of BIGINT and DOUBLE. `ScalarType` is gone, and `FunctionResult` has an
+  instance for each type with `ToDuckValue`.
+- `Database.DuckDB.Simple.Registration` has `TypeDeclaration`, `parameter`,
+  `defaultValue`, `registerCustomType`, and typed replacement scans.
+  `registerReplacementScan` and `registerInstanceReplacementScan` give the
+  parts of an unknown table name to a Haskell function. The function can return
+  a SELECT statement that DuckDB reads instead.
+- Add `registerCopyFromFunction`, `registerCopyFunction` with the record
+  `CopyTo`, `CopyFromInfo`, and `registerMultiFileFunction` to
+  `Database.DuckDB.Simple.Copy`. `registerCopyFromFunction` registers a COPY
+  FROM side that gives a list of typed rows. `registerCopyFunction` registers a
+  COPY TO side and a COPY FROM side under one name. DuckDB keeps the first
+  registration of a format name and ignores a later one. Thus a format with two
+  directions needs `registerCopyFunction`.
+- Add `Database.DuckDB.Simple.Pragma`. `registerPragmaFunction` takes a typed
+  callback `PragmaCallback args`. The callback gets the arguments of the call
+  as a `FromRow` row.
+- Add custom options to `Database.DuckDB.Simple.Config`. `customOptionUpdate`
+  is a function that gets the new value as a `FieldValue`. An exception in the
+  function rejects the value.
+- `Database.DuckDB.Simple.Extension` has the same typed registrations for a
+  loadable extension: `createAggregate`, `createTableFunction`,
+  `registerReplacementScan`, `registerCustomType`,
+  `registerMultiFileFunction`, `registerCopyToFunction`,
+  `registerCopyFromFunction`, `registerCopyFunction`,
+  `registerPragmaFunction`, and `registerCustomOption`.
+- A typed registration has more overhead for each row than raw vector access.
+  Use the V2 modules for speed, projection and filter pushdown,
+  parallel table scans, and scalar functions with a bind callback or variadic
+  parameters.
+- Add `SettingScope`, `LogLevel`, `LogScope`, `TokenType`, `MacroFunctionType`,
+  `ErrorType`, and `LogicalTypeId`. The configuration, logging, tokenizer,
+  macro, error, and logical type APIs use these types instead of the generated
+  V2 enum types, so a later C API version does not change these APIs. The file
+  system API uses `FileFlag` and the opaque `FileHandle` instead of the
+  generated V2 types. `ToDuckValue.toDuckValue` uses the synonyms
+  `ValueFactory` and `NativeValue` for the two native handles in its signature.
+- The functions with native handles are in modules with `V2` in the name.
+  `Database.DuckDB.Simple.V2.Registration` has the scalar, aggregate, table,
+  and cast registrations and the replacement scans with native callbacks. It
+  also has `registerMacroFunctionWith`, which gives the native macro builder to
+  an action. It takes the `RegistrationTarget` from
+  `Extension.extensionTarget`. `Database.DuckDB.Simple.V2.Copy` has the native
+  COPY callback interface: `CopyToCallbacks`, `CopyFromCallbacks`, the raw
+  `registerCopyFunction`, `registerCopyFunctionWith`,
+  `registerCopyToCallbacks`, `registerCopyFromCallbacks`, and
+  `registerMultiFileFunctionWith`. `Database.DuckDB.Simple.V2.Pragma` has the
+  pragma callbacks with native handles. `Database.DuckDB.Simple.V2.Config` has
+  `registerCustomOptionWith`. `Database.DuckDB.Simple.V2.FunctionDocs` has
+  `setFunctionDocs`. `Database.DuckDB.Simple.V2.Logging` has `logMessage`,
+  which writes a message through the context of a native callback.
+  `Database.DuckDB.Simple.V2.LogicalRep` has `logicalTypeToRep`,
+  `logicalTypeFromRep`, `logicalTypeFromRepWith`, and `destroyLogicalType`.
+- Keep statements alive while reading cached schemas for column metadata and
+  parameter types. `Internal.withStatementSchemas` scopes these borrowed handles.
+- Release acquired native handles if evaluation of a lazy input list fails.
+- Mask native parameter cleanup so cancellation cannot skip releases.
+- Read LIST, ARRAY, and MAP elements with a constant stack. Keep native reads in
+  element order.
+- Read VARIANT metadata from its result vector. Construct VARIANT types by name.
+  Read singleton INT64 and UINT64 cast payloads with native getters.
+- `Database.DuckDB.Simple.Internal` changes. It re-exports the native helper
+  layer. It no longer exports `toSQLError`, `fetchPrepareError`,
+  `fetchResultError`, `throwResultError`, `mkExecuteError`,
+  `throwRegistrationError`, `withClientContext`, and `destroyClientContext`.
+  `Connection` adds `connectionInstance`, `connectionLock`,
+  `connectionWindow`, and `connectionOptions`. `ConnectionOpen` has no
+  `connectionDatabase` and adds `connectionStatements` and
+  `connectionReleaseParent`. `Statement` adds `statementArrowResult`,
+  `statementBindings`, `statementParameterNames`, and
+  `statementParameterTypes`.
+  `StatementOpen` adds `statementParsed` and `statementSchemaCache`.
+  `StatementStream` has no `statementStreamMode` and adds
+  `statementStreamPendingChunks`. `StatementStreamColumn` has no
+  `statementStreamColumnType` and adds `statementStreamColumnTree`.
+- The SQL error of a failed Haskell callback has the plain message of the
+  exception. Version 0.3 gave `user error (...)` for a `userError` and the
+  Haskell record for an `SQLError`.
+  The error of an argument that does not convert names the argument (`arg0`,
+  `arg1`, and so on). Its text has one form for scalar functions, table
+  functions, and aggregate functions, for example
+  `cannot convert argument arg0 from VARCHAR to Int64`. A table function and an
+  aggregate function put their name before it:
+  `duckdb-simple: NAME: cannot convert argument ...`.
+- Add scoped named collection inputs and prepared dynamic PIVOT with a deferred
+  output schema. Prepared dynamic PIVOT cannot have parameters.
+- Rename `Database.DuckDB.Simple.Deprecated.Streaming` to
+  `Database.DuckDB.Simple.Streaming`.
+- Export Arrow release helpers from `Database.DuckDB.Simple.Arrow`.
+- A DuckDB callback that waits for the lock of a connection waits at most the
+  time limit of that connection. Add `connectionCallbackLockWait` to
+  `ConnectionOptions`, in microseconds, with the default
+  `defaultCallbackLockWait` (10 seconds). `Nothing` sets no time limit, and the
+  open rejects a negative time limit. A statement of a callback on the
+  connection that runs the callback thus raises an `SQLError` of the type
+  `ErrorResourceInUse` after the time limit. For most callbacks, the outer
+  statement then fails. The README gives the cases that the time limit does
+  not cover.
+- The README and the module header of `Database.DuckDB.Simple.Function` say that
+  a program that registers a callback must be linked with `-threaded`. DuckDB
+  can call a callback from several threads at the same time, and without
+  `-threaded` such a program can crash. Version 0.3 needed `-threaded` in the
+  same way, and its README named it only for prompt cancellation. A program
+  that is not linked with `-threaded` now gets an `SQLError` of the type
+  `ErrorInputInvalid` when it registers a callback for a database with the
+  DuckDB setting `threads` above 1. COPY format callbacks and log sinks
+  require `-threaded` even when `threads` is 1: DuckDB can call them on its
+  asynchronous workers. For other registrations the library reads the setting
+  at registration and cannot detect a later `SET threads`.
+- Add `connectionAggregateStripes` to `ConnectionOptions`. It sets the number
+  of stripes in the state table of each typed aggregate that `createAggregate`
+  registers through the connection. The
+  default is `defaultAggregateStripes` (64). The open rejects a number that is
+  not positive. A registration on an extension uses the default.
+- Add `connectionArrowBatchSize` to `ConnectionOptions`. It sets the largest
+  number of rows in one Arrow array of an Arrow fold on the connection. The
+  default is `defaultArrowBatchSize` (2048 rows). The open rejects a value that
+  is not positive.
+- The library decodes the message of a native error with replacement
+  characters. Thus `show` of such an `SQLError` does not raise for a text that
+  is not valid UTF-8. Version 0.3 decoded the text with `decodeUtf8`, which
+  raises for such a text.
+- While an explicit stream is incomplete, DuckDB rejects other statements on
+  its connection. Closing an incomplete stream aborts its statement.
+- Each connection serializes statement preparation, its open native result,
+  and each fetch of an explicit stream. Threads that share a connection wait
+  for each other in the default query functions. Serialize transactions and
+  explicit streams in the application.
+- `query_` and `execute_` parse all statements before they run any.
+- An INSERT, UPDATE, or DELETE without RETURNING gives one row with the number
+  of changed rows in each function that reads rows, also in `fold`, `nextRow`,
+  and the same functions of `Database.DuckDB.Simple.Streaming`.
+- Decode and bind TUPLE values with `TupleValue`, `FieldTuple`, and
+  `LogicalTypeTuple`.
+- Preserve composite VARCHAR collations with `LogicalTypeCollatedVarchar`.
+- Keep the alias of a type with `LogicalTypeAlias`, at each depth. A
+  `ColumnDescription` of a JSON column gives
+  `LogicalTypeAlias "JSON" (LogicalTypeScalar LogicalTypeIdVarchar)`, and a
+  column of a type from `registerCustomType` gives the name of the type.
+  `logicalTypeFromRep` creates the alias type, so a `DuckValue` field can
+  declare JSON in a typed registration and in a parameter. The type fields of
+  a STRUCT, TUPLE, or UNION value keep the alias, so a value that a query reads
+  binds again with its type. The readers and the binding of parameters convert
+  with the base type. A column of a type from `CREATE TYPE name AS base` has the
+  base type and no alias.
+- `logicalTypeToRep` takes a factory before the logical type handle. Keep the
+  factory valid throughout the conversion. The returned `LogicalTypeRep` is
+  pure and remains valid after the factory closes. The function does not
+  destroy the logical type handle. See MIGRATION.md.
+- Decoders and field metadata use `Conversion a` with explicit IO. `Field`
+  loses its `Eq` and `Show` instances. Native field metadata expires with its
+  query result or callback scope. See the
+  [source migration](https://github.com/Tritlo/duckdb-haskell/blob/main/MIGRATION.md#duckdb-simple-03-to-10)
+  for changed signatures and instances, and
+  [Decoding rows](https://github.com/Tritlo/duckdb-haskell/blob/main/duckdb-simple/README.md#decoding-rows) for conversion and metadata rules.
+- Read errors name the type of the column with `logicalTypeSQL`, the type
+  text of DuckDB, for example DECIMAL(18,2), TIMESTAMP_NS, ENUM('a', 'b'), or
+  JSON. For a VARIANT column, they name the type of the stored value in the
+  same text, for example TIMESTAMP WITH TIME ZONE. The bind errors
+  `cannot encode a value of type ... as ...` and
+  `unsupported scalar conversion for ... from a value of type ...` name each
+  type in the same text.
+- Decode nanosecond timezone timestamps in results and VARIANT values.
+- Preserve the digits below a microsecond of a `TimeOfDay`, a `LocalTime`, and
+  a `UTCTime`, and of their `Unbounded` forms, for a nanosecond parameter
+  (`TIME_NS`, `TIMESTAMP_NS`, or `TIMESTAMPTZ_NS`), also in collections,
+  STRUCTs, MAPs, and UNIONs. For a `VARIANT` parameter, one such value keeps
+  them when it fits the range of the nanosecond type, but the elements of a
+  list, a `SizedArray`, or a `Map` of such values get the microsecond value (see
+  the entry on `VARIANT` parameters below). Only a value with such digits
+  reads the parameter type. Each other parameter gets the microsecond value,
+  as for the SQL literal. An explicit cast such as `?::TIMESTAMP_NS` makes a
+  nanosecond parameter, so for a `TIMESTAMP` column DuckDB rounds the value to
+  the microsecond, where a plain `?` cuts the digits. Version 0.3 bound the
+  microsecond value for each parameter.
+- Decode VARIANT values through public V2 operations. Object keys use DuckDB's
+  lexicographic order.
+- Allow a VARIANT object to contain an empty key with other named keys.
+  Version 0.3 rejected such an object.
+- A `Variant` parameter with a UNION, a MAP, an ENUM, or a GEOMETRY with a CRS
+  in its payload, at any depth, raises `SQLError` with the type
+  `ErrorInputInvalid`. The error gives the reason: a VARIANT keeps only the
+  member value of a UNION, stores a MAP as a list of key and value objects,
+  stores an ENUM as its text, and does not keep the CRS of a GEOMETRY. Version
+  0.3 bound a UNION payload with no error.
+- Read GEOMETRY results through a native cast to BLOB. DuckDB 2.0 rejects WKB
+  with mixed Z/M member layouts.
+- `ToDuckValue.toDuckValue`, `logicalTypeFromRep`, and `logicalTypeFromRepWith`
+  take a V2 factory. Composite parameters keep GEOMETRY CRS metadata, including
+  unknown custom labels resolved through SQL on a helper connection.
+- `logicalTypeFromRep` creates a VARIANT type, and a GEOMETRY type with a CRS
+  that DuckDB recognizes. Version 0.3 raised an error for VARIANT and created
+  GEOMETRY without the CRS.
+- Add a `ToDuckValue` instance for `Variant`. Version 0.3 had none.
+- A composite parameter that the native value constructor rejects raises an
+  `SQLError`. For example, a STRUCT parameter with a MAP field that has a NULL
+  key raises an `SQLError` with the type `ErrorInputInvalid`. Version 0.3
+  raised an `IOException`.
+- Remove `connectionGeometryCRS` from `ConnectionOptions` and `withTypeCache`
+  from `Database.DuckDB.Simple.Internal`. Remove the field
+  from record construction and updates, or its argument from positional
+  construction and patterns. Parameters construct recognized CRS names and full
+  definitions directly. Unknown custom labels use a helper SQL query on demand,
+  including in nested types, typed NULLs, empty collections, and inactive UNION
+  members. The library does not keep a permanent cache of custom CRS types.
+  Blank labels and labels with NUL fail when used by a parameter, not when the
+  connection opens. Query reads retain custom labels. Typed registrations and
+  direct `logicalTypeFromRep` calls still require a recognized CRS or a full
+  definition.
+- The library builds a UNION parameter in a one-row UNION vector, because the
+  V2 API has no UNION value constructor. This requires flat child vectors.
+  DuckDB 2.0.0 supplies them in a new vector, but its header does not guarantee
+  this.
+- A STRUCT, TUPLE, or UNION parameter binds a `FieldGeometry` value as a
+  GEOMETRY with the same WKB bytes and CRS, through DuckDB's cast from BLOB.
+  A value whose CRS is not the CRS of its declared type raises `SQLError` with
+  the type `ErrorInputInvalid`. A `Variant` parameter binds a `FieldGeometry`
+  value without a CRS. One with a CRS raises `SQLError`, because a VARIANT does
+  not keep the CRS. Version 0.3 raised an error for each such value, because
+  DuckDB 1.5 has no cast from BLOB to GEOMETRY.
+- Add a `ToField` instance for `RawGeometry`. It binds as a GEOMETRY with the
+  same WKB bytes and its own CRS. DuckDB casts it to the type of the parameter,
+  as in SQL text. A value without a CRS takes the CRS of the target. A target
+  without a CRS removes the CRS. A target with another CRS raises `SQLError`.
+  Version 0.3 had only a `FromField` instance for `RawGeometry`. A
+  `SizedArray`, a list, or a typed row cannot hold a `RawGeometry`.
+- An empty ARRAY parameter, a `SizedArray` of size 0 or a `FieldArray` with no
+  element, raises `SQLError`. Version 0.3 bound an empty `Array` of scalar
+  elements. Bind an empty list for an empty LIST.
+- `TimeWithZone` holds the offset in seconds east of UTC, as a TIMETZ stores it.
+  The field `timeWithZoneZone :: TimeZone` of version 0.3 is now
+  `timeWithZoneOffsetSeconds :: Int32`. `timeWithZone` and `timeWithZoneZone`
+  convert from and to a `TimeZone`. A TIMETZ with an offset that has seconds,
+  for example `12:00:00+01:00:30`, now reads. Version 0.3 raised an error for
+  it. Update code that uses the old field. See MIGRATION.md.
+- Add `ToField` instances for `IntervalValue`, `TimeWithZone`, and
+  `DecimalValue`, and `ToDuckValue` instances for `IntervalValue` and
+  `TimeWithZone`. An `IntervalValue` binds as an INTERVAL and a `TimeWithZone`
+  as a TIMETZ, also in a `SizedArray`, a list, or a typed row. A `TimeWithZone`
+  reads back equal to the bound value, except that a time loses its digits
+  below one microsecond. An offset outside -15:59:59 to +15:59:59 raises an
+  error. A `DecimalValue` binds as a DECIMAL with its own width and scale. A
+  `SizedArray`, a list, or a typed row cannot hold a `DecimalValue`. Version 0.3
+  had only `FromField` instances for these types.
+- Add `ToField` and `ToDuckValue` instances for `Map`. A `Map` binds as a MAP
+  value with its pairs in ascending key order. The keys and the values follow
+  the element rules of a list, and an empty `Map` binds as an empty MAP of its
+  key and value types. Version 0.3 had only a `FromField` instance for `Map`.
+- Add `ToField` and `ToDuckValue` instances for lists. A list binds as a LIST
+  value with the element rules of a `SizedArray`, and an empty list binds as an
+  empty LIST of its element type (for an empty list of `Integer` or `Natural`
+  values, see the entry on `Integer` parameters). A `String` stays one VARCHAR
+  parameter, and a list as a row is still a row of parameters, so a list
+  parameter is `Only [..]`. Version 0.3 had no `ToField` instance for lists.
+- Each input check of the library raises `SQLError` with the type
+  `ErrorInputInvalid`: a parameter value that does not fit its type (for example
+  a `BitString` with bad padding, a `UnionValue` with a tag out of range, or an
+  empty `SizedArray`), a logical type with a NUL in a name or a bad DECIMAL
+  width, a CRS name that DuckDB does not keep, a NUL in a database path, an
+  alias, an attach option, a configuration, a query, or a parameter name, a NUL
+  in a file path, a negative file offset or read size, a file range outside
+  `Int64`, a bad `ConnectionOptions` field, SQL text with no statement or with
+  more than one statement, a parameter index out of bounds, a column index of
+  `columnName` out of bounds, a bad name or argument of a registration, a
+  catalog lookup, a configuration option, or a log sink, and the column count of a
+  COPY FROM table. An error about a statement has
+  the query of the statement, and each other error has no query. A value outside
+  the range of its SQL type raises `SQLError` with the type
+  `ErrorTypeConversion` when it binds, the type of the "Conversion Error" that
+  DuckDB raises for the same value in SQL: a date or a timestamp outside the
+  range of DuckDB, an integer outside the range of its parameter type or its
+  declared type, a nanosecond timestamp outside its storage or at an infinity
+  value as a STRUCT field, a TUPLE element, a UNION member, or an element of a
+  list, a `SizedArray`, or a `Map`, a `FieldHugeInt` or a `FieldUHugeInt`
+  outside its type, a TIMETZ offset outside -57599 to 57599 seconds, a time of
+  day that is not a TIME value (a field outside its own range, or a time after
+  24:00:00), an ENUM label that is not in the dictionary of its type, and a
+  `DecimalValue` that its width cannot hold. For such a nanosecond timestamp in
+  the range of DuckDB, for example in the year 2300, as a TIMESTAMP_NS or
+  TIMESTAMPTZ_NS parameter, DuckDB raises its own error, of the same type. A
+  `LocalTime` or a `UTCTime` (in UTC) from 2262-04-11 23:47:16.854775807 to
+  23:47:16.854775999 gets the error of the library in each position. A value of
+  the wrong shape or type keeps `ErrorInputInvalid`, also where DuckDB gives
+  another type for the same input, for example a UNION tag that is not a member,
+  a leaf built from another type, a STRUCT field that does not match its type,
+  or a blank GEOMETRY CRS label. A parameter count or a parameter name that does not match
+  the query keeps its `FormatError`. A check in a callback fails the outer
+  statement with the type of the check: such a value as the result of a typed
+  function or a row of a typed table function gives `ErrorTypeConversion` and
+  the text `Conversion Error: duckdb-simple: ...`. Version 0.3 raised an
+  `IOException` for the checks of parameter values, logical types, and CRS
+  names. The error for a scalar value that does not match its declared type
+  names the SQL type, for example `"NULL"` in place of `LogicalTypeIdSQLNull`.
+- A check of the state of the library, or of a vector, a type, or a value that
+  DuckDB gave, raises `SQLError` with the type `ErrorRuntimeInternal`. Such an
+  error means a defect of the library or of DuckDB. When a statement raises it,
+  it has the query of the statement, as each other `SQLError` of a statement
+  has. Inside a callback, the statement that runs the callback fails instead,
+  with an `SQLError` of the type `ErrorInputInvalid` and the text "Invalid Input
+  Error: duckdb-simple: ...", because a callback does not pass the type
+  `ErrorRuntimeInternal` (a cast gives `ErrorTypeMismatch`). The use of a closed
+  environment, instance, connection, or statement, a DuckDB library
+  of another version, and a callback state read with the wrong type are not
+  internal checks; they raise an `SQLError` with no type. Version 0.3 raised an
+  `IOException` (a `userError`) or an `ErrorCall` for the internal checks, for
+  example for a UNION tag outside the members of a result vector.
+- A `TimeOfDay`, a `LocalTime`, or a `UTCTime` with digits below a microsecond,
+  and a `FieldTime`, a `FieldTimestamp`, or a `FieldTimestampTZ` with such
+  digits, binds with the nanosecond type for a nanosecond parameter, and for a
+  `VARIANT` parameter when it fits the range of that type, so the VARIANT keeps
+  the digits. A value with no such digits binds as before, with no read of the
+  parameter type. These values get the microsecond value: a value outside the
+  range of the nanosecond type, an element of a list, a `SizedArray`, or a `Map`
+  for a `VARIANT` parameter, and an element of a `VARIANT[]` or a
+  `MAP(..., VARIANT)` parameter. In a `Variant` payload, each time leaf, also
+  an element of a list payload and a field of an object payload, binds with the
+  nanosecond type when it has such digits and fits the range.
+- An empty `SizedArray` and an empty `FieldArray` raise the same `SQLError`, of
+  the type `ErrorInputInvalid`.
+- Add a parameter instance for `FieldValue`, so a row read as `[FieldValue]`
+  binds back. A scalar constructor binds as the DuckDB type of the
+  constructor, and a `FieldList`, a `FieldArray`, or a `FieldMap` takes the
+  element type that its elements give, with the rule of a SQL list literal.
+  A `FieldEnum` binds its label as a VARCHAR. An empty `FieldArray` raises
+  `SQLError` with the type `ErrorInputInvalid`. A `FieldTimestamp`, a
+  `FieldTime`, and a `FieldTimestampTZ` bind with the microsecond type. A value
+  with digits below a microsecond binds with the nanosecond type for a
+  nanosecond parameter, and for a `VARIANT` parameter when it fits the range of
+  that type.
+- A `SizedArray`, a list, or a `Map` of STRUCT values, UNION values, generic
+  records, lists, or arrays with different element types gets the type that
+  DuckDB gives a SQL list literal of the elements, for example
+  `STRUCT(a INTEGER, b INTEGER)` for `{'a': 1}` and `{'b': 2}`. Elements with
+  no common type raise the `SQLError` of DuckDB. Version 0.3 raised an error
+  for each `SizedArray` with different element types.
+- A list or a `Map` of such elements that has no element, and a `SizedArray`, a
+  list, or a `Map` with only NULL elements, take the element type of the
+  parameter when the parameter has a known type, for example for an `INSERT`
+  into a typed column. An empty `SizedArray` raises an error, as an entry above
+  says. For a parameter with no known type, such a list of generic records
+  through `ViaDuckDB` takes the STRUCT or UNION type of the record. Each other
+  such list or `Map` with only NULL elements takes the type of the SQL list
+  literal, such as `"NULL"[]`, and each other empty list or `Map` takes the
+  type NULL, as `[]` and `MAP {}` have. Version 0.3 raised an error for an
+  `SizedArray` of NULL elements.
+- Some parameters bind for the type that DuckDB gives the parameter: a time
+  value with digits below a microsecond, a `SizedArray`, a list, a `Map`, a
+  manual STRUCT, TUPLE, or UNION value, and an `Integer` or a `Natural` outside
+  the HUGEINT range. `executeMany` reads these types one time for each call. A
+  column type that changes during the call does not change how the later rows of
+  that call bind.
+- An `Integer` or a `Natural` parameter binds as a HUGEINT value when the value
+  is in the HUGEINT range. Before, it bound as a BIGNUM value in each case. In
+  DuckDB 2.0.0 the casts from BIGNUM to the integer types have three defects. A
+  cast to HUGEINT, UHUGEINT, or DECIMAL fails. A cast of a negative value to an
+  unsigned type gives a wrapped value. A cast of a value of 2^128 or more gives
+  the value modulo 2^128. DuckDB checks the range of a HUGEINT value for its
+  target. A value outside the HUGEINT range binds as BIGNUM, or as UHUGEINT for
+  a UHUGEINT parameter that can hold it. For each other integer or DECIMAL
+  parameter, such a value raises an `SQLError` of the type
+  `ErrorTypeConversion`. `typeof(?)` is thus HUGEINT for an `Integer` in the
+  HUGEINT range. Bind a `BigNum` to bind a BIGNUM value in each case. A
+  `SizedArray` of `Integer` or `Natural` values takes the element type of its
+  target when that type is an integer type or DECIMAL, so DuckDB checks the
+  range of each element. Before, a negative element for an unsigned array column
+  was stored as a wrapped value. For each other target, a `SizedArray`, a list,
+  or a `Map` of such values takes the type that its elements give, as a SQL list
+  literal of the HUGEINT and BIGNUM values: `[1, 2^64]` is `HUGEINT[]`,
+  `[1, 2^200]` is `BIGNUM[]`, and an empty list or a list of only NULL elements
+  is `"NULL"[]`. The rule follows the column type name BIGNUM, so an all-NULL
+  list of `BigNum` values with no target is also `"NULL"[]` in place of
+  `BIGNUM[]`, and a type whose column type name is BIGNUM follows it too.
+- `toDuckValue` for an `Integer` or a `Natural` gives a HUGEINT value when the
+  value is in the HUGEINT range, and a `Natural` up to 2^128 - 1 gives a
+  UHUGEINT value. Each other value raises an `SQLError` of the type
+  `ErrorTypeConversion`; use `BigNum` for a larger value. Before, it gave a
+  BIGNUM value in each case. DuckDB checks the range when it casts a HUGEINT
+  value. Thus `setConfigValue` with -5 for an unsigned option raises an error,
+  and a default value from `defaultValue` that its parameter cannot hold raises
+  an error at a call that omits the argument. A newtype over `Integer` with the
+  default `toField` binds through `toDuckValue`, so its parameter outside the
+  HUGEINT range also raises this error.
+- An `Integer` declares HUGEINT and a `Natural` declares UHUGEINT as a column of
+  a typed row, an argument, and a result, as for a field of a generic record. A
+  list or a `Map` of them in a typed row has HUGEINT or UHUGEINT elements. The
+  column type name (`duckdbColumnTypeFor`) still gives BIGNUM for them, the type
+  of a parameter that holds each value.
+- A product type with no fields has one encoding: the STRUCT without fields,
+  which DuckDB shows as `{}`. `genericToFieldValue` gives this STRUCT, as the
+  `ViaDuckDB` binding and `genericToStructValue` did before. A constructor with
+  no fields in a sum type has this STRUCT as its payload. This includes each
+  constructor of an enum-like sum type, such as `data Colour = Red | Blue`.
+  Version 0.3 gave `FieldNull` in these two places, so `Just x` and `Nothing`
+  of such a type were the same value in a field. The decoders accept
+  `FieldNull` and the STRUCT without fields.
+- A value that is not NULL with the declared type SQLNULL raises a conversion
+  error. Before, it was bound as NULL with no error. This applies to a manual
+  `StructValue`, `TupleValue`, or `UnionValue`, to a LIST of that type, and to
+  a `Variant` that holds such a value.
+- `errSQLType` of a `ResultError`, and the `SQLError` message of a failed
+  conversion, give the DuckDB type names `TIMESTAMPTZ` and `TIMETZ`. Earlier
+  versions gave `TIMESTAMP_TZ` and `TIME_TZ`, which DuckDB does not accept as
+  type names.
+- `errSQLType` of a `ResultError`, and the `SQLError` message of a failed
+  conversion, give the type names of DuckDB's `typeof`: `TINYINT`, `SMALLINT`,
+  `INTEGER`, `BIGINT`, and `VARCHAR`. Earlier versions gave `INT1`, `INT2`,
+  `INT4`, `INT8`, and `TEXT`. The errors of DuckDB use `INT8` for the 8-bit
+  type, not for `BIGINT`.
+- `duckdbColumnType` gives `VARCHAR` for `Text` and `String`. Earlier versions
+  gave `TEXT`.
+- A DECIMAL read as `Double` or `Float`, and a BIGINT read as `Float`, give
+  the value of the cast of DuckDB to DOUBLE or FLOAT. Earlier versions rounded
+  two times, so the value could differ from the cast in the last bit. For
+  example, `2706284552926637.70::DECIMAL(18,2)` read as `2706284552926638.0`,
+  and the cast gives `2706284552926637.5`. For scale 0 and a width of 19 to 38,
+  the cast of DuckDB does not always give the nearest value, and the library
+  gives the value of the cast. As seen in CI, the DuckDB 2.0.0 build for macOS
+  on Apple Silicon rounds some BIGINT values above 2^53 two times in its cast
+  to FLOAT, and the library gives the nearest value there.
+- A BOOLEAN read as `Text` or `String` gives `true` or `false`, as the cast to
+  VARCHAR does. Earlier versions gave `1` or `0`.
+- A `FromField` instance reads another SQL type only when it gives the value
+  of the cast of DuckDB, or an error. The Haddock of each instance gives the
+  SQL types that it reads. MIGRATION.md gives the SQL to write in place of each
+  read that the next three entries remove.
+- A TIMESTAMP, TIMESTAMP_S, TIMESTAMP_MS, TIMESTAMP_NS, or DATE read as
+  `UTCTime`, and a TIMESTAMPTZ or TIMESTAMPTZ_NS read as `LocalTime`, raise the
+  error of an incompatible column, also in the `Unbounded` forms. The casts of
+  DuckDB use the TimeZone setting of the session. Earlier versions used UTC.
+- A FLOAT or DOUBLE read as `Text` or `String` raises the error of an
+  incompatible column. Earlier versions gave the text of `show`, for example
+  `1.0e-2` for 0.01, where the cast gives `0.01`.
+- A VARCHAR read as `ByteString` raises the error of an incompatible column.
+  Earlier versions gave the UTF-8 bytes, where the cast to BLOB reads escape
+  sequences.
+- `FieldEnum` holds the index and the label of an ENUM value:
+  `FieldEnum Word32 Text`. An ENUM value reads as `Text` or `String` with its
+  label, as the cast to VARCHAR gives it. Earlier versions raised an error. An
+  ENUM value read as an integer type raises the error of an incompatible
+  column. Earlier versions gave the index, where the cast of DuckDB parses the
+  label. The reader reads a label through the dictionary of the type and does
+  not cast. A result column reads each label that it needs one time for each
+  execution. The readers of a MAP key or value, of an argument, and of a COPY
+  TO row read the labels again for each vector. A child of a STRUCT, a TUPLE,
+  or a UNION reads the whole dictionary one time for each execution.
+- A `FieldEnum` inside a value of a declared ENUM type binds its label, not its
+  index. A label that is not in the dictionary raises `SQLError` with the type
+  `ErrorTypeConversion`, as the cast of DuckDB gives for that label.
+- `displayException` of a `ResultError` gives the text of the error, with the
+  column and the two types, as the `SQLError` of a column. Earlier versions
+  gave the derived `show`. The error of a field of a `ViaDuckDB` record names
+  the field, for example
+  `duckdb-simple: field stampedAt: a value has type TIMESTAMP but expected UTCTime`.
+- A list field of a generic record reads an ARRAY, as a top-level list does.
+  Earlier versions read only a LIST in a field.
+- The errors of the generic decoders name the SQL type of a value, for
+  example
+  `duckdb-simple: field xs: a value has type MAP(VARCHAR, BIGINT) but expected LIST or ARRAY`.
+  Earlier versions printed the derived `show` of the whole value.
+- Two bind errors name the SQL type of the value in the same way:
+  `cannot encode a value of type INTEGER as ...` and
+  `unsupported scalar conversion for BIGINT from a value of type VARCHAR`.
+  Earlier versions printed the derived `show` of the whole `FieldValue`.
+- A `Variant` read accepts only a value that a VARIANT can hold. A column that
+  holds an ENUM, a MAP, a UNION, an ARRAY, a TUPLE, a STRUCT that is not in the
+  form of a VARIANT object (each field of the type VARIANT, the keys in
+  ascending order), or a GEOMETRY with a CRS, at any depth, raises the error of
+  an incompatible column. Earlier versions wrapped the value, which DuckDB's cast
+  to VARIANT changes. A type that is or contains JSON, at any depth, also raises
+  that error, because DuckDB casts JSON to VARIANT by parsing the text.
+- Preserve the previous set of bindings when positional or named parameter
+  validation or conversion fails.
+- Allow session variables to supply omitted named parameters. Too few named
+  parameters no longer raise `FormatError`. Too many named parameters still
+  raise it.
+- Reject duplicate named parameters with DuckDB's ASCII case rules. Keep
+  distinct non-ASCII names separate. Preserve sparse numeric parameter names
+  such as `$3` and distinguish quoted parameter names that start with
+  `$`, `:`, or `@`.
+- Resolve configuration names and aliases case-insensitively. Use DuckDB's
+  ASCII identifier rules for catalog names and top-level schemas.
+- `deleteFunction` reports the error from DuckDB. DuckDB does not permit
+  deletion of functions registered through the C API, so the call raises
+  `SQLError` for a function made with `createFunction`. Version 0.3 ignored
+  this error. A `WARNING` pragma on `deleteFunction` causes a compile-time
+  warning at each use. A build with `-Werror` must allow that warning, for
+  example with `-Wno-error=deprecations`.
+- Add the optional `quack-tests` suite for authenticated remote queries,
+  parameter binding, writes, streaming, and nanosecond timestamps.
+
 ## 0.3.0.0
 
 - Use native DuckDB 1.5.6 by default. Keep native support for DuckDB >= 1.5.3
@@ -12,8 +604,8 @@
   depth limit for acyclic values.
 - Add `Variant`, a `FieldValue` that binds as a VARIANT, and `variantObject`,
   which builds an object payload. Scalars keep their native type. Object
-  parameters reject duplicate, empty, and NUL-containing keys because the
-  native constructors cannot represent all of these names.
+  parameters reject duplicate and NUL-containing keys, and objects with only
+  an empty key, because the native constructors cannot represent these names.
   `Variant` has no `ToDuckValue` instance, and `logicalTypeFromRep` raises an
   error for VARIANT.
 - A VARIANT timestamp payload outside the microsecond range binds as a
diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -1,597 +1,1767 @@
 # duckdb-simple
 
-`duckdb-simple` provides a high-level Haskell interface to DuckDB inspired by
-the APIs of [`sqlite-simple`](https://hackage.haskell.org/package/sqlite-simple) and
-[`postgresql-simple`](https://hackage.haskell.org/package/postgresql-simple).
-It builds on the low-level bindings exposed by [`duckdb-ffi`](../duckdb-ffi) and
-provides a focused API for opening connections, running queries, binding
-parameters, and decoding typed results—including the full set of DuckDB scalar
-types (signed/unsigned integers, decimals, hugeints, intervals, precise and
-timezone-aware temporals, blobs, enums, bit strings, and bignums).
-
-## Getting Started
-
-```haskell
-{-# LANGUAGE OverloadedStrings #-}
-
-import Database.DuckDB.Simple
-import Database.DuckDB.Simple.Types (Only (..))
-
-main :: IO ()
-main =
-  withConnection ":memory:" \conn -> do
-    _ <- execute_ conn "CREATE TABLE items (id INTEGER, name TEXT)"
-    _ <- execute conn "INSERT INTO items VALUES (?, ?)" (1 :: Int, "banana" :: String)
-    rows <- query_ conn "SELECT id, name FROM items ORDER BY id"
-    mapM_ print (rows :: [(Int, String)])
-```
-
-### Key Modules
-
-- `Database.DuckDB.Simple` – connections, prepared statements, execution,
-  queries, metadata, and error handling.
-- `Database.DuckDB.Simple.ToField` / `ToRow` – typeclasses and helpers for
-  preparing positional or named parameters.
-- `Database.DuckDB.Simple.FromField` / `FromRow` – typeclasses for decoding
-  query results, with generic deriving support for product types.
-- `Database.DuckDB.Simple.Generic` – automatic encoding/decoding of Haskell
-  ADTs as DuckDB STRUCTs and UNIONs via GHC generics and the `ViaDuckDB`
-  deriving-via helper.
-- `Database.DuckDB.Simple.LogicalRep` – structured value types (`StructValue`,
-  `UnionValue`) for working with DuckDB's composite types.
-- `Database.DuckDB.Simple.Types` – shared types (`Query`, `Null`, `Only`,
-  `(:.)`, `SQLError`).
-- `Database.DuckDB.Simple.Function` – register scalar Haskell functions that
-  can be invoked directly from SQL.
-
-## Querying Data
-
-```haskell
-import Database.DuckDB.Simple
-import Database.DuckDB.Simple.Types (Only (..))
-
-fetchNames :: Connection -> IO [Maybe String]
-fetchNames conn = do
-  _ <- execute_ conn "CREATE TABLE names (value TEXT)"
-  _ <- executeMany conn "INSERT INTO names VALUES (?)"
-    [Only (Just "Alice"), Only (Nothing :: Maybe String)]
-  fmap fromOnly <$> query_ conn "SELECT value FROM names ORDER BY value IS NULL, value"
-```
-
-The execution helpers return the number of affected rows (`Int`) so callers can
-assert on data changes when needed.
-
-## Named Parameters
-
-duckdb-simple supports both positional (`?`) and named parameters. Named
-parameters are bound with the `(:=)` helper exported from
-`Database.DuckDB.Simple.ToField`.
-
-```haskell
-import Database.DuckDB.Simple
-import Database.DuckDB.Simple.ToField (NamedParam ((:=)))
-
-insertNamed :: Connection -> IO Int
-insertNamed conn =
-  executeNamed conn
-    "INSERT INTO events VALUES ($kind, $payload)"
-    ["$kind" := ("metric" :: String), "$payload" := ("ok" :: String)]
-```
-
-DuckDB does not allow mixing positional and named placeholders within the same
-SQL statement; the library preserves DuckDB’s error message in that situation.
-DuckDB does not support savepoints. This library does not provide `withSavepoint`.
-
-If the number of supplied parameters does not match the statement’s declared
-placeholders—or if you attempt to bind named arguments to a positional-only
-statement—`duckdb-simple` raises a `FormatError` before executing the query.
-
-### Decoding rows
-
-`FromRow` is powered by a `RowParser`, which means instances can be written in a
-monadic/Applicative style and even derived generically for product types:
-
-```haskell
-{-# LANGUAGE DeriveAnyClass #-}
-{-# LANGUAGE DeriveGeneric #-}
-
-import Database.DuckDB.Simple
-import GHC.Generics (Generic)
-
-data Person = Person
-  { personId :: Int
-  , personName :: Text
-  }
-  deriving stock (Show, Generic)
-  deriving anyclass (FromRow)
-
-fetchPeople :: Connection -> IO [Person]
-fetchPeople conn = query_ conn "SELECT id, name FROM person ORDER BY id"
-```
-
-Helper combinators such as `field`, `fieldWith`, and `numFieldsRemaining` are
-available when a custom instance needs fine-grained control.
-
-## Generic Encoding with ViaDuckDB
-
-The `Database.DuckDB.Simple.Generic` module provides automatic encoding and
-decoding of Haskell algebraic data types as DuckDB STRUCTs and UNIONs via
-GHC generics.
-
-### Product Types as STRUCTs
-
-Product types (records) are automatically encoded as DuckDB STRUCT values:
-
-```haskell
-{-# LANGUAGE DeriveGeneric #-}
-{-# LANGUAGE DerivingVia #-}
-
-import Data.Int (Int64)
-import Data.Text (Text)
-import Database.DuckDB.Simple
-import Database.DuckDB.Simple.Generic (ViaDuckDB (..))
-import GHC.Generics (Generic)
-
-data User = User
-  { userId :: Int64
-  , userName :: Text
-  }
-  deriving stock (Eq, Show, Generic)
-  deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB User)
-
--- Round-trip through the database
-storeAndFetchUser :: Connection -> User -> IO [User]
-storeAndFetchUser conn user = do
-  _ <- execute_ conn "CREATE TABLE users (data STRUCT(userId BIGINT, userName TEXT))"
-  _ <- execute conn "INSERT INTO users VALUES (?)" (Only user)
-  fmap fromOnly <$> query_ conn "SELECT data FROM users"
-```
-
-### Sum Types as UNIONs
-
-Sum types are encoded as DuckDB UNION values, with each constructor becoming a
-union member:
-
-```haskell
-data Shape
-  = Circle Double
-  | Rectangle Double Double
-  | Point
-  deriving stock (Eq, Show, Generic)
-  deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB Shape)
-
--- Store and retrieve shape data
-storeShape :: Connection -> Shape -> IO [Shape]
-storeShape conn shape = do
-  _ <- execute_ conn
-    "CREATE TABLE shapes (s UNION(Circle STRUCT(field1 DOUBLE), \
-    \Rectangle STRUCT(field1 DOUBLE, field2 DOUBLE), Point STRUCT()))"
-  _ <- execute conn "INSERT INTO shapes VALUES (?)" (Only shape)
-  fmap fromOnly <$> query_ conn "SELECT s FROM shapes"
-```
-
-Nullary constructors (like `Point`) are encoded with a null payload.
-Non-record constructors use positional field names (`field1`, `field2`, etc.).
-
-### Arrays and Lists
-
-DuckDB arrays (fixed-length) and lists (variable-length) are also supported:
-
-```haskell
-import Data.Array (Array, listArray)
-
-storeArray :: Connection -> IO [Array Int Int]
-storeArray conn = do
-  _ <- execute_ conn "CREATE TABLE arrays (vals INTEGER[3])"
-  let arr = listArray (0, 2) [1, 2, 3] :: Array Int Int
-  _ <- execute conn "INSERT INTO arrays VALUES (?)" (Only arr)
-  fmap fromOnly <$> query_ conn "SELECT vals FROM arrays"
-
-storeList :: Connection -> IO [[Int]]
-storeList conn = do
-  _ <- execute_ conn "CREATE TABLE lists (vals INTEGER[])"
-  let arr = listArray (0, 2) [1, 2, 3] :: Array Int Int
-  _ <- execute conn "INSERT INTO lists VALUES (?)" (Only arr)
-  fmap fromOnly <$> query_ conn "SELECT vals FROM lists"
-```
-
-A Haskell list reads a LIST result. Lists have no parameter instance, so bind
-an `Array`. DuckDB casts the array to the LIST column type.
-
-An array parameter with scalar elements takes its element type from the
-column type name of the element, so an empty array keeps its type. An array
-of STRUCT values, UNION values, generic records, or arrays takes the type of
-its first element that is not NULL. All other non-NULL elements must have the
-same type, including field names, decimal precision and scale, and nested
-types. Different types raise an error before DuckDB can cast away fields or
-round values. An empty or all-NULL array of such elements raises an error.
-
-### Infinite dates and timestamps
-
-Use `Database.DuckDB.Simple.Time` when a column can contain temporal infinity.
-Its `Date`, `LocalTimestamp`, and `UTCTimestamp` types wrap `Day`, `LocalTime`,
-and `UTCTime` in `Unbounded`: `NegInfinity`, `Finite value`, or `PosInfinity`.
-These types support parameters, results, and fields in generic composites.
-`UTCTimestamp` binds as TIMESTAMPTZ.
-
-```haskell
-import Database.DuckDB.Simple.Time
-
-infiniteDates :: Connection -> IO [Only Date]
-infiniteDates conn = query conn "SELECT ?::DATE" (Only (PosInfinity :: Date))
-```
-
-The ordinary `Day`, `LocalTime`, and `UTCTime` instances reject infinity with
-a conversion error. Use `Maybe Date` to distinguish SQL NULL from infinity.
-Floating-point NaN and infinities remain valid `Float` and `Double` values.
-
-### Manual STRUCT and UNION Handling
-
-Temporal fields retain their SQL units when composite values are rebound.
-The `FieldDate`, `FieldTimestamp`, and `FieldTimestampTZ` constructors hold
-`Unbounded` values. Wrap finite payloads in `Finite` when constructing them.
-For TIMESTAMP_S or TIMESTAMP_MS values outside the TIMESTAMP range, use an
-explicit parameter cast, such as `SELECT ?::STRUCT(value TIMESTAMP_S)`.
-DuckDB otherwise attempts to convert these parameters to microseconds.
-
-For more control, you can work directly with `StructValue` and `UnionValue`
-from `Database.DuckDB.Simple.LogicalRep`:
-
-```haskell
-import Database.DuckDB.Simple.LogicalRep (StructValue (..), UnionValue (..))
-import Database.DuckDB.Simple.FromField (FieldValue (..))
-
-manualStruct :: Connection -> IO [(StructValue FieldValue, UnionValue FieldValue)]
-manualStruct conn = do
-  _ <- execute_ conn
-    "CREATE TABLE composite (s STRUCT(a INT, b INT), \
-    \u UNION(x INT, y VARCHAR))"
-  [(s, u)] <- query_ conn
-    "SELECT {'a': 1, 'b': 2}, \
-    \CAST(union_value(x := 42) AS UNION(x INT, y VARCHAR))"
-    :: IO [(StructValue FieldValue, UnionValue FieldValue)]
-  _ <- execute conn "INSERT INTO composite VALUES (?, ?)" (s, u)
-  query_ conn "SELECT s, u FROM composite"
-```
-
-### Resource Management
-
-- `withConnection` and `withStatement` wrap the open/close lifecycle and guard
-  against exceptions; use them whenever possible to avoid leaking C handles.
-- All intermediate DuckDB objects (results, prepared statements, values) are
-  released immediately after use. Query helpers return a Haskell list of all
-  rows. Folds and cursors decode rows incrementally, while DuckDB retains the
-  materialized native result until it is exhausted, reset, or closed.
-- `execute`/`query` variants reset statement bindings each run so prepared
-  statements can be reused safely.
-
-For concurrent workers, use a separate connection per worker. A connection
-can move between threads or be shared when the application serializes access.
-Hold that lock for the whole transaction or cursor lifetime, including `close`.
-DuckDB serializes native query calls, but this does not protect the Haskell
-handle state or prevent another call from interfering with an active cursor.
-Statements and connections do not provide their own lock. A callback must not
-execute another query on its active connection or close that connection.
-
-Link your executable with `ghc-options: -threaded` to allow prompt cancellation
-of native queries, including Ctrl-C. On cancellation, the library interrupts
-DuckDB and waits for the native call to return before it releases resources
-and propagates the exception. Cancellation is cooperative: native code and
-Haskell callbacks must return before cleanup can finish.
-
-Close or reset an abandoned statement to release its result. DuckDB can retain
-native result buffers until that result is destroyed.
-Use `withStatement` for manual iteration. `fold` releases the result after
-success or an exception. The accumulator determines Haskell memory use.
-
-### Metadata helpers
-
-- `columnCount` and `columnName` expose prepared-statement metadata so you can
-  inspect result shapes before executing a query.
-- `execute` returns the number of affected rows. Use SQL `RETURNING` clauses
-  when you need generated identifiers.
-### Cursors and folds
-
-`fold`, `fold_`, and `foldNamed` decode one row at a time from DuckDB's result
-chunks. DuckDB 1.5 materializes the native result before the first row is
-returned. These functions avoid a complete Haskell row list, but native memory
-use still depends on the result size. The native API for starting a streaming
-result is deprecated; the default interface uses the supported execution API.
-
-```haskell
-import Database.DuckDB.Simple.Types (Only (..))
-
-sumValues :: Connection -> IO Int
-sumValues conn =
-  fold_ conn "SELECT n FROM stream_fold ORDER BY n" 0 $ \acc (Only n) ->
-    pure (acc + n)
-```
-
-For manual cursor-style iteration, use `nextRow`/`nextRowWith` on an open
-`Statement` to pull rows one at a time and decide when to stop.
-
-Cursors support the same column types as eager queries, including STRUCT
-and UNION values with nested collections and NULLs. VARIANT and GEOMETRY
-work with eager queries, cursors, and folds.
-
-#### Optional native streaming
-
-`Database.DuckDB.Simple.Deprecated.Streaming` provides `fold`, `fold_`,
-`foldNamed`, `nextRow`, and `nextRowWith` with native streaming enabled.
-Import it qualified:
-
-```haskell
-import qualified Database.DuckDB.Simple.Deprecated.Streaming as Streaming
-
-streamSum :: Connection -> IO Int
-streamSum conn =
-  Streaming.fold_ conn "SELECT i FROM range(1000000) t(i)" 0 $ \acc (Only n) ->
-    pure (acc + n)
-```
-
-The import emits a deprecation warning because DuckDB has deprecated the
-execution entry point. DuckDB can still materialize some queries. Streaming
-does not bound the memory used by query operators.
-
-The first cursor fetch selects the execution mode until an explicit reset.
-Switching between default and streaming `nextRow` calls retains that mode.
-Keep the connection dedicated to the active stream; another query on that
-connection can invalidate it. Cancellation interrupts native chunk fetching
-as well as execution.
-
-This module also provides `foldArrow` and `foldArrow_` for streaming Arrow
-batches. They use the same supported Arrow conversion and scoped ownership
-as `Database.DuckDB.Simple.Arrow`.
-
-### Arrow batches
-
-`Database.DuckDB.Simple.Arrow` provides `foldArrow` and `foldArrow_` for clients
-that consume the Arrow C Data Interface. Each callback receives a separate
-schema and array batch. It can read them or pass them to an Arrow consumer
-that releases or moves them. The fold releases any remaining contents on
-success, failure, or cancellation. The consumer owns any contents it moves.
-
-The original pointers are valid only during the callback. To retain contents,
-a consumer must move the root structs into its own storage and set the source
-release fields to NULL. Moved contents remain valid after the query and
-connection close. Empty results do not produce a callback.
-
-For example, the `dataframe-arrow-bridge` package can copy each batch into a
-Haskell `DataFrame` and release the Arrow objects:
-
-```haskell
-import qualified DataFrame.IO.Arrow as DataFrame
-import qualified Database.DuckDB.Simple.Arrow as Arrow
-import Foreign.Ptr (castPtr)
-
-frames <- Arrow.foldArrow_ conn "SELECT id::BIGINT, name::VARCHAR FROM people" [] $ \acc schema array -> do
-  frame <- DataFrame.arrowToDataframe (castPtr schema) (castPtr array)
-  pure (frame : acc)
--- Reverse frames to recover the query's batch order.
-```
-
-The bridge currently imports signed 32-bit and 64-bit integers, Float, Double,
-and text columns. It is a test dependency of this repository; applications
-that use it must declare their own dependency on `dataframe-arrow-bridge`.
-
-Arrow export uses DuckDB's schema and chunk conversion API. DuckDB materializes
-the native result before callbacks start, so its memory use depends on the
-result size. The older Arrow query and scan bindings remain available through
-`Database.DuckDB.FFI.Deprecated` and emit deprecation warnings.
-
-### VARIANT
-
-A VARIANT result decodes to the `FieldValue` of the stored value, with its
-native type. The usual `FromField` instances read VARIANT columns, for example
-as `Int64`, `Text`, `[a]`, or a generic record. Arrays decode to `FieldList`.
-Objects decode to `FieldStruct` values whose fields have the VARIANT type, in
-entry order. `variantObject` builds such a payload from a list of entries.
-SQL NULL decodes to `FieldNull`.
-
-`Variant` from `Database.DuckDB.Simple.Variant` wraps a `FieldValue`. Its
-`FromField` instance reads any column. Its `ToField` instance binds the
-payload as a VARIANT, so `SELECT ?` returns a VARIANT:
-
-```haskell
-query conn "SELECT ?" (Only (Variant (FieldList [FieldInt8 1, FieldText "two"])))
-```
-
-A scalar payload keeps its native type, such as `TINYINT` or `DECIMAL(4,2)`.
-Time and timestamp payloads bind as microsecond types, or as nanosecond types
-when they have sub-microsecond digits. So a `TIMESTAMP_S` result binds back as
-a `TIMESTAMP` when its value fits. Wider timestamp values use milliseconds or
-seconds without losing digits. Lists, arrays, and STRUCT fields bind as
-VARIANT values. MAP and ENUM payloads raise an error. Object parameters reject
-duplicate keys, empty keys, and keys that contain NUL. You can also bind a
-plain value and cast it in SQL, as in `?::VARIANT`.
-
-The C API cannot create a usable VARIANT type
-([#27](https://github.com/Tritlo/duckdb-haskell/issues/27)). Each connection
-reads the VARIANT type the first time a parameter needs it, and its
-parameters use that type. The connection reads the type with a query on a
-separate connection. So the query does not run in your transaction, and it
-does not end a streaming result.
-`Variant` has no `ToDuckValue` instance, and `logicalTypeFromRep` raises an
-error for VARIANT, because neither has a connection.
-
-A GEOMETRY payload decodes to `FieldGeometry` with raw WKB and no CRS. Import
-these bytes with `ST_GeomFromWKB(?)::VARIANT`. A `Variant` parameter that
-contains `FieldGeometry` raises an error, also inside arrays and objects. A
-TIMETZ payload with an offset in seconds raises an error, as a TIMETZ column
-does. Results can contain empty or NUL object keys. Text and blob payloads can
-contain NUL.
-
-DuckDB 1.5 has no C API for reading VARIANT values. The decoder checks the
-native version and physical schema before it reads the internal representation.
-It checks payload bounds and rejects unknown tags. This format dependency is
-limited to the supported DuckDB 1.5 line.
-
-Persistent VARIANT columns require storage format `v1.5.0` or later. For a new
-database, pass `[("storage_compatibility_version", "v1.5.0")]` to
-`openWithConfig` or `withConnectionWithConfig`. The library does not change an
-existing database's storage compatibility setting.
-
-### GEOMETRY
-
-Use `Geometry` from `Data.Geometry` for decoded shapes. The `geometry-simple`
-package supplies the type and unboxed coordinate vectors. `duckdb-simple`
-supplies its parameter and result instances:
-
-```haskell
-import qualified Data.Geometry as G
-import qualified Data.Vector.Unboxed as U
-import Database.DuckDB.Simple
-
-let line = G.LineString (G.CoordinatesXY (U.fromList [G.XY 0 0, G.XY 1 2, G.XY 3 4]))
-rows <- query conn "SELECT ?" (Only line) :: IO [Only G.Geometry]
-```
-
-Points and coordinate sequences store their XY, XYZ, XYM, or XYZM layout.
-`G.EmptyPoint G.DimXYZ` is an empty XYZ point. Use `Maybe G.Geometry` for SQL NULL.
-Use `decodeWKT` from `Data.Geometry.WKT` to parse text without a database.
-
-`G.Geometry` has no CRS metadata. Reading it returns the coordinates without
-their CRS label. Binding it creates a `GEOMETRY` with no CRS. To attach a label,
-use `ST_SetCRS(?, ?)` with a shape and CRS text. This does not transform coordinates.
-
-Use `RawGeometry` from `Database.DuckDB.Simple.Geometry` to read WKB and CRS
-without decoding coordinates. Its `rawGeometryWKB` and `rawGeometryCRS` fields
-own their data. They remain usable after the connection closes. Existing
-`ByteString` result decoding also returns WKB.
-
-`RawGeometry` has no `ToField` instance. Import its bytes explicitly:
-
-```haskell
-import Database.DuckDB.Simple.Geometry
-
-[Only raw] <- query_ conn "SELECT 'POINT Z (1 2 3)'::GEOMETRY('OGC:CRS84')"
-rows <- (case rawGeometryCRS raw of
-    Nothing -> query conn
-        "SELECT system.main.ST_GeomFromWKB(?)"
-        (Only (rawGeometryWKB raw))
-    Just crs -> query conn
-        "SELECT system.main.ST_SetCRS(system.main.ST_GeomFromWKB(?), ?)"
-        (rawGeometryWKB raw, crs)
-    ) :: IO [Only RawGeometry]
-```
-
-Use `Nothing` for no CRS and omit `ST_SetCRS` in that case. Passing SQL NULL
-to `ST_SetCRS` returns a NULL geometry. CRS text can contain `OGC:CRS84`,
-a custom name, or a full WKT2/PROJJSON definition. DuckDB can reduce a known
-CRS definition to its registered identifier. It can also normalize WKB byte
-order. The qualified function names select DuckDB's built-ins even if a user
-macro has the same name.
-
-`fromRawGeometry` decodes the shape and drops CRS metadata. `toRawGeometry`
-encodes a shape with no CRS. These helpers follow the geometry-simple contracts.
-NaN in both WKB point X and Y denotes an empty point. Empty multi-geometries
-and collections have no stored layout tag in the decoded representation.
-Keep the raw bytes when these details must survive.
-
-Structured parameters use `encodeWKT` and DuckDB's native cast. DuckDB 1.5
-has no WKB value constructor in its C API. The WKT writer combines layouts
-in multi-geometries and polygon rings. It fills absent Z or M with NaN.
-DuckDB's WKT parser limits nesting to 16 levels and rejects empty polygon rings
-and mixed collection layouts. Explicit WKB import preserves mixed member
-layouts and native NaN payload bits that WKT cannot retain.
-
-`FieldGeometry` contains a raw result. Generic STRUCT and UNION parameters
-that contain non-NULL raw geometry raise an error. Construct those values in
-SQL with explicit WKB import. Their result decoding retains WKB and CRS,
-including inside LIST, ARRAY, MAP, STRUCT, and UNION values.
-
-`LogicalTypeGeometry` describes CRS metadata. The C API cannot create a
-GEOMETRY type with a CRS. So each connection reads a GEOMETRY type for each
-CRS in a list, together with the VARIANT type, the first time a parameter
-needs one of them. The default list holds
-`OGC:CRS84`. Composite parameters use these types, so typed NULLs, empty
-collections, and inactive UNION members keep their CRS. Set the list in
-`ConnectionOptions`:
-
-```haskell
-let options = defaultConnectionOptions{connectionGeometryCRS = ["OGC:CRS84", "EPSG:3857"]}
-withConnectionWithOptions "shapes.duckdb" options \conn -> ...
-```
-
-A list entry can be an identifier, a custom name, or a full WKT2 or PROJJSON
-definition. A composite parameter with a CRS that is not in the list binds its
-geometry members without a CRS. `logicalTypeFromRep` has no connection, so it
-creates `GEOMETRY` without a CRS. To apply a CRS in these cases, insert the
-value into a column with that CRS, or cast it in SQL:
-
-```haskell
-query conn "SELECT ?::UNION(number BIGINT, shape GEOMETRY('OGC:CRS84'))" (Only value)
-```
-
-The CRS in a cast must be a constant. DuckDB rejects a parameter as a type
-modifier, so `?::GEOMETRY(?)` is not valid. To use a CRS that is known only at
-run time, write it into the query text as a SQL string literal, and double each
-single quote. A cast accepts a CRS that DuckDB recognizes, such as `OGC:CRS84`,
-or a full WKT2 or PROJJSON definition. Unless an extension recognizes it,
-DuckDB rejects other identifiers, such as `EPSG:4326`, and custom names.
-`ST_SetCRS` also accepts custom names, but it returns `GEOMETRY` with no CRS
-for a NULL input.
-
-A bound composite without a CRS also changes the type of expressions that
-combine it with CRS data. `UNION ALL` and `COALESCE` of `GEOMETRY` and
-`GEOMETRY('OGC:CRS84')` give `GEOMETRY` with no CRS for all rows. Cast the
-parameter before you combine it with other values.
-
-See [geometry-simple](https://github.com/Tritlo/geometry-simple) for the seven
-supported families, construction checks, and codec normalization rules.
-
-### Feature Coverage
-
-- Connections, prepared statements, positional/named parameter binding.
-- High-level execution (`execute*`) and eager queries (`query*`, `queryNamed`).
-- Cursor and fold helpers (`fold`, `foldNamed`, `fold_`, `nextRow`) that decode
-  native result chunks one row at a time.
-- Comprehensive scalar type support: signed/unsigned integers, HUGEINT/UHUGEINT,
-  decimals (with width/scale), intervals, precise and timezone-aware temporals,
-  enums, bit strings, blobs, bignums, and UUIDs.
-- Composite types: STRUCTs, UNIONs, LISTs, fixed-length ARRAYs, and MAPs with
-  typed parameters and results.
-- Generic encoding/decoding: automatic STRUCT/UNION mapping for Haskell ADTs via
-  GHC generics and the `ViaDuckDB` deriving-via helper.
-- Row decoding via `FromField`/`FromRow`, with generic deriving for product types.
-- User-defined scalar functions backed by Haskell functions (including IO and
-  nullable arguments).
-- Transaction helpers (`withTransaction`) and metadata accessors (`columnCount`,
-  `columnName`).
-
-## User-Defined Functions
-
-Scalar Haskell functions can be registered with DuckDB connections and used in
-SQL expressions. Argument and result types reuse the existing `FromField` and
-`FunctionResult` machinery, so `Maybe` values and `IO` actions work out of the
-box.
-
-```haskell
-import Data.Int (Int64)
-import Database.DuckDB.Simple
-import Database.DuckDB.Simple.Function (createFunction, deleteFunction)
-import Database.DuckDB.Simple.Types (Only (..))
-
-registerAndUse :: Connection -> IO [Only Int64]
-registerAndUse conn = do
-  createFunction conn "hs_times_two" (\(x :: Int64) -> x * 2)
-  result <- query_ conn "SELECT hs_times_two(21)" :: IO [Only Int64]
-  deleteFunction conn "hs_times_two"
-  pure result
-```
-
-Exceptions raised while the function executes are propagated back to DuckDB as
-`SQLError` values, and `deleteFunction` issues a `DROP FUNCTION IF EXISTS`
-statement to remove the registration. DuckDB registers C API scalar functions
-as internal entries; attempting to drop them this way will yield an error, which
-the library surfaces as an `SQLError`.
-
-## Tests
-
-The test suite is built with [tasty](https://hackage.haskell.org/package/tasty)
-and covers connection management, statement lifecycle, parameter binding, and
-query execution.
-
-```
-cabal test duckdb-simple-test --test-show-details=direct
-```
+`duckdb-simple` is a Haskell interface to DuckDB. Its API is like the APIs of
+[`sqlite-simple`](https://hackage.haskell.org/package/sqlite-simple) and
+[`postgresql-simple`](https://hackage.haskell.org/package/postgresql-simple).
+It uses the [`duckdb-ffi`](https://hackage.haskell.org/package/duckdb-ffi) bindings.
+It opens connections, runs queries, binds parameters, and decodes results into
+Haskell types. It supports DuckDB scalar types, for example signed and unsigned integers,
+decimals, HUGEINT and UHUGEINT, intervals, dates, times, and timestamps of each
+precision and with a time zone, blobs, enums, bit strings, and bignums.
+
+The backend uses the generated DuckDB V2 API. Upstream marks the complete V2
+API as unstable: "The C API v2 is not yet stable. Its interface may change in
+upcoming releases." This release therefore requires exactly DuckDB 2.0.0.
+Creating an environment raises `SQLError` for another library version.
+
+The examples use the `OverloadedStrings` extension for `Query` and `Text`
+literals.
+
+## Shared environments and instances
+
+Use an explicit instance when several connections must share catalogs and
+configuration. Each connection has at most one open native result. Use a
+separate connection for each concurrent worker.
+Wait for child creation and all worker operations to finish before calling
+`closeInstance` or `closeEnvironment`. Closing a parent also closes its children.
+
+```haskell
+withEnvironment $ \environment ->
+  withInstance environment [("threads", "2")] $ \instance_ -> do
+    attachDatabase instance_ ":memory:" "shared" []
+    setDefaultDatabase instance_ "shared"
+    withConnectionOn instance_ $ \writer -> do
+      execute_ writer "CREATE TABLE items(id BIGINT)"
+      execute writer "INSERT INTO items VALUES (?)" (Only (42 :: Int))
+    withConnectionOn instance_ $ \reader ->
+      query_ reader "SELECT id FROM items" :: IO [Only Int]
+```
+
+Closing an environment closes its instances, connections, and statements.
+DuckDB can keep an instance alive that `createInstance` did not create. In
+that case, `closeEnvironment` raises an `SQLError` and keeps the environment open.
+Closing an instance closes its connections and statements. Each close operation
+is idempotent. `open` and `withConnection` continue to create private parents.
+
+## V2 facilities
+
+- `Config` lists options with effective values, typed defaults, aliases, and
+  supported scopes. It reads and writes typed values and registers custom
+  options. The update function of a custom option gets the new value as a
+  `FieldValue`. `V2.Config` registers custom options with native builders.
+- `Catalog.describeTable` copies resolved names, column types, default flags,
+  generated-column flags, and catalog read-only status. A column type keeps the
+  alias of DuckDB at each depth as a `LogicalTypeAlias`, for example JSON and
+  the name of a type from `registerCustomType`. A column of a type from
+  `CREATE TYPE name AS base` has the base type, and an ENUM from `CREATE TYPE`
+  has no name.
+- `V2.LogicalRep.logicalTypeToRep factory logical` copies a native logical type
+  into a pure `LogicalTypeRep`. Keep the factory valid throughout the
+  conversion. The function does not destroy the logical type handle.
+- `Tokenizer.tokenize` returns token kinds, UTF-8 byte offsets, token bytes, and
+  the native indication of an unterminated final token.
+- `Function` registers scalar, aggregate, and table functions with
+  Haskell values. `Registration` registers custom types and replacement scans,
+  and has the type and parameter declarations. See
+  [Typed registration](#typed-registration).
+- `V2.Registration` supports scalar, aggregate, table, cast, and custom-type
+  registration, replacement scans, function properties, and parameter kinds,
+  names, and defaults. Haskell callbacks use typed V2 info handles. The library
+  retains their function pointers and contains callback exceptions. The advanced
+  extension builders accept a borrowed native extension handle and context.
+  Scalar type resolution runs before binding. Table callbacks can report
+  multi-file column identifiers and metadata after binding.
+- `Copy` registers COPY formats and multi-file table functions with Haskell
+  values. `V2.Copy` has the native COPY callbacks, with batch transfer, flush,
+  statistics, progress, and multi-file setup.
+- `FileSystem` supports sequential and positioned reads and writes, file size,
+  position, seek, sync, path tests, expansion, globbing, movement, and removal.
+- `Logging` registers native log sinks with managed write and flush callbacks.
+  It copies timestamps, severity, scope, and available context identifiers.
+  Callbacks can run concurrently. They must not log or change logging settings.
+  `V2.Logging` writes a message through the context of a native callback.
+- `Pragma` registers query and execution callbacks. A callback gets the
+  arguments of the call as a `FromRow` row. `V2.Pragma` has the callbacks that
+  get native handles.
+- `Extension` has the typed registrations for a loadable extension. It also
+  registers scalar and table macros during extension initialization. The
+  native macro builder has no connection target; use SQL `CREATE MACRO` on a
+  connection. `V2.Registration.registerMacroFunctionWith` gives the native
+  macro builder to a configuration action.
+- `V2.FunctionDocs` sets descriptions, examples, and categories on function
+  builders.
+- `QueryMetrics` enables profiling and copies query and operator metric trees.
+- `Internal.withCollectionStatement` binds native column collections as named
+  table inputs for one scoped prepared-statement action. The caller retains the
+  collections.
+
+The pinned V2 API does not expose custom file-system registration or collation
+lookup. DuckDB 2.0 rejects an ARRAY type with zero elements. An empty LIST is
+valid. The direct `query_` and `execute_` paths support statements that expand
+during parsing, including dynamic PIVOT. Prepared dynamic PIVOT supports
+repeated execution with a changing schema. It does not support parameters or a
+cacheable plan. Read its schema after execution starts. VARIANT decoding uses
+SQL metadata and native casts on a helper connection. An unknown custom
+GEOMETRY CRS label uses a helper SQL query when a parameter needs its type.
+GEOMETRY results use a native cast to BLOB. Native GEOMETRY collections require
+the same Z/M dimensions on every member, including empty members. The standalone WKB codec
+retains mixed layouts.
+
+## Getting started
+
+```haskell
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+import Database.DuckDB.Simple
+
+main :: IO ()
+main =
+  withConnection ":memory:" \conn -> do
+    _ <- execute_ conn "CREATE TABLE items (id INTEGER, name TEXT)"
+    _ <- execute conn "INSERT INTO items VALUES (?, ?)" (1 :: Int, "banana" :: String)
+    rows <- query_ conn "SELECT id, name FROM items ORDER BY id"
+    mapM_ print (rows :: [(Int, String)])
+```
+
+### Key modules
+
+- `Database.DuckDB.Simple`: connections, prepared statements, execution,
+  queries, metadata, and error handling.
+- `Database.DuckDB.Simple.ToField` / `ToRow`: typeclasses and helpers for
+  preparing positional or named parameters.
+- `Database.DuckDB.Simple.FromField` / `FromRow`: typeclasses for decoding
+  query results, with generic deriving support for product types.
+- `Database.DuckDB.Simple.Conversion`: explicit IO and conversion errors for
+  custom decoders. `runConversion` returns `IO (Ok a)`.
+- `Database.DuckDB.Simple.Generic`: automatic encoding/decoding of Haskell
+  ADTs as DuckDB STRUCTs and UNIONs via GHC generics and the `ViaDuckDB`
+  deriving-via helper.
+- `Database.DuckDB.Simple.LogicalRep`: structured value types (`StructValue`,
+  `TupleValue`, `UnionValue`) for working with DuckDB's composite types.
+- `Database.DuckDB.Simple.Types`: shared types (`Query`, `Null`, `Only`,
+  `(:.)`, `SQLError`).
+- `Database.DuckDB.Simple.Function`: register scalar Haskell functions that
+  SQL can call, and casts, aggregate functions, and table functions.
+- `Database.DuckDB.Simple.Registration`, `Copy`, `Pragma`, and `Config`:
+  register custom types, replacement scans, COPY formats, pragmas, and custom
+  options with Haskell values.
+
+[Types](#types) lists the SQL type of each Haskell type.
+[Errors](#errors) describes the exceptions that a program can catch.
+
+## Querying data
+
+```haskell
+import Database.DuckDB.Simple
+
+fetchNames :: Connection -> IO [Maybe String]
+fetchNames conn = do
+  _ <- execute_ conn "CREATE TABLE names (value TEXT)"
+  _ <- executeMany conn "INSERT INTO names VALUES (?)"
+    [Only (Just "Alice"), Only (Nothing :: Maybe String)]
+  fmap fromOnly <$> query_ conn "SELECT value FROM names ORDER BY value IS NULL, value"
+```
+
+The execution helpers return the number of affected rows (`Int`). Callers can
+use this count to check data changes.
+
+An `Integer` or a `Natural` parameter binds as a HUGEINT, a UHUGEINT, or a
+BIGNUM value, or raises an error, depending on its size and target type:
+note 1 of [Types](#types) gives the rule.
+
+In DuckDB 2.0.0 the casts from BIGNUM to the integer types have defects: some
+fail, and some store a wrong value with no error ([issue
+41](https://github.com/Tritlo/duckdb-haskell/issues/41)). A `SizedArray` or a
+list of `Integer` or `Natural` values takes the element type of its target when
+that type is an integer type or DECIMAL, so DuckDB checks each element. A
+`BigNum` value, and a `SizedArray` or a list of `BigNum` values, still have
+these defects for an integer target. For each other target, and for a parameter
+with no known type, a `SizedArray`, a list, or a `Map` of `Integer` or `Natural`
+values takes the type that its elements give, as a scalar `Integer` and a SQL
+list literal of the HUGEINT and BIGNUM values do: `[1, 2^64]` binds as
+`HUGEINT[]`, and `[1, 2^200]` as `BIGNUM[]`. An empty list and a list of only
+NULL elements get the type `"NULL"[]`, as `[]` and `[NULL]` in SQL, because an
+`Integer` has no fixed SQL type. The rule follows the column type name BIGNUM,
+so an all-NULL list of `BigNum` values with no target also gets `"NULL"[]`.
+
+An `IntervalValue` binds as an INTERVAL, and DuckDB keeps its months, days, and
+microseconds. DuckDB compares intervals with 30 days for each month, so
+`INTERVAL 30 DAY = INTERVAL 1 MONTH`. A `TimeWithZone` binds as a TIMETZ with
+its time and its offset in seconds east of UTC (`timeWithZoneOffsetSeconds`).
+`timeWithZone` makes a value from a `Data.Time` `TimeZone`, and
+`timeWithZoneZone` gives the zone of a value, with the seconds of its offset
+dropped. DuckDB stores an offset from -15:59:59 to +15:59:59, that is from
+-57599 to 57599 seconds, and a value reads back equal to the bound value. A time
+with digits below one microsecond loses these digits, as in SQL text. A
+`DecimalValue` binds as a DECIMAL with its own width and scale. DuckDB casts it
+to the type of its target: a smaller scale rounds half away from zero, and a
+value that the target cannot hold raises an error. A `SizedArray`, a list, or a
+typed row (a row type with `TypedRow`) of `DecimalValue` does not compile: note
+14 of [Types](#types).
+
+`query_` and `execute_` parse all input statements before execution. A syntax
+error prevents every statement in that input from running. An execution error
+can leave effects from earlier statements. Use `withTransaction` when those
+effects must roll back together.
+
+## Named parameters
+
+duckdb-simple supports both positional (`?`) and named parameters. Bind a
+named parameter with `(:=)` from `Database.DuckDB.Simple`.
+
+```haskell
+import Database.DuckDB.Simple
+
+insertNamed :: Connection -> IO Int
+insertNamed conn =
+  executeNamed conn
+    "INSERT INTO events VALUES ($kind, $payload)"
+    ["$kind" := ("metric" :: String), "$payload" := ("ok" :: String)]
+```
+
+DuckDB does not allow positional and named placeholders in the same SQL
+statement. The library preserves DuckDB's error message in that case.
+DuckDB does not support savepoints. This library does not provide `withSavepoint`.
+
+Parameter names use DuckDB's ASCII case rules. For example, `$amount` and
+`$AMOUNT` refer to the same parameter. Supplying both raises a `FormatError`.
+Non-ASCII characters retain their case. Session variables
+can supply omitted named parameters. DuckDB rejects an omitted parameter
+that has no variable value.
+
+`duckdb-simple` raises a `FormatError` before it executes the query in these
+cases:
+
+- The number of positional parameters is not the number of placeholders.
+- You bind positional parameters to a statement with named placeholders.
+- You supply more named parameters than the statement declares.
+- You supply a name that the statement does not declare.
+- You supply one parameter two times, for example as `$amount` and `$AMOUNT`.
+- You bind named parameters to a statement with only positional placeholders.
+
+`bind` and `bindNamed` reset the statement cursor before validation. If
+validation or value conversion fails, the previous set of bindings remains.
+A successful `bindNamed` replaces the explicit bindings. Current session
+variables can supply omitted parameters when the statement executes.
+
+### Decoding rows
+
+The `fromRow` method of a `FromRow` instance is a `RowParser`. Write it with
+`Applicative` or `Monad` functions, or derive the instance with `Generic` for a
+product type:
+
+```haskell
+{-# LANGUAGE DeriveAnyClass #-}
+{-# LANGUAGE DeriveGeneric #-}
+{-# LANGUAGE DerivingStrategies #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+import Data.Text (Text)
+import Database.DuckDB.Simple
+import GHC.Generics (Generic)
+
+data Person = Person
+  { personId :: Int
+  , personName :: Text
+  }
+  deriving stock (Show, Generic)
+  deriving anyclass (FromRow)
+
+fetchPeople :: Connection -> IO [Person]
+fetchPeople conn = query_ conn "SELECT id, name FROM person ORDER BY id"
+```
+
+Use `field`, `fieldWith`, and `numFieldsRemaining` for more control in a custom
+instance.
+
+A `FromField` instance reads its Haskell type's SQL type, for example BIGINT
+for `Int64`. It also reads other SQL types when it can return the value of
+DuckDB's cast. The "Reads" column and notes 3 to 5 of [Types](#types) list
+these types.
+
+Decoders return `Conversion a`. This follows the `postgresql-simple` style:
+a conversion can run IO and report conversion errors. This library's
+`runConversion` takes no connection argument. The query and callback APIs run
+conversions for you. The decoder types are:
+
+```haskell
+type FieldParser a = Field -> Conversion a
+
+fromField :: FromField a => Field -> Conversion a
+parseRow :: RowParser a -> [Field] -> Conversion a
+runConversion :: Conversion a -> IO (Ok a)
+```
+
+For example, `runConversion (fromField field :: Conversion Int64)` returns
+`Ok value` or `Errors errors` in IO. Import the runner from
+`Database.DuckDB.Simple.Conversion` and the result constructors from
+`Database.DuckDB.Simple.Ok`. Use `liftConversion` to run IO inside a custom
+decoder. IO exceptions, including cancellation, propagate to the caller.
+Sequential and applicative conversions stop at the first conversion failure.
+`Alternative` tries the second branch if the first fails. If both fail, it
+combines their diagnostics.
+
+A decoder for a registered function's arguments runs inside its callback.
+Do not run another query on that callback's connection from the decoder. Use
+another connection. See [User-defined functions](#user-defined-functions)
+for the connection rules.
+`fieldType` reads its scoped logical type without taking the connection lock.
+
+`fieldType :: Field -> Conversion LogicalTypeRep` reads the SQL type of a
+column, or of an element, key, or value in a LIST, ARRAY, or MAP. It preserves
+aliases such as JSON. A query result or callback owns the native metadata.
+The library converts a column's type to `LogicalTypeRep` when a decoder
+requests `fieldType` and caches a successful result within that scope. This
+metadata action does no tree traversal or ENUM dictionary copy until requested.
+Structured value readers can also build type trees to decode their values.
+If cancellation interrupts a metadata read while the scope remains open,
+another call can retry it. The cache does not store exceptions.
+
+Native metadata is available while a query parser runs. A cursor retains its
+metadata until exhaustion, reset, or statement closure. Callback metadata is
+available during that callback invocation. An escaped native `fieldType`
+action raises `SQLError` with the message
+`duckdb-simple: field type scope is closed`, including when its result was
+cached before closure. Read a pure
+`LogicalTypeRep` snapshot inside the scope if you need the type later.
+Snapshots remain usable after the statement, connection, instance, and
+environment close.
+
+Metadata scopes release their native types when they close. They use no
+metadata finalizers. Existing statement and connection finalizers are
+unchanged. `Field` has no `Eq` or `Show` instance. A value in a VARIANT has the
+type VARIANT, and so does a `Field` made from a `FieldValue` alone. In those
+cases, the stored value determines the type. `logicalTypeSQL` gives the SQL
+type text, for example DECIMAL(18,3). A custom decoder can check the type:
+
+```haskell
+newtype Cents = Cents DecimalValue
+
+instance FromField Cents where
+  fromField field = do
+    logical <- fieldType field
+    case logical of
+      LogicalTypeDecimal _ 2 -> Cents <$> fromField field
+      _ -> returnError Incompatible field "expected a DECIMAL with the scale 2"
+```
+
+A field of a `ViaDuckDB` record reads with its type when its `DuckValue`
+instance sets `duckFromTypedField = typedFromField`. The library's instances
+do this. Generic decoders have these types:
+
+```haskell
+duckFromField :: DuckValue a => FieldValue -> Conversion a
+duckFromTypedField :: DuckValue a => LogicalTypeRep -> FieldValue -> Conversion a
+typedFromField :: FromField a => LogicalTypeRep -> FieldValue -> Conversion a
+genericFromFieldValue :: (Generic a, GFromField (Rep a)) => FieldValue -> Conversion a
+```
+
+Encoding and logical type declarations remain pure.
+
+## Types
+
+Each row gives a Haskell type and these facts:
+
+- Binds as: the SQL type of a parameter of this type.
+- Declared: the SQL type that a typed registration declares, if it differs
+  from "Binds as". This applies to columns and parameters of
+  `createTableFunction`, and arguments and results of `createAggregate` and
+  `createFunction`. "none" means that the type has no declaration.
+  `registerCopyFromFunction` declares no type. The COPY FROM table supplies the
+  column types. The row type must have the same number of columns. DuckDB casts
+  each row value to its column's type.
+- Reads: the SQL types that the `FromField` instance reads.
+- Function: the use of the type in `createFunction`, as an argument, a result,
+  or both. See the paragraph after the notes.
+
+| Haskell type | Binds as | Declared | Reads | Function |
+| --- | --- | --- | --- | --- |
+| `Bool` | BOOLEAN | | BOOLEAN, TINYINT to BIGINT (2) | argument, result |
+| `Int8`, `Int16`, `Int32`, `Int64`, `Int` | TINYINT, SMALLINT, INTEGER, BIGINT, BIGINT | | TINYINT to BIGINT, HUGEINT, UHUGEINT (3) | argument, result |
+| `Word8`, `Word16`, `Word32`, `Word64`, `Word` | UTINYINT, USMALLINT, UINTEGER, UBIGINT, UBIGINT | | each integer type (3) | argument, result |
+| `Integer` | HUGEINT (1) | | each integer type, BIGNUM (3) | argument, result |
+| `Natural` | HUGEINT (1) | UHUGEINT (10) | each integer type, BIGNUM (3) | argument, result |
+| `BigNum` | BIGNUM | | BIGNUM | argument, result |
+| `Double` | DOUBLE | | DOUBLE, FLOAT, TINYINT to BIGINT, DECIMAL (4) | argument, result |
+| `Float` | FLOAT | | as `Double` (4) | argument, result |
+| `DecimalValue` | DECIMAL of the value | none (14) | DECIMAL | none |
+| `Text`, `String` | VARCHAR | | VARCHAR, TINYINT to BIGINT, BOOLEAN, ENUM (5) | argument, result |
+| `ByteString` | BLOB | | BLOB, BIT, GEOMETRY (5) | argument, result |
+| `BitString` | BIT | | BIT | argument, result |
+| `UUID` | UUID | | UUID, VARCHAR (5) | argument, result |
+| `Day`, `Unbounded Day` | DATE (7) | | DATE, each timestamp type (6) | argument, result |
+| `TimeOfDay` | TIME (7) | | TIME, TIME_NS, each timestamp type (6) | argument, result |
+| `LocalTime`, `Unbounded LocalTime` | TIMESTAMP (7) | | each timestamp type (6), DATE (5) | argument, result |
+| `UTCTime`, `Unbounded UTCTime` | TIMESTAMPTZ (7) | | TIMESTAMPTZ, TIMESTAMPTZ_NS (5) | argument, result |
+| `TimeWithZone` | TIMETZ | | TIMETZ | argument, result |
+| `IntervalValue` | INTERVAL | | INTERVAL | argument, result |
+| `[a]` | LIST | | LIST, ARRAY | argument, result |
+| `SizedArray n a` | ARRAY of size `n` (8) | | ARRAY, LIST (8) | argument, result |
+| `Map k v` | MAP | | MAP | argument, result |
+| `StructValue FieldValue` | STRUCT (9) | none | STRUCT | none |
+| `TupleValue FieldValue` | TUPLE (9) | none | TUPLE | none |
+| `UnionValue FieldValue` | UNION (9) | none | UNION | none |
+| `ViaDuckDB a` | STRUCT or UNION (10) | | STRUCT or UNION | argument, result |
+| `Maybe a` | as `a`, or NULL | as `a` | NULL, or as `a` | as `a` |
+| `G.Geometry` | GEOMETRY without a CRS | | GEOMETRY | argument, result |
+| `RawGeometry` | GEOMETRY with its CRS | none (14) | GEOMETRY | none |
+| `Variant` | VARIANT | | VARIANT, and the values that a VARIANT can hold (13) | argument, result |
+| `FieldValue` | the type of its constructor (11) | none | each type | none |
+| `Null` | `"NULL"` (12) | | NULL | argument, result (12) |
+
+Notes:
+
+1. A value from -2^127 to 2^127 - 1 binds as a HUGEINT. DuckDB then checks that
+   the value fits its target: for example, a negative value for an unsigned
+   column raises an error. A value outside that range binds as a UHUGEINT for a
+   UHUGEINT parameter that can hold it. It binds as a BIGNUM for a parameter
+   that has no integer or DECIMAL type. For each other integer or DECIMAL
+   parameter, it raises an `SQLError` of the type `ErrorTypeConversion`. Bind a
+   `BigNum` to bind a BIGNUM value in each case. [Querying Data](#querying-data)
+   gives the defects of the casts from BIGNUM in DuckDB 2.0.0, and the rule for
+   a list, a `SizedArray`, or a `Map` of `Integer` values.
+2. The value 0 reads as `False`, and each other value reads as `True`.
+3. "Each integer type" is TINYINT to UHUGEINT. A value that the Haskell type
+   cannot hold raises a library conversion error: an `SQLError` with no type.
+   This includes a negative value for an unsigned type or for `Natural`. An ENUM
+   value does not read as an integer type. Write `enum_code(c)::BIGINT` in SQL
+   for its index, or `c::INTEGER` for the value of its label.
+4. A read returns the value of DuckDB's `c::DOUBLE` or `c::FLOAT` cast. This
+   includes a DECIMAL, and a BIGINT read as `Float`. As seen in CI, the DuckDB
+   2.0.0 build for macOS on Apple Silicon rounds some BIGINT values above 2^53 two
+   times in its cast to FLOAT, and the library gives the nearest value there. A
+   finite value that `Float` cannot hold raises a conversion error of the
+   library, an `SQLError` with no type.
+5. A read of another SQL type returns the value of DuckDB's cast to the Haskell
+   type's SQL type, or an error if the value does not fit. For
+   example, `Int8` reads a BIGINT that fits in a TINYINT, and `Double` reads a
+   DECIMAL with the value of `c::DOUBLE`. Thus `Text` reads a BOOLEAN as `true`
+   or `false`, and `Text` and `String` read an ENUM as its label, the text of
+   `c::VARCHAR`; a `FieldEnum` holds the index and the label. `ByteString` reads
+   a BIT or a GEOMETRY as the bytes of `c::BLOB`. `UUID` reads a VARCHAR in the
+   form `a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11`, and another form that the cast
+   reads, for example with braces, raises an error. A read that needs the
+   TimeZone setting of the session, or another text than the cast gives, raises
+   the error of an incompatible column. For each such read, write the SQL in the
+   parentheses in place of the column `c` (note 3 gives the SQL for an ENUM read
+   as an integer type):
+   - `Text` from FLOAT or DOUBLE (`c::VARCHAR`).
+   - `ByteString` from VARCHAR (`encode(c)`).
+   - `LocalTime` from TIMESTAMPTZ or TIMESTAMPTZ_NS (`c AT TIME ZONE 'UTC'`).
+   - `UTCTime` from DATE, TIMESTAMP_S, TIMESTAMP_MS, or TIMESTAMP
+     (`c::TIMESTAMP AT TIME ZONE 'UTC'`), and from TIMESTAMP_NS
+     (`c AT TIME ZONE 'UTC'`).
+
+   The `Unbounded` forms of `LocalTime` and `UTCTime` follow the same rule. The
+   Haddock of each `FromField` instance gives the SQL types that it reads.
+6. "Each timestamp type" is TIMESTAMP_S, TIMESTAMP_MS, TIMESTAMP, and
+   TIMESTAMP_NS. TIMESTAMP alone is the type with microseconds. `Day` reads the
+   date of a timestamp, and `TimeOfDay` reads its time. A nanosecond type keeps
+   its nanoseconds. An infinite value raises a conversion error of the library,
+   an `SQLError` with no type, for `Day`, `TimeOfDay`, `LocalTime`, and
+   `UTCTime`. The `Unbounded` forms read it. Use `Maybe Date` to distinguish SQL
+   NULL from infinity. `Date`, `LocalTimestamp`, and `UTCTimestamp` from
+   `Database.DuckDB.Simple.Time` are the `Unbounded` forms.
+7. A value with digits below a microsecond keeps them for a nanosecond
+   parameter, and as a scalar value that fits the range of the nanosecond type
+   for a `VARIANT` parameter: [Infinite dates and
+   timestamps](#infinite-dates-and-timestamps) gives the rule. The range of
+   `Day` is 5877642-06-25 (BC), the year -5877641 of `Data.Time`, to
+   5881580-07-10. The range of `LocalTime` and `UTCTime` is 290309-12-22 (BC)
+   00:00:00 to 294247-01-10 04:00:54.775806. A value outside its range raises an
+   `SQLError` of the type `ErrorTypeConversion`. A target of the type
+   TIMESTAMP_NS or TIMESTAMPTZ_NS has a smaller range, about the years 1677 to
+   2262, and a value outside it gets the same type in each position. A
+   `TimeOfDay` with 60 seconds binds as the next second, as `make_time` of
+   DuckDB gives it: 23:59:60 binds as 24:00:00. A later time, for example
+   23:59:60.5, and a field outside its own range, for example 61 minutes, raise
+   an `SQLError` of the type `ErrorTypeConversion`. [Infinite dates and
+   timestamps](#infinite-dates-and-timestamps) gives the full rule.
+8. A DuckDB ARRAY type has a size, for example `BIGINT[3]`. A `SizedArray n a`
+   is the Haskell type of that ARRAY: an `Array Int a` of exactly `n` values,
+   with the bounds `(0, n - 1)`. `sizedArray` makes one from an `Array` with
+   any bounds and gives `Nothing` for an `Array` of another count. The value
+   has the elements in their order, and `sizedArrayToArray` gives its `Array`.
+   `sizedArrayFromList` makes one from a list, and `toList` gives the values.
+   A `SizedArray`
+   binds as an ARRAY of size `n`, and a typed registration declares that type
+   in each position, also as a field of a record through `ViaDuckDB`. It reads
+   an ARRAY and a LIST of `n` elements, as the cast of DuckDB to the ARRAY
+   does. A query that reads a value of another length raises an `SQLError`.
+   Its message names the column type, the `SizedArray` type, and the length.
+   In a typed registration, DuckDB rejects an ARRAY of another size when it
+   binds the call. It casts a LIST of the same length to the ARRAY with no
+   error, by its own implicit cast, and a LIST of another length raises an
+   `SQLError` when the statement runs. Use one type for each need:
+   - An ARRAY of a fixed size: a `SizedArray n a`.
+   - An ARRAY of a size that varies: a list. A list reads an ARRAY of each
+     size, and DuckDB casts a bound list to an ARRAY column of the same
+     length.
+   - An ARRAY value that the program builds at run time: a `FieldArray`.
+
+   A DuckDB ARRAY has 1 to 100000 elements. A `SizedArray` or a `FieldArray`
+   parameter with no element or with more than 100000 elements raises an
+   `SQLError` of the type `ErrorInputInvalid`, and a typed registration raises
+   the same error for a `SizedArray` of such a size. Bind an empty list for an
+   empty LIST.
+9. A STRUCT, TUPLE, or UNION parameter binds with the types of its own fields
+   or members. These types keep an alias, so a value that a query reads from a
+   `STRUCT(k JSON)` column binds as `STRUCT(k JSON)`. These values have no
+   static field types, so a typed registration with such a type raises an
+   error. Use a record with `ViaDuckDB`.
+10. A record binds as a STRUCT, and a sum type binds as a UNION. A typed
+    registration declares the STRUCT or UNION type of a record or a sum type
+    that derives `DuckDBColumnType` and `ToDuckValue` via `ViaDuckDB`, also in a
+    list or a MAP. Each field type comes from `DuckValue`. An `Integer` declares
+    HUGEINT and a `Natural` declares UHUGEINT, as a field, a column of a typed
+    row, an argument, and a result. A value that this type cannot hold raises an
+    `SQLError` of the type `ErrorTypeConversion`: use `BigNum`, which declares
+    BIGNUM, for a larger value. DuckDB computes with these types: HUGEINT
+    arithmetic stays HUGEINT and raises an error on overflow. DuckDB casts a
+    non-negative integer literal to a UHUGEINT argument, but no signed column or
+    typed value without an explicit cast. `sum()` over a UHUGEINT column gives a
+    DOUBLE value, and so do UHUGEINT + INTEGER and HUGEINT + UHUGEINT for
+    columns and typed values. A `SizedArray` field declares the ARRAY of its
+    size (see note 8). A `duckLogicalType`
+    that gives a `LogicalTypeAlias`, for example
+    `LogicalTypeAlias "JSON" (LogicalTypeScalar LogicalTypeIdVarchar)`, declares
+    that alias type in a typed registration and in a parameter, and a value of
+    the field reads as its base type. See
+    [Generic Encoding with ViaDuckDB](#generic-encoding-with-viaduckdb).
+11. Each constructor binds as its SQL type, with these exceptions:
+    - A `FieldEnum` binds its label as a VARCHAR.
+    - A `FieldTimestamp` binds as TIMESTAMP, also when it came from another
+      timestamp type. [Infinite dates and
+      timestamps](#infinite-dates-and-timestamps) gives the rule for digits
+      below a microsecond.
+    - An empty `FieldArray` raises an `SQLError` of the type
+      `ErrorInputInvalid`, because a DuckDB ARRAY has at least one element.
+    - An empty `FieldList` or `FieldMap`, and a `FieldList`, a `FieldArray`, or
+      a `FieldMap` with only `FieldNull` elements, bind as the SQL list literal
+      does: they take the element type of a parameter with a known type. For a
+      parameter with no known type, `[]` and `[NULL, NULL]` have the type
+      `"NULL"[]`, and `MAP {}` has the type `MAP("NULL", "NULL")`.
+
+    See [FieldValue parameters](#fieldvalue-parameters).
+12. `typeof` gives `"NULL"`, with the quotes, for a `Null` parameter and for a
+    `Null` declaration. A `Null` argument takes only a NULL value. A call with
+    another value is a Binder Error. A record cannot have a `Null` field.
+13. A `Variant` reads a value that a VARIANT can hold: a VARIANT column, or a
+    column of another type with the same shape. That is a value of each scalar
+    type other than ENUM, for example an INTEGER or a GEOMETRY with no CRS, a
+    LIST of such values, and a STRUCT in the form of a VARIANT object: each
+    field of the type VARIANT, the keys in ascending order. At each depth, it
+    refuses an ENUM, an ARRAY, a MAP, a TUPLE, a UNION, another STRUCT, and a
+    GEOMETRY with a CRS, with the error of an incompatible column, because the
+    cast of DuckDB to VARIANT changes these values. Write `c::VARIANT` in SQL to
+    read such a column. It also refuses a type that is or contains JSON, at
+    each depth, because DuckDB casts JSON to VARIANT by parsing the text: the
+    error says `DuckDB casts JSON to VARIANT by parsing the text; write
+    c::VARIANT`, and `c::VARIANT` gives the parsed value.
+14. `DecimalValue` and `RawGeometry` have no `DuckDBColumnType` and no
+    `ToDuckValue` instance, so a `SizedArray`, a list, or a typed row of either
+    does not compile: GHC reports
+    `No instance for 'DuckDBColumnType DecimalValue'` (or `RawGeometry`), or the
+    same for `ToDuckValue` in a typed row. One column type cannot give the width
+    and scale of each `DecimalValue`. A declared GEOMETRY type has no CRS, so it
+    would remove the CRS of each `RawGeometry`. A composite parameter holds a
+    `RawGeometry` as a `FieldGeometry`.
+
+A value of a VARIANT column reads as its stored value, so the row of the stored
+type applies. A value in a LIST, ARRAY, MAP, STRUCT, or UNION reads with the
+same rules, and so does a field of a `ViaDuckDB` record. A SQL type that is not
+in "Reads" raises the error of an incompatible column. See [Errors](#errors).
+
+A function registered with `createFunction` or `createAggregate` declares the "Declared" type, or
+the "Binds as" type if "Declared" is empty, for each argument and its result.
+An argument type needs `FromField` and a declaration. A result
+type needs `ToDuckValue` and a declaration. Some result types write each value
+directly into the data of the result vector: `Bool` (BOOLEAN), an integer of 8
+to 64 bits (TINYINT to BIGINT, UTINYINT to UBIGINT), `Float` (FLOAT), `Double`
+(DOUBLE), `Text` and `String` (VARCHAR), `Maybe` of one of them, and a newtype
+that derives `FunctionResult` from one of them
+(`deriving newtype (FunctionResult)`). Each other result type, for example a
+record or a list, requires a native value for each row. DuckDB uses its default
+cast to convert that value to the declared type. For example, it rounds a
+DECIMAL to the declared scale and raises an error if the value does not fit.
+
+An aggregate result encoder receives an instance factory. This factory resolves
+built-in types. DuckDB resolves the result declaration on the registration
+host, so a custom encoder can return the underlying value of a catalog type.
+See [User-Defined Functions](#user-defined-functions).
+
+## Errors
+
+A program can catch these exceptions:
+
+- `SQLError`: an error of DuckDB, an input check of the library, a failed
+  internal check of the library, or a result value that does not convert.
+- `FormatError`: parameters that do not agree with the placeholders of the
+  statement.
+- The exception of a cancellation, for example from `timeout`.
+
+A failed check of the library state, or of a vector, type, or value from
+DuckDB, raises an `SQLError` of the type `ErrorRuntimeInternal`. Such an error
+indicates a defect in the library or DuckDB, not an input error. Report it.
+Inside a callback, the statement that runs the callback fails with
+the type `ErrorInputInvalid` and the text
+`Invalid Input Error: duckdb-simple: ...`, because a callback does not pass the
+type `ErrorRuntimeInternal`; a cast gives `ErrorTypeMismatch` (see the errors of
+a callback below). Using a closed environment, instance, connection, or
+statement raises an `SQLError` with no type. A DuckDB version mismatch and
+reading callback state with the wrong type also raise untyped `SQLError`s.
+
+`SQLError` has four fields:
+
+- `sqlErrorMessage` is the text of the error. For an error of DuckDB, it is
+  the text of DuckDB, for example `Binder Error: ...`.
+- `sqlErrorType` is the error category, as `Just` an `ErrorType`. For a DuckDB
+  error, it is DuckDB's error code. The library assigns a type to an input
+  check, a lock wait, or a failed internal check.
+  `ErrorType` has one constructor for each error code of the V2 C API, for
+  example `ErrorQueryBinder` and `ErrorTypeConversion`.
+- `sqlErrorQuery` is the SQL text of the statement for an error during its
+  preparation or execution, and for a result value that does not convert. It
+  is `Nothing` for an error outside a statement, for example when a connection
+  opens. An error of a parameter value can also have `Nothing`.
+- `sqlErrorBody` is DuckDB's error text without the type prefix. It is
+  `Nothing` for a library error.
+
+An input check of the library raises an `SQLError`. A check for a value outside
+the range of its SQL type gives the type `ErrorTypeConversion`, the type of the
+Conversion Error that DuckDB gives the same value in SQL: an `Integer` that its
+parameter or its declared type cannot hold, a date or a timestamp outside the
+range of DATE or TIMESTAMP of DuckDB (note 7), a nanosecond timestamp outside
+its storage, a time of day that is not a TIME value, a TIMETZ offset outside
+-57599 to 57599 seconds, an `Integer` or `Natural` field of a record outside HUGEINT or
+UHUGEINT, a `DecimalValue` that its width cannot hold, and an ENUM label that is
+not in the dictionary of a declared ENUM type. Each other input check gives the
+type `ErrorInputInvalid`. This includes a value of the wrong shape or type, also
+where DuckDB gives another type for the same input, for example a UNION tag that
+is not a member, a leaf built from another type, a STRUCT field that does not
+match its type, or a blank GEOMETRY CRS label. Examples are a VARIANT object with two equal
+keys, a registration with an argument type that the library cannot read, and a
+DECIMAL width above 38.
+
+A statement in a callback that waits for a connection lock longer than
+`connectionCallbackLockWait` raises an `SQLError` of the type
+`ErrorResourceInUse` ([User-Defined Functions](#user-defined-functions) gives
+the rule). A statement on a connection that streams a result, for example in the
+step of a fold of `Database.DuckDB.Simple.Streaming`, also gives
+`ErrorResourceInUse`, and so does a close of an environment while an instance
+that `createInstance` did not create is alive.
+
+A result value that its Haskell type cannot read raises an `SQLError` with no
+type. The error includes the query. Its message describes the first field that
+fails:
+
+- The error of an incompatible column, for a SQL type that the instance does
+  not read: `duckdb-simple: column NAME has type TYPE but expected HASKELLTYPE`.
+  The message can end with `: ` and a detail, for example `: expected NULL`
+  for `Null`. TYPE is the type of the column in the text of DuckDB, as
+  `typeof` gives it, for example DECIMAL(18,2), TIMESTAMP_NS, TIMESTAMP WITH
+  TIME ZONE, ENUM('a', 'b'), INTEGER[], or JSON. `logicalTypeSQL` gives that
+  text. For a VARIANT column, TYPE is the type of the stored value in the same
+  text, for example DOUBLE or TIMESTAMP WITH TIME ZONE. A value that does not
+  hold its full type, for example a LIST or a STRUCT in a VARIANT, gives the
+  name of its kind: LIST or STRUCT. The library reads the diagnostic type
+  only when the conversion's failure is selected.
+  HASKELLTYPE is the type of the instance that reads, for example `Text` for
+  `String`.
+- `duckdb-simple: column NAME is NULL but expected HASKELLTYPE` for NULL in a
+  type without `Maybe`.
+- `duckdb-simple: field FIELD: ` and the error of the value for a field of a
+  `ViaDuckDB` record, for example
+  `duckdb-simple: field pairValue: a value has type DOUBLE but expected Int64`.
+- A conversion error of the library, for a value that the instance cannot
+  convert: the message of the instance, for example `integer value out of
+  bounds`.
+
+The library creates a `ResultError` for each failure and puts its text in the
+`SQLError`. It does not raise the `ResultError`. A custom `FromField` instance
+reports a failure with `returnError` and a constructor of `ResultError`.
+`returnError` defers its metadata read until the final conversion fails. If an
+`Alternative` branch succeeds, the library discards the other branch's error
+without reading its diagnostic metadata. A completed `ResultError` contains
+pure data. Its rendering and comparison perform no native IO.
+`query` and `query_` raise the error and give no rows. A fold raises it at the
+row that fails. A row type with more or fewer fields than the result has
+columns raises an `SQLError` with the text `column index N out of bounds`.
+
+An exception in a registered Haskell function, for example one registered with
+`createFunction`, fails the statement that runs the function. That statement
+raises an `SQLError`. An `SQLError` with a type keeps its type, and its text
+gets one prefix. For example, a function that runs a failing query on another
+connection fails the outer statement with `ErrorTypeConversion` and the text
+`Conversion Error: ...` of the inner query, and a check of the library in a
+result, for example a time of day after 24:00:00, keeps its type
+`ErrorTypeConversion`. A failed cast is the exception: it gives
+`ErrorTypeMismatch` (see below). Each other exception, an `SQLError` with no
+type, and an `SQLError` of one of the 16 types below give `ErrorInputInvalid`
+and the text `Invalid Input Error: ` followed by the message of the exception:
+the message of an `SQLError`, the text of a `userError`, or the
+`displayException` text of another exception. An argument that does not convert
+gives an `SQLError` of the type `ErrorInputInvalid` with a text that names the
+argument, for example
+`duckdb-simple: argument arg0 is NULL, but Int64 cannot hold NULL` for a scalar
+function. For an aggregate or a table function, the text names the function
+after the prefix, for example `duckdb-simple: tf_int: argument arg0 ...`. DuckDB
+ignores an exception of a log sink.
+
+These 16 types do not pass through a callback:
+
+- `ErrorQueryBinder`, `ErrorDatabaseCatalog`, `ErrorResourceConnection`,
+  `ErrorQueryParameterNotAllowed`, `ErrorQueryParser`,
+  `ErrorConfigurationPermission`, and `ErrorResourceInUse`. DuckDB expects these
+  types before the execution of a statement. Under the DuckDB setting
+  `SYNTACTIC_ERRORS_DO_NOT_INVALIDATE`, it does not invalidate an explicit
+  transaction after them, and a callback raises during the execution.
+- `ErrorRuntimeInternal` and `ErrorRuntimeFatal`. DuckDB can invalidate the
+  database after them.
+- `ErrorApi`, `ErrorIOFileNotFound`, `ErrorIOReadFailure`, `ErrorIOEof`,
+  `ErrorInputParameterInvalid`, `ErrorInputMetadataDeferred`, and
+  `ErrorIONetwork`. DuckDB 2.0.0 cannot raise them again with their own type.
+
+When an error of a callback fails a statement in an explicit transaction, DuckDB
+aborts that transaction, also under the setting
+`SYNTACTIC_ERRORS_DO_NOT_INVALIDATE`: [User-Defined
+Functions](#user-defined-functions) gives what this means for a `COMMIT`.
+
+An exception in the callback of `registerCast` in
+`Database.DuckDB.Simple.V2.Registration` fails the cast with an `SQLError` of
+the type `ErrorTypeMismatch`, also an `SQLError` with another type. Its message
+is `Mismatch Type Error: ` and the text of the exception. When DuckDB casts a
+constant through the cast while it binds the query, for example the INTEGER
+literal of `range(10)` with a cast from INTEGER to BIGINT, the error has the
+type `ErrorInputInvalid` and the text `Failed to cast value: ` before the text
+of the exception, and the database stays usable. The type `ErrorTypeMismatch`
+is the same for each pair of types, because of a property of DuckDB 2.0.0.
+DuckDB plans casts between some pairs of types as casts that cannot fail,
+including registered casts. Examples are casts to VARCHAR, including
+from an ENUM, a LIST, or a STRUCT, and a widening cast such as INTEGER to
+BIGINT or FLOAT to DOUBLE.
+For such a cast, DuckDB changes an error of the type `ErrorInputInvalid`,
+`ErrorInputOutOfRange`, or `ErrorTypeConversion` to an INTERNAL error. It does
+the same for an error type that it does not map, for example `ErrorApi`. An
+INTERNAL error during the execution of a query invalidates the database. Then
+each statement on each connection of the database fails until a new instance
+opens the database. An error of the type `ErrorTypeMismatch` keeps the database
+usable, and it aborts an explicit transaction. In `TRY_CAST`, DuckDB discards
+the error and keeps the rows that the callback wrote, so the callback must write
+each row, for example NULL for a failed row. `TRY(CAST(...))` raises the error,
+because `TRY` catches only the types `ErrorInputInvalid`,
+`ErrorInputOutOfRange`, and `ErrorTypeConversion`. DuckDB still plans such a
+cast as one that cannot fail, so it can run the cast for a row that another
+condition of the query excludes, for example in
+`WHERE c < 2500 AND CAST(c AS VARCHAR) <> 'x'`. In DuckDB 2.0.0, only a guard in
+a CASE expression, for example
+`CASE WHEN d <> 0 THEN CAST(c AS VARCHAR) <> 'x' ELSE false END`, kept the cast
+from the excluded rows. A cast that a program registers with the native API of
+`duckdb-ffi` also gets the INTERNAL error for such a pair and such an error
+type. A V2 cast can report the code `DUCKDB_V2_ERROR_TYPE_MISMATCH` in their
+place.
+
+An asynchronous exception, for example from `timeout` or Ctrl-C, cancels a
+running query. The library interrupts DuckDB, waits until the native call
+returns, and raises the same exception again. Catch that exception, not
+`SQLError`. See [Resource Management](#resource-management) for `-threaded`.
+
+`FormatError` has the fields `formatErrorMessage`, `formatErrorQuery`, and
+`formatErrorParams` (the parameter values as text). The library raises it
+before it executes the statement, in the cases that
+[Named Parameters](#named-parameters) lists. A `FormatError` is not an
+`SQLError`, so catch it separately.
+
+This function gives `Nothing` when the table `items` has no column `value`:
+
+```haskell
+import Control.Exception (throwIO, try)
+import Database.DuckDB.Simple
+
+countValues :: Connection -> IO (Maybe Int)
+countValues conn = do
+  result <- try (query_ conn "SELECT count(value) FROM items")
+  case result of
+    Right [Only n] -> pure (Just n)
+    Right _ -> pure Nothing
+    Left err
+      | sqlErrorType err == Just ErrorQueryBinder -> pure Nothing
+      | otherwise -> throwIO err
+```
+
+## Generic encoding with ViaDuckDB
+
+The `Database.DuckDB.Simple.Generic` module provides automatic encoding and
+decoding of Haskell algebraic data types as DuckDB STRUCTs and UNIONs via
+GHC generics.
+
+### Product types as STRUCTs
+
+The generic encoder converts product types (records) to DuckDB STRUCT values:
+
+```haskell
+{-# LANGUAGE DeriveGeneric #-}
+{-# LANGUAGE DerivingVia #-}
+
+import Data.Int (Int64)
+import Data.Text (Text)
+import Database.DuckDB.Simple
+import Database.DuckDB.Simple.Generic (ViaDuckDB (..))
+import GHC.Generics (Generic)
+
+data User = User
+  { userId :: Int64
+  , userName :: Text
+  }
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB User)
+
+-- Round-trip through the database
+storeAndFetchUser :: Connection -> User -> IO [User]
+storeAndFetchUser conn user = do
+  _ <- execute_ conn "CREATE TABLE users (data STRUCT(userId BIGINT, userName TEXT))"
+  _ <- execute conn "INSERT INTO users VALUES (?)" (Only user)
+  fmap fromOnly <$> query_ conn "SELECT data FROM users"
+```
+
+### Sum types as UNIONs
+
+The generic encoder converts sum types to DuckDB UNION values. Each constructor
+becomes a union member:
+
+```haskell
+data Shape
+  = Circle Double
+  | Rectangle Double Double
+  | Point
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB Shape)
+
+-- Store and retrieve shape data
+storeShape :: Connection -> Shape -> IO [Shape]
+storeShape conn shape = do
+  _ <- execute_ conn
+    "CREATE TABLE shapes (s UNION(Circle STRUCT(field1 DOUBLE), \
+    \Rectangle STRUCT(field1 DOUBLE, field2 DOUBLE), Point STRUCT))"
+  _ <- execute conn "INSERT INTO shapes VALUES (?)" (Only shape)
+  fmap fromOnly <$> query_ conn "SELECT s FROM shapes"
+```
+
+A constructor without fields (like `Point`) has an empty STRUCT as
+its payload. DuckDB shows this payload as `{}`, and it is not NULL.
+Non-record constructors use positional field names (`field1`, `field2`, etc.).
+
+### Arrays and lists
+
+The library supports fixed-length DuckDB arrays and variable-length lists:
+
+```haskell
+{-# LANGUAGE DataKinds #-}
+
+import Control.Monad (forM_)
+import Data.Array (listArray)
+
+storeArray :: Connection -> IO [SizedArray 3 Int]
+storeArray conn = do
+  _ <- execute_ conn "CREATE TABLE arrays (vals INTEGER[3])"
+  forM_ (sizedArray (listArray (0, 2) [1, 2, 3]) :: Maybe (SizedArray 3 Int)) $ \arr ->
+    execute conn "INSERT INTO arrays VALUES (?)" (Only arr)
+  fmap fromOnly <$> query_ conn "SELECT vals FROM arrays"
+
+storeList :: Connection -> IO [[Int]]
+storeList conn = do
+  _ <- execute_ conn "CREATE TABLE lists (vals INTEGER[])"
+  _ <- execute conn "INSERT INTO lists VALUES (?)" (Only ([1, 2, 3] :: [Int]))
+  _ <- execute conn "INSERT INTO lists VALUES (?)" (Only ([] :: [Int]))
+  fmap fromOnly <$> query_ conn "SELECT vals FROM lists"
+```
+
+A Haskell list binds as a LIST parameter and reads a LIST result. Put a list
+parameter in `Only`, because a list as a row is a row of parameters. A
+`String` stays one VARCHAR parameter. A `SizedArray` binds as an ARRAY of its
+size (note 8 of [Types](#types)). DuckDB casts a LIST or an ARRAY to the type
+of a LIST column. It casts a LIST to an ARRAY column only when the lengths are
+equal.
+
+A list or an array parameter with scalar elements takes its element type from
+the column type name (`duckdbColumnTypeFor`) of the element. Some elements take
+the element type of the target instead: `Integer`, `Natural`, and `BigNum`
+elements for an integer or DECIMAL element type, and otherwise the type of their
+values (see above), and `TimeOfDay`, `LocalTime`, and `UTCTime` elements for a
+nanosecond element type (see [Infinite dates and
+timestamps](#infinite-dates-and-timestamps)). An empty list binds as an empty
+LIST of its element type, except an empty list of `Integer` or `Natural` values
+with no integer or DECIMAL target (see above). An empty array raises an error:
+note 8 of [Types](#types).
+
+A list or an array of STRUCT values, UNION values, generic records, lists, or
+arrays gets the type that DuckDB gives a SQL list literal of the same elements.
+When the elements that are not NULL have one type, the list has that type.
+When their types are different, DuckDB uses their common type: `{'a': 1}` and
+`{'b': 2}` give `STRUCT(a INTEGER, b INTEGER)[]`, with NULL for a field that an
+element does not have. A `BIGINT` field and a `DOUBLE` field give a `DOUBLE`
+field, so `9007199254740993` becomes `9007199254740992.0`, as in SQL. Elements
+with no common type, such as `{'a': 1}` and `{'a': 'x'}`, raise the `SQLError`
+of DuckDB. The column type of an `INSERT` does not change the type of the
+list: DuckDB casts the list to the column type after it gives the list its
+type. A list or an array of such elements that are all NULL, and an empty
+list, take the element type of the parameter when the parameter has a known
+type, as for `INSERT INTO t VALUES ([])` and `([NULL, NULL])` in SQL. For a
+parameter with no known type, an empty list or a list of NULL elements gets
+the type of the SQL literal, `"NULL"[]`, and an empty `Map` of such values gets
+the type NULL for its values, as `MAP {}` does. A generic record through
+`ViaDuckDB` has a declared type, so for a parameter with no known type an
+empty list or a list of NULL records gets the STRUCT or UNION type of the
+record.
+
+A `Map` from `Data.Map` binds as a MAP parameter and reads a MAP result. The
+pairs go in ascending key order. The keys and the values follow the element
+rules of a list, and an empty `Map` binds as an empty MAP of its key and value
+types. DuckDB compares two MAP values pair by pair in their order, so
+`WHERE m = ?` finds a stored MAP only when it has the same pairs in ascending
+key order. DuckDB rejects a NULL key and two equal keys, for example two NaN
+keys of a `Map Double`. When reading a MAP, a decoder rejects keys that become
+equal after conversion. For example, the integer keys 1 and 2 both decode as
+`True` in a `Map Bool v`.
+
+### Infinite dates and timestamps
+
+Use `Database.DuckDB.Simple.Time` when a column can contain temporal infinity.
+Its `Date`, `LocalTimestamp`, and `UTCTimestamp` types wrap `Day`, `LocalTime`,
+and `UTCTime` in `Unbounded`: `NegInfinity`, `Finite value`, or `PosInfinity`.
+These types support parameters, results, and fields in generic composites.
+`UTCTimestamp` binds as TIMESTAMPTZ.
+
+```haskell
+import Database.DuckDB.Simple
+import Database.DuckDB.Simple.Time
+
+infiniteDates :: Connection -> IO [Only Date]
+infiniteDates conn = query conn "SELECT ?::DATE" (Only (PosInfinity :: Date))
+```
+
+The ordinary `Day`, `LocalTime`, and `UTCTime` instances reject infinity: note 6
+of [Types](#types). Floating-point NaN and infinities remain valid `Float` and
+`Double` values.
+
+A `TimeOfDay`, a `LocalTime`, or a `UTCTime` parameter, and an `Unbounded`
+form, keeps its digits below a microsecond for a nanosecond parameter:
+`TIME_NS`, `TIMESTAMP_NS`, or `TIMESTAMPTZ_NS`. Use an explicit cast, such as
+`SELECT ?::TIMESTAMP_NS`, or a column with that type. A `VARIANT` parameter
+also gets the nanosecond value, when the value fits the range of the nanosecond
+type, because a VARIANT holds `TIME_NS`, `TIMESTAMP_NS`, and `TIMESTAMPTZ_NS`
+values. This applies only to a scalar value: a list, a `SizedArray`, or a `Map` of
+time values for a `VARIANT` parameter binds microsecond elements, and so does
+an element of a `VARIANT[]` list or a value of a MAP with `VARIANT` values,
+because one list has one element type for all its elements. Each other
+parameter, and a parameter with no known type, gets the microsecond value: the
+digits below a microsecond are discarded, as for the SQL literal. Only a value
+with such digits reads the parameter type. An explicit cast such as
+`?::TIMESTAMP_NS` makes a nanosecond parameter. For a `TIMESTAMP` column, DuckDB
+then rounds the value to the microsecond. A plain `?` truncates the digits.
+Values inside collections, STRUCTs, MAPs, and UNIONs follow their target types.
+The library refreshes prepared metadata when it resets or
+rebinds a statement.
+One `executeMany` call reads the parameter types once. A column type that
+changes during the call does not change how its later rows bind.
+Use separate parameters when one expression requires microseconds and another
+requires nanoseconds.
+
+A date or a timestamp outside the range of DuckDB raises an `SQLError` of the
+type `ErrorTypeConversion` when it binds, also as an element of a list, a
+`SizedArray`, or a `Map`, inside a STRUCT, a TUPLE, or a UNION, and in a VARIANT.
+For a `Day`, that range is the range of DATE, from -5877641-06-25 to 5881580-07-10.
+For a `LocalTime` or a `UTCTime` (in UTC), it is the range of TIMESTAMP,
+TIMESTAMPTZ, TIMESTAMP_S, and TIMESTAMP_MS, from -290308-12-22 00:00:00 to
+294247-01-10 04:00:54.775806. The dates are in the notation of `Data.Time`. A
+TIMESTAMP_NS or TIMESTAMPTZ_NS target has a smaller range, about the years
+1677 to 2262. A value outside that range also gets the type
+`ErrorTypeConversion` in each position. The position of the value determines
+whether the library or DuckDB raises the error:
+
+- A parameter: the error of the library for a value outside the range of DuckDB,
+  and the Conversion Error of DuckDB for each other such value, for example in
+  the year 2300.
+- An element of a list, a `SizedArray`, or a `Map`: the error of the library.
+  For a value in the range of DuckDB, its text is "TIMESTAMP value out of finite
+  range".
+- A field of a STRUCT, an element of a TUPLE, or a member of a UNION: the error
+  of the library, "TIMESTAMP value out of finite range", also for a value
+  outside the range of DuckDB.
+- In each position, a `LocalTime` or a `UTCTime` (in UTC) from 2262-04-11
+  23:47:16.854775807 to 23:47:16.854775999 gets that error of the library.
+
+In the notation of `Data.Time`, the year -5877641 is 5877642 BC and the year
+-290308 is 290309 BC. The rule holds also for a finite `Unbounded` value. DuckDB
+does not accept a value outside its range: its SQL literals reject it, and a
+stored value can read as an infinity or make DuckDB raise an INTERNAL error. A
+leap second, a `TimeOfDay` with 60 seconds, binds as the next second, as
+`make_time` and `make_timestamp` of DuckDB give it. The SQL literal `'23:59:60'`
+raises an error. A time after 24:00:00, for example 23:59:60.5, and a field
+outside its own range, for example 61 minutes, raise an `SQLError` of the type
+`ErrorTypeConversion`, also as the result of a typed function or a row of a
+table function.
+
+### Manual STRUCT, TUPLE, and UNION handling
+
+SQL tuples, such as `row(42, 'text')`, decode as `TupleValue`. Read their
+positional fields in `tupleValueFields` and types in `tupleValueTypes`.
+`FieldTuple` and `LogicalTypeTuple` preserve empty tuples independently of
+empty STRUCT values. STRUCT fields retain their names in `StructValue`.
+`LogicalTypeCollatedVarchar` preserves a VARCHAR field's collation in composite
+parameters. Its comparisons use that collation after a round trip.
+
+Temporal fields retain their SQL units when composite values are rebound.
+The `FieldDate`, `FieldTimestamp`, and `FieldTimestampTZ` constructors hold
+`Unbounded` values. Wrap finite payloads in `Finite` when constructing them.
+TIMESTAMP_S and TIMESTAMP_MS fields use the finite range described in
+[Infinite dates and timestamps](#infinite-dates-and-timestamps). An explicit
+parameter cast does not extend that range.
+
+For more control, you can work directly with `StructValue` and `UnionValue`
+from `Database.DuckDB.Simple.LogicalRep`:
+
+```haskell
+import Database.DuckDB.Simple
+import Database.DuckDB.Simple.LogicalRep (StructValue (..), UnionValue (..))
+import Database.DuckDB.Simple.FromField (FieldValue (..))
+
+manualStruct :: Connection -> IO [(StructValue FieldValue, UnionValue FieldValue)]
+manualStruct conn = do
+  _ <- execute_ conn
+    "CREATE TABLE composite (s STRUCT(a INT, b INT), \
+    \u UNION(x INT, y VARCHAR))"
+  [(s, u)] <- query_ conn
+    "SELECT {'a': 1, 'b': 2}, \
+    \CAST(union_value(x := 42) AS UNION(x INT, y VARCHAR))"
+    :: IO [(StructValue FieldValue, UnionValue FieldValue)]
+  _ <- execute conn "INSERT INTO composite VALUES (?, ?)" (s, u)
+  query_ conn "SELECT s, u FROM composite"
+```
+
+Low-level `ToDuckValue.toDuckValue` takes a `ValueFactory`, which is the V2
+factory handle, and `logicalTypeFromRep` takes the same handle.
+`Database.DuckDB.Simple.V2.LogicalRep` has `logicalTypeFromRep`.
+Get the factory of a connection with `withConnectionHandle` and
+`withConnectionFactory` from `Database.DuckDB.Simple.Internal`. Keep owned
+values and logical types within the lifetime of the factory's owner.
+
+### FieldValue parameters
+
+A `FieldValue` binds as a parameter, so a row that a query reads as
+`[FieldValue]` binds back as a row. A scalar constructor binds as the DuckDB
+type of the constructor, with the parameter instance of its payload.
+`FieldStruct`, `FieldTuple`, and `FieldUnion` bind with their own types, and
+`FieldGeometry` binds with its CRS. `FieldList`, `FieldArray`, and `FieldMap`
+take the element type that their elements give, with the rule of a SQL list
+literal (see [Arrays and Lists](#arrays-and-lists)). They read the parameter
+type, so that a list read from a `TIME_NS[]` column binds back with its
+nanoseconds.
+
+TIME aliases keep their alias and exact microsecond value when they bind
+inside a composite. The library uses public vector storage because the
+default TIME-to-alias cast fails in DuckDB 2.0.0. Other aliases require native
+cast support.
+
+Some values bind with another type than the column that they came from. A
+`FieldTimestamp` binds as a `TIMESTAMP`, or as a `TIMESTAMP_NS` when it has
+digits below a microsecond and the parameter has the type `TIMESTAMP_NS` or
+`VARIANT` (see [Infinite dates and timestamps](#infinite-dates-and-timestamps)).
+The same holds for `FieldTime` and `FieldTimestampTZ`. A `FieldText` binds as a
+`VARCHAR` with no collation, also when it came from a `JSON` value. A value
+from a `VARIANT` column binds as its payload. A `FieldEnum` binds its label as
+a `VARCHAR`. `FieldNull` binds as an untyped NULL. DuckDB casts each of these
+values to the type of a column with no loss, with one exception: a time value
+with digits below a microsecond in a `FieldList` or a `FieldMap` for a
+`VARIANT` parameter gets the microsecond value, so a `VARIANT` array of
+`TIMESTAMP_NS` values loses these digits when it binds back. A `VARIANT` object
+reads as a `FieldStruct` with `VARIANT` fields and keeps them.
+
+An empty or all-NULL `FieldList`, `FieldArray`, or `FieldMap` follows note 11 of
+[Types](#types). Inside a `FieldStruct`, a `FieldTuple`, or a `FieldUnion`, a
+`FieldEnum` binds its label to the declared ENUM type, and a label that is not
+in the dictionary raises an `SQLError` of the type `ErrorTypeConversion`, as the
+cast of DuckDB gives for that label. `FieldValue` has no `DuckDBColumnType` and
+no `ToDuckValue` instance, because no one DuckDB type holds each of its values.
+
+### Resource management
+
+- `withConnection` and `withStatement` open and close resources, including when
+  an exception occurs. Use them whenever possible to avoid leaking C handles.
+- The query functions release their results, prepared statements, and values
+  after use, and return a Haskell list of all rows. Folds and cursors decode
+  rows incrementally from owned native chunks. The materialized functions of
+  `Database.DuckDB.Simple` drain and close the native result before row
+  callbacks; the streaming functions of `Database.DuckDB.Simple.Streaming` do
+  not.
+- `execute`/`query` variants reset statement bindings each run so prepared
+  statements can be reused safely.
+
+For concurrent workers, use a separate connection per worker. Threads can also
+share one connection. DuckDB permits one open result for each connection, so
+each connection has a lock. `query`, `execute`, and the materialized folds hold
+this lock from the execution of a statement until its native result closes.
+Statement preparation holds it only while DuckDB prepares the statement.
+Metadata binding holds it only while DuckDB binds the statement. A call from
+another thread waits. The lock does not cover these cases. Serialize them in
+the application:
+
+- A transaction. Statements of other threads run inside it.
+- One `Statement` that two threads use.
+- An explicit stream from `Database.DuckDB.Simple.Streaming`. Each fetch of
+  the stream holds the lock, but its result stays open between calls, and
+  another query on that connection fails until the stream is complete or
+  closed.
+- `close`. Wait for all operations on the connection before you close it.
+
+A callback must not run a statement on the connection that runs the callback,
+or close that connection: [User-Defined Functions](#user-defined-functions)
+gives the rule, its time limit, and its limits.
+
+Link your executable with `ghc-options: -threaded`. A program that registers a
+callback needs it, because DuckDB can call a callback from several threads at
+the same time: [User-Defined Functions](#user-defined-functions) gives the rule.
+It also allows prompt cancellation of native queries, including Ctrl-C. On
+cancellation, the library interrupts DuckDB and waits for the native call to
+return before it releases resources and propagates the exception. Cancellation
+is cooperative: native code and Haskell callbacks must return before cleanup can
+finish.
+
+Native work that can take a long time runs in a helper thread so that an
+asynchronous exception can interrupt it. The materialized functions run the
+native calls of one result in one helper thread. A bound thread, such as the
+main thread, changes operating system threads to wait for a helper thread.
+Thus a small query takes longer from a bound thread than from an unbound
+thread. Run code with many small queries in a thread made with `forkIO`, or
+wrap the main action in `Control.Concurrent.runInUnboundThread`.
+
+Call `closeStatement` or `clearStatementBindings` on an abandoned statement to
+release its result. DuckDB can retain native result buffers until that result
+is destroyed.
+Use `withStatement` for manual iteration. `fold` releases the result after
+success or an exception. The accumulator determines Haskell memory use.
+
+### Metadata helpers
+
+- `columnCount` and `columnName` expose prepared-statement metadata so you can
+  inspect result shapes before executing a query.
+- `execute` returns the number of affected rows. Use SQL `RETURNING` clauses
+  when you need generated identifiers.
+
+### Cursors and folds
+
+`fold`, `fold_`, and `foldNamed` decode one row at a time from DuckDB's result
+chunks. This API materializes the native result before the first row is
+returned. These functions avoid a complete Haskell row list, but native memory
+use still depends on the result size. The materialized functions close the
+native result before row delivery. A row callback can run another query on the
+same connection.
+
+```haskell
+import Database.DuckDB.Simple
+
+sumValues :: Connection -> IO Int
+sumValues conn =
+  fold_ conn "SELECT n FROM stream_fold ORDER BY n" 0 $ \acc (Only n) ->
+    pure (acc + n)
+```
+
+For manual cursor-style iteration, use `nextRow`/`nextRowWith` on an open
+`Statement` to pull rows one at a time and decide when to stop.
+
+Cursors support the same column types as the query functions, including STRUCT
+and UNION values with nested collections and NULLs. GEOMETRY and VARIANT work
+with the query functions, cursors, and folds.
+
+#### Optional native streaming
+
+`Database.DuckDB.Simple.Streaming` provides `fold`, `fold_`,
+`foldNamed`, `nextRow`, and `nextRowWith` with native streaming enabled.
+Import it qualified:
+
+```haskell
+import Database.DuckDB.Simple
+import qualified Database.DuckDB.Simple.Streaming as Streaming
+
+streamSum :: Connection -> IO Int
+streamSum conn =
+  Streaming.fold_ conn "SELECT i FROM range(1000000) t(i)" 0 $ \acc (Only n) ->
+    pure (acc + n)
+```
+
+This module uses V2 execution and incremental chunk fetching. DuckDB can still
+materialize some queries. Streaming does not bound the memory used by query
+operators.
+
+The first cursor fetch selects the execution mode. The mode stays until `bind`,
+`bindNamed`, `clearStatementBindings`, or `executeStatement` releases the
+result. Switching between materialized and streaming `nextRow` calls retains
+that mode. Keep the connection dedicated to the explicit stream. Until the
+stream is complete, DuckDB rejects other statements on that connection with the
+`ErrorResourceInUse` error of DuckDB. If you close an incomplete stream, DuckDB
+aborts its statement. In autocommit mode, DuckDB rolls back the writes of that
+statement. Cancellation interrupts native chunk fetching as well as execution.
+
+This module also provides `foldArrow` and `foldArrow_` for streaming Arrow
+batches. They use the same supported Arrow conversion and scoped ownership
+as `Database.DuckDB.Simple.Arrow`.
+
+### Arrow batches
+
+`Database.DuckDB.Simple.Arrow` provides `foldArrow` and `foldArrow_` for clients
+that consume the Arrow C Data Interface. Each callback receives a separate
+schema and array batch. It can read them or pass them to an Arrow consumer
+that releases or moves them. The fold releases any remaining contents on
+success, failure, or cancellation. The consumer owns any contents it moves.
+
+Each array has at most `connectionArrowBatchSize` rows. Set this option in
+`ConnectionOptions`. The default is `defaultArrowBatchSize`, 2048 rows. DuckDB
+can give shorter arrays. Opening a connection rejects a value that is not
+positive. For DuckDB's batch size, set 131072.
+
+The original pointers are valid only during the callback. To retain contents,
+a consumer must move the root structs into its own storage and set the source
+release fields to NULL. Moved contents remain valid after the query and
+connection close. Empty results do not produce a callback.
+
+For example, the `dataframe-arrow-bridge` package can copy each batch into a
+Haskell `DataFrame` and release the Arrow objects:
+
+```haskell
+import qualified DataFrame.IO.Arrow as DataFrame
+import qualified Database.DuckDB.Simple.Arrow as Arrow
+import Foreign.Ptr (castPtr)
+
+frames <- Arrow.foldArrow_ conn "SELECT id::BIGINT, name::VARCHAR FROM people" [] $ \acc schema array -> do
+  frame <- DataFrame.arrowToDataframe (castPtr schema) (castPtr array)
+  pure (frame : acc)
+-- Reverse frames to recover the query's batch order.
+```
+
+The bridge currently imports signed 32-bit and 64-bit integers, Float, Double,
+and text columns. It is a test dependency of this repository; applications
+that use it must declare their own dependency on `dataframe-arrow-bridge`.
+
+Arrow export uses V2 Arrow results. The materialized `foldArrow` retains owned
+batches and closes the native result before callbacks start. Its memory use
+depends on the result size. The streaming `foldArrow` delivers each batch while
+the native result remains open.
+
+### VARIANT
+
+VARIANT results decode to the `FieldValue` of the stored value. Existing
+`FromField` instances read scalar payloads. Objects decode to `FieldStruct`
+values with VARIANT fields in DuckDB's native key order (lexicographic).
+Arrays decode to `FieldList` and preserve element order.
+The decoder uses SQL type metadata and native casts. It preserves scalar types,
+precision, and nested values without reading DuckDB's private payload format.
+
+```haskell
+query_ conn "SELECT 42::BIGINT::VARIANT" :: IO [Only Int64]
+```
+
+SQL NULL VARIANT values decode to `FieldNull`. `Variant` from
+`Database.DuckDB.Simple.Variant` wraps a `FieldValue`. Its `ToField` instance
+binds the payload as VARIANT. `variantObject` builds an object from named fields.
+It can read the bound value back directly:
+
+```haskell
+query conn "SELECT ?"
+  (Only (Variant (FieldList [FieldInt64 1, FieldInt64 2])))
+  :: IO [Only Variant]
+```
+
+A scalar payload keeps its native type, such as `TINYINT` or `DECIMAL(4,2)`.
+Time and timestamp payloads bind as microsecond types, or as nanosecond types
+when they have sub-microsecond digits and fit the nanosecond range. So a
+`TIMESTAMP_S` result binds back as a `TIMESTAMP` when its value fits. Each
+element of a list payload and each field of an object payload follow the same
+rule, so one list payload can hold both types. A Haskell list, a `SizedArray`,
+or a `Map` of time values for a `VARIANT` parameter is not a payload: it binds
+microsecond elements (see [Infinite dates and
+timestamps](#infinite-dates-and-timestamps)). A value outside the range of
+DuckDB raises an `SQLError` of the type `ErrorTypeConversion`. Lists, arrays,
+and STRUCT fields bind as VARIANT values. A VARIANT does not keep a UNION, a
+MAP, an ENUM, or the CRS of a GEOMETRY, so these payloads raise an error at any
+depth: a VARIANT keeps only the member value of a UNION, stores a MAP as a list
+of key and value objects, and stores an ENUM as its text. Object parameters
+reject duplicate keys and keys that contain NUL. An object with only an empty
+key also raises an error because DuckDB treats its STRUCT type as a tuple.
+DuckDB 2.0 permits an empty key with other named keys. You can also bind a plain
+value and cast it in SQL, as in `?::VARIANT`.
+
+A `Variant` result reads only a value that a VARIANT can hold: note 13 of
+[Types](#types) gives the shapes, and the refusal of a JSON type.
+
+For query results the library uses a separate helper connection for VARIANT decoder metadata.
+It caches one prepared VARIANT metadata statement and the types for VARIANT
+casts. It batches VARIANT metadata queries. It constructs VARIANT types
+directly through the native factory. This preserves an explicit stream on the
+caller's connection. The helper connection has the settings of the database,
+not the caller's session settings. Metadata preparation needs an expression
+depth of 11. A GLOBAL `max_expression_depth` below 11 fails preparation with a
+Binder Error, including preparation for a connection's COPY TO. Extension COPY TO
+and typed callback arguments use an independent instance with default expression
+depth. A prepared plan on a query helper can remain
+usable after the limit is lowered. The query for unusual object keys still
+binds on each execution and can fail at a lower limit.
+
+New DuckDB 2.0 databases use storage format 2.0, which supports VARIANT columns.
+The library does not change an existing database's storage compatibility
+setting. VARIANT columns require storage format `v1.5.0` or later.
+
+### GEOMETRY
+
+Use `Geometry` from `Data.Geometry` for decoded shapes. The `geometry-simple`
+package supplies the type and unboxed coordinate vectors. `duckdb-simple`
+supplies its `ToField` and `FromField` instances:
+
+```haskell
+import qualified Data.Geometry as G
+import qualified Data.Vector.Unboxed as U
+import Database.DuckDB.Simple
+
+let line = G.LineString (G.CoordinatesXY (U.fromList [G.XY 0 0, G.XY 1 2, G.XY 3 4]))
+rows <- query conn "SELECT ?" (Only line) :: IO [Only G.Geometry]
+```
+
+Points and coordinate sequences store their XY, XYZ, XYM, or XYZM layout.
+`G.EmptyPoint G.DimXYZ` is an empty XYZ point. Use `Maybe G.Geometry` for SQL NULL.
+Use `decodeWKT` from `Data.Geometry.WKT` to parse text without a database.
+
+`G.Geometry` has no CRS metadata. Reading it returns the coordinates without
+their CRS label. Binding it creates a `GEOMETRY` with no CRS. To attach a label,
+use `ST_SetCRS(?, ?)` with a shape and CRS text. This does not transform coordinates.
+
+Use `RawGeometry` from `Database.DuckDB.Simple.Geometry` to read WKB and CRS
+without decoding coordinates. Its `rawGeometryWKB` and `rawGeometryCRS` fields
+own their data. They remain usable after the connection closes. Existing
+`ByteString` result decoding also returns WKB.
+
+A `RawGeometry` parameter binds as a `GEOMETRY` value with the same WKB bytes
+and its own CRS. DuckDB then casts it to the type of the parameter, as it casts
+a `GEOMETRY` value in SQL text. A value without a CRS takes the CRS of the
+target. A target without a CRS removes the CRS of the value, with no error. A
+target with another CRS raises `SQLError`. Use `Maybe RawGeometry` for SQL NULL.
+A `SizedArray`, a list, and a typed row cannot hold a `RawGeometry` (note 14 of
+[Types](#types)). A composite parameter holds it as `FieldGeometry` (see below):
+
+```haskell
+import Database.DuckDB.Simple.Geometry
+
+[Only raw] <- query_ conn "SELECT 'POINT Z (1 2 3)'::GEOMETRY('OGC:CRS84')" :: IO [Only RawGeometry]
+rows <- query conn "SELECT ?" (Only raw) :: IO [Only RawGeometry]
+```
+
+For explicit SQL import, use `system.main.ST_GeomFromWKB(?)` with the WKB
+bytes. To attach a CRS, use
+`system.main.ST_SetCRS(system.main.ST_GeomFromWKB(?), ?)` with the bytes and CRS
+text. Omit `ST_SetCRS` for no CRS: a NULL CRS argument returns NULL geometry.
+CRS text can be a recognized name, a custom label, or WKT2/PROJJSON text.
+DuckDB can normalize WKB byte order and reduce a known CRS definition to its
+registered identifier. The qualified names select the built-ins even if a
+user macro has the same name.
+
+`fromRawGeometry` decodes the shape and drops CRS metadata. `toRawGeometry`
+encodes a shape with no CRS. These helpers follow the geometry-simple contracts.
+NaN in both WKB point X and Y denotes an empty point. Empty multi-geometries
+and collections have no stored layout tag in the decoded representation.
+Keep the raw bytes when these details must survive.
+
+Structured parameters use `encodeWKT` and DuckDB's native cast. The WKT writer
+combines layouts in multi-geometries and polygon rings. It fills absent Z or M
+with NaN.
+DuckDB's WKT parser limits nesting to 16 levels and rejects empty polygon rings
+and mixed collection layouts. DuckDB 2.0 also rejects WKB with mixed Z/M member
+layouts. Explicit WKB import preserves native NaN payload bits that WKT cannot
+retain.
+
+`FieldGeometry` contains a raw result. Result decoding retains WKB and CRS,
+including inside LIST, ARRAY, MAP, STRUCT, and UNION values. A STRUCT, TUPLE,
+or UNION parameter binds each `FieldGeometry` as a `GEOMETRY` with the same
+WKB bytes and CRS, also inside LIST, ARRAY, and MAP values. Thus a value that
+a query returns binds again without a change. The CRS of the value must be
+equal to the CRS of its declared type. A mismatch raises `SQLError` with the
+type `ErrorInputInvalid`, for example for a value with the CRS `OGC:CRS84` in
+a field of type `GEOMETRY`. A `Variant` parameter binds a `FieldGeometry`
+without a CRS as a `GEOMETRY` payload. A VARIANT does not keep the CRS of a
+GEOMETRY, so a `FieldGeometry` with a CRS in a `Variant` raises `SQLError`.
+
+`LogicalTypeGeometry` describes CRS metadata. Composite parameters retain it.
+Recognized names, such as `OGC:CRS84`, and full WKT2/PROJJSON definitions use
+direct V2 type construction. For an unknown custom label, parameter binding
+reads a SQL-derived type with `ST_SetCRS` on a helper connection. This happens
+on demand, including for nested types, typed NULLs, empty collections, and
+inactive UNION members. Binding the same custom label again repeats the lookup.
+A blank label or a label with NUL raises `SQLError` at bind time.
+
+Query results retain a custom CRS label. Typed registrations and direct
+low-level `logicalTypeFromRep` calls use native type construction. They require
+a recognized name or a full definition. A custom label in a declared argument,
+result, cast source or target, pragma parameter, or table-function column fails
+at registration. DuckDB casts a plain `GEOMETRY` argument to its declared type,
+which removes the CRS. Direct type construction raises an error if DuckDB
+drops the CRS under `ignore_unknown_crs`.
+
+The CRS in a cast must be a constant. DuckDB rejects a parameter as a type
+modifier, so `?::GEOMETRY(?)` is not valid. To use a CRS that is known only at
+run time, write it into the query text as a SQL string literal, and double each
+single quote. A cast accepts a CRS that DuckDB recognizes, such as `OGC:CRS84`,
+or a full WKT2 or PROJJSON definition. Unless an extension recognizes it,
+DuckDB rejects other identifiers, such as `EPSG:4326`, and custom names.
+`ST_SetCRS` also accepts custom names, but it returns `GEOMETRY` with no CRS
+for a NULL input.
+
+A bound composite without a CRS also changes the type of expressions that
+combine it with CRS data. `UNION ALL` and `COALESCE` of `GEOMETRY` and
+`GEOMETRY('OGC:CRS84')` give `GEOMETRY` with no CRS for all rows. Cast the
+parameter before you combine it with other values.
+
+See [geometry-simple](https://github.com/Tritlo/geometry-simple) for the seven
+supported families, construction checks, and codec normalization rules.
+
+### Feature coverage
+
+- Connections, prepared statements, positional/named parameter binding.
+- High-level execution (`execute*`) and the query functions (`query*`,
+  `queryNamed`).
+- Cursor and fold helpers (`fold`, `foldNamed`, `fold_`, `nextRow`) that decode
+  native result chunks one row at a time.
+- Scalar types: signed/unsigned integers, HUGEINT/UHUGEINT,
+  decimals (with width/scale), intervals, precise and timezone-aware temporals,
+  enums, bit strings, blobs, bignums, and UUIDs.
+- Composite types: STRUCTs, UNIONs, LISTs, fixed-length ARRAYs, and MAPs with
+  typed parameters and results.
+- Generic encoding/decoding: automatic STRUCT/UNION mapping for Haskell ADTs via
+  GHC generics and the `ViaDuckDB` deriving-via helper.
+- Row decoding via `FromField`/`FromRow`, with generic deriving for product types.
+- User-defined scalar functions backed by Haskell functions (including IO and
+  nullable arguments).
+- Aggregate functions, table functions, replacement scans, COPY formats, and
+  pragmas. See [Typed registration](#typed-registration).
+- Transaction helpers (`withTransaction`) and metadata accessors (`columnCount`,
+  `columnName`).
+
+## User-defined functions
+
+Register a scalar Haskell function on a connection, and call it in SQL
+expressions. The arguments use `FromField`, and the result uses
+`ToDuckValue`. A function can accept and return `Maybe` values, and it can
+run an `IO` action.
+
+An argument type needs `FromField` and `DuckDBColumnType` instances. Its SQL
+type is the `duckdbTypeDeclaration` of the type, as for a column of a typed row.
+A newtype with its own column type name (`duckdbColumnTypeFor`), for example
+`DECIMAL(18,3)`, gives that text. Arguments use the same conversion as query
+results, including nested values. Registered casts do not change how the
+library reads GEOMETRY arguments. See [Typed registration](#typed-registration).
+
+The SQL type of the result is the `duckdbTypeDeclaration` of the result type:
+an `Int16` result is SMALLINT, and a `Float` result is FLOAT. DuckDB computes
+with that type. Thus `hs_small(x) * hs_small(y)` of an `Int16` function raises
+an Out of Range Error when the product does not fit in SMALLINT, as
+`30000::SMALLINT * 30000::SMALLINT` does. Cast the result to a wider type
+first. Some result types write directly into the result vector. Each other
+result type requires a native value for each row. [Types](#types) lists them.
+
+```haskell
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+
+import Data.Int (Int64)
+import Database.DuckDB.Simple
+
+registerAndUse :: Connection -> IO [Only Int64]
+registerAndUse conn = do
+  createFunction conn "hs_times_two" (\(x :: Int64) -> x * 2)
+  query_ conn "SELECT hs_times_two(21)"
+```
+
+An exception in the function fails the statement with an `SQLError`:
+[Errors](#errors) gives its text. `deleteFunction` issues a
+`DROP FUNCTION IF EXISTS` statement and reports native errors. DuckDB registers
+C API scalar functions as internal entries and rejects their deletion. The
+function remains registered after this `SQLError`. Deleting an absent name
+succeeds. To replace a function, register the name again. `deleteFunction` has a
+GHC `WARNING` pragma, so each use causes a compile-time warning. A build with
+`-Werror` must allow that warning, for example with `-Wno-error=deprecations`.
+
+A program that registers a callback, for example of a scalar function, a cast,
+an aggregate function, a table function, a COPY format, a replacement scan, a
+pragma, or a log sink, must be linked with `ghc-options: -threaded`. DuckDB can
+call a callback from several of its threads at the same time. Without
+`-threaded`, the GHC runtime does not support calls from several operating
+system threads at the same time, so the program can crash.
+
+Without `-threaded`, registering a COPY format with callbacks or a log sink
+raises `ErrorInputInvalid` regardless of the settings. DuckDB can open a COPY
+file on an asynchronous worker, which can also write to the log sink.
+For other callbacks, registration raises `ErrorInputInvalid` when the DuckDB
+setting `threads` is above 1. This check only reads the setting at registration.
+It cannot prevent another connection from raising the thread count later.
+
+With `-threaded`, each call of a callback needs a capability of the GHC runtime.
+With one capability, which is the default, a callback from a second DuckDB
+thread waits until the capability is free, and the operating system switches
+threads for each such call. A query that makes many callbacks on several DuckDB
+threads is then much slower. Give the program as many capabilities as DuckDB has
+threads, for example with `ghc-options: -threaded -rtsopts "-with-rtsopts=-N"`,
+or set the DuckDB setting `threads` to 1.
+
+A callback must not run a statement on the connection that runs the callback,
+and it must not close that connection. Use another connection of the same
+instance. This rule applies to each registered callback, for example of a scalar
+function, a cast, an aggregate function, a table function, a COPY format, a
+replacement scan, a pragma, or a log sink. `query`, `execute`, the materialized
+folds, statement preparation, and each fetch of an explicit stream hold the lock
+of the connection while DuckDB runs these callbacks. The lock is not reentrant,
+so a statement in the callback waits for the lock. With more than one DuckDB
+thread, DuckDB can also run a callback of an explicit stream between two
+fetches, while no fetch holds the lock. Then a statement in the callback on the
+same connection fails at once with the `ErrorResourceInUse` error of DuckDB,
+because the stream has an open result.
+
+That wait has a time limit. `connectionCallbackLockWait` in `ConnectionOptions`
+sets it in microseconds. The default is `defaultCallbackLockWait`, 10 seconds,
+and `Nothing` sets no time limit. When the time limit ends, the statement in the
+callback raises an `SQLError` of the type `ErrorResourceInUse`, and its text
+gives the rule. If the callback does not catch the error, the outer statement
+fails with the type `ErrorInputInvalid`, because a callback does not pass the
+type `ErrorResourceInUse` ([Errors](#errors) gives the list; a cast gives
+`ErrorTypeMismatch`), and its message contains the text of that error. The
+connection can run the next statement. DuckDB ignores the error of a log sink.
+The time limit applies to each wait of a callback for the lock of a connection.
+It applies also to another connection that a different statement uses. If
+callbacks share a connection that runs slow statements, set a larger time limit
+or `Nothing` for that connection.
+
+In these cases the time limit does not apply, and a statement in the callback
+can wait indefinitely:
+
+- DuckDB runs the callback during a call that does not hold the lock of the
+  connection, for example a log sink for a message of `logConnectionMessage`.
+  Then the statement goes into DuckDB on the same connection.
+- The statement runs in a thread that the callback starts. The library marks
+  only the thread of the callback.
+- The statement runs inside `uninterruptibleMask`.
+- The statement runs in the flush function of a log sink when DuckDB destroys
+  the sink.
+
+A statement in a callback on another connection of the same instance runs in its
+own transaction, also when the outer statement runs in an explicit transaction.
+It does not see rows that the outer transaction has not committed. A write to
+a row that the outer transaction changed fails immediately with DuckDB's
+`TransactionContext Error: Conflict on update!` error. The outer statement
+fails with that text. That failure aborts the outer transaction, as each error
+during the execution of a statement does in DuckDB:
+each later statement in the transaction fails, and a `COMMIT` returns with no
+error but stores no change of the transaction.
+
+A callback that refers to a connection keeps that connection and its instance
+reachable while DuckDB keeps the callback, possibly until the database closes.
+The garbage collector cannot close them while they remain reachable. The
+program must close them.
+
+## Typed registration
+
+These functions register SQL objects with Haskell values. Their signatures have
+no native handle. `Database.DuckDB.Simple.Extension` has the same functions for
+a loadable extension. An exception in a Haskell function gives an SQL error with
+the message of the exception (see [Errors](#errors)). The examples use these
+imports:
+
+```haskell
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+
+import Data.Int (Int64)
+import Data.Text (Text)
+import qualified Data.Text as Text
+import qualified Data.Text.IO as TextIO
+import Database.DuckDB.Simple
+import Database.DuckDB.Simple.Copy
+import Database.DuckDB.Simple.FromField (Field (..), FieldValue (..))
+import Database.DuckDB.Simple.Pragma (PragmaCallback (..), registerPragmaFunction)
+import Database.DuckDB.Simple.Registration
+```
+
+The library has no typed cast in this release. A registered cast can give
+wrong rows with no error, because the optimizer of DuckDB 2.0.0 decides from
+the two types of a cast alone whether it can move the cast away from a column
+in a filter or a join. In a run, it also gave min and max from the statistics
+of the column without the cast. The cast function then does not run on that
+column, or, in a comparison of two columns, it runs on one side only. In runs
+with DuckDB 2.0.0, a cast from INTEGER to BIGINT, and a cast between BIGINT and
+a custom type with the base type BIGINT, gave wrong rows when its function
+changed the value. `registerCast` in
+`Database.DuckDB.Simple.V2.Registration` registers a native cast, and its
+Haddock gives the warning. For a conversion that changes the value, register a
+scalar function with `createFunction` (see
+[User-Defined Functions](#user-defined-functions)).
+
+A registered cast does not change a value that the library reads or binds, on
+a connection and in the callbacks of an extension. The library reads GEOMETRY
+and VARIANT values with the built-in casts, and it builds GEOMETRY, ENUM, and
+VARIANT values with the default cast of DuckDB. For example, a cast from
+GEOMETRY to BLOB changes the result of `CAST(g AS BLOB)`, but not a GEOMETRY
+value that a query gives or that a callback reads. Of the casts that the library
+performs itself, only `setConfigValue` and `setConfigOption` use registered
+casts. DuckDB casts the value to the type of the option, as SQL `SET` does.
+
+`createAggregate` registers an aggregate function as a fold. Its result needs
+`ToDuckValue` and a static `duckdbTypeDeclaration`, as a scalar function result
+does. Lists, maps, and records or sum types through `ViaDuckDB` can be results.
+A `Maybe a` result declares the type of `a`, and `Nothing` gives NULL. Types
+with no static declaration, such as `StructValue`, are errors at registration.
+See [Types](#types) for the encoding rules. Aggregates support `GROUP BY`,
+`DISTINCT`, `FILTER`, `ORDER BY`, and window functions.
+
+```haskell
+aggregateExample :: Connection -> IO [Only Int64]
+aggregateExample conn = do
+  createAggregate conn "haskell_sum" Aggregate
+    { aggregateInitial = 0 :: Int64
+    , aggregateStep = \total (Only value) -> pure (total + value)
+    , aggregateCombine = \a b -> pure (a + b)
+    , aggregateResult = pure
+    }
+  query_ conn "SELECT haskell_sum(i) FROM range(10) t(i)" -- [Only 45]
+```
+
+The library keeps the live aggregate states in a table with stripes. Two
+DuckDB threads wait for each other only when they change the same stripe.
+`connectionAggregateStripes` in `ConnectionOptions` sets the number of stripes
+for each aggregate that `createAggregate` registers through the connection.
+The default is `defaultAggregateStripes`, 64. No result depends on the number.
+
+Scalar and aggregate registrations create a private helper instance when an
+argument needs VARIANT decoding. In a loadable extension, this helper also
+supplies the factory for type metadata, GEOMETRY reads, and aggregate result
+encoders. The registration shares the instance
+across queries until the last native callback owner releases it. Each VARIANT
+vector uses a separate connection and decoder state. The helper uses
+`threads=1` and `async_threads=0`, with no background worker pool. A registration
+on a connection uses its existing instance for type metadata and GEOMETRY reads.
+
+`createTableFunction` registers a table function that gives its rows as a
+list. DuckDB reads only the columns that the query uses, also in `WHERE` and
+`ORDER BY`. For a query that uses no column, such as `SELECT count(*)`, DuckDB
+reads the first column. The library does not evaluate the other columns of a
+row, so an exception in such a column does not fail the query. The library
+evaluates each row that it writes to its constructor. This evaluates each
+strict field of the row (a field with `!`, or each field with `StrictData`).
+
+```haskell
+tableExample :: Connection -> IO [(Int64, Int64)]
+tableExample conn = do
+  createTableFunction conn "squares" ["n", "square"] \(Only count) ->
+    pure [(n, n * n) | n <- [0 .. count - 1 :: Int64]]
+  query_ conn "SELECT n, square FROM squares(3)" -- [(0, 0), (1, 1), (2, 4)]
+```
+
+The type of a column, a parameter, or an aggregate argument comes from
+`duckdbTypeDeclaration`: notes 8, 9, and 10 of [Types](#types) give the rule
+for a `SizedArray`, records, sum types, and `StructValue`, `TupleValue`, and
+`UnionValue`. Arguments use the same conversion as query results.
+
+The decoder uses SQL to inspect VARIANT values. For callback arguments it
+copies the rows into a private DuckDB instance. The helper has no access to
+the host's catalog, settings, or registered casts. A concrete SQL argument type
+avoids this work when all rows have a known type. A decoding error fails the
+calling statement under the usual callback error rules.
+
+`registerReplacementScan` gives the parts of an unknown table name to the
+function. The function can give a SELECT statement that DuckDB reads instead.
+
+```haskell
+scanExample :: Connection -> IO [Only Int64]
+scanExample conn = do
+  registerReplacementScan conn \parts ->
+    pure (if parts == ["numbers"] then Just (ReplaceWithQuery "SELECT i FROM range(3) t(i)") else Nothing)
+  query_ conn "SELECT i FROM numbers ORDER BY i" -- [Only 0, Only 1, Only 2]
+```
+
+`registerCopyFunction` registers a COPY format with a COPY TO side and a COPY
+FROM side. DuckDB keeps the first registration of a format name. Thus register
+a format with two directions in one call.
+
+```haskell
+copyExample :: Connection -> Text -> IO [Only Text]
+copyExample conn path = do
+  registerCopyFunction conn "haskell_lines" linesTo \info ->
+    map Only . Text.lines <$> TextIO.readFile (copyFromPath info)
+  _ <- execute conn "COPY (SELECT i::VARCHAR AS line FROM range(3) t(i)) TO ? (FORMAT haskell_lines)" (Only path)
+  _ <- execute_ conn "CREATE TABLE copied (line VARCHAR)"
+  _ <- execute conn "COPY copied FROM ? (FORMAT haskell_lines)" (Only path)
+  query_ conn "SELECT line FROM copied ORDER BY line" -- [Only "0", Only "1", Only "2"]
+
+linesTo :: CopyTo () FilePath
+linesTo =
+  CopyTo
+    { copyToBind = \_ -> pure ()
+    , copyToInit = \info -> TextIO.writeFile (copyInitFilePath info) "" >> pure (copyInitFilePath info)
+    , copyToSink = \info rows -> TextIO.appendFile (copySinkGlobalState info) (Text.unlines (map line rows))
+    , copyToFinalize = \_ -> pure ()
+    }
+  where
+    line [Field{fieldValue = FieldText text}] = text
+    line _ = error "haskell_lines: each row must have one VARCHAR value"
+```
+
+`registerPragmaFunction` gives the arguments of the call to the callback as a
+`FromRow` row. A `QueryPragma` callback gives SQL that DuckDB runs in place of
+the PRAGMA statement.
+
+```haskell
+pragmaExample :: Connection -> IO [Only Int64]
+pragmaExample conn = do
+  registerPragmaFunction conn "repeat_answer" [parameter "times" (TypeExpression "BIGINT")] $
+    QueryPragma \(Only (times :: Int64)) -> pure ("SELECT 42::BIGINT FROM range(" <> Text.pack (show times) <> ")")
+  query_ conn "PRAGMA repeat_answer(2)" -- [Only 42, Only 42]
+```
+
+A typed registration has more overhead for each row than raw vector access. Use
+`Database.DuckDB.Simple.V2.Registration`, `V2.Copy`, `V2.Pragma`, and
+`V2.Config` for speed, and for filter pushdown, parallel table scans, and
+scalar functions with a bind callback or variadic parameters. A typed table
+function has projection pushdown (see `createTableFunction` above), but no
+filter pushdown.
+
+## Loadable extensions
+
+`Database.DuckDB.Simple.Extension` registers the typed functions of this package
+from a loadable DuckDB extension. Build the extension with the `extension` flag
+of `duckdb-ffi` and of `duckdb-simple`. The module's Haddock describes the
+entry point, typed registrations, and resource lifetimes. See
+`dev/extensions/README.md` in this repo. CI builds and tests the example.
+
+## Tests
+
+The package has five test suites. Each suite tests the library through a
+database.
+
+- `duckdb-simple-test` is the main suite, built with
+  [tasty](https://hackage.haskell.org/package/tasty). It covers connections,
+  statements, parameters, results, streaming, Arrow batches, cancellation,
+  COPY functions, VARIANT and GEOMETRY values, typed registrations, and
+  callbacks.
+- `duckdb-simple-leak-test` counts native threads and resident memory through
+  repeated queries, failures, and cancellation.
+- `duckdb-simple-nonthreaded-test` is linked without `-threaded`. It checks the
+  error for the registration of a callback in such a program.
+- `duckdb-simple-dataframe-test` tests the Arrow export with the dataframe
+  library. It needs the flag `dataframe-tests`.
+- `duckdb-simple-quack-test` tests authenticated local Quack connections. It
+  needs the flag `quack-tests`, and the variables `DUCKDB_HTTPFS_EXTENSION` and
+  `DUCKDB_QUACK_EXTENSION` must name the extension files.
+
+```
+cabal test all --test-show-details=direct
+cabal test duckdb-simple-test --test-show-details=direct
+cabal test duckdb-simple-dataframe-test -fdataframe-tests
+```
+
+`cabal test all` runs the first three suites. The repository's CONTRIBUTING.md
+gives the rules for new tests and the variables for a test run.
diff --git a/bench/Main.hs b/bench/Main.hs
--- a/bench/Main.hs
+++ b/bench/Main.hs
@@ -1,23 +1,30 @@
+{-# LANGUAGE BangPatterns #-}
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE ScopedTypeVariables #-}
 
--- | Repeatable end-to-end benchmarks with checked results.
+-- |
+-- Module      : Main
+-- Description : Repeatable end-to-end benchmarks with checked results.
 module Main (main) where
 
 import Control.Exception (evaluate)
-import Control.Monad (forM_, replicateM, unless)
+import Control.Monad (forM_, unless)
+import Data.Array (Array, elems, listArray, (!))
 import qualified Data.ByteString as BS
+import qualified Data.Foldable as Foldable
 import qualified Data.Geometry as G
 import Data.Int (Int64)
 import qualified Data.List as List
+import qualified Data.Map.Strict as Map
 import qualified Data.Text as Text
-import Data.Time.Clock.POSIX (utcTimeToPOSIXSeconds)
+import Data.Time.Clock.POSIX (posixSecondsToUTCTime, utcTimeToPOSIXSeconds)
 import Data.Time.LocalTime (LocalTime, localTimeToUTC, utc)
 import Database.DuckDB.Simple
-import Database.DuckDB.Simple.FromField (FieldValue (..))
+import Database.DuckDB.Simple.FromField (BigNum (..), FieldValue (..), StructField (..), StructValue (..))
 import Database.DuckDB.Simple.Geometry (RawGeometry (..))
 import Database.DuckDB.Simple.Variant (Variant (..))
 import GHC.Clock (getMonotonicTimeNSec)
+import GHC.Stats (RTSStats (allocated_bytes), getRTSStats, getRTSStatsEnabled)
 import System.Environment (getArgs)
 import System.Mem (performMajorGC)
 import Text.Printf (printf)
@@ -25,76 +32,154 @@
 -- | Run one workload seven times after a warm-up run.
 main :: IO ()
 main = do
-    args <- getArgs
-    let workload = case args of name : _ -> name; _ -> "eager"
-        count = case args of _ : n : _ -> read n; _ -> 100000 :: Int64
-        expected = count * (count - 1) `div` 2
-    withConnectionWithConfig ":memory:" [("threads", "1")] $ \conn -> do
-        createFunction conn "bench_identity" (id :: Int64 -> Int64)
-        [Only geometry] <- query_ conn "SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84')" :: IO [Only RawGeometry]
-        let typedGeometry = G.PointGeometry (G.PointXY (G.XY 1 2))
-        let sql = Query ("SELECT i FROM range(" <> Text.pack (show count) <> ") t(i)")
-            action = case workload of
-                "eager" -> do
-                    rows <- query_ conn sql
-                    evaluate (List.foldl' (\acc (Only n) -> acc + n) 0 rows)
-                "fold" -> fold_ conn sql 0 (\acc (Only n) -> pure (acc + n))
-                "scalar" -> do
-                    rows <- query_ conn (Query ("SELECT bench_identity(i) FROM range(" <> Text.pack (show count) <> ") t(i)"))
-                    evaluate (List.foldl' (\acc (Only n) -> acc + n) 0 rows)
-                "text" -> do
-                    rows <- query_ conn (Query ("SELECT repeat('duckdb λ text', 4) FROM range(" <> Text.pack (show count) <> ")"))
-                    evaluate (List.foldl' (\acc (Only value) -> acc + fromIntegral (Text.length value)) 0 rows)
-                "timestamp" -> do
-                    rows <- query_ conn (Query ("SELECT TIMESTAMP '2000-01-01' + i * INTERVAL 1 SECOND FROM range(" <> Text.pack (show count) <> ") t(i)"))
-                    evaluate (List.foldl' (\acc (Only (value :: LocalTime)) -> acc + floor (utcTimeToPOSIXSeconds (localTimeToUTC utc value))) 0 rows)
-                "parameters" -> do
-                    rows <- replicateM (fromIntegral count) (query conn "SELECT ?::BIGINT" (Only (1 :: Int64)))
-                    evaluate (sum [n | [Only n] <- rows])
-                "variant" -> do
-                    rows <- query_ conn (Query ("SELECT i::VARIANT FROM range(" <> Text.pack (show count) <> ") t(i)"))
-                    evaluate (List.foldl' (\acc (Only value) -> acc + variantNumber value) 0 rows)
-                "variant-parameters" -> do
-                    rows <- replicateM (fromIntegral count) (query conn "SELECT ?" (Only (Variant (FieldInt64 1))))
-                    evaluate (sum [variantNumber value | [Only value] <- rows])
-                "geometry" -> do
-                    rows <- query_ conn (Query ("SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84') FROM range(" <> Text.pack (show count) <> ")"))
-                    evaluate (sum [fromIntegral (BS.length (rawGeometryWKB value)) | Only value <- rows])
-                "geometry-parameters" -> do
-                    rows <- replicateM (fromIntegral count) (query conn "SELECT system.main.ST_SetCRS(system.main.ST_GeomFromWKB(?), ?)" (rawGeometryWKB geometry, rawGeometryCRS geometry))
-                    evaluate (sum [fromIntegral (BS.length (rawGeometryWKB value)) | [Only value] <- rows])
-                "geometry-typed" -> do
-                    rows <- query_ conn (Query ("SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84') FROM range(" <> Text.pack (show count) <> ")"))
-                    evaluate (sum [pointChecksum value | Only value <- rows])
-                "geometry-typed-parameters" -> do
-                    rows <- replicateM (fromIntegral count) (query conn "SELECT ?" (Only typedGeometry))
-                    evaluate (sum [pointChecksum value | [Only value] <- rows])
-                _ -> fail "Expected eager, fold, scalar, text, timestamp, parameters, variant, variant-parameters, geometry, geometry-parameters, geometry-typed, or geometry-typed-parameters"
-            expectedResult = case workload of
-                "parameters" -> count
-                "variant-parameters" -> count
-                "geometry" -> count * 21
-                "geometry-parameters" -> count * 21
-                "geometry-typed" -> count * 3
-                "geometry-typed-parameters" -> count * 3
-                "text" -> count * fromIntegral (Text.length (Text.replicate 4 "duckdb λ text"))
-                "timestamp" -> count * 946684800 + expected
-                _ -> expected
-            check actual = unless (actual == expectedResult) (fail "benchmark result mismatch")
-        action >>= check
-        putStrLn "workload,rows,run,milliseconds,checksum"
-        forM_ [1 .. 7 :: Int] $ \run -> do
-            performMajorGC
-            start <- getMonotonicTimeNSec
-            result <- action
-            end <- getMonotonicTimeNSec
-            check result
-            printf "%s,%d,%d,%.3f,%d\n" workload count run (fromIntegral (end - start) / 1000000 :: Double) result
+  statsEnabled <- getRTSStatsEnabled
+  unless statsEnabled (fail "Run the benchmark with +RTS -T")
+  args <- getArgs
+  let workload = case args of name : _ -> name; _ -> "eager"
+      count = case args of _ : n : _ -> read n; _ -> 100000 :: Int64
+      expected = count * (count - 1) `div` 2
+      collectionQuery expression = Query ("SELECT " <> expression <> " FROM range(" <> Text.pack (show count) <> ") t(i)")
+      objectKeys = listArray (0, 63) ["k" <> Text.pack (show index) | index <- [0 .. 63 :: Int]]
+  withConnectionWithConfig ":memory:" [("threads", "1")] $ \conn -> do
+    createFunction conn "bench_identity" (id :: Int64 -> Int64)
+    [Only geometry] <- query_ conn "SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84')" :: IO [Only RawGeometry]
+    let typedGeometry = G.PointGeometry (G.PointXY (G.XY 1 2))
+    let sql = Query ("SELECT i FROM range(" <> Text.pack (show count) <> ") t(i)")
+        action = case workload of
+          "eager" -> do
+            rows <- query_ conn sql
+            evaluate (List.foldl' (\acc (Only n) -> acc + n) 0 rows)
+          "fold" -> fold_ conn sql 0 (\acc (Only n) -> pure (acc + n))
+          "scalar" -> do
+            rows <- query_ conn (Query ("SELECT bench_identity(i) FROM range(" <> Text.pack (show count) <> ") t(i)"))
+            evaluate (List.foldl' (\acc (Only n) -> acc + n) 0 rows)
+          "text" -> do
+            rows <- query_ conn (Query ("SELECT repeat('duckdb λ text', 4) FROM range(" <> Text.pack (show count) <> ")"))
+            evaluate (List.foldl' (\acc (Only value) -> acc + fromIntegral (Text.length value)) 0 rows)
+          "timestamp" -> do
+            rows <- query_ conn (Query ("SELECT TIMESTAMP '2000-01-01' + i * INTERVAL 1 SECOND FROM range(" <> Text.pack (show count) <> ") t(i)"))
+            evaluate (List.foldl' (\acc (Only (value :: LocalTime)) -> acc + floor (utcTimeToPOSIXSeconds (localTimeToUTC utc value))) 0 rows)
+          "parameters" -> do
+            repeatChecksum count $ do
+              [Only value] <- query conn "SELECT ?::BIGINT" (Only (1 :: Int64))
+              pure value
+          "timestamp-parameters" -> do
+            repeatChecksum count $ do
+              [Only value] <- query conn "SELECT 1::BIGINT WHERE ? IS NOT NULL" (Only (posixSecondsToUTCTime 0))
+              pure value
+          "list-bigint" -> do
+            [Only values] <- query_ conn (collectionQuery "list(i::BIGINT)") :: IO [Only [Int64]]
+            collectionChecksum count values
+          "list-bignum" -> do
+            [Only values] <- query_ conn (collectionQuery "list(i::BIGNUM)") :: IO [Only [Integer]]
+            collectionChecksum count values
+          "array-bignum" -> do
+            -- The array size comes from the command line, so read its FieldValue.
+            [Only (FieldArray values)] <-
+              query_ conn (collectionQuery ("list(i::BIGNUM)::BIGNUM[" <> Text.pack (show count) <> "]")) :: IO [Only FieldValue]
+            collectionChecksum count [value | FieldBigNum (BigNum value) <- elems values]
+          "map-bignum" -> do
+            [Only values] <- query_ conn (collectionQuery "map(list(i::BIGINT), list(i::BIGNUM))") :: IO [Only (Map.Map Int64 Integer)]
+            collectionChecksum count values
+          "variant" -> do
+            rows <- query_ conn (Query ("SELECT i::VARIANT FROM range(" <> Text.pack (show count) <> ") t(i)"))
+            evaluate (List.foldl' (\acc (Only value) -> acc + variantNumber value) 0 rows)
+          "variant-list" -> do
+            [Only (Variant value)] <- query_ conn (collectionQuery "list(i)::VARIANT")
+            case value of
+              FieldList values -> collectionChecksum count (map (variantNumber . Variant) values)
+              _ -> fail "unexpected VARIANT list benchmark shape"
+          "variant-parameters" -> do
+            repeatChecksum count $ do
+              [Only value] <- query conn "SELECT ?" (Only (Variant (FieldInt64 1)))
+              pure (variantNumber value)
+          -- Objects with 64 different key sets.
+          "variant-objects" -> do
+            rows <- query_ conn (Query ("SELECT json_object('k' || (i % 64)::VARCHAR, i)::VARIANT FROM range(" <> Text.pack (show count) <> ") t(i)"))
+            collectionChecksum count (map (\(Only value) -> variantObjectNumber objectKeys value) rows)
+          "geometry" -> do
+            rows <- query_ conn (Query ("SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84') FROM range(" <> Text.pack (show count) <> ")"))
+            evaluate (sum [fromIntegral (BS.length (rawGeometryWKB value)) | Only value <- rows])
+          "geometry-parameters" -> do
+            repeatChecksum count $ do
+              [Only value] <-
+                query conn "SELECT system.main.ST_SetCRS(system.main.ST_GeomFromWKB(?), ?)" (rawGeometryWKB geometry, rawGeometryCRS geometry)
+              pure (fromIntegral (BS.length (rawGeometryWKB value)))
+          "geometry-typed" -> do
+            rows <- query_ conn (Query ("SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84') FROM range(" <> Text.pack (show count) <> ")"))
+            evaluate (sum [pointChecksum value | Only value <- rows])
+          "geometry-typed-parameters" -> do
+            repeatChecksum count $ do
+              [Only value] <- query conn "SELECT ?" (Only typedGeometry)
+              pure (pointChecksum value)
+          _ ->
+            fail
+              "Expected eager, fold, scalar, text, timestamp, timestamp-parameters, parameters, list-bigint, list-bignum, array-bignum, map-bignum, variant, variant-list, variant-parameters, variant-objects, geometry, geometry-parameters, geometry-typed, or geometry-typed-parameters"
+        expectedResult = case workload of
+          "parameters" -> count
+          "timestamp-parameters" -> count
+          "variant-parameters" -> count
+          "geometry" -> count * 21
+          "geometry-parameters" -> count * 21
+          "geometry-typed" -> count * 3
+          "geometry-typed-parameters" -> count * 3
+          "text" -> count * fromIntegral (Text.length (Text.replicate 4 "duckdb λ text"))
+          "timestamp" -> count * 946684800 + expected
+          _ -> expected
+        check actual = unless (actual == expectedResult) (fail "benchmark result mismatch")
+    action >>= check
+    putStrLn "workload,rows,run,milliseconds,allocated_bytes,checksum"
+    forM_ [1 .. 7 :: Int] $ \run -> do
+      performMajorGC
+      before <- getRTSStats
+      start <- getMonotonicTimeNSec
+      result <- action >>= evaluate
+      end <- getMonotonicTimeNSec
+      performMajorGC
+      after <- getRTSStats
+      check result
+      printf
+        "%s,%d,%d,%.3f,%d,%d\n"
+        workload
+        count
+        run
+        (fromIntegral (end - start) / 1000000 :: Double)
+        (allocated_bytes after - allocated_bytes before)
+        result
 
--- | Fail if the VARIANT benchmark changes its scalar type.
+-- | Repeat an action and add its results with a constant stack.
+repeatChecksum :: Int64 -> IO Int64 -> IO Int64
+repeatChecksum count action = go count 0
+  where
+    go remaining !total
+      | remaining <= 0 = pure total
+      | otherwise = do
+          value <- action
+          go (remaining - 1) (total + value)
+
+-- | Check the element count and force the checksum of a collection.
+collectionChecksum :: (Foldable f, Integral a) => Int64 -> f a -> IO Int64
+collectionChecksum count values = do
+  let (!actualCount, !checksum) = Foldable.foldl' (\(!size, !total) value -> (size + 1, total + fromIntegral value)) (0, 0) values
+  unless (actualCount == count) (fail "benchmark collection size mismatch")
+  pure checksum
+
+-- | Read the integer in a scalar VARIANT.
 variantNumber :: Variant -> Int64
 variantNumber (Variant (FieldInt64 value)) = value
+variantNumber (Variant (FieldWord64 value))
+  | value <= fromIntegral (maxBound :: Int64) = fromIntegral value
 variantNumber value = error ("unexpected VARIANT benchmark value: " <> show value)
+
+-- | Check one object field and its key, then read its integer payload.
+variantObjectNumber :: Array Int Text.Text -> Variant -> Int64
+variantObjectNumber keys (Variant (FieldStruct value)) = case elems (structValueFields value) of
+  [StructField key payload]
+    | let number = variantNumber (Variant payload)
+    , key == keys ! fromIntegral (number `mod` 64) ->
+        number
+  _ -> error "unexpected VARIANT object benchmark fields"
+variantObjectNumber _ _ = error "unexpected VARIANT object benchmark shape"
 
 -- | Force coordinate decoding and check the point shape.
 pointChecksum :: G.Geometry -> Int64
diff --git a/dataframe-test/Main.hs b/dataframe-test/Main.hs
--- a/dataframe-test/Main.hs
+++ b/dataframe-test/Main.hs
@@ -1,23 +1,30 @@
 {-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE DuplicateRecordFields #-}
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE ScopedTypeVariables #-}
-{-# OPTIONS_GHC -Wno-deprecations #-}
+{-# LANGUAGE TypeApplications #-}
 
--- | Consume DuckDB Arrow batches with the dataframe library.
+-- |
+-- Module      : Main
+-- Description : Consume DuckDB Arrow batches with the dataframe library.
 module Main (main) where
 
 import Control.Exception (ErrorCall, displayException, try)
 import Control.Monad (forM_)
+import Data.Coerce (coerce)
 import Data.Int (Int64)
 import qualified Data.Text as Text
+import Data.Void (Void)
 import qualified DataFrame.Core as DataFrame
 import qualified DataFrame.IO.Arrow as DataFrameArrow
-import Database.DuckDB.FFI (ArrowArray (..), ArrowSchema (..))
+import Database.DuckDB.FFI.V2 (ArrowArray (..), ArrowSchema (..))
 import Database.DuckDB.Simple
 import qualified Database.DuckDB.Simple.Arrow as Arrow
-import qualified Database.DuckDB.Simple.Deprecated.Streaming as Streaming
+import qualified Database.DuckDB.Simple.Streaming as Streaming
 import Foreign.Ptr (Ptr, castPtr, nullFunPtr)
 import Foreign.Storable (peek)
+import GHC.Records (getField)
 import Test.Tasty (TestTree, defaultMain, testGroup)
 import Test.Tasty.HUnit
 
@@ -28,45 +35,45 @@
 -- | Check data and ownership across successful and failed imports.
 dataframeTests :: Bool -> TestTree
 dataframeTests streaming =
-    testGroup
-        (if streaming then "deprecated streaming" else "materialized")
-        [ testCase "several batches remain readable after connection close" do
-            (rowCount, batches) <- withDb \conn ->
-                foldArrow
-                    conn
-                    "SELECT i::INTEGER AS id, CASE WHEN i % 3 = 0 THEN NULL ELSE i - 2500 END AS \"íslenska_λ\", (i::FLOAT / 4)::FLOAT AS small, CASE WHEN i % 5 = 0 THEN NULL ELSE i::DOUBLE / 4 END AS real, CASE WHEN i % 7 = 0 THEN NULL WHEN i % 7 = 1 THEN '' ELSE ? || i::VARCHAR END AS label, NULL::BIGINT AS missing FROM range(?::BIGINT) t(i)"
-                    ("λ\0雪" :: Text.Text, 5000 :: Int64)
-                    (0 :: Int, [])
-                    \(offset, acc) schema array -> do
-                        assertLiveSchema schema
-                        count <- fromIntegral . arrowArrayLength <$> peek array
-                        frame <- DataFrameArrow.arrowToDataframe (castPtr schema) (castPtr array)
-                        assertConsumed schema array
-                        pure (offset + count, (offset, count, frame) : acc)
-            rowCount @?= 5000
-            assertBool "multiple native batches" (length batches > 1)
-            forM_ batches \(offset, count, frame) -> do
-                let expected = expectedFrame [offset .. offset + count - 1]
-                DataFrame.columnNames frame @?= DataFrame.columnNames expected
-                frame @?= expected
-        , testCase "an unsupported type releases the failed export" $
-            withDb \conn -> do
-                -- Import one supported column before the unsupported column fails.
-                result <- try $ foldArrow conn "SELECT 42::BIGINT AS n, true AS unsupported" () () \() schema array -> do
-                    _ <- DataFrameArrow.arrowToDataframe (castPtr schema) (castPtr array)
-                    pure ()
-                case result of
-                    Left (err :: ErrorCall) ->
-                        assertBool "DataFrame format error" ("unsupported format" `Text.isInfixOf` Text.pack (displayException err))
-                    Right () -> assertFailure "expected an unsupported Arrow type"
-                query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
-        , testCase "an empty result does not call the consumer" $
-            withDb \conn -> do
-                count <- foldArrow conn "SELECT 1::BIGINT AS n WHERE false" () (0 :: Int) \_ schema array -> do
-                    _ <- DataFrameArrow.arrowToDataframe (castPtr schema) (castPtr array)
-                    assertFailure "unexpected batch"
-                count @?= 0
-        ]
+  testGroup
+    (if streaming then "native streaming" else "materialized")
+    [ testCase "several batches remain readable after connection close" do
+        (rowCount, batches) <- withDb \conn ->
+          foldArrow
+            conn
+            "SELECT i::INTEGER AS id, CASE WHEN i % 3 = 0 THEN NULL ELSE i - 2500 END AS \"íslenska_λ\", (i::FLOAT / 4)::FLOAT AS small, CASE WHEN i % 5 = 0 THEN NULL ELSE i::DOUBLE / 4 END AS real, CASE WHEN i % 7 = 0 THEN NULL WHEN i % 7 = 1 THEN '' ELSE ? || i::VARCHAR END AS label, NULL::BIGINT AS missing FROM range(?::BIGINT) t(i)"
+            ("λ\0雪" :: Text.Text, 5000 :: Int64)
+            (0 :: Int, [])
+            \(offset, acc) schema array -> do
+              assertLiveSchema schema
+              count <- fromIntegral . (getField @"length") <$> peek array
+              frame <- DataFrameArrow.arrowToDataframe (castPtr schema) (castPtr array)
+              assertConsumed schema array
+              pure (offset + count, (offset, count, frame) : acc)
+        rowCount @?= 5000
+        assertBool "multiple native batches" (length batches > 1)
+        forM_ batches \(offset, count, frame) -> do
+          let expected = expectedFrame [offset .. offset + count - 1]
+          DataFrame.columnNames frame @?= DataFrame.columnNames expected
+          frame @?= expected
+    , testCase "an unsupported type releases the failed export" $
+        withDb \conn -> do
+          -- Import one supported column before the unsupported column fails.
+          result <- try $ foldArrow conn "SELECT 42::BIGINT AS n, true AS unsupported" () () \() schema array -> do
+            _ <- DataFrameArrow.arrowToDataframe (castPtr schema) (castPtr array)
+            pure ()
+          case result of
+            Left (err :: ErrorCall) ->
+              assertBool "DataFrame format error" ("unsupported format" `Text.isInfixOf` Text.pack (displayException err))
+            Right () -> assertFailure "expected an unsupported Arrow type"
+          query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+    , testCase "an empty result does not call the consumer" $
+        withDb \conn -> do
+          count <- foldArrow conn "SELECT 1::BIGINT AS n WHERE false" () (0 :: Int) \_ schema array -> do
+            _ <- DataFrameArrow.arrowToDataframe (castPtr schema) (castPtr array)
+            assertFailure "unexpected batch"
+          count @?= 0
+    ]
   where
     foldArrow :: (ToRow q) => Connection -> Query -> q -> a -> (a -> Ptr ArrowSchema -> Ptr ArrowArray -> IO a) -> IO a
     foldArrow = if streaming then Streaming.foldArrow else Arrow.foldArrow
@@ -74,31 +81,31 @@
 -- | Construct the expected values independently of the Arrow buffer layout.
 expectedFrame :: [Int] -> DataFrame.DataFrame
 expectedFrame rows =
-    DataFrame.fromNamedColumns
-        [ ("id", DataFrame.fromList rows)
-        , ("íslenska_λ", DataFrame.fromList [if i `rem` 3 == 0 then Nothing else Just (i - 2500) | i <- rows])
-        , ("small", DataFrame.fromList [fromIntegral i / 4 :: Double | i <- rows])
-        , ("real", DataFrame.fromList [if i `rem` 5 == 0 then Nothing else Just (fromIntegral i / 4 :: Double) | i <- rows])
-        , ("label", DataFrame.fromList [label i | i <- rows])
-        , ("missing", DataFrame.fromList [Nothing :: Maybe Int | _ <- rows])
-        ]
+  DataFrame.fromNamedColumns
+    [ ("id", DataFrame.fromList rows)
+    , ("íslenska_λ", DataFrame.fromList [if i `rem` 3 == 0 then Nothing else Just (i - 2500) | i <- rows])
+    , ("small", DataFrame.fromList [fromIntegral i / 4 :: Double | i <- rows])
+    , ("real", DataFrame.fromList [if i `rem` 5 == 0 then Nothing else Just (fromIntegral i / 4 :: Double) | i <- rows])
+    , ("label", DataFrame.fromList [label i | i <- rows])
+    , ("missing", DataFrame.fromList [Nothing :: Maybe Int | _ <- rows])
+    ]
   where
     label i
-        | i `rem` 7 == 0 = Nothing
-        | i `rem` 7 == 1 = Just ""
-        | otherwise = Just ("λ\0雪" <> Text.pack (show i))
+      | i `rem` 7 == 0 = Nothing
+      | i `rem` 7 == 1 = Just ""
+      | otherwise = Just ("λ\0雪" <> Text.pack (show i))
 
 -- | Fail before the consumer can dereference a previously released schema.
 assertLiveSchema :: Ptr ArrowSchema -> Assertion
 assertLiveSchema ptr = do
-    schema <- peek ptr
-    assertBool "each batch needs an unreleased schema" (arrowSchemaRelease schema /= nullFunPtr)
+  schema <- peek ptr
+  assertBool "each batch needs an unreleased schema" ((getField @"release") schema /= (coerce (nullFunPtr @Void)))
 
 -- | The DataFrame importer releases both objects after copying their contents.
 assertConsumed :: Ptr ArrowSchema -> Ptr ArrowArray -> Assertion
 assertConsumed schema array = do
-    arrowSchemaRelease <$> peek schema >>= (@?= nullFunPtr)
-    arrowArrayRelease <$> peek array >>= (@?= nullFunPtr)
+  (getField @"release") <$> peek schema >>= (@?= (coerce (nullFunPtr @Void)))
+  (getField @"release") <$> peek array >>= (@?= (coerce (nullFunPtr @Void)))
 
 -- | Keep native batch ordering deterministic in both execution modes.
 withDb :: (Connection -> IO a) -> IO a
diff --git a/duckdb-simple.cabal b/duckdb-simple.cabal
--- a/duckdb-simple.cabal
+++ b/duckdb-simple.cabal
@@ -1,6 +1,6 @@
 cabal-version: 3.4
 name: duckdb-simple
-version: 0.3.0.0
+version: 1.0.0.0
 license: MPL-2.0
 license-file: LICENSE
 author: Matthias Pall Gissurarson
@@ -21,9 +21,12 @@
   A high-level DuckDB interface with typed parameters and results,
   prepared statements, chunked folds, transactions, and Haskell scalar
   functions. The API follows the style of sqlite-simple and postgresql-simple.
-  .
-  Supports native DuckDB >= 1.5.3 and < 1.6. Tested with versions 1.5.3 through 1.5.6.
 
+  The backend uses the generated V2 API from duckdb-ffi. Upstream marks
+  that API as unstable, so this release requires exactly DuckDB 2.0.0.
+  It provides shared environments and instances, function registration,
+  native streaming, and Arrow batches.
+
 extra-doc-files:
   CHANGELOG.md
   README.md
@@ -38,14 +41,25 @@
   default: False
   manual: True
 
+flag extension
+  description: Build loadable extensions with private C callback helpers.
+  default: False
+  manual: True
+
+flag quack-tests
+  description: Test authenticated local Quack connections with supplied extensions.
+  default: False
+  manual: True
+
 library
   exposed-modules:
     Database.DuckDB.Simple
     Database.DuckDB.Simple.Arrow
     Database.DuckDB.Simple.Catalog
     Database.DuckDB.Simple.Config
+    Database.DuckDB.Simple.Conversion
     Database.DuckDB.Simple.Copy
-    Database.DuckDB.Simple.Deprecated.Streaming
+    Database.DuckDB.Simple.Extension
     Database.DuckDB.Simple.FileSystem
     Database.DuckDB.Simple.FromField
     Database.DuckDB.Simple.FromRow
@@ -56,49 +70,91 @@
     Database.DuckDB.Simple.Logging
     Database.DuckDB.Simple.LogicalRep
     Database.DuckDB.Simple.Ok
+    Database.DuckDB.Simple.Pragma
+    Database.DuckDB.Simple.QueryMetrics
+    Database.DuckDB.Simple.Registration
+    Database.DuckDB.Simple.Streaming
     Database.DuckDB.Simple.Time
     Database.DuckDB.Simple.ToField
+    Database.DuckDB.Simple.Tokenizer
     Database.DuckDB.Simple.ToRow
     Database.DuckDB.Simple.Types
+    Database.DuckDB.Simple.V2.Config
+    Database.DuckDB.Simple.V2.Copy
+    Database.DuckDB.Simple.V2.FunctionDocs
+    Database.DuckDB.Simple.V2.Logging
+    Database.DuckDB.Simple.V2.LogicalRep
+    Database.DuckDB.Simple.V2.Pragma
+    Database.DuckDB.Simple.V2.Registration
     Database.DuckDB.Simple.Variant
 
   other-modules:
     Database.DuckDB.Simple.Arrow.Internal
     Database.DuckDB.Simple.Callback
+    Database.DuckDB.Simple.CallbackMark
+    Database.DuckDB.Simple.Config.Internal
+    Database.DuckDB.Simple.Copy.Internal
     Database.DuckDB.Simple.Element
+    Database.DuckDB.Simple.Function.Internal
+    Database.DuckDB.Simple.Logging.Internal
     Database.DuckDB.Simple.Materialize
+    Database.DuckDB.Simple.Native
+    Database.DuckDB.Simple.Pragma.Internal
     Database.DuckDB.Simple.Result
-    Database.DuckDB.Simple.TypeCache
+    Database.DuckDB.Simple.Typed
+    Database.DuckDB.Simple.Typed.Aggregate
+    Database.DuckDB.Simple.Typed.Table
+    Database.DuckDB.Simple.TypeScope
     Database.DuckDB.Simple.VariantCodec
 
   hs-source-dirs: src
   default-language: Haskell2010
+
+  if flag(extension)
+    if os(linux) || os(osx)
+      -- Keep the C stubs private to this shared library. Omit unfoldings, so
+      -- optimized clients cannot inline references to the hidden stubs.
+      cc-options: -fvisibility=hidden
+      ghc-options:
+        -fomit-interface-pragmas
+        -optc-fvisibility=hidden
+    else
+      buildable: False
   build-depends:
     array >=0.5 && <0.6,
-    base >=4.14 && <5,
+    base >=4.18 && <5,
     bytestring >=0.11 && <0.13,
     containers >=0.6 && <0.9,
-    duckdb-ffi >=1.5.6.0 && <1.6,
+    duckdb-ffi >=2.0.0.0 && <2.0.1,
     geometry-simple >=0.1.1.0 && <0.2,
+    hs-bindgen-runtime >=1.0.0.0 && <1.1,
     text >=2.0 && <2.2,
     time >=1.12 && <1.16,
     transformers >=0.6 && <0.7,
     uuid >=1.3 && <1.4,
 
 test-suite duckdb-simple-test
+  if flag(extension)
+    buildable: False
   type: exitcode-stdio-1.0
   hs-source-dirs: test
   main-is: Spec.hs
   other-modules:
     ArrowTests
     CancellationTests
+    CopyTests
     CoreRegressionTests
     ExtensionRegressionTests
     GeometryRegressionTests
     Properties
+    RegistrationTests
+    SizedArrayTests
+    SqlFeatureTests
     StreamingTests
     TestUtils
     TimeTests
+    TypedRegistrationTests
+    UserCastTests
     ValueRegressionTests
     VariantRegressionTests
 
@@ -109,13 +165,15 @@
 
   build-depends:
     array >=0.5 && <0.6,
-    base >=4.14 && <5,
+    base >=4.18 && <5,
     bytestring,
     containers >=0.6 && <0.9,
     directory >=1.3 && <1.4,
-    duckdb-ffi >=1.5.6.0 && <1.6,
+    duckdb-ffi >=2.0.0.0 && <2.0.1,
     duckdb-simple,
+    filepath >=1.4 && <1.6,
     geometry-simple >=0.1.1.0 && <0.2,
+    hs-bindgen-runtime >=1.0.0.0 && <1.1,
     QuickCheck >=2.14 && <2.18,
     tasty >=1.4 && <1.6,
     tasty-expected-failure >=0.12 && <0.13,
@@ -126,51 +184,34 @@
     uuid >=1.3 && <1.4,
     vector >=0.13 && <0.14,
 
-test-suite duckdb-simple-codec-test
+test-suite duckdb-simple-leak-test
+  if flag(extension)
+    buildable: False
   type: exitcode-stdio-1.0
-  hs-source-dirs:
-    test-codec
-    src
-
+  hs-source-dirs: leaktest
   main-is: Main.hs
-  other-modules:
-    Database.DuckDB.Simple.Element
-    Database.DuckDB.Simple.FromField
-    Database.DuckDB.Simple.Geometry
-    Database.DuckDB.Simple.Internal
-    Database.DuckDB.Simple.LogicalRep
-    Database.DuckDB.Simple.Ok
-    Database.DuckDB.Simple.Time
-    Database.DuckDB.Simple.TypeCache
-    Database.DuckDB.Simple.Variant
-    Database.DuckDB.Simple.VariantCodec
-
   default-language: Haskell2010
+  ghc-options: -threaded
   build-depends:
-    array >=0.5 && <0.6,
-    base >=4.14 && <5,
-    bytestring >=0.11 && <0.13,
+    base >=4.18 && <5,
+    bytestring,
     containers >=0.6 && <0.9,
-    duckdb-ffi >=1.5.6.0 && <1.6,
+    duckdb-simple,
     geometry-simple >=0.1.1.0 && <0.2,
-    tasty >=1.4 && <1.6,
-    tasty-hunit >=0.10 && <0.12,
-    text >=2.0 && <2.2,
-    time >=1.12 && <1.16,
-    transformers >=0.6 && <0.7,
-    uuid >=1.3 && <1.4,
+    text,
 
-test-suite duckdb-simple-leak-test
+-- This suite has no -threaded. It checks the guard for such a program.
+test-suite duckdb-simple-nonthreaded-test
+  if flag(extension)
+    buildable: False
   type: exitcode-stdio-1.0
-  hs-source-dirs: leaktest
+  hs-source-dirs: nonthreaded-test
   main-is: Main.hs
   default-language: Haskell2010
-  ghc-options: -threaded
   build-depends:
-    base >=4.14 && <5,
-    bytestring,
+    base >=4.18 && <5,
     duckdb-simple,
-    geometry-simple >=0.1.1.0 && <0.2,
+    text,
 
 test-suite duckdb-simple-dataframe-test
   type: exitcode-stdio-1.0
@@ -179,19 +220,40 @@
   default-language: Haskell2010
   ghc-options: -threaded
 
-  if !flag(dataframe-tests)
+  if flag(extension) || !flag(dataframe-tests)
     buildable: False
   build-depends:
-    base >=4.14 && <5,
+    base >=4.18 && <5,
     dataframe-arrow-bridge >=1.0 && <1.1,
     dataframe-core >=2.5 && <2.6,
-    duckdb-ffi >=1.5.6.0 && <1.6,
+    duckdb-ffi >=2.0.0.0 && <2.0.1,
     duckdb-simple,
+    hs-bindgen-runtime >=1.0.0.0 && <1.1,
     tasty >=1.4 && <1.6,
     tasty-hunit >=0.10 && <0.12,
     text,
 
+test-suite duckdb-simple-quack-test
+  type: exitcode-stdio-1.0
+  hs-source-dirs: test-quack
+  main-is: Main.hs
+  default-language: Haskell2010
+  ghc-options: -threaded
+
+  if flag(extension) || !flag(quack-tests)
+    buildable: False
+  build-depends:
+    base >=4.18 && <5,
+    directory >=1.3 && <1.4,
+    duckdb-simple,
+    tasty >=1.4 && <1.6,
+    tasty-hunit >=0.10 && <0.12,
+    text,
+    time,
+
 benchmark duckdb-simple-bench
+  if flag(extension)
+    buildable: False
   type: exitcode-stdio-1.0
   hs-source-dirs: bench
   main-is: Main.hs
@@ -202,8 +264,10 @@
     -rtsopts
 
   build-depends:
-    base >=4.14 && <5,
+    array >=0.5 && <0.6,
+    base >=4.18 && <5,
     bytestring,
+    containers >=0.6 && <0.9,
     duckdb-simple,
     geometry-simple >=0.1.1.0 && <0.2,
     text,
diff --git a/leaktest/Main.hs b/leaktest/Main.hs
--- a/leaktest/Main.hs
+++ b/leaktest/Main.hs
@@ -1,38 +1,56 @@
 {-# LANGUAGE BlockArguments #-}
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE ScopedTypeVariables #-}
-{-# OPTIONS_GHC -Wno-deprecations #-}
 
-{- | Regression check for leaked DuckDB handles.
-
-The handles live in C memory, so the GHC heap statistics cannot see them.
-The open/close check counts native threads and resident memory. The sustained
-checks keep one connection open through repeated queries, failures, cursor
-resets, callback replacement, and cancellation. Weak references check callback
-state release independently of resident memory.
-
-Each check runs in this dedicated process. On systems without
-@/proc/self/status@, the native resource counters are unavailable. The
-functional checks and callback collection checks still run.
--}
+-- |
+-- Module      : Main
+-- Description : Regression check for leaked DuckDB handles.
+--
+-- The handles live in C memory, so the GHC heap statistics cannot see them. The
+-- open/close check counts native threads and resident memory. The sustained
+-- checks keep one connection open through repeated queries, failures, cursor
+-- resets, callback replacement, and cancellation. Weak references check callback
+-- state release independently of resident memory.
+--
+-- Each check runs in this dedicated process. On systems without
+-- @/proc/self/status@, the native resource counters are unavailable. The
+-- functional checks and callback collection checks still run.
 module Main (main) where
 
 import Control.Concurrent (forkFinally, killThread, newEmptyMVar, putMVar, takeMVar, threadDelay, tryPutMVar)
-import Control.Exception (AsyncException (ThreadKilled), IOException, SomeException, evaluate, fromException, try)
-import Control.Monad (forM_, replicateM, unless, void, when)
+import Control.Exception (
+  AsyncException (ThreadKilled),
+  BlockedIndefinitelyOnMVar (..),
+  IOException,
+  SomeException,
+  evaluate,
+  finally,
+  fromException,
+  throwIO,
+  try,
+ )
+import Control.Monad (forM, forM_, replicateM, replicateM_, unless, void, when)
 import qualified Data.ByteString as BS
 import qualified Data.Geometry as G
 import Data.IORef (atomicModifyIORef', atomicWriteIORef, mkWeakIORef, newIORef, readIORef)
 import Data.Int (Int64)
-import Data.List (isPrefixOf)
-import Data.Maybe (catMaybes, listToMaybe)
+import Data.List (isPrefixOf, minimumBy)
+import qualified Data.Map.Strict as Map
+import Data.Maybe (catMaybes, isJust, listToMaybe)
+import Data.Ord (comparing)
+import Data.Text (Text)
+import qualified Data.Text as Text
 import Database.DuckDB.Simple
+import qualified Database.DuckDB.Simple.Arrow as Arrow
 import qualified Database.DuckDB.Simple.Copy as Copy
-import qualified Database.DuckDB.Simple.Deprecated.Streaming as Streaming
-import Database.DuckDB.Simple.FromField (DecimalValue (..), FieldValue (..))
+import Database.DuckDB.Simple.FromField (BigNum (..), DecimalValue (..), FieldValue (..), StructValue, UnionValue)
 import Database.DuckDB.Simple.Geometry (RawGeometry (..), fromRawGeometry)
 import qualified Database.DuckDB.Simple.Logging as Logging
-import Database.DuckDB.Simple.Variant (Variant (..))
+import Database.DuckDB.Simple.Registration (TypeDeclaration (..), registerCustomType)
+import qualified Database.DuckDB.Simple.Streaming as Streaming
+import qualified Database.DuckDB.Simple.V2.Registration as R
+import Database.DuckDB.Simple.Variant (Variant (..), variantObject)
+import GHC.Weak.Finalize (getFinalizerExceptionHandler, setFinalizerExceptionHandler)
 import System.Environment (getArgs, lookupEnv)
 import System.Exit (exitFailure)
 import System.Mem (performMajorGC)
@@ -41,10 +59,10 @@
 
 -- | The process-global resource counters that a leaked handle increases.
 data Usage = Usage
-    { usageThreads :: Int
-    , usageRssKb :: Int
-    }
-    deriving (Show)
+  { usageThreads :: Int
+  , usageRssKb :: Int
+  }
+  deriving (Show)
 
 -- | The number of open\/close cycles that the check runs.
 cycles :: Int
@@ -58,263 +76,406 @@
 rssSlackKb :: Int
 rssSlackKb = 32 * 1024
 
-{- | Read the current resource counters.  The result is 'Nothing' if the system
-has no @\/proc\/self\/status@.
--}
+-- | Read the current resource counters.  The result is 'Nothing' if the system
+-- has no @\/proc\/self\/status@.
 readUsage :: IO (Maybe Usage)
 readUsage = do
-    result <- try (readFile "/proc/self/status") :: IO (Either IOException String)
-    case result of
-        Left _ -> pure Nothing
-        Right contents -> do
-            _ <- evaluate (length contents)
-            pure (Usage <$> statusField "Threads" contents <*> statusField "VmRSS" contents)
+  result <- try (readFile "/proc/self/status") :: IO (Either IOException String)
+  case result of
+    Left _ -> pure Nothing
+    Right contents -> do
+      _ <- evaluate (length contents)
+      pure (Usage <$> statusField "Threads" contents <*> statusField "VmRSS" contents)
   where
     statusField name contents =
-        listToMaybe
-            [ value
-            | line <- lines contents
-            , (name <> ":") `isPrefixOf` line
-            , (value, _) <- reads (drop (length name + 1) line)
-            ]
+      listToMaybe
+        [ value
+        | line <- lines contents
+        , (name <> ":") `isPrefixOf` line
+        , (value, _) <- reads (drop (length name + 1) line)
+        ]
 
 -- | Open a connection, use a statement, then close both.
 openCloseCycle :: IO ()
 openCloseCycle = do
-    conn <- open ":memory:"
-    stmt <- openStatement conn "SELECT 42"
-    closeStatement stmt
-    _ <- query_ conn "SELECT 42" :: IO [Only Int64]
-    -- The first VARIANT parameter fills the type cache. Close must destroy it.
-    _ <- query conn "SELECT ?" (Only (Variant (FieldInt64 42))) :: IO [Only Variant]
-    -- A TIMETZ offset with seconds fails during result materialization.
-    -- The result and connection must still be destroyed.
-    rejected <- try (query_ conn "SELECT {'xs': [i, i + 1, i + 2, i + 3], 'bad': '12:00:00+01:23:45'::TIMETZ} FROM range(100000) t(i)") :: IO (Either SomeException [Only FieldValue])
-    case rejected of
-        Left _ -> pure ()
-        Right _ -> fail "expected TIMETZ offset conversion failure"
-    close conn
+  conn <- open ":memory:"
+  stmt <- openStatement conn "SELECT 42"
+  closeStatement stmt
+  _ <- query_ conn "SELECT 42" :: IO [Only Int64]
+  values <- query conn "SELECT ?" (Only (Variant (FieldInt64 42)))
+  unless (values == [Only (Variant (FieldInt64 42))]) (fail "wrong VARIANT payload")
+  -- The reader of a VARIANT value fails while it reads the chunk. See
+  -- breakVariantReads. The result and connection must still be destroyed.
+  breakVariantReads conn
+  rejected <- try (query_ conn rejectedQuery) :: IO (Either SomeException [Only FieldValue])
+  case rejected of
+    Left _ -> pure ()
+    Right _ -> fail "expected the failure of the VARIANT reader"
+  close conn
 
 main :: IO ()
 main = do
-    args <- getArgs
-    let (mode, batches) = case args of
-            [] -> ("all", 10)
-            [name] -> (name, 10)
-            [name, n] | Just count <- readMaybe n, count > 0 -> (name, count)
-            _ -> ("invalid", 0)
-    unless (mode `elem` ["all", "open-close", "long-lived", "callbacks", "cancel", "decode-failure", "new-types"]) $
-        fail "Expected [all|open-close|long-lived|callbacks|cancel|decode-failure|new-types] [positive batch count]"
-    when (mode `elem` ["all", "open-close"]) checkOpenClose
-    when (mode `elem` ["all", "long-lived"]) (checkLongLived batches)
-    when (mode `elem` ["all", "callbacks"]) (checkCallbacks batches)
-    when (mode `elem` ["all", "cancel"]) (checkCancellation batches)
-    when (mode == "decode-failure") checkDecodeFailure
-    when (mode `elem` ["all", "new-types"]) (checkNewTypes batches)
+  args <- getArgs
+  let (mode, batches) = case args of
+        [] -> ("all", 10)
+        [name] -> (name, 10)
+        [name, n] | Just count <- readMaybe n, count > 0 -> (name, count)
+        _ -> ("invalid", 0)
+  unless (mode `elem` ["all", "open-close", "dropped-handles", "long-lived", "callbacks", "cancel", "decode-failure", "new-types", "typed"]) $
+    fail "Expected [all|open-close|dropped-handles|long-lived|callbacks|cancel|decode-failure|new-types|typed] [positive batch count]"
+  when (mode `elem` ["all", "open-close"]) checkOpenClose
+  when (mode `elem` ["all", "dropped-handles"]) checkDroppedHandles
+  when (mode `elem` ["all", "long-lived"]) (checkLongLived batches)
+  when (mode `elem` ["all", "callbacks"]) (checkCallbacks batches)
+  when (mode `elem` ["all", "cancel"]) (checkCancellation batches)
+  when (mode == "decode-failure") checkDecodeFailure
+  when (mode `elem` ["all", "new-types"]) (checkNewTypes batches)
+  when (mode `elem` ["all", "typed"]) (checkTyped batches)
 
+-- | Drop a connection and one of its statements without closing them. The
+-- statement is younger than the connection, so the collector can run the
+-- finalizer of the connection first. Cleanup must still release the database,
+-- and no finalizer may wait for a finalizer that runs after it.
+checkDroppedHandles :: IO ()
+checkDroppedHandles = do
+  blocked <- newIORef (0 :: Int)
+  previous <- getFinalizerExceptionHandler
+  let record err = do
+        case fromException err of
+          Just BlockedIndefinitelyOnMVar -> atomicModifyIORef' blocked (\count -> (count + 1, ()))
+          Nothing -> pure ()
+        previous err
+      -- The database owns the callback, and the callback retains the token.
+      allocate before after = do
+        token <- newIORef (42 :: Int64)
+        weak <- mkWeakIORef token (pure ())
+        conn <- open ":memory:"
+        createFunction conn "dropped_token" (readIORef token)
+        -- Decoding a VARIANT opens the helper that the finalizer must release.
+        values <- query conn "SELECT ?" (Only (Variant (FieldInt64 42)))
+        unless (values == [Only (Variant (FieldInt64 42))]) (fail "wrong VARIANT payload before the drop")
+        replicateM_ before performMajorGC
+        stmt <- openStatement conn "SELECT dropped_token()"
+        replicateM_ after performMajorGC
+        row <- nextRow stmt
+        unless (row == Just (Only (42 :: Int64))) (fail "wrong row before the drop")
+        pure weak
+      released weak attempts
+        | attempts == (0 :: Int) = fail "a dropped connection kept its database open"
+        | otherwise = do
+            performMajorGC
+            token <- deRefWeak weak
+            when (isJust token) (threadDelay 10000 >> released weak (attempts - 1))
+  flip finally (setFinalizerExceptionHandler previous) do
+    setFinalizerExceptionHandler record
+    forM_ [(before, after) | before <- [0 .. 3 :: Int], after <- [0, 1 :: Int]] \(before, after) ->
+      allocate before after >>= \weak -> released weak 500
+    count <- readIORef blocked
+    unless (count == 0) (fail ("a finalizer waited for a later finalizer " <> show count <> " time(s)"))
+
 -- | Import raw WKB and release native values after failed nested construction.
 checkNewTypes :: Int -> IO ()
 checkNewTypes batches =
-    withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
-        [Only geometry] <- query_ conn "SELECT 'POINT ZM (1 2 3 4)'::GEOMETRY('OGC:CRS84')" :: IO [Only RawGeometry]
-        typed <- either fail pure (fromRawGeometry geometry) :: IO G.Geometry
-        let variant = Variant (FieldList [FieldInt64 42, FieldList [FieldNull, FieldText "before\0after"]])
-            batch = forM_ [1 .. 100 :: Int] \_ -> do
-                rows <- query conn "SELECT ?, system.main.ST_SetCRS(system.main.ST_GeomFromWKB(?), ?), ?" (variant, rawGeometryWKB geometry, rawGeometryCRS geometry, typed)
-                unless (rows == [(variant, geometry, typed)]) (fail "new type round trip failed")
-                expectFailure (query conn "SELECT ?, system.main.ST_GeomFromWKB(?)" (typed, BS.pack [1, 1, 0, 0, 0]) :: IO [(G.Geometry, RawGeometry)])
-                expectFailure (query conn "SELECT system.main.ST_GeomFromWKB(?)" (Only (rawGeometryWKB geometry)) :: IO [Only Int64])
-                expectFailure (query conn "SELECT ?" (Only (Variant (FieldList [variantPayload variant, FieldDecimal (DecimalValue 0 0 0)]))) :: IO [Only Variant])
-                expectFailure (query conn "SELECT ?" (Only variant) :: IO [Only Int64])
-        batch
-        performMajorGC
-        before <- readUsage
-        forM_ [1 .. batches] \n -> do
-            batch
-            performMajorGC
-            after <- readUsage
-            reportOptional ("open connection, " <> show (n * 100) <> " new type cycles") before after
+  withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+    [Only geometry] <- query_ conn "SELECT 'POINT ZM (1 2 3 4)'::GEOMETRY('OGC:CRS84')" :: IO [Only RawGeometry]
+    typed <- either fail pure (fromRawGeometry geometry) :: IO G.Geometry
+    -- These values come from DuckDB, so that they have the native types.
+    [Only collated] <- query_ conn "SELECT {'text': 'A' COLLATE nocase, 'items': ['B' COLLATE nocase]}" :: IO [Only (StructValue FieldValue)]
+    [Only union] <- query_ conn "SELECT union_value(t := 'λ')::UNION(n BIGINT, t VARCHAR)" :: IO [Only (UnionValue FieldValue)]
+    let emptyKey = Variant (variantObject [("", FieldWord64 1), ("n", FieldWord64 2)])
+        foldedKeys = Variant (variantObject [("A", FieldWord64 1), ("a", FieldWord64 2), ("b", FieldWord64 3)])
+        -- The encoded value of this number has more than 100 bytes.
+        large = 2 ^ (1000 :: Int) + 12345 :: Integer
+        roundTrip :: (ToField a, FromField a, Eq a) => String -> a -> IO ()
+        roundTrip label value = query conn "SELECT ?" (Only value) >>= \rows -> unless (rows == [Only value]) (fail (label <> " binding failed"))
+    let variant = Variant (FieldList [FieldInt64 42, FieldList [FieldNull, FieldText "before\0after"]])
+        custom = geometry{rawGeometryCRS = Just "local' íslenska λ"}
+        batch = forM_ [1 .. 100 :: Int] \_ -> do
+          roundTrip "custom CRS" custom
+          expectFailure (query conn "SELECT ?" (Only geometry{rawGeometryCRS = Just " "}) :: IO [Only RawGeometry])
+          rows <-
+            query
+              conn
+              "SELECT ?, system.main.ST_SetCRS(system.main.ST_GeomFromWKB(?), ?), ?"
+              (variant, rawGeometryWKB geometry, rawGeometryCRS geometry, typed)
+          unless (rows == [(variant, geometry, typed)]) (fail "new type round trip failed")
+          expectFailure (query conn "SELECT ?, system.main.ST_GeomFromWKB(?)" (typed, BS.pack [1, 1, 0, 0, 0]) :: IO [(G.Geometry, RawGeometry)])
+          expectFailure (query conn "SELECT system.main.ST_GeomFromWKB(?)" (Only (rawGeometryWKB geometry)) :: IO [Only Int64])
+          expectFailure
+            (query conn "SELECT ?" (Only (Variant (FieldList [variantPayload variant, FieldDecimal (DecimalValue 0 0 0)]))) :: IO [Only Variant])
+          expectFailure (query conn "SELECT ?" (Only variant) :: IO [Only Int64])
+          -- STRUCT field names cannot be an empty key or two keys that differ
+          -- only in case. Thus these objects use the extraction query. The two
+          -- key counts replace the kept extraction statement.
+          objects <- query_ conn "SELECT json_object('', 1, 'n', 2)::VARIANT, json_object('A', 1, 'a', 2, 'b', 3)::VARIANT"
+          unless (objects == [(emptyKey, foldedKeys)]) (fail "VARIANT object read failed")
+          roundTrip "collated STRUCT" collated
+          roundTrip "UNION" union
+          roundTrip "MAP" (Map.fromList [(1 :: Int64, [10, 11 :: Int64]), (2, [])])
+          roundTrip "LIST" [[1, 2], [3 :: Int64]]
+          query conn "SELECT ?::VARCHAR" (Only (BigNum large)) >>= \text ->
+            unless (text == [Only (show large)]) (fail "BIGNUM binding failed")
+    batch
+    performMajorGC
+    before <- readUsage
+    forM_ [1 .. batches] \n -> do
+      batch
+      performMajorGC
+      after <- readUsage
+      reportOptional ("open connection, " <> show (n * 100) <> " new type cycles") before after
 
 -- | Check native results and database handles across connection lifetimes.
 checkOpenClose :: IO ()
 checkOpenClose = do
-    -- The first cycle also does the one-time initialization, which must not
-    -- count as growth.
-    openCloseCycle
-    before <- readUsage
-    case before of
-        Nothing -> putStrLn "duckdb-simple leak check: /proc/self/status is unavailable; skipped."
-        Just baseline -> do
-            forM_ [1 .. cycles] \_ -> openCloseCycle
-            after <- readUsage
-            case after of
-                Nothing -> putStrLn "duckdb-simple leak check: /proc/self/status disappeared; skipped."
-                Just final -> report ("open/close, " <> show cycles <> " cycles") baseline final
+  -- The first cycle also does the one-time initialization, which must not
+  -- count as growth.
+  openCloseCycle
+  before <- readUsage
+  case before of
+    Nothing -> putStrLn "duckdb-simple leak check: /proc/self/status is unavailable; skipped."
+    Just baseline -> do
+      forM_ [1 .. cycles] \_ -> openCloseCycle
+      after <- readUsage
+      case after of
+        Nothing -> putStrLn "duckdb-simple leak check: /proc/self/status disappeared; skipped."
+        Just final -> report ("open/close, " <> show cycles <> " cycles") baseline final
 
 -- | Reuse one connection and statement through successful and failed operations.
 checkLongLived :: Int -> IO ()
 checkLongLived batches =
-    withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
-        withStatement conn "SELECT ?::BIGINT FROM range(10000)" \stmt -> do
-            let cycleQuery = do
-                    rows <- query_ conn "SELECT sum(i)::BIGINT FROM range(10000) t(i)"
-                    unless (rows == [Only (49995000 :: Int64)]) (fail "wrong query result")
-                    expectFailure (query_ conn "SELECT {'xs': [i, i + 1, i + 2, i + 3], 'bad': '12:00:00+01:23:45'::TIMETZ} FROM range(10000) t(i)" :: IO [Only FieldValue])
-                    expectFailure (query_ conn "SELECT CAST('bad' AS BIGINT)" :: IO [Only Int64])
-                    bind stmt [toField (42 :: Int64)]
-                    nextRow stmt >>= \row -> unless (row == Just (Only (42 :: Int64))) (fail "wrong cursor result")
-                    clearStatementBindings stmt
-                    expectFailure (nextRow stmt :: IO (Maybe (Only Int64)))
-                batch = forM_ [1 .. 100 :: Int] (const cycleQuery)
-            batch
-            performMajorGC
-            before <- readUsage
-            forM_ [1 .. batches] \n -> do
-                batch
-                performMajorGC
-                after <- readUsage
-                reportOptional ("open connection, " <> show (n * 100) <> " cycles") before after
+  withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+    breakVariantReads conn
+    withStatement conn "SELECT ?::BIGINT FROM range(10000)" \stmt -> do
+      let cycleQuery = do
+            rows <- query_ conn "SELECT sum(i)::BIGINT FROM range(10000) t(i)"
+            unless (rows == [Only (49995000 :: Int64)]) (fail "wrong query result")
+            expectFailure
+              (query_ conn "SELECT {'xs': [i, i + 1, i + 2, i + 3], 'bad': 42::BIGINT::VARIANT} FROM range(10000) t(i)" :: IO [Only FieldValue])
+            expectFailure (query_ conn "SELECT CAST('bad' AS BIGINT)" :: IO [Only Int64])
+            bind stmt [toField (42 :: Int64)]
+            nextRow stmt >>= \row -> unless (row == Just (Only (42 :: Int64))) (fail "wrong cursor result")
+            clearStatementBindings stmt
+            expectFailure (nextRow stmt :: IO (Maybe (Only Int64)))
+            -- Close a statement while its cursor holds the other chunks of a
+            -- materialized result, and then while its cursor holds a native stream.
+            withStatement conn "SELECT i FROM range(100000) t(i)" \cursor -> void (nextRow cursor :: IO (Maybe (Only Int64)))
+            withStatement conn "SELECT i FROM range(100000) t(i)" \cursor -> void (Streaming.nextRow cursor :: IO (Maybe (Only Int64)))
+            -- The step fails at the first batch of a materialized Arrow fold.
+            -- The fold must release each batch that it did not deliver.
+            expectFailure (Arrow.foldArrow_ conn "SELECT i FROM range(100000) t(i)" () (\() _ _ -> fail "step"))
+          batch = forM_ [1 .. 100 :: Int] (const cycleQuery)
+      batch
+      performMajorGC
+      before <- readUsage
+      forM_ [1 .. batches] \n -> do
+        batch
+        performMajorGC
+        after <- readUsage
+        reportOptional ("open connection, " <> show (n * 100) <> " cycles") before after
 
 -- | Isolate failed result cleanup for comparison with earlier package versions.
 checkDecodeFailure :: IO ()
 checkDecodeFailure =
-    withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
-        let rejected = expectFailure (query_ conn "SELECT {'xs': [i, i + 1, i + 2, i + 3], 'bad': '12:00:00+01:23:45'::TIMETZ} FROM range(100000) t(i)" :: IO [Only FieldValue])
-        rejected
-        performMajorGC
-        before <- readUsage
-        forM_ [1 .. cycles] (const rejected)
-        performMajorGC
-        after <- readUsage
-        reportOptional ("open connection, " <> show cycles <> " decode failures") before after
+  withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+    breakVariantReads conn
+    let rejected = expectFailure (query_ conn rejectedQuery :: IO [Only FieldValue])
+    rejected
+    performMajorGC
+    before <- readUsage
+    forM_ [1 .. cycles] (const rejected)
+    performMajorGC
+    after <- readUsage
+    reportOptional ("open connection, " <> show cycles <> " failed VARIANT reads") before after
 
 -- | Check that callback closures and query state are released before close.
 checkCallbacks :: Int -> IO ()
 checkCallbacks batches =
-    withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
-        Logging.registerLogStorage conn "leak_log" (\_ -> pure ())
-        copyStates <- newIORef []
-        let newCopyState = do
+  withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+    copyStates <- newIORef []
+    let newCopyState = do
+          state <- newIORef (7 :: Int64)
+          weak <- mkWeakIORef state (pure ())
+          atomicModifyIORef' copyStates (\old -> (weak : old, ()))
+          pure state
+    Copy.registerCopyToFunction conn "leak_copy" (\_ -> newCopyState) (\_ -> newCopyState) (\_ _ -> pure ()) (\_ -> pure ())
+    Copy.registerCopyToFunction
+      conn
+      "leak_copy_failure"
+      (\_ -> newCopyState)
+      (\_ -> fail "COPY init failure" :: IO ())
+      (\_ _ -> pure ())
+      (\_ -> pure ())
+    -- Register leak_log once, so that the registration in each cycle fails and
+    -- the test can check that the rejected callback is released.
+    Logging.registerLogStorage conn "leak_log" (\_ -> pure ())
+    let cycleCallback = do
+          retained <- newIORef (42 :: Int64)
+          weak <- mkWeakIORef retained (pure ())
+          createFunction conn "leak_scalar" (readIORef retained)
+          query_ conn "SELECT leak_scalar()" >>= \rows -> unless (rows == [Only (42 :: Int64)]) (fail "wrong callback result")
+          states <- newIORef []
+          createFunctionWithState
+            conn
+            "leak_state"
+            ( do
                 state <- newIORef (7 :: Int64)
-                weak <- mkWeakIORef state (pure ())
-                atomicModifyIORef' copyStates (\old -> (weak : old, ()))
+                stateWeak <- mkWeakIORef state (pure ())
+                -- The initializer returns each weak reference to the test.
+                atomicModifyIORef' states (\old -> (stateWeak : old, ()))
                 pure state
-        Copy.registerCopyToFunction conn "leak_copy" (\_ -> newCopyState) (\_ -> newCopyState) (\_ _ -> pure ()) (\_ -> pure ())
-        Copy.registerCopyToFunction conn "leak_copy_failure" (\_ -> newCopyState) (\_ -> fail "COPY init failure" :: IO ()) (\_ _ -> pure ()) (\_ -> pure ())
-        let cycleCallback = do
-                retained <- newIORef (42 :: Int64)
-                weak <- mkWeakIORef retained (pure ())
-                createFunction conn "leak_scalar" (readIORef retained)
-                query_ conn "SELECT leak_scalar()" >>= \rows -> unless (rows == [Only (42 :: Int64)]) (fail "wrong callback result")
-                states <- newIORef []
-                createFunctionWithState
-                    conn
-                    "leak_state"
-                    ( do
-                        state <- newIORef (7 :: Int64)
-                        stateWeak <- mkWeakIORef state (pure ())
-                        -- The initializer returns each weak reference to the test.
-                        atomicModifyIORef' states (\old -> (stateWeak : old, ()))
-                        pure state
-                    )
-                    readIORef
-                query_ conn "SELECT leak_state()" >>= \rows -> unless (rows == [Only (7 :: Int64)]) (fail "wrong state result")
-                rejectedLog <- newIORef (0 :: Int64)
-                logWeak <- mkWeakIORef rejectedLog (pure ())
-                expectFailure (Logging.registerLogStorage conn "leak_log" (\_ -> void (readIORef rejectedLog)))
-                void (execute_ conn "COPY (SELECT i FROM range(100) t(i)) TO 'unused' (FORMAT leak_copy)")
-                expectFailure (execute_ conn "COPY (SELECT 1) TO 'unused' (FORMAT leak_copy_failure)")
-                copyRefs <- atomicModifyIORef' copyStates (\refs -> ([], refs))
-                stateRefs <- readIORef states
-                pure (weak : logWeak : stateRefs <> copyRefs)
-            batch = concat <$> replicateM 100 cycleCallback
-            checkReleased refs = do
-                -- Replace the last closure, then run a new transaction.
-                createFunction conn "leak_scalar" (0 :: Int64)
-                createFunction conn "leak_state" (0 :: Int64)
-                void (query_ conn "SELECT 1" :: IO [Only Int64])
-                performMajorGC
-                performMajorGC
-                live <- length . catMaybes <$> mapM deRefWeak refs
-                unless (live == 0) (fail (show live <> " callback values remain live after replacement"))
-        batch >>= checkReleased
-        before <- readUsage
-        forM_ [1 .. batches] \n -> do
-            batch >>= checkReleased
-            after <- readUsage
-            reportOptional ("open connection, " <> show (n * 100) <> " callback cycles") before after
+            )
+            readIORef
+          query_ conn "SELECT leak_state()" >>= \rows -> unless (rows == [Only (7 :: Int64)]) (fail "wrong state result")
+          rejectedLog <- newIORef (0 :: Int64)
+          logWeak <- mkWeakIORef rejectedLog (pure ())
+          expectFailure (Logging.registerLogStorage conn "leak_log" (\_ -> void (readIORef rejectedLog)))
+          void (execute_ conn "COPY (SELECT i FROM range(100) t(i)) TO 'unused' (FORMAT leak_copy)")
+          expectFailure (execute_ conn "COPY (SELECT 1) TO 'unused' (FORMAT leak_copy_failure)")
+          copyRefs <- atomicModifyIORef' copyStates (\refs -> ([], refs))
+          stateRefs <- readIORef states
+          pure (weak : logWeak : stateRefs <> copyRefs)
+        batch = concat <$> replicateM 100 cycleCallback
+        checkReleased refs = do
+          -- Replace the last closure, then run a new transaction.
+          createFunction conn "leak_scalar" (0 :: Int64)
+          createFunction conn "leak_state" (0 :: Int64)
+          void (query_ conn "SELECT 1" :: IO [Only Int64])
+          performMajorGC
+          performMajorGC
+          live <- length . catMaybes <$> mapM deRefWeak refs
+          unless (live == 0) (fail (show live <> " callback values remain live after replacement"))
+    batch >>= checkReleased
+    before <- readUsage
+    forM_ [1 .. batches] \n -> do
+      batch >>= checkReleased
+      after <- readUsage
+      reportOptional ("open connection, " <> show (n * 100) <> " callback cycles") before after
 
+-- | Make VARIANT metadata preparation and object extraction fail. A prepared
+-- metadata plan can survive a lower expression depth. 'rejectedQuery' uses an
+-- unusual key, so its extraction query still binds on each execution and fails
+-- at depth 3. Set the caller's SESSION depth first, so its control statements
+-- can still bind after the GLOBAL depth changes.
+breakVariantReads :: Connection -> IO ()
+breakVariantReads conn = do
+  void (execute_ conn "SET SESSION max_expression_depth = 1000")
+  void (execute_ conn "SET GLOBAL max_expression_depth = 3")
+
+-- | A query whose result fails in the VARIANT reader after 'breakVariantReads'.
+rejectedQuery :: Query
+rejectedQuery = "SELECT {'xs': [i, i + 1, i + 2, i + 3], 'bad': json_object('', i)::VARIANT} FROM range(100000) t(i)"
+
 -- | Require an error without retaining the exception or its native resources.
 expectFailure :: IO a -> IO ()
 expectFailure action = do
-    outcome <- try (void action) :: IO (Either SomeException ())
-    case outcome of
-        Left _ -> pure ()
-        Right () -> fail "expected operation to fail"
+  outcome <- try (void action) :: IO (Either SomeException ())
+  case outcome of
+    Left _ -> pure ()
+    Right () -> fail "expected operation to fail"
 
 -- | Reuse a connection after cancelling native execution and row decoding.
+--
+-- Each batch reports its resident memory and fails if the thread count grew
+-- too much. The rule for the resident memory comes after the last batch. The
+-- resident memory rises in the first batches, and later single samples go up
+-- and down. A leak never returns memory, so it raises each later sample, also
+-- the lowest sample. A single high sample does not raise the lowest sample.
+-- Thus the rule compares the lowest sample of the second half of the batches
+-- with the lowest sample of batch 3 to the half. Batches 1 and 2 are not in the
+-- rule, because the memory can still rise in them. The rule needs at least 6
+-- batches. With fewer batches, the check does not compare the memory.
 checkCancellation :: Int -> IO ()
 checkCancellation batches =
-    withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
-        void (execute_ conn "SET streaming_buffer_size = '64KB'")
-        let cancel action = do
-                started <- newEmptyMVar
-                done <- newEmptyMVar
-                let signal = void (tryPutMVar started ())
-                tid <- forkFinally (action signal) (\outcome -> putMVar done outcome >> signal)
-                takeMVar started
-                threadDelay 1000
-                killThread tid
-                outcome <- takeMVar done
-                case outcome of
-                    Left err | fromException err == Just ThreadKilled -> pure ()
-                    Left err -> fail ("unexpected cancellation error: " <> show err)
-                    Right () -> fail "query completed before cancellation"
-                rows <- query_ conn "SELECT 42"
-                unless (rows == [Only (42 :: Int64)]) (fail "connection failed after cancellation")
-            batch = forM_ [1 .. 10 :: Int] \_ -> do
-                cancel \signal -> do
-                    createFunction conn "leak_cancel_started" (signal >> pure (1 :: Int64))
-                    void
-                        ( query_
-                            conn
-                            "WITH started AS MATERIALIZED (SELECT leak_cancel_started() AS seed) \
-                            \SELECT sum(sin((a.i + b.j + started.seed)::DOUBLE)) \
-                            \FROM started, range(1000000) a(i), range(1000000) b(j)" ::
-                            IO [Only Double]
-                        )
-                cancel \signal -> do
-                    signal
-                    void (query_ conn "SELECT {'x': i, 'values': [i, i + 1]} FROM range(100000) t(i)" :: IO [Only FieldValue])
-                cancel \signal -> do
-                    blocked <- newEmptyMVar
-                    -- Keep the first chunk live until the worker is cancelled.
-                    void (fold_ conn "SELECT {'x': i, 'values': [i, NULL]} FROM range(100000) t(i)" (0 :: Int64) (\n (Only (_ :: FieldValue)) -> signal >> takeMVar blocked >> pure (n + 1)))
-                forM_ [False, True] \arrow -> cancel \signal -> do
-                    filtering <- newIORef False
-                    createFunction conn "leak_stream_filter" \(_ :: Int64) -> do
-                        active <- readIORef filtering
-                        when active signal
-                        pure active
-                    let sql = "SELECT i FROM range(1000000000000) t(i) WHERE NOT leak_stream_filter(i)"
-                        delivered = atomicWriteIORef filtering True
-                    if arrow
-                        then Streaming.foldArrow_ conn sql () (\() _ _ -> delivered)
-                        else Streaming.fold_ conn sql () (\() (Only (_ :: Int64)) -> delivered)
-                cancel \signal -> do
-                    signal
-                    void (query_ conn "SELECT {'x': i, 'values': [i, i + 1]}::VARIANT FROM range(100000) t(i)" :: IO [Only Variant])
-                cancel \signal -> do
-                    blocked <- newEmptyMVar
-                    void (fold_ conn "SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84') FROM range(100000)" (0 :: Int64) (\n (Only (_ :: RawGeometry)) -> signal >> takeMVar blocked >> pure (n + 1)))
-        batch
-        performMajorGC
-        before <- readUsage
-        forM_ [1 .. batches] \n -> do
-            batch
-            performMajorGC
-            after <- readUsage
-            reportOptional ("open connection, " <> show (n * 70) <> " cancellations") before after
+  withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+    void (execute_ conn "SET streaming_buffer_size = '64KB'")
+    let run mayFinish action = do
+          started <- newEmptyMVar
+          done <- newEmptyMVar
+          let signal = void (tryPutMVar started ())
+          tid <- forkFinally (action signal) (\outcome -> putMVar done outcome >> signal)
+          takeMVar started
+          threadDelay 1000
+          killThread tid
+          outcome <- takeMVar done
+          case outcome of
+            Left err | fromException err == Just ThreadKilled -> pure ()
+            Left err -> fail ("unexpected cancellation error: " <> show err)
+            Right ()
+              | mayFinish -> pure ()
+              | otherwise -> fail "query completed before cancellation"
+          rows <- query_ conn "SELECT 42"
+          unless (rows == [Only (42 :: Int64)]) (fail "connection failed after cancellation")
+        -- These queries block or run until the thread is killed.
+        cancel = run False
+        -- These finite queries can finish before the interrupt reaches them.
+        interrupt = run True
+        batch = forM_ [1 .. 10 :: Int] \_ -> do
+          cancel \signal -> do
+            createFunction conn "leak_cancel_started" (signal >> pure (1 :: Int64))
+            void
+              ( query_
+                  conn
+                  "WITH started AS MATERIALIZED (SELECT leak_cancel_started() AS seed) \
+                  \SELECT sum(sin((a.i + b.j + started.seed)::DOUBLE)) \
+                  \FROM started, range(1000000) a(i), range(1000000) b(j)"
+                  :: IO [Only Double]
+              )
+          interrupt \signal -> do
+            signal
+            void (query_ conn "SELECT {'x': i, 'values': [i, i + 1]} FROM range(100000) t(i)" :: IO [Only FieldValue])
+          cancel \signal -> do
+            blocked <- newEmptyMVar
+            -- Keep the first chunk live until the worker is cancelled.
+            void
+              ( fold_
+                  conn
+                  "SELECT {'x': i, 'values': [i, NULL]} FROM range(100000) t(i)"
+                  (0 :: Int64)
+                  (\n (Only (_ :: FieldValue)) -> signal >> takeMVar blocked >> pure (n + 1))
+              )
+          forM_ [False, True] \arrow -> cancel \signal -> do
+            filtering <- newIORef False
+            createFunction conn "leak_stream_filter" \(_ :: Int64) -> do
+              active <- readIORef filtering
+              when active signal
+              pure active
+            let sql = "SELECT i FROM range(1000000000000) t(i) WHERE NOT leak_stream_filter(i)"
+                delivered = atomicWriteIORef filtering True
+            if arrow
+              then Streaming.foldArrow_ conn sql () (\() _ _ -> delivered)
+              else Streaming.fold_ conn sql () (\() (Only (_ :: Int64)) -> delivered)
+          interrupt \signal -> do
+            signal
+            void (query_ conn "SELECT {'x': i, 'values': [i, i + 1]}::VARIANT FROM range(100000) t(i)" :: IO [Only FieldValue])
+          cancel \signal -> do
+            blocked <- newEmptyMVar
+            void
+              ( fold_
+                  conn
+                  "SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84') FROM range(100000)"
+                  (0 :: Int64)
+                  (\n (Only (_ :: RawGeometry)) -> signal >> takeMVar blocked >> pure (n + 1))
+              )
+    batch
+    performMajorGC
+    before <- readUsage
+    samples <- forM [1 .. batches] \n -> do
+      batch
+      performMajorGC
+      after <- readUsage
+      let label = "open connection, " <> show (n * 70) <> " cancellation attempts"
+      case (before, after) of
+        (Just first, Just current) -> reportWith False label first current
+        _ -> reportOptional label before after
+      pure after
+    case sequence samples of
+      Just usages | batches >= 6 -> do
+        let half = batches `div` 2
+            (early, late) = splitAt half usages
+            lowest = minimumBy (comparing usageRssKb)
+            label = "open connection, lowest rss of cancellation batches 3 to " <> show half <> " -> batches " <> show (half + 1) <> " to " <> show batches
+        report label (lowest (drop 2 early)) (lowest late)
+      _ -> pure ()
 
 -- | Report native counters when the operating system provides them.
 reportOptional :: String -> Maybe Usage -> Maybe Usage -> IO ()
@@ -323,29 +484,85 @@
 
 -- | Print both measurements and fail if either one grew too much.
 report :: String -> Usage -> Usage -> IO ()
-report label before after = do
-    checkRss <- (/= Just "0") <$> lookupEnv "DUCKDB_LEAK_RSS_CHECK"
-    putStrLn label
-    putStrLn $
-        "threads: "
-            <> show (usageThreads before)
-            <> " -> "
-            <> show (usageThreads after)
-            <> " (slack "
-            <> show threadSlack
-            <> ")"
-    putStrLn $
-        "rss kB: "
-            <> show (usageRssKb before)
-            <> " -> "
-            <> show (usageRssKb after)
-            <> " (slack "
-            <> show rssSlackKb
-            <> ")"
-    unless checkRss (putStrLn "RSS assertion disabled for native memory instrumentation")
-    when (threadGrowth > threadSlack || (checkRss && rssGrowth > rssSlackKb)) do
-        putStrLn ("FAIL: " <> label <> " retains DuckDB resources")
-        exitFailure
+report = reportWith True
+
+-- | Print both measurements. Fail if the thread count grew too much. If the
+-- first argument is 'True', also fail if the resident memory grew too much.
+reportWith :: Bool -> String -> Usage -> Usage -> IO ()
+reportWith rssRule label before after = do
+  enabled <- (/= Just "0") <$> lookupEnv "DUCKDB_LEAK_RSS_CHECK"
+  let checkRss = enabled && rssRule
+  putStrLn label
+  putStrLn $
+    "threads: "
+      <> show (usageThreads before)
+      <> " -> "
+      <> show (usageThreads after)
+      <> " (slack "
+      <> show threadSlack
+      <> ")"
+  putStrLn $
+    "rss kB: "
+      <> show (usageRssKb before)
+      <> " -> "
+      <> show (usageRssKb after)
+      <> " (slack "
+      <> show rssSlackKb
+      <> ")"
+  unless enabled (putStrLn "RSS assertion disabled for native memory instrumentation")
+  when (threadGrowth > threadSlack || (checkRss && rssGrowth > rssSlackKb)) do
+    putStrLn ("FAIL: " <> label <> " retains DuckDB resources")
+    exitFailure
   where
     threadGrowth = usageThreads after - usageThreads before
     rssGrowth = usageRssKb after - usageRssKb before
+
+-- | Run the typed registrations through the public API on one connection: a
+-- scalar function with VARCHAR and BIGINT results over 5000 rows, a grouped
+-- aggregate with VARCHAR results, a typed table function, and a cast that
+-- fails.
+-- Each VARCHAR value is longer than 12 bytes, so DuckDB stores it outside the
+-- string slot.
+checkTyped :: Int -> IO ()
+checkTyped batches =
+  withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+    let label prefix n = Text.pack (prefix <> "-" <> show n <> "-with-a-long-suffix")
+        numbers = [0 .. 4999] :: [Int64]
+        labelLength prefix = sum (map (fromIntegral . Text.length . label prefix) numbers) :: Int64
+        groups = [(group, label "total" (sum [n | n <- numbers, n `mod` 50 == group])) | group <- [0 .. 49]]
+    createFunction conn "leak_text" (label "row" :: Int64 -> Text)
+    createFunction conn "leak_double" ((* 2) :: Int64 -> Int64)
+    createAggregate
+      conn
+      "leak_total"
+      Aggregate
+        { aggregateInitial = 0 :: Int64
+        , aggregateStep = \total (Only n) -> pure (total + n)
+        , aggregateCombine = \a b -> pure (a + b)
+        , aggregateResult = pure . label "total"
+        }
+    createTableFunction conn "leak_rows" ["n", "label"] \(Only count) ->
+      pure [(n, label "row" n) | n <- [0 .. count - 1 :: Int64]]
+    registerCustomType conn "leak_tag" (TypeExpression "VARCHAR")
+    -- Each cycle fails the cast, so that the error path of the callback runs.
+    R.registerCast conn (TypeExpression "BIGINT") (TypeExpression "leak_tag") Nothing \_ _ -> throwIO (userError "leak cast refused the value")
+    let cycleTyped = do
+          scalar <- query_ conn "SELECT sum(length(leak_text(i)))::BIGINT, sum(leak_double(i))::BIGINT FROM range(5000) t(i)"
+          unless (scalar == [(labelLength "row", 2 * sum numbers)]) (fail "wrong typed scalar result")
+          grouped <- query_ conn "SELECT i % 50 AS g, leak_total(i) FROM range(5000) t(i) GROUP BY g ORDER BY g"
+          unless (grouped == groups) (fail "wrong typed aggregate result")
+          table <- query_ conn "SELECT count(*), sum(n)::BIGINT, sum(length(label))::BIGINT FROM leak_rows(5000)"
+          unless (table == [(5000 :: Int64, sum numbers, labelLength "row")]) (fail "wrong typed table function result")
+          cast <- try (query_ conn "SELECT CAST(i AS leak_tag) FROM range(5000) t(i)" :: IO [Only Text])
+          case cast of
+            Left (err :: SQLError) | sqlErrorType err == Just ErrorTypeMismatch -> pure ()
+            _ -> fail "wrong cast result"
+        batch = forM_ [1 .. 20 :: Int] (const cycleTyped)
+    batch
+    performMajorGC
+    before <- readUsage
+    forM_ [1 .. batches] \n -> do
+      batch
+      performMajorGC
+      after <- readUsage
+      reportOptional ("open connection, " <> show (n * 20) <> " typed registration cycles") before after
diff --git a/nonthreaded-test/Main.hs b/nonthreaded-test/Main.hs
new file mode 100644
--- /dev/null
+++ b/nonthreaded-test/Main.hs
@@ -0,0 +1,50 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+-- | Check the guard for a program that is not linked with @-threaded@. This
+-- suite has no @-threaded@ in its @ghc-options@. See Note [Callbacks without
+-- the threaded runtime] in "Database.DuckDB.Simple.Callback".
+module Main (main) where
+
+import Control.Exception (try)
+import Control.Monad (unless, void)
+import Data.IORef (modifyIORef', newIORef, readIORef)
+import Data.Int (Int64)
+import qualified Data.Text as Text
+import Database.DuckDB.Simple
+import qualified Database.DuckDB.Simple.Copy as Copy
+import qualified Database.DuckDB.Simple.Logging as Logging
+import qualified Database.DuckDB.Simple.V2.Copy as V2Copy
+import System.Exit (exitFailure)
+
+main :: IO ()
+main = do
+  -- With the setting threads above 1, the registration raises the input error.
+  withConnection ":memory:" \conn -> do
+    void (execute_ conn "SET threads = 4")
+    result <- try (createFunction conn "plus_one" ((+ 1) :: Int64 -> Int64))
+    case result of
+      Left SQLError{sqlErrorType = Just ErrorInputInvalid, sqlErrorMessage}
+        | "not linked with -threaded" `Text.isInfixOf` sqlErrorMessage -> pure ()
+      other -> failWith ("threads = 4: expected the error of the guard, got " <> show other)
+  -- With the setting threads at 1, a query of a registered function runs.
+  withConnection ":memory:" \conn -> do
+    void (execute_ conn "SET threads = 1")
+    createFunction conn "plus_one" ((+ 1) :: Int64 -> Int64)
+    rows <- query_ conn "SELECT sum(plus_one(i))::BIGINT FROM range(100000) t(i)" :: IO [Only Int64]
+    unless (rows == [Only 5000050000]) (failWith ("threads = 1: expected 5000050000, got " <> show rows))
+    checkGuard "COPY" $ Copy.registerCopyFromFunction conn "lines" (\_ -> pure [Only (1 :: Int64)])
+    let noop _ _ = pure ()
+    checkGuard "COPY" $ V2Copy.registerCopyToCallbacks conn "raw_lines" (V2Copy.copyToCallbacks noop noop)
+    flushCount <- newIORef (0 :: Int)
+    checkGuard "log sink" $ Logging.registerLogSink conn "events" (const (pure ())) (modifyIORef' flushCount (+ 1))
+    flushed <- readIORef flushCount
+    unless (flushed == 1) (failWith ("rejected log sink: expected one flush, got " <> show flushed))
+  where
+    checkGuard kind action =
+      try action >>= \result -> case result of
+        Left SQLError{sqlErrorType = Just ErrorInputInvalid, sqlErrorMessage}
+          | (kind <> " callbacks require a program linked with -threaded") `Text.isInfixOf` sqlErrorMessage -> pure ()
+        other -> failWith ("threads = 1: expected the " <> Text.unpack kind <> " guard, got " <> show (other :: Either SQLError ()))
+    failWith message = putStrLn message >> exitFailure
diff --git a/src/Database/DuckDB/Simple.hs b/src/Database/DuckDB/Simple.hs
--- a/src/Database/DuckDB/Simple.hs
+++ b/src/Database/DuckDB/Simple.hs
@@ -3,701 +3,646 @@
 {-# 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
-    Connection,
-    open,
-    openWithConfig,
-    ConnectionOptions (..),
-    defaultConnectionOptions,
-    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 (..),
-    FormatError (..),
-    ResultError (..),
-    FieldParser,
-    FromField (..),
-    FromRow (..),
-    RowParser,
-    field,
-    fieldWith,
-    numFieldsRemaining,
-    -- Re-export parameter helper types.
-    ToField (..),
-    ToRow (..),
-    FieldBinding,
-    NamedParam (..),
-    DuckDBColumnType (..),
-    duckdbColumnType,
-    Null (..),
-    Only (..),
-    (:.) (..),
-
-    -- * User-defined scalar functions
-    Function (..),
-    createFunction,
-    createFunctionWithState,
-    deleteFunction,
-) where
-
-import Control.Exception (SomeException, bracket, finally, mask, mask_, onException, throwIO, try)
-import Control.Monad (forM, forM_, join, void, when, zipWithM_)
-import Data.IORef (atomicModifyIORef', mkWeakIORef, newIORef)
-import Data.Maybe (isJust, isNothing)
-import qualified Data.Set as Set
-import Data.Text (Text)
-import qualified Data.Text as Text
-import qualified Data.Text.Foreign as TextForeign
-import Database.DuckDB.FFI
-import Database.DuckDB.Simple.FromField (
-    Field (..),
-    FieldParser,
-    FromField (..),
-    ResultError (..),
- )
-import Database.DuckDB.Simple.FromRow (
-    FromRow (..),
-    RowParser,
-    field,
-    fieldWith,
-    numFieldsRemaining,
-    parseRow,
-    rowErrorsToSqlError,
- )
-import Database.DuckDB.Simple.Function (Function (..), createFunction, createFunctionWithState, deleteFunction)
-import Database.DuckDB.Simple.Internal (
-    Connection (..),
-    ConnectionState (..),
-    Query (..),
-    ResultMode (..),
-    SQLError (..),
-    Statement (..),
-    StatementState (..),
-    StatementStreamState (..),
-    fetchPrepareError,
-    keepAlive,
-    peekUtf8CString,
-    runInterruptibleQuery,
-    withConnectionHandle,
-    withQueryCString,
-    withResult,
-    withStatementHandle,
- )
-import Database.DuckDB.Simple.Ok (Ok (..))
-import Database.DuckDB.Simple.Result (cleanupStatementStreamRef, collectRows, resetStatementStream)
-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.TypeCache (TypeCache, createTypeCache, defaultGeometryCRS, destroyTypeCache)
-import Database.DuckDB.Simple.Types (FormatError (..), Null (..), Only (..), (:.) (..))
-import Foreign.C.String (CString)
-import Foreign.Marshal.Alloc (alloca)
-import Foreign.Ptr (Ptr, castPtr, nullPtr)
-import Foreign.Storable (peek, poke)
-
--- | 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}
-
--- | Settings that duckdb-simple applies when it opens a connection.
-data ConnectionOptions = ConnectionOptions
-    { connectionConfig :: [(Text, Text)]
-    -- ^ DuckDB configuration flags, as for 'openWithConfig'.
-    , connectionGeometryCRS :: [Text]
-    {- ^ CRS definitions. The connection reads a GEOMETRY type for each CRS
-    the first time a parameter needs a VARIANT type or a GEOMETRY type with a
-    CRS. Parameters can then contain GEOMETRY types with these CRSs.
-    -}
-    }
-    deriving (Eq, Show)
-
--- | No configuration flags, and the CRS @OGC:CRS84@.
-defaultConnectionOptions :: ConnectionOptions
-defaultConnectionOptions =
-    ConnectionOptions
-        { connectionConfig = []
-        , connectionGeometryCRS = defaultGeometryCRS
-        }
-
-{- | Open a DuckDB database with options. The connection reads the VARIANT type
-and the GEOMETRY types for the configured CRSs the first time a parameter
-needs one of them. It reads them with one query on a separate connection.
--}
-openWithOptions :: FilePath -> ConnectionOptions -> IO Connection
-openWithOptions path ConnectionOptions{connectionConfig, connectionGeometryCRS} =
-    mask_ do
-        db <- openDatabaseWithConfig path connectionConfig
-        conn <-
-            connectDatabase db
-                `onException` closeDatabaseHandle db
-        let closeBoth = closeConnectionHandle conn >> closeDatabaseHandle db
-        cache <-
-            createTypeCache db connectionGeometryCRS
-                `onException` closeBoth
-        createConnection db conn cache
-            `onException` (destroyTypeCache cache >> closeBoth)
-
--- | Close a connection.  The operation is idempotent.
-close :: Connection -> IO ()
-close Connection{connectionState} =
-    mask_ $
-        join $
-            atomicModifyIORef' connectionState \case
-                ConnectionClosed -> (ConnectionClosed, pure ())
-                openState@(ConnectionOpen{}) ->
-                    (ConnectionClosed, closeHandles openState)
-
--- | 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 =
-    mask_ do
-        handle <-
-            withConnectionHandle conn \connPtr ->
-                withQueryCString queryText \sql ->
-                    alloca \stmtPtr -> do
-                        poke stmtPtr nullPtr
-                        flip onException (c_duckdb_destroy_prepare stmtPtr) do
-                            rc <- runInterruptibleQuery conn (c_duckdb_prepare connPtr sql stmtPtr)
-                            stmt <- peek stmtPtr
-                            if rc == DuckDBSuccess
-                                then pure stmt
-                                else do
-                                    errMsg <- fetchPrepareError (Text.pack "duckdb-simple: prepare failed") stmt
-                                    throwIO $ mkPrepareError queryText errMsg
-        createStatement conn handle queryText
-            `onException` destroyPrepared handle
-
--- | Finalise a prepared statement.  The operation is idempotent.
-closeStatement :: Statement -> IO ()
-closeStatement stmt@Statement{statementState} = mask_ do
-    resetStatementStream stmt
-    finish <- atomicModifyIORef' statementState \case
-        StatementClosed -> (StatementClosed, pure ())
-        StatementOpen{statementHandle} ->
-            (StatementClosed, destroyPrepared statementHandle)
-    finish
-
--- | 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.
-bind :: Statement -> [FieldBinding] -> IO ()
-bind stmt fields = do
-    resetStatementStream stmt
-    withStatementHandle stmt \handle -> do
-        let actual = length fields
-        expected <- fmap fromIntegral (c_duckdb_nparams handle)
-        when (actual /= expected) $
-            throwFormatErrorBindings stmt (parameterCountMessage expected actual) fields
-        parameterNames <- fetchParameterNames handle expected
-        when (any isJust parameterNames) $
-            throwFormatErrorBindings stmt (Text.pack "duckdb-simple: statement defines named parameters; use executeNamed or bindNamed") fields
-    clearStatementBindings stmt
-    zipWithM_ apply [1 ..] fields
-  where
-    parameterCountMessage expected actual =
-        Text.pack $
-            "duckdb-simple: SQL query contains "
-                <> show expected
-                <> " parameter(s), but "
-                <> show actual
-                <> " argument(s) were supplied"
-
-    apply :: Int -> FieldBinding -> IO ()
-    apply idx = bindFieldBinding stmt (fromIntegral idx :: DuckDBIdx)
-
--- | Bind named parameters to a prepared statement, preserving any positional bindings.
-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
-                ]
-        apply (name, binding) = do
-            mIdx <- namedParameterIndex stmt name
-            case mIdx of
-                Nothing ->
-                    throwFormatErrorNamed stmt (unknownNameMessage name) bindings
-                Just idx -> bindFieldBinding stmt (fromIntegral idx :: DuckDBIdx) binding
-     in do
-            resetStatementStream stmt
-            let names = map (normalizeName . fst) bindings
-            when (Set.size (Set.fromList names) /= length names) $
-                throwFormatErrorNamed stmt (Text.pack "duckdb-simple: duplicate named parameter") bindings
-            withStatementHandle stmt \handle -> do
-                let actual = length bindings
-                expected <- fmap fromIntegral (c_duckdb_nparams handle)
-                when (actual /= expected) $
-                    throwFormatErrorNamed stmt (parameterCountMessage expected actual) bindings
-                parameterNames <- fetchParameterNames handle expected
-                when (all isNothing parameterNames && expected > 0) $
-                    throwFormatErrorNamed stmt (Text.pack "duckdb-simple: statement does not define named parameters; use positional bindings or adjust the SQL") bindings
-            clearStatementBindings stmt
-            mapM_ apply bindings
-
-fetchParameterNames :: DuckDBPreparedStatement -> Int -> IO [Maybe Text]
-fetchParameterNames handle count =
-    forM [1 .. count] \idx ->
-        bracket (c_duckdb_parameter_name handle (fromIntegral idx)) (c_duckdb_free . castPtr) \namePtr ->
-            if namePtr == nullPtr
-                then pure Nothing
-                else do
-                    name <- peekUtf8CString namePtr
-                    let normalized = normalizeName name
-                    if normalized == Text.pack (show idx)
-                        then pure Nothing
-                        else pure (Just name)
-
--- | Remove all parameter bindings associated with a prepared statement.
-clearStatementBindings :: Statement -> IO ()
-clearStatementBindings stmt =
-    withStatementHandle stmt \handle -> do
-        resetStatementStream stmt
-        rc <- c_duckdb_clear_bindings handle
-        when (rc /= DuckDBSuccess) $ do
-            err <- fetchPrepareError (Text.pack "duckdb-simple: prepare failed") handle
-            throwIO $ mkPrepareError (statementQuery stmt) err
-
--- | Look up the 1-based index of a named placeholder.
-namedParameterIndex :: Statement -> Text -> IO (Maybe Int)
-namedParameterIndex stmt name =
-    withStatementHandle stmt \handle -> do
-        when (Text.any (== '\0') name) $
-            throwIO (mkPrepareError (statementQuery stmt) (Text.pack "duckdb-simple: parameter name contains NUL"))
-        let normalized = normalizeName name
-        TextForeign.withCString normalized \cName ->
-            alloca \idxPtr -> do
-                rc <- c_duckdb_bind_parameter_index handle idxPtr cName
-                if rc == DuckDBSuccess
-                    then do
-                        idx <- peek idxPtr
-                        if idx == 0
-                            then pure Nothing
-                            else pure (Just (fromIntegral idx))
-                    else pure Nothing
-
--- | Retrieve the number of columns produced by the supplied prepared statement.
-columnCount :: Statement -> IO Int
-columnCount stmt =
-    withStatementHandle stmt $ \handle ->
-        fmap fromIntegral (c_duckdb_prepared_statement_column_count handle)
-
--- | Look up the zero-based column name exposed by a prepared statement result.
-columnName :: Statement -> Int -> IO Text
-columnName stmt columnIndex
-    | columnIndex < 0 = throwIO (columnIndexError stmt columnIndex Nothing)
-    | otherwise =
-        withStatementHandle stmt \handle -> do
-            total <- fmap fromIntegral (c_duckdb_prepared_statement_column_count handle)
-            when (columnIndex >= total) $
-                throwIO (columnIndexError stmt columnIndex (Just total))
-            bracket (c_duckdb_prepared_statement_column_name handle (fromIntegral columnIndex)) (c_duckdb_free . castPtr) \namePtr ->
-                if namePtr == nullPtr
-                    then throwIO (columnNameUnavailableError stmt columnIndex)
-                    else peekUtf8CString namePtr
-
-{- | 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 =
-    withStatementHandle stmt \handle -> do
-        resetStatementStream stmt
-        withResult (statementConnection stmt) (statementQuery stmt) (c_duckdb_execute_prepared handle) resultRowsChanged
-
--- | 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.
-executeMany :: (ToRow q) => Connection -> Query -> [q] -> IO Int
-executeMany conn queryText rows =
-    withStatement conn queryText \stmt -> do
-        sum <$> mapM (\row -> bind stmt (toRow row) >> executeStatement stmt) rows
-
--- | Execute an ad-hoc query without parameters and return the affected row count.
-execute_ :: Connection -> Query -> IO Int
-execute_ conn queryText =
-    withConnectionHandle conn \connPtr ->
-        withQueryCString queryText \sql ->
-            withResult conn queryText (c_duckdb_query connPtr sql) resultRowsChanged
-
--- | 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.
-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)
-        withStatementHandle stmt \handle ->
-            withResult conn queryText (c_duckdb_execute_prepared handle) \resPtr ->
-                collectRows queryText resPtr >>= 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
-        withStatementHandle stmt \handle ->
-            withResult conn queryText (c_duckdb_execute_prepared handle) \resPtr ->
-                collectRows queryText resPtr >>= 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 =
-    withConnectionHandle conn \connPtr ->
-        withQueryCString queryText \sql ->
-            withResult conn queryText (c_duckdb_query connPtr sql) \resPtr ->
-                collectRows queryText resPtr >>= convertRowsWith parser queryText
-
--- Cursors and folds ---------------------------------------------------------
-
-{- | Fold a parameterised result without constructing a complete Haskell row list.
-  DuckDB materializes the native result before decoding starts. Native memory
-  use depends on the result size; the step function controls Haskell memory use.
--}
-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
-        resetStatementStream stmt
-        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 -> do
-        resetStatementStream 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
-        resetStatementStream stmt
-        bindNamed stmt params
-        Result.foldStatementWith MaterializedResult fromRow stmt initial step
-
--- | Fetch the next row. The first call materializes the native result.
-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
-    begin = Query (Text.pack "BEGIN TRANSACTION")
-    commit = Query (Text.pack "COMMIT")
-    rollback = Query (Text.pack "ROLLBACK")
-
--- Internal helpers -----------------------------------------------------------
-
-createConnection :: DuckDBDatabase -> DuckDBConnection -> TypeCache -> IO Connection
-createConnection db conn cache = do
-    ref <- newIORef (ConnectionOpen db conn cache)
-    _ <-
-        mkWeakIORef ref $
-            join $
-                atomicModifyIORef' ref \case
-                    ConnectionClosed -> (ConnectionClosed, pure ())
-                    openState@(ConnectionOpen{}) ->
-                        (ConnectionClosed, closeHandles openState)
-    pure Connection{connectionState = ref}
-
-createStatement :: Connection -> DuckDBPreparedStatement -> Query -> IO Statement
-createStatement parent handle queryText = do
-    ref <- newIORef (StatementOpen handle)
-    streamRef <- newIORef StatementStreamIdle
-    _ <-
-        mkWeakIORef ref $
-            keepAlive parent do
-                join $
-                    atomicModifyIORef' ref $ \case
-                        StatementClosed -> (StatementClosed, pure ())
-                        StatementOpen{statementHandle} ->
-                            ( StatementClosed
-                            , do
-                                cleanupStatementStreamRef streamRef
-                                destroyPrepared statementHandle
-                            )
-    pure
-        Statement
-            { statementState = ref
-            , statementConnection = parent
-            , statementQuery = queryText
-            , statementStream = streamRef
-            }
-
-openDatabaseWithConfig :: FilePath -> [(Text, Text)] -> IO DuckDBDatabase
-openDatabaseWithConfig path settings = do
-    when ('\0' `elem` path || any (\(name, value) -> Text.any (== '\0') name || Text.any (== '\0') value) settings) $
-        throwIO (mkOpenError (Text.pack "duckdb-simple: database path or configuration contains NUL"))
-    alloca \dbPtr ->
-        alloca \configPtr ->
-            alloca \errPtr -> do
-                rcConfig <- c_duckdb_create_config configPtr
-                when (rcConfig /= DuckDBSuccess) $
-                    throwIO (mkOpenError (Text.pack "duckdb-simple: failed to allocate DuckDB config"))
-                config <- peek configPtr
-                poke errPtr nullPtr
-                let destroyConfig =
-                        when (config /= nullPtr) $
-                            alloca \cfgPtr -> poke cfgPtr config >> c_duckdb_destroy_config cfgPtr
-                flip finally destroyConfig $
-                    do
-                        forM_ settings \(name, value) ->
-                            TextForeign.withCString name \cName ->
-                                TextForeign.withCString value \cValue -> do
-                                    rcSet <- c_duckdb_set_config config cName cValue
-                                    when (rcSet /= DuckDBSuccess)
-                                        $ throwIO
-                                        $ mkOpenError
-                                        $ Text.concat
-                                            [ Text.pack "duckdb-simple: failed to set config option "
-                                            , name
-                                            ]
-                        TextForeign.withCString (Text.pack path) \cPath -> do
-                            rc <- c_duckdb_open_ext cPath dbPtr config errPtr
-                            if rc == DuckDBSuccess
-                                then do
-                                    db <- peek dbPtr
-                                    maybeFreeErr errPtr
-                                    pure db
-                                else do
-                                    errMsg <- peekError errPtr
-                                    maybeFreeErr errPtr
-                                    throwIO $ mkOpenError errMsg
-
-connectDatabase :: DuckDBDatabase -> IO DuckDBConnection
-connectDatabase db =
-    alloca \connPtr -> do
-        rc <- c_duckdb_connect db connPtr
-        if rc == DuckDBSuccess
-            then peek connPtr
-            else throwIO mkConnectError
-
-closeHandles :: ConnectionState -> IO ()
-closeHandles ConnectionClosed = pure ()
-closeHandles ConnectionOpen{connectionDatabase, connectionHandle, connectionTypeCache} = do
-    destroyTypeCache connectionTypeCache
-    closeConnectionHandle connectionHandle
-    closeDatabaseHandle connectionDatabase
-
-closeConnectionHandle :: DuckDBConnection -> IO ()
-closeConnectionHandle conn =
-    alloca \ptr -> poke ptr conn >> c_duckdb_disconnect ptr
-
-closeDatabaseHandle :: DuckDBDatabase -> IO ()
-closeDatabaseHandle db =
-    alloca \ptr -> poke ptr db >> c_duckdb_close ptr
-
-destroyPrepared :: DuckDBPreparedStatement -> IO ()
-destroyPrepared stmt =
-    alloca \ptr -> poke ptr stmt >> c_duckdb_destroy_prepare ptr
-
-mkOpenError :: Text -> SQLError
-mkOpenError msg =
-    SQLError
-        { sqlErrorMessage = msg
-        , sqlErrorType = Nothing
-        , sqlErrorQuery = Nothing
-        }
-
-mkConnectError :: SQLError
-mkConnectError =
-    SQLError
-        { sqlErrorMessage = Text.pack "duckdb-simple: failed to create connection handle"
-        , sqlErrorType = Nothing
-        , sqlErrorQuery = Nothing
-        }
-
-mkPrepareError :: Query -> Text -> SQLError
-mkPrepareError queryText msg =
-    SQLError
-        { sqlErrorMessage = msg
-        , sqlErrorType = Nothing
-        , sqlErrorQuery = Just queryText
-        }
-
-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
-
-columnIndexError :: Statement -> Int -> Maybe Int -> SQLError
-columnIndexError stmt idx total =
-    let base =
-            Text.concat
-                [ Text.pack "duckdb-simple: 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 SQLError
-            { sqlErrorMessage = message
-            , sqlErrorType = Nothing
-            , sqlErrorQuery = Just (statementQuery stmt)
-            }
-
-columnNameUnavailableError :: Statement -> Int -> SQLError
-columnNameUnavailableError stmt idx =
-    SQLError
-        { sqlErrorMessage =
-            Text.concat
-                [ Text.pack "duckdb-simple: column name unavailable for index "
-                , Text.pack (show idx)
-                ]
-        , sqlErrorType = Nothing
-        , sqlErrorQuery = Just (statementQuery stmt)
-        }
-
-normalizeName :: Text -> Text
-normalizeName name =
-    case Text.uncons name of
-        Just (prefix, rest)
-            | prefix == ':' || prefix == '$' || prefix == '@' -> rest
-        _ -> name
-
-resultRowsChanged :: Ptr DuckDBResult -> IO Int
-resultRowsChanged resPtr = fromIntegral <$> c_duckdb_rows_changed resPtr
-
-convertRows :: (FromRow r) => Query -> [[Field]] -> IO [r]
-convertRows = convertRowsWith fromRow
-
-convertRowsWith :: RowParser r -> Query -> [[Field]] -> IO [r]
-convertRowsWith parser queryText rows =
-    case traverse (parseRow parser) rows of
-        Errors err -> throwIO (rowErrorsToSqlError queryText err)
-        Ok ok -> pure ok
-
-peekError :: Ptr CString -> IO Text
-peekError ptr = do
-    errPtr <- peek ptr
-    if errPtr == nullPtr
-        then pure (Text.pack "duckdb-simple: failed to open database")
-        else do
-            peekUtf8CString errPtr
-
-maybeFreeErr :: Ptr CString -> IO ()
-maybeFreeErr ptr = do
-    errPtr <- peek ptr
-    when (errPtr /= nullPtr) $ c_duckdb_free (castPtr errPtr)
+-- |
+-- 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
diff --git a/src/Database/DuckDB/Simple/Arrow.hs b/src/Database/DuckDB/Simple/Arrow.hs
--- a/src/Database/DuckDB/Simple/Arrow.hs
+++ b/src/Database/DuckDB/Simple/Arrow.hs
@@ -1,48 +1,47 @@
-{- |
-Module      : Database.DuckDB.Simple.Arrow
-Description : Scoped Arrow export through the DuckDB C Data Interface.
-
-These functions execute a query and visit its Arrow batches. DuckDB materializes
-the native result before the first callback. The Haskell code converts and
-releases one batch at a time. Native result memory can grow with the query size.
-
-Each callback receives a separate schema and array. It may read them or pass
-them to a consumer that releases or moves them under the Arrow C Data Interface.
-The fold releases objects that the consumer has not released or moved, including
-when the callback throws. The consumer must release any contents it moves.
-
-The pointers themselves are valid during the callback only. To retain contents,
-the consumer must move the root structs into its own storage and set the source
-release fields to NULL. Do not retain the original pointers or move children
-separately. Moved contents remain valid after the query and connection close.
-Haskell consumers must mask asynchronous exceptions while moving a root and
-register its cleanup before restoring exceptions.
-
-This module uses the schema and chunk conversion API. The older query and scan
-functions in @Database.DuckDB.FFI.Deprecated@ are deprecated by DuckDB.
--}
+-- |
+-- Module      : Database.DuckDB.Simple.Arrow
+-- Description : Scoped Arrow export through the Arrow C Data Interface.
+--
+-- These functions execute a query with V2 and visit its Arrow batches. The
+-- default fold collects owned batches and closes the native cursor before the
+-- first callback.
+-- It releases each batch after its callback. Memory use can grow with the query size.
+--
+-- Each callback receives a separate schema and array. It may read them or pass
+-- them to a consumer that releases or moves them under the Arrow C Data Interface.
+-- The fold releases objects that the consumer has not released or moved, including
+-- when the callback throws. The consumer must release any contents it moves.
+--
+-- The pointers themselves are valid during the callback only. To retain contents,
+-- the consumer must move the root structs into its own storage and set the source
+-- release fields to NULL. Do not retain the original pointers or move children
+-- separately. Moved contents remain valid after the query and connection close.
+-- Haskell consumers must mask asynchronous exceptions while moving a root and
+-- register its cleanup before restoring exceptions.
 module Database.DuckDB.Simple.Arrow (
-    foldArrow,
-    foldArrow_,
+  foldArrow,
+  foldArrow_,
+  releaseArrowSchema,
+  releaseArrowArray,
+  releaseArrowStream,
 ) where
 
-import Database.DuckDB.FFI (ArrowArray, ArrowSchema)
-import Database.DuckDB.Simple.Arrow.Internal (foldArrowWith)
+import Database.DuckDB.FFI.V2 (ArrowArray, ArrowSchema)
+import Database.DuckDB.Simple.Arrow.Internal (foldArrowWith, releaseArrowArray, releaseArrowSchema, releaseArrowStream)
 import Database.DuckDB.Simple.Internal (Connection, Query, ResultMode (MaterializedResult))
 import Database.DuckDB.Simple.ToRow (ToRow)
 import Foreign.Ptr (Ptr)
 
-{- | Execute a parameterized query and fold over Arrow batches.
-
-The schema includes the executed result's column names and types. The callback
-runs once per nonempty batch and never runs for an empty result. The schema and
-array pointers are valid only during the callback. A consumer may release or
-move their contents as described in the module documentation. The accumulator
-is evaluated to weak head normal form after each callback.
-
-DuckDB materializes the native result before this fold starts. This function
-does not provide bounded-memory query execution.
--}
+-- | Execute a parameterized query and fold over Arrow batches.
+--
+-- The schema includes the executed result's column names and types. The callback
+-- runs once per nonempty batch and never runs for an empty result. The schema and
+-- array pointers are valid only during the callback. A consumer may release or
+-- move their contents as described in the module documentation. The accumulator
+-- is evaluated to weak head normal form after each callback.
+--
+-- The fold collects all owned batches and closes the native cursor before it
+-- calls the step function. It does not provide bounded-memory query execution.
 foldArrow :: (ToRow q) => Connection -> Query -> q -> a -> (a -> Ptr ArrowSchema -> Ptr ArrowArray -> IO a) -> IO a
 foldArrow = foldArrowWith MaterializedResult
 
diff --git a/src/Database/DuckDB/Simple/Arrow/Internal.hs b/src/Database/DuckDB/Simple/Arrow/Internal.hs
--- a/src/Database/DuckDB/Simple/Arrow/Internal.hs
+++ b/src/Database/DuckDB/Simple/Arrow/Internal.hs
@@ -1,91 +1,127 @@
 {-# LANGUAGE BlockArguments #-}
-{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE MultiWayIf #-}
+{-# LANGUAGE OverloadedRecordDot #-}
+{-# LANGUAGE TypeApplications #-}
 
-{- |
-Module      : Database.DuckDB.Simple.Arrow.Internal
-Description : Shared ownership and conversion for Arrow result batches.
--}
+-- |
+-- Module      : Database.DuckDB.Simple.Arrow.Internal
+-- Description : V2 Arrow execution and ownership of exported schemas and arrays.
 module Database.DuckDB.Simple.Arrow.Internal (
-    foldArrowWith,
+  foldArrowWith,
+  releaseArrowSchema,
+  releaseArrowArray,
+  releaseArrowStream,
 ) where
 
-import Control.Exception (bracket, bracket_, throwIO)
-import Control.Monad (forM, when)
-import Database.DuckDB.FFI
+import Control.Exception (bracket, finally, mask, mask_, onException)
+import Control.Monad (when)
+import Data.IORef (atomicModifyIORef', newIORef, readIORef)
+import Data.Proxy (Proxy (..))
 import Database.DuckDB.Simple (bind, withStatement)
-import Database.DuckDB.Simple.Internal (Connection, Query, ResultMode, SQLError (..), destroyDataChunk, destroyLogicalType, executePreparedResult, fetchResultChunk, peekUtf8CString, throwResultError, withResult, withStatementHandle)
+import Database.DuckDB.Simple.Internal
 import Database.DuckDB.Simple.ToRow (ToRow (..))
-import Foreign.Marshal.Alloc (alloca)
-import Foreign.Marshal.Array (withArray)
-import Foreign.Marshal.Utils (fillBytes, withMany)
-import Foreign.Ptr (Ptr, nullPtr)
-import Foreign.Storable (Storable (sizeOf), poke)
+import Foreign.Marshal.Alloc (free, malloc)
+import Foreign.Marshal.Utils (fillBytes)
+import Foreign.Ptr (Ptr, nullFunPtr)
+import Foreign.Storable (peek)
+import HsBindgen.Runtime.Marshal (staticSizeOf)
+import HsBindgen.Runtime.Support.FunPtr (fromFunPtr)
 
--- | Fold over Arrow batches with the selected native execution mode.
+-- | Owned root storage for an Arrow schema and array.
+type ArrowBatch = (Ptr ArrowSchema, Ptr ArrowArray)
+
+-- | Fold over owned Arrow batches with materialized or incremental execution.
 foldArrowWith :: (ToRow q) => ResultMode -> Connection -> Query -> q -> a -> (a -> Ptr ArrowSchema -> Ptr ArrowArray -> IO a) -> IO a
-foldArrowWith mode conn queryText params initial step =
-    withStatement conn queryText \stmt -> do
-        bind stmt (toRow params)
-        withStatementHandle stmt \handle ->
-            withResult conn queryText (executePreparedResult mode handle) \result ->
-                bracket (c_duckdb_result_get_arrow_options result) destroyArrowOptions \options ->
-                    loop result options initial
-  where
-    loop result options acc = do
-        next <- bracket (fetchResultChunk mode conn result) destroyDataChunk \chunk ->
-            if chunk == nullPtr
-                then do
-                    throwResultError queryText result
-                    pure Nothing
-                else do
-                    rowCount <- c_duckdb_data_chunk_get_size chunk
-                    if rowCount == 0
-                        then pure (Just acc)
-                        else withResultSchema queryText result options \schema ->
-                            withArrowArray \array -> do
-                                checkArrowError queryText (c_duckdb_data_chunk_to_arrow options chunk array)
-                                nextAcc <- step acc schema array
-                                nextAcc `seq` pure (Just nextAcc)
-        case next of
-            Nothing -> pure acc
-            Just nextAcc -> loop result options nextAcc
+foldArrowWith mode conn queryText params initial step = withStatement conn queryText \stmt -> do
+  bind stmt (toRow params)
+  mask \restore -> do
+    -- The native calls of the fold attach its query to an error. The step runs
+    -- outside them, so that an error of the step keeps its own query, as in
+    -- the row folds.
+    let native = withQueryError queryText
+        deliver acc (schema, array) = do
+          -- A step that closes the connection stops the later steps.
+          withStatementHandle stmt (\_ -> pure ())
+          next <- restore (step acc schema array)
+          next `seq` pure next
+    case mode of
+      StreamingResult ->
+        -- Serialize the execution call. The stream stays open after it. See
+        -- Note [Connection lock] in "Database.DuckDB.Simple.Internal".
+        bracket (native (withConnectionLock conn (executePreparedArrowResult stmt))) (const (native (clearArrowResult stmt))) \result ->
+          -- Recurse outside the handle scope, so that the stack does not grow for each batch.
+          -- Each fetch holds the connection lock. The step runs after the
+          -- fetch, without the lock.
+          let stream acc =
+                withStatementHandle stmt (\_ -> withConnectionLock conn (fetchBatch stmt result)) >>= \case
+                  Nothing -> pure acc
+                  Just batch -> (deliver acc batch `finally` releaseBatch batch) >>= stream
+          in  stream initial
+      MaterializedResult -> do
+        owned <- newIORef []
+        let gather result =
+              fetchBatch stmt result >>= \case
+                Nothing -> pure ()
+                Just batch -> atomicModifyIORef' owned (\batches -> (batch : batches, ())) >> gather result
+            consume acc =
+              atomicModifyIORef' owned (\case [] -> ([], Nothing); batch : rest -> (rest, Just batch)) >>= \case
+                Nothing -> pure acc
+                Just batch -> do
+                  acc' <- deliver acc batch `finally` releaseBatch batch
+                  consume acc'
+            release = readIORef owned >>= mapM_ releaseBatch
+        flip finally release do
+          -- Hold the lock until the native result closes. The callbacks run after that.
+          -- The batches are in storage that this thread releases. See
+          -- Note [Result window] in "Database.DuckDB.Simple.Internal".
+          native (withResultWindow conn (const (pure ())) (withArrowResult stmt gather))
+          atomicModifyIORef' owned (\batches -> (reverse batches, ()))
+          consume initial
 
--- | Convert the executed result's schema and release it after the action.
-withResultSchema :: Query -> Ptr DuckDBResult -> DuckDBArrowOptions -> (Ptr ArrowSchema -> IO a) -> IO a
-withResultSchema queryText result options action = do
-    count <- c_duckdb_column_count result
-    let indices = if count == 0 then [] else [0 .. count - 1]
-    withMany (\idx -> bracket (c_duckdb_column_logical_type result idx) destroyLogicalType) indices \types -> do
-        names <- forM indices (c_duckdb_column_name result)
-        withArray types \typeArray ->
-            withArray names \nameArray ->
-                alloca \schema ->
-                    bracket_ (fillBytes schema 0 (sizeOf (undefined :: ArrowSchema))) (releaseArrowSchema schema) do
-                        checkArrowError queryText (c_duckdb_to_arrow_schema options typeArray nameArray count schema)
-                        action schema
+-- | Fetch one owned nonempty batch and its independent schema. See
+-- Note [Interruptible native calls] in "Database.DuckDB.Simple.Internal".
+fetchBatch :: Statement -> DuckDBV2ArrowResultHandle -> IO (Maybe ArrowBatch)
+fetchBatch stmt result = mask_ do
+  schema <- malloc
+  fillBytes schema 0 (staticSizeOf (Proxy @ArrowSchema))
+  array <- malloc `onException` free schema
+  fillBytes array 0 (staticSizeOf (Proxy @ArrowArray))
+  let batch = (schema, array)
+  exported <- flip onException (releaseBatch batch) do
+    runInterruptibleQuery (statementConnection stmt) (checked (c_duckdb_v2_arrow_result_fetch_array result array))
+    exported <- peek array
+    when (exported.release /= nullFunPtr && exported.length /= 0) $
+      checked (c_duckdb_v2_arrow_result_get_schema result schema)
+    pure exported
+  if
+    | exported.release == nullFunPtr -> releaseBatch batch >> pure Nothing
+    | exported.length == 0 -> releaseBatch batch >> fetchBatch stmt result
+    | otherwise -> pure (Just batch)
 
--- | Allocate an empty Arrow array and release its contents after the action.
-withArrowArray :: (Ptr ArrowArray -> IO a) -> IO a
-withArrowArray action =
-    alloca \array ->
-        bracket_ (fillBytes array 0 (sizeOf (undefined :: ArrowArray))) (releaseArrowArray array) (action array)
+-- | Release both Arrow objects and free their root storage.
+releaseBatch :: ArrowBatch -> IO ()
+releaseBatch (schema, array) =
+  mask_ $
+    (releaseArrowArray array `finally` free array) `finally` (releaseArrowSchema schema `finally` free schema)
 
--- | Convert and release an owned Arrow conversion error.
-checkArrowError :: Query -> IO DuckDBErrorData -> IO ()
-checkArrowError queryText makeError =
-    bracket makeError destroyError \err ->
-        when (err /= nullPtr) do
-            failed <- c_duckdb_error_data_has_error err
-            when (failed /= 0) do
-                messagePtr <- c_duckdb_error_data_message err
-                message <- if messagePtr == nullPtr then pure "DuckDB Arrow conversion failed" else peekUtf8CString messagePtr
-                errorType <- c_duckdb_error_data_error_type err
-                throwIO (SQLError message (Just errorType) (Just queryText))
+-- | Release an initialized schema if its release callback is present.
+-- The caller still owns the storage for the structure.
+releaseArrowSchema :: Ptr ArrowSchema -> IO ()
+releaseArrowSchema ptr = mask_ do
+  schema <- peek ptr
+  when (schema.release /= nullFunPtr) $ fromFunPtr schema.release ptr
 
--- | Destroy the result's Arrow conversion options.
-destroyArrowOptions :: DuckDBArrowOptions -> IO ()
-destroyArrowOptions options = alloca \ptr -> poke ptr options >> c_duckdb_destroy_arrow_options ptr
+-- | Release an initialized array if its release callback is present.
+-- The caller still owns the storage for the structure.
+releaseArrowArray :: Ptr ArrowArray -> IO ()
+releaseArrowArray ptr = mask_ do
+  array <- peek ptr
+  when (array.release /= nullFunPtr) $ fromFunPtr array.release ptr
 
--- | Destroy an Arrow conversion error handle.
-destroyError :: DuckDBErrorData -> IO ()
-destroyError err = alloca \ptr -> poke ptr err >> c_duckdb_destroy_error_data ptr
+-- | Release an initialized stream if its release callback is present.
+-- The caller still owns the storage for the structure.
+releaseArrowStream :: Ptr ArrowArrayStream -> IO ()
+releaseArrowStream ptr = mask_ do
+  stream <- peek ptr
+  when (stream.release /= nullFunPtr) $ fromFunPtr stream.release ptr
diff --git a/src/Database/DuckDB/Simple/Callback.hs b/src/Database/DuckDB/Simple/Callback.hs
--- a/src/Database/DuckDB/Simple/Callback.hs
+++ b/src/Database/DuckDB/Simple/Callback.hs
@@ -3,95 +3,485 @@
 {-# LANGUAGE RankNTypes #-}
 {-# LANGUAGE ScopedTypeVariables #-}
 
--- | Manage callback resources at the DuckDB ownership boundary.
+-- |
+-- Module      : Database.DuckDB.Simple.Callback
+-- Description : Manage callback resources and registration builders at the DuckDB ownership boundary.
 module Database.DuckDB.Simple.Callback (
-    withCallbackResources,
-    transferCallbackState,
-    runCallback,
-    ignoreCallbackExceptions,
+  RegistrationTarget (..),
+  withRegistrationFactory,
+  targetCastFactory,
+  checkTargetThreads,
+  checkQueryThreads,
+  requireWorkerCallbackRuntime,
+  withTarget,
+  Allocator,
+  install,
+  installOptional,
+  installAll,
+  guardContext,
+  withCallbackResources,
+  withCallbackResourcesFinally,
+  transferCallbackState,
+  readCallbackState,
+  runCallback,
+  runCallbackWith,
+  ignoreCallbackExceptions,
+  attachOpaque,
 ) where
 
-import Control.Exception (SomeException, catch, displayException, finally, mask, mask_, onException, try)
+import Control.Concurrent (rtsSupportsBoundThreads)
+import Control.Exception (SomeException, bracket, catch, finally, fromException, mask, mask_, onException, try)
+import Control.Monad (unless, when)
 import Data.IORef (modifyIORef', newIORef, readIORef)
+import Data.Maybe (fromMaybe)
+import Data.Text (Text)
 import qualified Data.Text as Text
-import qualified Data.Text.Foreign as TextForeign
-import Database.DuckDB.FFI (DuckDBDeleteCallback)
-import Foreign.C.String (CString, withCString)
-import Foreign.Ptr (FunPtr, Ptr, freeHaskellFunPtr, nullPtr)
+import Data.Void (Void)
+import Database.DuckDB.Simple.CallbackMark (withCallbackMark)
+import Database.DuckDB.Simple.Internal (Connection, connectionInstance, instanceCastFactory, withConnectionHandle)
+import Database.DuckDB.Simple.Native
+import Foreign.Marshal.Alloc (alloca)
+import Foreign.Marshal.Utils (with)
+import Foreign.Ptr (FunPtr, Ptr, castFunPtr, castPtr, freeHaskellFunPtr, nullFunPtr, nullPtr)
 import Foreign.StablePtr (StablePtr, castPtrToStablePtr, castStablePtrToPtr, deRefStablePtr, freeStablePtr, newStablePtr)
+import Foreign.Storable (Storable, peek)
+import HsBindgen.Runtime.Support.FunPtr (ToFunPtr, toFunPtr)
+import System.IO.Error (ioeGetErrorString, isUserError)
 
-{- | Acquire callbacks and transfer their cleanup to a DuckDB object.
-The object must be non-null. Its destructor must run after the action.
+-- | A registration target. Extension handles are borrowed from an extension load
+-- callback and must not escape it. Configure extension types and values with
+-- the context supplied to that callback.
+data RegistrationTarget = ConnectionTarget Connection | ExtensionTarget DuckDBV2ExtensionHandle DuckDBV2ContextHandle
+
+-- | Borrow the factory of a registration target. The factory must not escape
+-- this action. Use it to construct signature types and values in a configuration action.
+withRegistrationFactory :: RegistrationTarget -> (DuckDBV2FactoryHandle -> IO a) -> IO a
+withRegistrationFactory target action = case target of
+  ConnectionTarget connection -> withConnectionHandle connection $ \native -> withConnectionFactory native action
+  ExtensionTarget _ context -> withContextFactory context action
+
+-- | The factory for the casts that the library runs in the callbacks of a
+-- target. A connection target gives the factory of its instance. An extension
+-- target gives 'Nothing', because an extension has no instance. A callback with
+-- a context can use the default per-row cast. Scalar and aggregate functions
+-- use a private instance. See Note [Function argument readers] in
+-- "Database.DuckDB.Simple.Typed". A registration
+-- takes the factory one time, and its callbacks keep it. The factory is valid
+-- until the instance handle is destroyed. The library destroys that handle only
+-- after it closes each child of the instance (Note [Native handle ownership] in
+-- "Database.DuckDB.Simple.Internal"), and a callback runs only in a statement on
+-- a connection of the instance. A callback keeps the factory and not the connection, for the
+-- reason that withVariantReader in "Database.DuckDB.Simple.Copy.Internal" gives.
+-- See Note [User casts and the casts of the library] in
+-- "Database.DuckDB.Simple.Materialize".
+targetCastFactory :: RegistrationTarget -> IO (Maybe DuckDBV2FactoryHandle)
+targetCastFactory target = case target of
+  ConnectionTarget connection -> withConnectionHandle connection \_ -> Just <$> instanceCastFactory (connectionInstance connection)
+  ExtensionTarget _ _ -> pure Nothing
+
+-- | Check the query thread count of a connection or extension registration.
+checkTargetThreads :: RegistrationTarget -> IO ()
+checkTargetThreads target = checkQueryThreads $ case target of
+  ConnectionTarget connection -> withConnectionHandle connection (output . c_duckdb_v2_connection_get_config)
+  ExtensionTarget _ context -> output (c_duckdb_v2_context_get_config context)
+
+-- | Keep the target alive while borrowing its factory and registration builder.
+withTarget
+  :: (Storable handle)
+  => RegistrationTarget
+  -> (DuckDBV2FactoryHandle -> Ptr handle -> Ptr DuckDBV2ErrorInfoHandle -> IO DuckDBV2Error)
+  -> (Ptr handle -> IO DuckDBV2Error)
+  -> (DuckDBV2ConnectionHandle -> handle -> Ptr DuckDBV2ErrorInfoHandle -> IO DuckDBV2Error)
+  -> (DuckDBV2ExtensionHandle -> handle -> Ptr DuckDBV2ErrorInfoHandle -> IO DuckDBV2Error)
+  -> (handle -> IO () -> IO a)
+  -> IO a
+withTarget target create release registerConnection registerExtension action = case target of
+  ConnectionTarget connection -> withConnectionHandle connection $ \native ->
+    withConnectionFactory native $ \factory ->
+      bracket (output (create factory)) (destroy release) $ \handle -> action handle (checked (registerConnection native handle))
+  ExtensionTarget extension context -> withContextFactory context $ \factory ->
+    bracket (output (create factory)) (destroy release) $ \handle -> action handle (checked (registerExtension extension handle))
+
+-- | Allocate a callback pointer tracked by the native registration owner.
+type Allocator = forall a. IO (FunPtr a) -> IO (FunPtr a)
+
+-- | Allocate one generated callback and defer its checked setter.
+install
+  :: (ToFunPtr auxiliary)
+  => Allocator -> (FunPtr auxiliary -> callback) -> auxiliary -> (callback -> Ptr DuckDBV2ErrorInfoHandle -> IO DuckDBV2Error) -> IO (IO ())
+install allocate wrap callback setter = do
+  pointer <- wrap <$> allocate (toFunPtr callback)
+  pure (checked (setter pointer))
+
+-- | Allocate an optional callback when it is present.
+installOptional :: Maybe a -> (a -> IO (IO ())) -> IO (IO ())
+installOptional value action = maybe (pure (pure ())) action value
+
+-- | Run each install action now, and return one action that runs their setters
+-- in order. A registration has two phases. First the install actions allocate
+-- each function pointer, in the acquire step of 'withCallbackResources', so
+-- that its cleanup frees each pointer. Then the setters run after the
+-- configuration action of the registration, so a callback of the library
+-- replaces a callback that the configuration action set.
+installAll :: [IO (IO ())] -> IO (IO ())
+installAll installers = sequence_ <$> sequence installers
+
+-- | Translate a callback exception through its native error channel.
+guardContext :: (info -> DuckDBV2ContextHandle -> IO ()) -> info -> DuckDBV2ContextHandle -> Ptr DuckDBV2ErrorInfoHandle -> IO ()
+guardContext callback info context err = runCallback err (callback info context)
+
+{- Note [Callback ownership]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The library gives two kinds of Haskell values to DuckDB. DuckDB holds each
+value as a stable pointer with a destructor, in an opaque structure
+(attachOpaque). After a setter takes the pointer, DuckDB owns it, and only the
+destructor frees it.
+
+- Callback resources. withCallbackResourcesFinally collects the cleanup of the
+  function pointers of one registration, and its final action, in one IO
+  action. It gives a stable pointer to this action to the user data of the
+  registered object, with the destructor
+  duckdb_simple_release_callback_resources. This destructor runs the action and
+  frees the stable pointer.
+
+- Callback state. transferCallbackState gives a stable pointer to one value to
+  a state slot, for example the bind data, the init data, or the global state.
+  The destructor duckdb_simple_release_callback_state frees only the stable
+  pointer. readCallbackState reads the slot and dereferences the pointer. The
+  caller supplies the type, so it must be the type of the value in the slot.
+
+These two rules are the behaviour of DuckDB 2.0.0. The header does not state
+them.
+
+- A setter that fails has not taken the pointer. Thus the handlers of
+  withCallbackResourcesFinally and transferCallbackState free it.
+
+- A setter for init data, batch data, global state, or local state does not
+  release a value that it replaces. Thus give one value to each slot.
+
+The two destructors are foreign exports, and DuckDB gets their static
+addresses. A static address needs no release. A function pointer of a wrapper
+import must be freed with freeHaskellFunPtr after its last call. The destructor
+is the last call for its object, so no later call could free such a pointer.
+The destructors mask asynchronous exceptions (mask_). They have no error
+channel, so they contain each exception (ignoreCallbackExceptions). Other
+modules attach destructors of their own with attachOpaque, for example
+duckdb_simple_release_aggregate_states in
+"Database.DuckDB.Simple.Typed.Aggregate" and duckdb_simple_release_copy_binding
+in "Database.DuckDB.Simple.Copy.Internal".
 -}
-withCallbackResources ::
-    ((forall a. IO (FunPtr a) -> IO (FunPtr a)) -> IO r) ->
-    (Ptr () -> DuckDBDeleteCallback -> IO ()) ->
-    (r -> IO b) ->
-    IO b
-withCallbackResources acquire attach action = mask \restore -> do
-    cleanups <- newIORef []
-    let cleanup = readIORef cleanups >>= sequence_
-        allocate make = do
-            ptr <- make
-            modifyIORef' cleanups (freeHaskellFunPtr ptr :)
-                `onException` freeHaskellFunPtr ptr
-            pure ptr
-    resources <- acquire allocate `onException` cleanup
-    stable <- newStablePtr cleanup `onException` cleanup
-    attach (castStablePtrToPtr stable) callbackResourcesDestructor
-        `onException` (freeStablePtr stable >> cleanup)
-    restore (action resources)
 
+-- | Acquire callbacks and transfer their cleanup to a DuckDB object.
+-- The object must be non-null. Its destructor must run after the action. The
+-- first argument checks whether the runtime supports the callbacks. See
+-- Note [Callback ownership] and Note [Callbacks without the threaded runtime].
+withCallbackResources
+  :: IO ()
+  -> (Allocator -> IO r)
+  -> (Ptr Void -> DuckDBV2OpaqueDestroyFn -> IO ())
+  -> (r -> IO b)
+  -> IO b
+withCallbackResources checkRuntime = withCallbackResourcesFinally checkRuntime (pure ())
+
+-- | Run a final action before the callback resources are released.
+-- This includes acquisition and registration failure. Contain final-action errors.
+-- A registration that acquires a callback checks the runtime before it
+-- registers. See Note [Callbacks without the threaded runtime].
+withCallbackResourcesFinally
+  :: IO ()
+  -> IO ()
+  -> (Allocator -> IO r)
+  -> (Ptr Void -> DuckDBV2OpaqueDestroyFn -> IO ())
+  -> (r -> IO b)
+  -> IO b
+withCallbackResourcesFinally checkRuntime finalizer acquire attach action = mask \restore -> do
+  cleanups <- newIORef []
+  let cleanup = ignoreCallbackExceptions finalizer `finally` (readIORef cleanups >>= sequence_)
+      allocate make = do
+        ptr <- make
+        modifyIORef' cleanups (freeHaskellFunPtr ptr :)
+          `onException` freeHaskellFunPtr ptr
+        pure ptr
+  resources <- acquire allocate `onException` cleanup
+  acquired <- readIORef cleanups
+  unless (null acquired) checkRuntime `onException` cleanup
+  stable <- newStablePtr cleanup `onException` cleanup
+  -- A setter that fails has not taken the pointer, so this handler frees it.
+  -- See Note [Callback ownership].
+  attach (castPtr (castStablePtrToPtr stable)) callbackResourcesDestructor
+    `onException` (freeStablePtr stable >> cleanup)
+  restore (action resources)
+
+{- Note [Callbacks without the threaded runtime]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+DuckDB calls a callback from its own threads. The GHC runtime without -threaded
+cannot take a call from a foreign thread. The GHC User's Guide says: "In order
+to use the FFI in a multi-threaded setting, you must use the -threaded option."
+A program without -threaded crashed in 20 of 20 runs when a scalar function ran
+over 2,000,000 rows with the setting threads = 4 ("schedule: re-entered
+unsafely", a segmentation fault, or a heap corruption). With threads = 1, or
+with -threaded, it crashed in none of 20 runs.
+
+COPY can open an output file on an asynchronous worker even with threads = 1.
+A log sink can receive the file-open log entry on that worker. Both kinds of
+registration require -threaded regardless of the current settings. Another
+connection can change async_threads after registration.
+
+Each other registration that acquires a callback calls checkQueryThreads.
+With the threaded runtime the check is one Bool test and no native call.
+Without it, the check reads the
+setting threads of the database that runs the callbacks (four native calls: the
+config, the option value, its BIGINT, and the release of the value) and raises
+the input error of the library when the setting is above 1. A registration with
+no callback, for example a custom type, a macro, or a custom option with no
+update function, does not check. The setting threads has only the GLOBAL scope
+("cannot be set locally" in DuckDB 2.0.0), so each connection of an instance and
+the instance itself give the same value.
+
+The check cannot see a later change. A statement SET threads = 4 after the
+registration, also on another connection of the instance, raises the count
+again, and the library does not read the SQL text of a statement. The check is
+a guard for the common mistake, not a proof that no callback runs on a second
+thread.
+-}
+
+-- | Raise the input error of the library when the GHC runtime is not threaded
+-- and the database that the config belongs to runs more than one thread. See
+-- Note [Callbacks without the threaded runtime].
+checkQueryThreads :: IO DuckDBV2ConfigHandle -> IO ()
+checkQueryThreads config = unless rtsSupportsBoundThreads do
+  handle <- config
+  threads <- withIdentifier (Text.pack "threads") \key -> alloca \scope ->
+    bracket
+      (output (\value -> c_duckdb_v2_config_get_option_value handle key value scope))
+      destroyValue
+      (output . c_duckdb_v2_value_get_bigint)
+  when (threads > 1) $
+    throwInvalidArgument
+      ( Text.pack
+          ( "this program is not linked with -threaded, and the database runs "
+              <> show threads
+              <> " threads: link the program with -threaded, or set the DuckDB setting threads to 1 before you register a callback"
+          )
+      )
+
+-- | Reject registrations whose callbacks can run on independent native workers.
+-- See Note [Callbacks without the threaded runtime].
+requireWorkerCallbackRuntime :: Text -> IO ()
+requireWorkerCallbackRuntime kind =
+  unless rtsSupportsBoundThreads $
+    throwInvalidArgument (kind <> Text.pack " callbacks require a program linked with -threaded")
+
 -- | Transfer one state value to a DuckDB callback state slot.
-transferCallbackState :: (Ptr () -> DuckDBDeleteCallback -> IO ()) -> a -> IO ()
+-- Use each slot once. See Note [Callback ownership].
+transferCallbackState :: (Ptr Void -> DuckDBV2OpaqueDestroyFn -> IO ()) -> a -> IO ()
 transferCallbackState attach state = mask_ do
-    stable <- newStablePtr state
-    attach (castStablePtrToPtr stable) callbackStateDestructor
-        `onException` freeStablePtr stable
+  stable <- newStablePtr state
+  -- A setter that fails has not taken the pointer, so this handler frees it.
+  -- See Note [Callback ownership].
+  attach (castPtr (castStablePtrToPtr stable)) callbackStateDestructor
+    `onException` freeStablePtr stable
 
--- | Convert callback exceptions to DuckDB errors.
-runCallback :: (CString -> IO ()) -> IO () -> IO ()
-runCallback setError action = mask \restore -> do
-    outcome <- try (restore action)
-    case outcome of
-        Right () -> pure ()
-        Left (err :: SomeException) ->
-            TextForeign.withCString (Text.pack (displayException err)) setError
-                `catch` \(_ :: SomeException) ->
-                    ignoreCallbackExceptions $
-                        withCString "duckdb-simple: Haskell callback failed" setError
+-- | Read state stored with 'transferCallbackState'. The caller supplies its type.
+-- See Note [Callback ownership].
+readCallbackState :: (Ptr (Ptr Void) -> Ptr DuckDBV2ErrorInfoHandle -> IO DuckDBV2Error) -> IO a
+readCallbackState getter = do
+  ptr <- output getter
+  when (ptr == nullPtr) $ throwInternalError (Text.pack "callback state is not initialized")
+  deRefStablePtr (castPtrToStablePtr (castPtr ptr))
 
+-- | Convert callback exceptions to native V2 diagnostics. Mark the thread as a
+-- thread inside a DuckDB callback for the time of the action, so that its
+-- waits for a connection lock have the bound of the connection. See
+-- 'Database.DuckDB.Simple.Internal.withConnectionLock' and
+-- Note [Callback marks] in "Database.DuckDB.Simple.CallbackMark". Each DuckDB
+-- callback with user code runs through this function or 'runCallbackWith',
+-- except the flush function of a log sink when DuckDB destroys the sink. See
+-- Note [Errors that leave a callback] for the code and the text of an error.
+runCallback :: Ptr DuckDBV2ErrorInfoHandle -> IO () -> IO ()
+runCallback = runCallbackAs DuckDBV2ErrorApi callbackError
+
+-- | 'runCallback' with another native error code for each failure. The code
+-- replaces the type of each exception, also the type of an t'SQLError', and the
+-- text is the 'failureText' of the exception. A cast callback uses it. See
+-- Note [The error code of a failed cast] in
+-- "Database.DuckDB.Simple.V2.Registration".
+runCallbackWith :: DuckDBV2Error -> Ptr DuckDBV2ErrorInfoHandle -> IO () -> IO ()
+runCallbackWith code = runCallbackAs code \failure -> (code, Text.pack (failureText failure))
+
+-- | Run a callback action. For an exception, write the code and the text that
+-- the description gives into the error slot. Use the fallback code if the
+-- description throws.
+runCallbackAs :: DuckDBV2Error -> (SomeException -> (DuckDBV2Error, Text)) -> Ptr DuckDBV2ErrorInfoHandle -> IO () -> IO ()
+runCallbackAs fallback describe err action = mask \restore -> do
+  outcome <- try (withCallbackMark (restore action))
+  case outcome of
+    Right () -> pure ()
+    Left (failure :: SomeException) ->
+      ignoreCallbackExceptions $
+        if err == nullPtr
+          then pure ()
+          else do
+            info <- peek err
+            if info == nullHandle
+              then pure ()
+              else do
+                c_duckdb_v2_error_info_set_code info fallback >>= checkCode
+                withText (Text.pack "Haskell callback failed") $ \message ->
+                  c_duckdb_v2_error_info_set_text info message >>= checkCode
+                let (code, text) = describe failure
+                when (code /= fallback) $ c_duckdb_v2_error_info_set_code info code >>= checkCode
+                withText text $ \message ->
+                  c_duckdb_v2_error_info_set_text info message >>= checkCode
+
+{- Note [Errors that leave a callback]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+An SQLError with a type leaves a callback with its own type, except for the ten
+types of typesWithoutOwnCode. An SQLError of one of these ten types leaves the
+callback as a plain Invalid Input error, because DuckDB would do something
+wrong or unsafe with its own code. There are three groups:
+
+- Seven types keep a transaction open: ErrorQueryBinder, ErrorDatabaseCatalog,
+  ErrorResourceConnection, ErrorQueryParameterNotAllowed, ErrorQueryParser,
+  ErrorConfigurationPermission, and ErrorResourceInUse. DuckDB expects these
+  types before the execution of a statement. Under the DuckDB setting
+  SYNTACTIC_ERRORS_DO_NOT_INVALIDATE of default_transaction_invalidation_policy,
+  DuckDB keeps the transaction after an error of these types
+  (Exception::InvalidatesTransaction in exception.cpp). A callback raises during
+  the execution, for example after an INSERT has written rows. With the code of
+  such a type, these rows would stay in the transaction, and COMMIT would store
+  them. With DuckDBV2ErrorApi, DuckDB invalidates the explicit transaction, and
+  COMMIT stores none of its rows.
+- ErrorRuntimeInternal and ErrorRuntimeFatal invalidate the database. For these
+  codes, DuckDB 2.0.0 invalidates the database of the outer statement, also
+  when the error came from another database.
+- ErrorIONetwork has no name. Its exception type has no name in DuckDB 2.0.0
+  (EXCEPTION_MAP in exception.cpp). With its code, the outer statement fails
+  with ErrorApi and the prefix "Invalid Error: " of a type with no name. With
+  DuckDBV2ErrorApi, it fails with ErrorInputInvalid, as for an SQLError without
+  a type.
+
+The section "Errors" of the README lists these types for users.
+
+runCallback writes an exception of a callback into the error slot of DuckDB as
+a code and a text. The statement that runs the callback then fails with an
+error of the type of the code. DuckDB puts the prefix of that type before the
+text, for example "Conversion Error: " for the code of ErrorTypeConversion, and
+"Invalid Input Error: " for DuckDBV2ErrorApi.
+
+- An SQLError with another type writes the code of its type. The text is the
+  body of the error (sqlErrorBody), the text of DuckDB without the prefix. An
+  error of duckdb-simple has no body, so the text is its message. Thus the error
+  of a statement in the callback reaches the outer statement with its type and
+  with one prefix. An error that passes through two callbacks keeps its type
+  and its body in the same way.
+- An SQLError of a type of typesWithoutOwnCode writes the code DuckDBV2ErrorApi
+  and its message.
+- DuckDB 2.0.0 cannot raise some codes again with their own type. Six codes
+  have no exception type in the map of the C API (TryGetExceptionTypeFromErrorCode
+  in capi_v2.cpp): the codes of ErrorApi, ErrorIOFileNotFound,
+  ErrorIOReadFailure, ErrorIOEof, ErrorInputParameterInvalid, and
+  ErrorInputMetadataDeferred. DuckDB raises them as Invalid Input, so the outer
+  statement fails with ErrorInputInvalid and "Invalid Input Error: ".
+- Each other exception writes the code DuckDBV2ErrorApi and failureText: an
+  SQLError without a type, a userError, or another exception.
+- A cast callback runs through runCallbackWith and not through this rule. It
+  writes the code DuckDBV2ErrorTypeMismatch and failureText for each
+  exception, also for an SQLError with a type. See
+  Note [The error code of a failed cast] in
+  "Database.DuckDB.Simple.V2.Registration".
+-}
+
+-- | The code and the text that a callback writes into its error slot for an
+-- exception. See Note [Errors that leave a callback].
+callbackError :: SomeException -> (DuckDBV2Error, Text)
+callbackError failure = case fromException failure of
+  Just SQLError{sqlErrorType = Just errorType, sqlErrorMessage = message, sqlErrorBody = body}
+    | errorType `notElem` typesWithoutOwnCode
+    , Just code <- lookup errorType errorTypeCodes ->
+        (code, fromMaybe message body)
+  _ -> (DuckDBV2ErrorApi, Text.pack (failureText failure))
+
+-- | The error types whose own code a callback must not write. An t'SQLError' of
+-- one of these types leaves the callback as a plain Invalid Input error,
+-- because DuckDB would do something wrong or unsafe with its own code.
+-- Note [Errors that leave a callback] gives the reason for each type.
+typesWithoutOwnCode :: [ErrorType]
+typesWithoutOwnCode =
+  [ ErrorQueryBinder
+  , ErrorDatabaseCatalog
+  , ErrorResourceConnection
+  , ErrorQueryParameterNotAllowed
+  , ErrorQueryParser
+  , ErrorConfigurationPermission
+  , ErrorResourceInUse
+  , ErrorIONetwork
+  , ErrorRuntimeInternal
+  , ErrorRuntimeFatal
+  ]
+
+-- | The text of a callback exception in the SQL error. An t'SQLError' gives its
+-- message, and a 'userError' gives its text. Thus the SQL error does not show a
+-- Haskell record or the words \"user error\". Each other exception gives its
+-- 'exceptionText'.
+failureText :: SomeException -> String
+failureText failure
+  | Just sqlError <- fromException failure = Text.unpack (sqlErrorMessage sqlError)
+  | Just ioError' <- fromException failure, isUserError ioError' = ioeGetErrorString ioError'
+  | otherwise = exceptionText failure
+
+-- | Transfer an opaque resource to a checked V2 setter. See
+-- Note [Callback ownership].
+attachOpaque
+  :: (Ptr DuckDBV2Opaque -> Ptr DuckDBV2ErrorInfoHandle -> IO DuckDBV2Error)
+  -> Ptr Void
+  -> DuckDBV2OpaqueDestroyFn
+  -> IO ()
+attachOpaque setter ptr release =
+  with (DuckDBV2Opaque ptr release (DuckDBV2OpaqueEqualsFn nullFunPtr)) $ \opaque ->
+    checked (setter opaque)
+
 -- | Contain exceptions in callbacks which have no error channel.
 ignoreCallbackExceptions :: IO () -> IO ()
 ignoreCallbackExceptions action = mask \restore ->
-    restore action `catch` \(_ :: SomeException) -> pure ()
+  restore action `catch` \(_ :: SomeException) -> pure ()
 
--- | Release object-owned callbacks through a static C entry point.
-releaseCallbackResources :: Ptr () -> IO ()
+-- | Release object-owned callbacks through a static C entry point. See
+-- Note [Callback ownership].
+releaseCallbackResources :: Ptr Void -> IO ()
 releaseCallbackResources raw =
-    mask_
-        $ ignoreCallbackExceptions
-        $ if raw == nullPtr
-            then pure ()
-            else do
-                let stable = castPtrToStablePtr raw :: StablePtr (IO ())
-                (deRefStablePtr stable >>= id) `finally` freeStablePtr stable
+  mask_
+    $ ignoreCallbackExceptions
+    $ if raw == nullPtr
+      then pure ()
+      else do
+        let stable = castPtrToStablePtr (castPtr raw) :: StablePtr (IO ())
+        (deRefStablePtr stable >>= id) `finally` freeStablePtr stable
 
--- | Release callback state independently of the registered function.
-releaseCallbackState :: Ptr () -> IO ()
+-- | Release callback state independently of the registered function. See
+-- Note [Callback ownership].
+releaseCallbackState :: Ptr Void -> IO ()
 releaseCallbackState raw =
-    mask_
-        $ ignoreCallbackExceptions
-        $ if raw == nullPtr then pure () else freeStablePtr (castPtrToStablePtr raw)
+  mask_
+    $ ignoreCallbackExceptions
+    $ if raw == nullPtr then pure () else freeStablePtr (castPtrToStablePtr (castPtr raw))
 
 foreign export ccall "duckdb_simple_release_callback_resources"
-    releaseCallbackResources :: Ptr () -> IO ()
+  releaseCallbackResources :: Ptr Void -> IO ()
 
 foreign import ccall "&duckdb_simple_release_callback_resources"
-    callbackResourcesDestructor :: DuckDBDeleteCallback
+  callbackResourcesDestructorAddress :: FunPtr (Ptr Void -> IO ())
 
 foreign export ccall "duckdb_simple_release_callback_state"
-    releaseCallbackState :: Ptr () -> IO ()
+  releaseCallbackState :: Ptr Void -> IO ()
 
 foreign import ccall "&duckdb_simple_release_callback_state"
-    callbackStateDestructor :: DuckDBDeleteCallback
+  callbackStateDestructorAddress :: FunPtr (Ptr Void -> IO ())
+
+-- | Use the generated callback type for the static destructor address.
+callbackResourcesDestructor :: DuckDBV2OpaqueDestroyFn
+callbackResourcesDestructor = DuckDBV2OpaqueDestroyFn (castFunPtr callbackResourcesDestructorAddress)
+
+-- | Use the generated callback type for the static state destructor address.
+callbackStateDestructor :: DuckDBV2OpaqueDestroyFn
+callbackStateDestructor = DuckDBV2OpaqueDestroyFn (castFunPtr callbackStateDestructorAddress)
diff --git a/src/Database/DuckDB/Simple/CallbackMark.hs b/src/Database/DuckDB/Simple/CallbackMark.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/CallbackMark.hs
@@ -0,0 +1,131 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE CPP #-}
+{-# LANGUAGE MagicHash #-}
+{-# LANGUAGE UnboxedTuples #-}
+{-# LANGUAGE UnliftedFFITypes #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.CallbackMark
+-- Description : Mark the threads that are inside a DuckDB callback.
+--
+-- 'withCallbackMark' marks the current thread for the time of an action.
+-- 'hasCallbackMark' tells if the current thread has a mark. See
+-- Note [Callback marks].
+module Database.DuckDB.Simple.CallbackMark (
+  withCallbackMark,
+  hasCallbackMark,
+) where
+
+import Control.Concurrent (myThreadId)
+import Control.Exception (evaluate, finally, mask)
+import Control.Monad (unless)
+import Data.IORef (newIORef, readIORef)
+import qualified Data.IntMap.Strict as IntMap
+import GHC.Exts (casMutVar#)
+import GHC.IO (IO (..))
+import GHC.IORef (IORef (..))
+import GHC.STRef (STRef (..))
+import System.IO.Unsafe (unsafePerformIO)
+#if MIN_VERSION_base(4,19,0)
+import GHC.Conc.Sync (ThreadId, fromThreadId)
+#else
+import Foreign.C.Types (CULLong (..))
+import GHC.Conc.Sync (ThreadId (..))
+import GHC.Exts (ThreadId#)
+#endif
+
+{- Note [Callback marks]
+~~~~~~~~~~~~~~~~~~~~~~~~
+DuckDB runs a callback while a native call of the library holds the lock of a
+connection. A statement that the callback runs on that connection waits for
+the lock, and the holder of the lock waits for the callback. Thus
+withConnectionLock gives a bound to the wait of a thread that is inside a
+callback. A mark tells it which threads these are. runCallback marks its thread
+with withCallbackMark, and withConnectionLock asks hasCallbackMark.
+
+The mark of a thread is an entry in callbackMarks, one table for the process.
+These are the reasons for its form.
+
+- The table is a top-level value. A callback does not always have a connection.
+  For example, an aggregate callback gets no context. Thus the table cannot be
+  a field of a connection.
+
+- The mark is not a thread label. In GHC 9.6 to 9.14.1, threadLabel gives a
+  null pointer for a thread without a label, and the garbage collector can
+  crash on that pointer (GHC issue 27618). DuckDB calls each callback in a new
+  thread without a label.
+
+- The key is the number of the thread, not its ThreadId. A ThreadId in the
+  table keeps its thread reachable. Then the GHC runtime does not raise
+  BlockedIndefinitelyOnMVar in a callback that waits for a value that no
+  thread can supply, and the statement does not return. The runtime gives each
+  thread a different number and does not use a number again.
+
+- The value is a count of marks. A thread that already has a mark thus keeps
+  it until the outer withCallbackMark ends.
+
+- A change is a compare-and-swap (changeCallbackMarks). atomicModifyIORef'
+  stores a value that is not evaluated, and it allocates more. If the runtime
+  stops a thread during that evaluation, each other thread that needs the value
+  waits. With one capability, each such wait of a callback thread is a context
+  switch of the operating system. With compare-and-swap, the table holds only
+  evaluated maps, and no thread waits for another thread.
+
+- The table is one IORef. Only the threads that are inside a callback at the
+  same time have an entry, so the map is small. Two threads that change the
+  table at the same time cost one more attempt for one of them.
+-}
+
+-- | The threads inside a DuckDB callback, with the number of marks of each
+-- thread. The key is the number of the thread. See Note [Callback marks].
+callbackMarks :: IORef (IntMap.IntMap Int)
+callbackMarks = unsafePerformIO (newIORef IntMap.empty)
+{-# NOINLINE callbackMarks #-}
+
+-- | The number of a Haskell thread. See Note [Callback marks].
+threadNumber :: ThreadId -> Int
+#if MIN_VERSION_base(4,19,0)
+threadNumber = fromIntegral . fromThreadId
+#else
+-- base 4.18 has no fromThreadId. This is the import that base 4.19 uses for it.
+threadNumber (ThreadId thread) = fromIntegral (rts_getThreadId thread)
+
+foreign import ccall unsafe "rts_getThreadId" rts_getThreadId :: ThreadId# -> CULLong
+#endif
+
+-- | Mark the current thread as a thread inside a DuckDB callback for the time
+-- of the action. The entry adds 1 to the marks of the thread, and each exit
+-- subtracts 1. A thread that the action starts has no mark. See
+-- Note [Callback marks].
+withCallbackMark :: IO a -> IO a
+withCallbackMark action = mask \restore -> do
+  key <- threadNumber <$> myThreadId
+  changeCallbackMarks (IntMap.insertWith (+) key 1)
+  restore action `finally` changeCallbackMarks (IntMap.update unmark key)
+  where
+    unmark :: Int -> Maybe Int
+    unmark count = if count > 1 then Just (count - 1) else Nothing
+
+-- | Change 'callbackMarks' with compare-and-swap. Read the map, evaluate the
+-- new map, and store it if the table still holds the map that was read. If
+-- another thread changed the table, do the change again. See
+-- Note [Callback marks].
+--
+-- The swap compares pointers. A map is a value of a type with more than one
+-- constructor, so GHC keeps its pointer and does not make a new box for it.
+changeCallbackMarks :: (IntMap.IntMap Int -> IntMap.IntMap Int) -> IO ()
+changeCallbackMarks change = do
+  old <- readIORef callbackMarks
+  new <- evaluate (change old)
+  swapped <- case callbackMarks of
+    IORef (STRef var) -> IO \s -> case casMutVar# var old new s of
+      (# s', 0#, _ #) -> (# s', True #)
+      (# s', _, _ #) -> (# s', False #)
+  unless swapped (changeCallbackMarks change)
+
+-- | Tell if 'withCallbackMark' marks the current thread. Only the thread
+-- itself adds and removes its key, so the answer is exact without a lock.
+hasCallbackMark :: IO Bool
+hasCallbackMark = do
+  key <- threadNumber <$> myThreadId
+  IntMap.member key <$> readIORef callbackMarks
diff --git a/src/Database/DuckDB/Simple/Catalog.hs b/src/Database/DuckDB/Simple/Catalog.hs
--- a/src/Database/DuckDB/Simple/Catalog.hs
+++ b/src/Database/DuckDB/Simple/Catalog.hs
@@ -1,88 +1,136 @@
-{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE StrictData #-}
 
-{- |
-Module      : Database.DuckDB.Simple.Catalog
-Description : High-level helpers for DuckDB catalog inspection.
--}
+-- |
+-- 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 (
-    CatalogEntry (..),
-    catalogTypeName,
-    lookupCatalogEntry,
+  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 qualified Data.Text.Foreign as TextForeign
-import Database.DuckDB.FFI
-import Database.DuckDB.Simple.Internal (Connection, peekUtf8CString, throwRegistrationError, withClientContext)
-import Foreign.C.String (CString)
-import Foreign.Marshal.Alloc (alloca)
-import Foreign.Ptr (nullPtr)
-import Foreign.Storable (poke)
+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)
 
--- | A simplified view of a catalog entry returned by DuckDB.
+-- | 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 :: !DuckDBCatalogEntryType
-    }
-    deriving (Eq, Show)
+  { catalogEntryName :: Text
+  , catalogEntryType :: CatalogEntryType
+  }
+  deriving (Eq, Show)
 
--- | Look up the backend type name of a named catalog.
-catalogTypeName :: Connection -> Text -> IO (Maybe Text)
-catalogTypeName conn catalogName
-    | Text.any (== '\0') catalogName = throwRegistrationError "catalog name contains NUL"
-    | otherwise =
-        withClientContext conn \ctx ->
-            TextForeign.withCString catalogName \cName ->
-                withMaybeCatalog ctx cName \catalog -> do
-                    namePtr <- c_duckdb_catalog_get_type_name catalog
-                    if namePtr == nullPtr
-                        then pure Nothing
-                        else Just <$> peekUtf8CString namePtr
+-- | A table's qualified name, access mode, and columns.
+data TableDescription = TableDescription
+  { tableDescriptionName :: [Text]
+  , tableDescriptionReadonly :: Bool
+  , tableDescriptionColumns :: [ColumnDescription]
+  }
+  deriving (Eq, Show)
 
--- | Look up a catalog entry by catalog, schema, name, and expected entry kind.
-lookupCatalogEntry :: Connection -> Text -> Text -> Text -> DuckDBCatalogEntryType -> IO (Maybe CatalogEntry)
-lookupCatalogEntry conn catalogName schemaName entryName entryType
-    | any (Text.any (== '\0')) [catalogName, schemaName, entryName] = throwRegistrationError "catalog lookup name contains NUL"
-    | entryType `notElem` [DuckDBCatalogEntryTypeTable, DuckDBCatalogEntryTypeView, DuckDBCatalogEntryTypeIndex, DuckDBCatalogEntryTypeSequence, DuckDBCatalogEntryTypeCollation, DuckDBCatalogEntryTypeType] =
-        throwRegistrationError "unsupported catalog entry type"
-    | otherwise =
-        withClientContext conn \ctx ->
-            TextForeign.withCString catalogName \cCatalog ->
-                TextForeign.withCString schemaName \cSchema ->
-                    TextForeign.withCString entryName \cEntry ->
-                        withMaybeCatalog ctx cCatalog \catalog ->
-                            withMaybeCatalogEntry catalog ctx entryType cSchema cEntry \entry -> do
-                                typ <- c_duckdb_catalog_entry_get_type entry
-                                namePtr <- c_duckdb_catalog_entry_get_name entry
-                                if namePtr == nullPtr
-                                    then pure Nothing
-                                    else do
-                                        name <- peekUtf8CString namePtr
-                                        pure (Just CatalogEntry{catalogEntryName = name, catalogEntryType = typ})
+-- | 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)
 
-destroyCatalog :: DuckDBCatalog -> IO ()
-destroyCatalog catalog =
-    alloca \ptr -> poke ptr catalog >> c_duckdb_destroy_catalog ptr
+-- | 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)
 
-destroyCatalogEntry :: DuckDBCatalogEntry -> IO ()
-destroyCatalogEntry entry =
-    alloca \ptr -> poke ptr entry >> c_duckdb_destroy_catalog_entry ptr
+-- | 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)
 
-withMaybeCatalog :: DuckDBClientContext -> CString -> (DuckDBCatalog -> IO (Maybe a)) -> IO (Maybe a)
-withMaybeCatalog ctx name action =
-    bracket (c_duckdb_client_context_get_catalog ctx name) destroyCatalog \catalog ->
-        if catalog == nullPtr then pure Nothing else action catalog
+-- | 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'))"
 
-withMaybeCatalogEntry ::
-    DuckDBCatalog ->
-    DuckDBClientContext ->
-    DuckDBCatalogEntryType ->
-    CString ->
-    CString ->
-    (DuckDBCatalogEntry -> IO (Maybe a)) ->
-    IO (Maybe a)
-withMaybeCatalogEntry catalog ctx entryType schemaName entryName action =
-    bracket (c_duckdb_catalog_get_entry catalog ctx entryType schemaName entryName) destroyCatalogEntry \entry ->
-        if entry == nullPtr then pure Nothing else action entry
+-- | 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"
diff --git a/src/Database/DuckDB/Simple/Config.hs b/src/Database/DuckDB/Simple/Config.hs
--- a/src/Database/DuckDB/Simple/Config.hs
+++ b/src/Database/DuckDB/Simple/Config.hs
@@ -1,89 +1,224 @@
 {-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE StrictData #-}
 
-{- |
-Module      : Database.DuckDB.Simple.Config
-Description : High-level helpers for DuckDB 1.5 configuration inspection.
--}
+-- |
+-- Module      : Database.DuckDB.Simple.Config
+-- Description : V2 configuration values, declared scopes, defaults, and aliases.
 module Database.DuckDB.Simple.Config (
-    ConfigFlag (..),
-    ConfigValue (..),
-    listConfigFlags,
-    getConfigOption,
+  ConfigFlag (..),
+  ConfigValue (..),
+  ConfigOption (..),
+  SettingScope (..),
+  listConfigFlags,
+  listConfigOptions,
+  listInstanceOptions,
+  getConfigOption,
+  setConfigOption,
+  getConfigValue,
+  getConfigDefaultValue,
+  setConfigValue,
+  CustomOption (..),
+  customOption,
+  registerCustomOption,
 ) where
 
-import Control.Exception (bracket)
+import Control.Exception (bracket, catch, throwIO)
+import Control.Monad (filterM, forM, when)
 import Data.Text (Text)
 import qualified Data.Text as Text
-import qualified Data.Text.Foreign as TextForeign
-import Database.DuckDB.FFI
-import Database.DuckDB.Simple.Internal (Connection, destroyValue, peekUtf8CString, throwRegistrationError, withClientContext)
+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.Ptr (castPtr, nullPtr)
-import Foreign.Storable (peek, poke)
+import Foreign.Storable (peek)
 
--- | Static metadata describing a known DuckDB configuration flag.
+-- | The canonical name and description of a configuration option.
 data ConfigFlag = ConfigFlag
-    { configFlagName :: !Text
-    , configFlagDescription :: !Text
-    }
-    deriving (Eq, Show)
+  { configFlagName :: Text
+  , configFlagDescription :: Text
+  }
+  deriving (Eq, Show)
 
--- | The current value of a configuration option plus its scope, when available.
+-- | An effective option value and the scope that supplied it.
+-- 'configValueText' is 'Nothing' for a NULL value, as 'configOptionSetting'.
 data ConfigValue = ConfigValue
-    { configValueText :: !Text
-    , configValueScope :: !(Maybe DuckDBConfigOptionScope)
-    }
-    deriving (Eq, Show)
+  { configValueText :: Maybe Text
+  , configValueScope :: SettingScope
+  }
+  deriving (Eq, Show)
 
--- | List all configuration flags known to the linked DuckDB runtime.
-listConfigFlags :: IO [ConfigFlag]
-listConfigFlags = do
-    count <- c_duckdb_config_count
-    let indices = [0 .. fromIntegral count - 1] :: [Int]
-    mapM fetchFlag indices
-  where
-    fetchFlag idx =
-        alloca \namePtr ->
-            alloca \descPtr -> do
-                rc <- c_duckdb_get_config_flag (fromIntegral idx) namePtr descPtr
-                if rc /= DuckDBSuccess
-                    then pure ConfigFlag{configFlagName = Text.pack (show idx), configFlagDescription = Text.pack ""}
-                    else do
-                        name <- peek namePtr >>= peekUtf8CString
-                        description <- peek descPtr >>= peekUtf8CString
-                        pure ConfigFlag{configFlagName = name, configFlagDescription = description}
+-- | 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)
 
--- | Read a configuration option from a live connection's client context.
+-- | 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
-    | Text.any (== '\0') name = throwRegistrationError "config option name contains NUL"
-    | otherwise =
-        withClientContext conn \ctx ->
-            TextForeign.withCString name \cName ->
-                alloca \scopePtr -> do
-                    poke scopePtr DuckDBConfigOptionScopeInvalid
-                    bracket
-                        (c_duckdb_client_context_get_config_option ctx cName scopePtr)
-                        destroyValue
-                        \duckValue ->
-                            if duckValue == nullPtr
-                                then pure Nothing
-                                else do
-                                    rendered <-
-                                        bracket
-                                            (c_duckdb_get_varchar duckValue)
-                                            (c_duckdb_free . castPtr)
-                                            \strPtr ->
-                                                if strPtr == nullPtr
-                                                    then pure Text.empty
-                                                    else peekUtf8CString strPtr
-                                    scope <- peek scopePtr
-                                    pure $
-                                        Just
-                                            ConfigValue
-                                                { configValueText = rendered
-                                                , configValueScope =
-                                                    if scope == DuckDBConfigOptionScopeInvalid
-                                                        then Nothing
-                                                        else Just scope
-                                                }
+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
diff --git a/src/Database/DuckDB/Simple/Config/Internal.hs b/src/Database/DuckDB/Simple/Config/Internal.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/Config/Internal.hs
@@ -0,0 +1,86 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.Config.Internal
+-- Description : Share the typed custom option registration for connections and extensions.
+--
+-- The cabal file lists this hidden module in @other-modules@.
+-- 'registerCustomOptionOn' takes a registration target.
+-- "Database.DuckDB.Simple.Config" exports the connection form.
+-- "Database.DuckDB.Simple.Extension" exports the extension form.
+module Database.DuckDB.Simple.Config.Internal (
+  CustomOption (..),
+  registerCustomOptionOn,
+) where
+
+import Control.Exception (bracket)
+import Control.Monad (forM, forM_, when)
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Database.DuckDB.Simple.Callback (targetCastFactory)
+import Database.DuckDB.Simple.FromField (FieldValue)
+import Database.DuckDB.Simple.Materialize (callbackReadFactory, materializeValue, readCallbackVariant)
+import Database.DuckDB.Simple.Native
+import Database.DuckDB.Simple.V2.Config (registerCustomOptionWith)
+import Database.DuckDB.Simple.V2.Registration (
+  ContextCallback,
+  DefaultValue (..),
+  RegistrationTarget (..),
+  TypeDeclaration,
+  withRegistrationFactory,
+  withTypeDeclaration,
+ )
+
+-- | A custom setting. The optional update function gets each new value of the
+-- option before DuckDB stores it. The value has the type of the option. An
+-- exception in the function rejects the value. The text of the exception is the
+-- SQL error. A RESET gives the default value to the function, or
+-- 'Database.DuckDB.Simple.FromField.FieldNull' for an option without a default.
+-- Thus the function must accept the default value. A VARIANT gives its
+-- contained value, as in 'Database.DuckDB.Simple.Config.getConfigValue'.
+data CustomOption = CustomOption
+  { customOptionName :: !Text
+  , customOptionType :: !TypeDeclaration
+  , customOptionDefault :: Maybe DefaultValue
+  , customOptionDescription :: !Text
+  , customOptionDefaultScope :: !SettingScope
+  , customOptionScopes :: ![SettingScope]
+  , customOptionUpdate :: Maybe (FieldValue -> IO ())
+  }
+
+-- | Register a declared option on a connection or loading extension.
+registerCustomOptionOn :: RegistrationTarget -> CustomOption -> IO ()
+registerCustomOptionOn target option = do
+  when (Text.null (customOptionName option) || Text.any (== '\0') (customOptionName option)) $
+    throwInvalidArgument "custom option name must be nonempty and must not contain NUL"
+  update <-
+    forM (customOptionUpdate option) \callback -> do
+      casts <- targetCastFactory target
+      pure (updateWithValue casts callback)
+  registerCustomOptionWith
+    target
+    ( \handle -> withRegistrationFactory target \factory -> do
+        withIdentifier (customOptionName option) $ checked . c_duckdb_v2_custom_option_set_name handle
+        withTypeDeclaration factory (customOptionType option) $ checked . c_duckdb_v2_custom_option_set_type handle
+        forM_ (customOptionDefault option) \(DefaultValue make) ->
+          bracket (make factory) destroyValue \native -> checked (c_duckdb_v2_custom_option_set_default_value handle native)
+        withText (customOptionDescription option) $ checked . c_duckdb_v2_custom_option_set_description handle
+        mapM_
+          ( \scope ->
+              checked
+                (c_duckdb_v2_custom_option_set_supports_scope handle (settingScopeToNative scope) (if scope `elem` customOptionScopes option then 1 else 0))
+          )
+          [SettingScopeGlobal, SettingScopeSession]
+        checked (c_duckdb_v2_custom_option_set_default_scope handle (settingScopeToNative (customOptionDefaultScope option)))
+    )
+    update
+
+-- | Copy the new value of an option update. Then give it to the update function.
+updateWithValue :: Maybe DuckDBV2FactoryHandle -> (FieldValue -> IO ()) -> ContextCallback DuckDBV2CustomOptionUpdateInfoHandle
+updateWithValue casts update info context = withContextFactory context \factory ->
+  bracket
+    (output (c_duckdb_v2_custom_option_update_get_value info))
+    destroyValue
+    (materializeValue readCallbackVariant (callbackReadFactory casts factory))
+    >>= update
diff --git a/src/Database/DuckDB/Simple/Conversion.hs b/src/Database/DuckDB/Simple/Conversion.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/Conversion.hs
@@ -0,0 +1,145 @@
+-- |
+-- Module      : Database.DuckDB.Simple.Conversion
+-- Description : Effectful conversion from DuckDB values.
+module Database.DuckDB.Simple.Conversion (
+  Conversion,
+  runConversion,
+  liftConversion,
+  conversionError,
+  conversionErrorWith,
+  mapConversionErrors,
+  mapConversionErrorsWith,
+) where
+
+import Control.Applicative (Alternative (..))
+import Control.Exception (Exception, SomeException, evaluate, toException)
+import Control.Monad (MonadPlus (..), ap)
+import qualified Control.Monad.Fail as Fail
+import Database.DuckDB.Simple.Ok (Ok (..))
+
+-- | A conversion with explicit IO and deferred conversion errors.
+-- See Note [Conversion effects].
+newtype Conversion a = Conversion (IO (Either (IO [SomeException]) a))
+
+{- Note [Conversion effects]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A conversion can read native metadata through liftConversion. These reads run
+only when the conversion demands them. IO exceptions, including cancellation,
+propagate to the caller. They are not conversion errors.
+
+A failed conversion stores an action that makes its diagnostics. Alternative
+discards this action when the other branch succeeds. runConversion runs the
+actions only after all branches fail. Thus a discarded error does not read
+metadata, such as an ENUM dictionary, just to name the SQL type.
+
+Field metadata uses Conversion too. Its native owner and successful-result
+cache belong to its result or callback scope. Native type actions fail after
+that scope closes. See Note [Scoped field types] in
+"Database.DuckDB.Simple.TypeScope". A child field maps its type projection
+over the parent's conversion. No pure thunk performs IO or stores an IO
+exception.
+
+Each successful step forces its value to weak head normal form, as Ok does.
+The force runs in IO with the caller's masking state. Thus a value nested in
+the final row cannot defer its field conversion until after runConversion.
+-}
+
+instance Functor Conversion where
+  {-# INLINE fmap #-}
+  fmap f (Conversion action) = Conversion $ fmap mapResult action
+    where
+      mapResult (Left errors) = Left errors
+      mapResult (Right value) = strictRight (f value)
+
+instance Applicative Conversion where
+  {-# INLINE pure #-}
+  pure value = Conversion (pure (strictRight value))
+  {-# INLINE (<*>) #-}
+  (<*>) = ap
+
+instance Monad Conversion where
+  {-# INLINE (>>=) #-}
+  Conversion action >>= next = Conversion $ do
+    result <- action
+    case result of
+      Left errors -> pure (Left errors)
+      Right value -> case next value of
+        Conversion following -> following
+
+instance Alternative Conversion where
+  empty = Conversion (pure (Left (pure [])))
+  Conversion first <|> Conversion second = Conversion $ do
+    result <- first
+    case result of
+      Right value -> pure (Right value)
+      Left firstErrors -> do
+        alternative <- second
+        pure $ case alternative of
+          Right value -> Right value
+          Left secondErrors -> Left ((<>) <$> firstErrors <*> secondErrors)
+
+instance MonadPlus Conversion where
+  mzero = empty
+  mplus = (<|>)
+
+instance Fail.MonadFail Conversion where
+  fail = conversionError . userError
+
+-- | Run a conversion and resolve the diagnostics if it fails.
+-- Force a successful value to weak head normal form. IO exceptions propagate
+-- to the caller.
+runConversion :: Conversion a -> IO (Ok a)
+{-# INLINE runConversion #-}
+runConversion (Conversion action) = do
+  result <- action
+  case result of
+    Left errors -> Errors <$> errors
+    Right value -> evaluate (Ok value)
+
+-- | Run an IO action when the conversion demands its result.
+-- A decoder in a registered callback must use another connection for nested
+-- SQL. Reads of the owned field type need no connection lock.
+liftConversion :: IO a -> Conversion a
+{-# INLINE liftConversion #-}
+liftConversion action = Conversion (strictRight <$> action)
+
+-- | Construct a success that forces its value when its result tag is read.
+strictRight :: a -> Either e a
+{-# INLINE strictRight #-}
+strictRight value = value `seq` Right value
+
+-- | Fail with a conversion error.
+conversionError :: (Exception e) => e -> Conversion a
+conversionError err = Conversion (pure (Left (pure [toException err])))
+
+-- | Make an error only if the final conversion fails.
+-- See Note [Conversion effects].
+conversionErrorWith :: (Exception e) => Conversion e -> Conversion a
+conversionErrorWith (Conversion diagnostic) = Conversion $ pure $ Left $ do
+  result <- diagnostic
+  case result of
+    Left errors -> errors
+    Right err -> pure [toException err]
+
+-- | Change deferred diagnostics without running them.
+mapConversionErrors :: ([SomeException] -> [SomeException]) -> Conversion a -> Conversion a
+mapConversionErrors f (Conversion action) = Conversion $ do
+  result <- action
+  pure $ case result of
+    Left errors -> Left (f <$> errors)
+    Right value -> Right value
+
+-- | Change the diagnostics with a conversion when the final conversion fails.
+mapConversionErrorsWith :: ([SomeException] -> Conversion [SomeException]) -> Conversion a -> Conversion a
+mapConversionErrorsWith f (Conversion action) = Conversion $ do
+  result <- action
+  pure $ case result of
+    Right value -> Right value
+    Left errors -> Left $ do
+      original <- errors
+      case f original of
+        Conversion following -> do
+          mapped <- following
+          case mapped of
+            Left failures -> failures
+            Right replacement -> pure replacement
diff --git a/src/Database/DuckDB/Simple/Copy.hs b/src/Database/DuckDB/Simple/Copy.hs
--- a/src/Database/DuckDB/Simple/Copy.hs
+++ b/src/Database/DuckDB/Simple/Copy.hs
@@ -1,203 +1,42 @@
-{-# LANGUAGE BlockArguments #-}
-{-# LANGUAGE NamedFieldPuns #-}
-{-# LANGUAGE ScopedTypeVariables #-}
-
-{- |
-Module      : Database.DuckDB.Simple.Copy
-Description : High-level wrappers for DuckDB custom COPY functions.
--}
+-- |
+-- Module      : Database.DuckDB.Simple.Copy
+-- Description : Register COPY formats and multi-file table functions with Haskell functions.
+--
+-- COPY format callbacks require the threaded GHC runtime (@-threaded@).
+-- The functions get and give Haskell values. Batch preparation can run
+-- concurrently. The sink calls for one output file run one at a time. A
+-- multi-file function uses the callbacks of a registered single-file table
+-- function. "Database.DuckDB.Simple.V2.Copy" has the native callback interface.
 module Database.DuckDB.Simple.Copy (
-    CopyBindInfo (..),
-    CopyInitInfo (..),
-    CopySinkInfo (..),
-    CopyFinalizeInfo (..),
-    registerCopyToFunction,
+  CopyBindInfo (..),
+  LogicalTypeId (..),
+  CopyInitInfo (..),
+  CopySinkInfo (..),
+  CopyFinalizeInfo (..),
+  registerCopyToFunction,
+  CopyFromInfo (..),
+  registerCopyFromFunction,
+  CopyTo (..),
+  registerCopyFunction,
+  TypedRow,
+  MultiFileOptions (..),
+  defaultMultiFileOptions,
+  registerMultiFileFunction,
 ) where
 
-import Control.Exception (bracket)
-import Control.Monad (forM, when)
-import Data.Text (Text)
-import qualified Data.Text as Text
-import qualified Data.Text.Foreign as TextForeign
-import Database.DuckDB.FFI
-import Database.DuckDB.Simple.Callback (runCallback, transferCallbackState, withCallbackResources)
-import Database.DuckDB.Simple.FromField (Field (..))
-import Database.DuckDB.Simple.Internal (Connection, destroyLogicalType, peekUtf8CString, throwRegistrationError, withConnectionHandle)
-import Database.DuckDB.Simple.Materialize (prepareVectorReader)
-import Foreign.Marshal.Alloc (alloca)
-import Foreign.Ptr (Ptr, nullPtr)
-import Foreign.StablePtr (StablePtr, castPtrToStablePtr, deRefStablePtr)
-import Foreign.Storable (poke)
-
--- | Bind-phase metadata for a custom `COPY ... TO` function.
-data CopyBindInfo = CopyBindInfo
-    { copyBindColumnTypes :: ![DuckDBType]
-    }
-    deriving (Eq, Show)
-
--- | Init-phase inputs for a custom `COPY ... TO` function.
-data CopyInitInfo bindState = CopyInitInfo
-    { copyInitBindState :: !bindState
-    , copyInitFilePath :: !FilePath
-    }
-
--- | Sink-phase inputs for a custom `COPY ... TO` function.
-data CopySinkInfo bindState globalState = CopySinkInfo
-    { copySinkBindState :: !bindState
-    , copySinkGlobalState :: !globalState
-    }
-
--- | Finalize-phase inputs for a custom `COPY ... TO` function.
-data CopyFinalizeInfo bindState globalState = CopyFinalizeInfo
-    { copyFinalizeBindState :: !bindState
-    , copyFinalizeGlobalState :: !globalState
-    }
-
-data CopyFunctionResources = CopyFunctionResources
-    { copyBindPtr :: !DuckDBCopyFunctionBindFun
-    , copyInitPtr :: !DuckDBCopyFunctionGlobalInitFun
-    , copySinkPtr :: !DuckDBCopyFunctionSinkFun
-    , copyFinalizePtr :: !DuckDBCopyFunctionFinalizeFun
-    }
-
--- | Register a custom `COPY ... TO` implementation backed by Haskell callbacks.
-registerCopyToFunction ::
-    forall bindState globalState.
-    Connection ->
-    Text ->
-    (CopyBindInfo -> IO bindState) ->
-    (CopyInitInfo bindState -> IO globalState) ->
-    (CopySinkInfo bindState globalState -> [[Field]] -> IO ()) ->
-    (CopyFinalizeInfo bindState globalState -> IO ()) ->
-    IO ()
-registerCopyToFunction conn name bindFn initFn sinkFn finalizeFn = do
-    when (Text.null name || Text.any (== '\0') name) $
-        throwRegistrationError "invalid copy function name"
-    bracket c_duckdb_create_copy_function destroyCopyFunction \copyFun -> do
-        when (copyFun == nullPtr) $ throwRegistrationError "allocate copy function"
-        withCallbackResources
-            ( \allocate -> do
-                copyBindPtr <- allocate (mkCopyBindFun (copyBindHandler bindFn))
-                copyInitPtr <- allocate (mkCopyGlobalInitFun (copyGlobalInitHandler initFn))
-                copySinkPtr <- allocate (mkCopySinkFun (copySinkHandler sinkFn))
-                copyFinalizePtr <- allocate (mkCopyFinalizeFun (copyFinalizeHandler finalizeFn))
-                pure CopyFunctionResources{copyBindPtr, copyInitPtr, copySinkPtr, copyFinalizePtr}
-            )
-            (c_duckdb_copy_function_set_extra_info copyFun)
-            \CopyFunctionResources{copyBindPtr, copyInitPtr, copySinkPtr, copyFinalizePtr} -> do
-                TextForeign.withCString name $ c_duckdb_copy_function_set_name copyFun
-                c_duckdb_copy_function_set_bind copyFun copyBindPtr
-                c_duckdb_copy_function_set_global_init copyFun copyInitPtr
-                c_duckdb_copy_function_set_sink copyFun copySinkPtr
-                c_duckdb_copy_function_set_finalize copyFun copyFinalizePtr
-                withConnectionHandle conn \connPtr -> do
-                    rc <- c_duckdb_register_copy_function connPtr copyFun
-                    when (rc /= DuckDBSuccess) $ throwRegistrationError "register copy function"
-
-copyBindHandler ::
-    forall bindState.
-    (CopyBindInfo -> IO bindState) ->
-    DuckDBCopyFunctionBindInfo ->
-    IO ()
-copyBindHandler bindFn info =
-    runCallback (c_duckdb_copy_function_bind_set_error info) do
-        copyBindColumnTypes <- fetchColumnTypes info
-        bindState <- bindFn CopyBindInfo{copyBindColumnTypes}
-        transferCallbackState (c_duckdb_copy_function_bind_set_bind_data info) bindState
-
-copyGlobalInitHandler ::
-    forall bindState globalState.
-    (CopyInitInfo bindState -> IO globalState) ->
-    DuckDBCopyFunctionGlobalInitInfo ->
-    IO ()
-copyGlobalInitHandler initFn info =
-    runCallback (c_duckdb_copy_function_global_init_set_error info) do
-        rawBindState <- c_duckdb_copy_function_global_init_get_bind_data info
-        when (rawBindState == nullPtr) $
-            throwRegistrationError "missing copy bind state"
-        bindState <- deRefStablePtr (castPtrToStablePtr rawBindState :: StablePtr bindState)
-        pathPtr <- c_duckdb_copy_function_global_init_get_file_path info
-        filePath <-
-            if pathPtr == nullPtr
-                then pure ""
-                else Text.unpack <$> peekUtf8CString pathPtr
-        globalState <- initFn CopyInitInfo{copyInitBindState = bindState, copyInitFilePath = filePath}
-        transferCallbackState (c_duckdb_copy_function_global_init_set_global_state info) globalState
-
-copySinkHandler ::
-    forall bindState globalState.
-    (CopySinkInfo bindState globalState -> [[Field]] -> IO ()) ->
-    DuckDBCopyFunctionSinkInfo ->
-    DuckDBDataChunk ->
-    IO ()
-copySinkHandler sinkFn info chunk =
-    runCallback (c_duckdb_copy_function_sink_set_error info) do
-        bindState <- readStablePtrState c_duckdb_copy_function_sink_get_bind_data info
-        globalState <- readStablePtrState c_duckdb_copy_function_sink_get_global_state info
-        rows <- materializeChunkRows chunk
-        sinkFn CopySinkInfo{copySinkBindState = bindState, copySinkGlobalState = globalState} rows
-
-copyFinalizeHandler ::
-    forall bindState globalState.
-    (CopyFinalizeInfo bindState globalState -> IO ()) ->
-    DuckDBCopyFunctionFinalizeInfo ->
-    IO ()
-copyFinalizeHandler finalizeFn info =
-    runCallback (c_duckdb_copy_function_finalize_set_error info) do
-        bindState <- readStablePtrState c_duckdb_copy_function_finalize_get_bind_data info
-        globalState <- readStablePtrState c_duckdb_copy_function_finalize_get_global_state info
-        finalizeFn CopyFinalizeInfo{copyFinalizeBindState = bindState, copyFinalizeGlobalState = globalState}
-
-fetchColumnTypes :: DuckDBCopyFunctionBindInfo -> IO [DuckDBType]
-fetchColumnTypes info = do
-    count <- c_duckdb_copy_function_bind_get_column_count info
-    let indices = [0 .. fromIntegral count - 1] :: [Int]
-    forM indices \idx -> do
-        bracket
-            (c_duckdb_copy_function_bind_get_column_type info (fromIntegral idx))
-            destroyLogicalType
-            c_duckdb_get_type_id
-
-readStablePtrState :: forall a i. (i -> IO (Ptr ())) -> i -> IO a
-readStablePtrState getter info = do
-    rawPtr <- getter info
-    if rawPtr == nullPtr
-        then throwRegistrationError "missing copy callback state"
-        else deRefStablePtr (castPtrToStablePtr rawPtr :: StablePtr a)
-
-materializeChunkRows :: DuckDBDataChunk -> IO [[Field]]
-materializeChunkRows chunk = do
-    rawColumnCount <- c_duckdb_data_chunk_get_column_count chunk
-    let columnCount = fromIntegral rawColumnCount :: Int
-    readers <- mapM (makeColumnReader chunk) [0 .. columnCount - 1]
-    rawRowCount <- c_duckdb_data_chunk_get_size chunk
-    let rowCount = fromIntegral rawRowCount :: Int
-    forM [0 .. rowCount - 1] \row ->
-        forM readers \reader ->
-            reader (fromIntegral row)
-
-type ColumnReader = DuckDBIdx -> IO Field
-
-makeColumnReader :: DuckDBDataChunk -> Int -> IO ColumnReader
-makeColumnReader chunk columnIndex = do
-    readValue <- c_duckdb_data_chunk_get_vector chunk (fromIntegral columnIndex) >>= prepareVectorReader
-    let name = Text.pack ("column" <> show columnIndex)
-    pure \rowIdx -> do
-        fieldValue <- readValue (fromIntegral rowIdx)
-        pure Field{fieldName = name, fieldIndex = columnIndex, fieldValue}
-
-destroyCopyFunction :: DuckDBCopyFunction -> IO ()
-destroyCopyFunction copyFun =
-    alloca \ptr -> poke ptr copyFun >> c_duckdb_destroy_copy_function ptr
-
-foreign import ccall "wrapper"
-    mkCopyBindFun :: (DuckDBCopyFunctionBindInfo -> IO ()) -> IO DuckDBCopyFunctionBindFun
-
-foreign import ccall "wrapper"
-    mkCopyGlobalInitFun :: (DuckDBCopyFunctionGlobalInitInfo -> IO ()) -> IO DuckDBCopyFunctionGlobalInitFun
-
-foreign import ccall "wrapper"
-    mkCopySinkFun :: (DuckDBCopyFunctionSinkInfo -> DuckDBDataChunk -> IO ()) -> IO DuckDBCopyFunctionSinkFun
-
-foreign import ccall "wrapper"
-    mkCopyFinalizeFun :: (DuckDBCopyFunctionFinalizeInfo -> IO ()) -> IO DuckDBCopyFunctionFinalizeFun
+import Database.DuckDB.Simple.Copy.Internal (
+  CopyBindInfo (..),
+  CopyFinalizeInfo (..),
+  CopyFromInfo (..),
+  CopyInitInfo (..),
+  CopySinkInfo (..),
+  CopyTo (..),
+  LogicalTypeId (..),
+  MultiFileOptions (..),
+  TypedRow,
+  defaultMultiFileOptions,
+  registerCopyFromFunction,
+  registerCopyFunction,
+  registerCopyToFunction,
+  registerMultiFileFunction,
+ )
diff --git a/src/Database/DuckDB/Simple/Copy/Internal.hs b/src/Database/DuckDB/Simple/Copy/Internal.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/Copy/Internal.hs
@@ -0,0 +1,394 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE ForeignFunctionInterface #-}
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.Copy.Internal
+-- Description : Share the typed COPY registrations for connections and extensions.
+--
+-- The cabal file lists this hidden module in @other-modules@.
+-- The functions with the suffix @On@ take a registration target.
+-- "Database.DuckDB.Simple.Copy" exports the connection forms.
+-- "Database.DuckDB.Simple.Extension" exports the extension forms.
+module Database.DuckDB.Simple.Copy.Internal (
+  CopyBindInfo (..),
+  LogicalTypeId (..),
+  CopyInitInfo (..),
+  CopySinkInfo (..),
+  CopyFinalizeInfo (..),
+  registerCopyToFunction,
+  registerCopyToFunctionOn,
+  CopyFromInfo (..),
+  registerCopyFromFunction,
+  registerCopyFromFunctionOn,
+  CopyTo (..),
+  registerCopyFunction,
+  registerCopyFunctionOn,
+  TypedRow,
+  MultiFileOptions (..),
+  defaultMultiFileOptions,
+  registerMultiFileFunction,
+  registerMultiFileFunctionOn,
+) where
+
+import Control.Concurrent.MVar (MVar, modifyMVar_, newMVar)
+import Control.Exception (bracket, finally, mask, mask_, onException)
+import Control.Monad (forM, forM_, when)
+import Data.Proxy (Proxy (..))
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Data.Void (Void)
+import Database.DuckDB.Simple.Callback (attachOpaque, ignoreCallbackExceptions, readCallbackState, targetCastFactory, transferCallbackState)
+import Database.DuckDB.Simple.FromField (Field (..), FieldValue)
+import Database.DuckDB.Simple.Internal (Connection, withDatabaseHandle)
+import Database.DuckDB.Simple.Materialize (
+  FallbackReaders (..),
+  ReadFactory,
+  VectorReader,
+  callbackReadFactory,
+  prepareGeometryReader,
+  prepareVectorReader,
+  readCallbackVariant,
+  readFactoryHandle,
+  readInstanceVariant,
+ )
+import Database.DuckDB.Simple.Native
+import Database.DuckDB.Simple.TypeScope (scopedTypeRep, withTypeScope)
+import Database.DuckDB.Simple.Typed (TypedRow (..))
+import Database.DuckDB.Simple.Typed.Table (writeRows)
+import Database.DuckDB.Simple.V2.Copy (
+  CopyFromCallbacks (..),
+  CopyToCallbacks (..),
+  RegistrationTarget (..),
+  copyFromCallbacks,
+  copyToCallbacks,
+  registerCopyFunctionWith,
+  registerMultiFileFunctionWith,
+ )
+import Database.DuckDB.Simple.V2.LogicalRep (logicalTypeToRep)
+import Foreign.C.ConstPtr (ConstPtr (..))
+import Foreign.Marshal.Array (withArray)
+import Foreign.Ptr (FunPtr, Ptr, castFunPtr, castPtr, nullPtr)
+import Foreign.StablePtr (castPtrToStablePtr, castStablePtrToPtr, deRefStablePtr, freeStablePtr, newStablePtr)
+
+-- | Bind-phase metadata for a custom COPY TO function.
+data CopyBindInfo = CopyBindInfo
+  { copyBindColumnTypes :: ![LogicalTypeId]
+  }
+  deriving (Eq, Show)
+
+-- | Init-phase inputs for one output file or partition.
+data CopyInitInfo bindState = CopyInitInfo
+  { copyInitBindState :: !bindState
+  , copyInitFilePath :: !FilePath
+  }
+
+-- | Flush-phase state passed to the row-oriented sink callback.
+data CopySinkInfo bindState globalState = CopySinkInfo
+  { copySinkBindState :: !bindState
+  , copySinkGlobalState :: !globalState
+  }
+
+-- | Finalize-phase inputs for one output file or partition.
+data CopyFinalizeInfo bindState globalState = CopyFinalizeInfo
+  { copyFinalizeBindState :: !bindState
+  , copyFinalizeGlobalState :: !globalState
+  }
+
+-- | Register row-oriented COPY TO callbacks. Native batch buffers are copied.
+-- Use 'registerCopyFunction' for a format with a COPY FROM side too. DuckDB keeps
+-- the first registration of a format name. A later registration of the same name
+-- has no effect and gives no error.
+registerCopyToFunction
+  :: Connection
+  -> Text
+  -> (CopyBindInfo -> IO bindState)
+  -> (CopyInitInfo bindState -> IO globalState)
+  -> (CopySinkInfo bindState globalState -> [[Field]] -> IO ())
+  -> (CopyFinalizeInfo bindState globalState -> IO ())
+  -> IO ()
+registerCopyToFunction = registerCopyToFunctionOn . ConnectionTarget
+
+-- | Register row-oriented COPY TO callbacks on a connection or a loading
+-- extension. The rules of 'registerCopyToFunction' apply.
+registerCopyToFunctionOn
+  :: RegistrationTarget
+  -> Text
+  -> (CopyBindInfo -> IO bindState)
+  -> (CopyInitInfo bindState -> IO globalState)
+  -> (CopySinkInfo bindState globalState -> [[Field]] -> IO ())
+  -> (CopyFinalizeInfo bindState globalState -> IO ())
+  -> IO ()
+registerCopyToFunctionOn target name bindFn initFn sinkFn finalizeFn = do
+  checkCopyName name
+  casts <- targetCastFactory target
+  withVariantReader target \readVariant ->
+    registerCopyOn target name (Just (copyToSide casts readVariant bindFn initFn sinkFn finalizeFn)) Nothing
+
+-- | Check the format name and register the native callbacks of each side.
+registerCopyOn :: RegistrationTarget -> Text -> Maybe CopyToCallbacks -> Maybe CopyFromCallbacks -> IO ()
+registerCopyOn target name to from = do
+  checkCopyName name
+  registerCopyFunctionWith target (\function -> withIdentifier name (checked . c_duckdb_v2_copy_function_set_name function)) to from
+
+-- | Raise the input error for a format name that is empty or contains NUL. A
+-- COPY TO side checks the name before the read of the state of the target.
+checkCopyName :: Text -> IO ()
+checkCopyName name = when (Text.null name || Text.any (== '\0') name) $ throwInvalidArgument "invalid copy function name"
+
+-- | Use the host instance for a connection's COPY TO and a private one for an extension.
+withVariantReader :: RegistrationTarget -> (VectorReader -> IO a) -> IO a
+withVariantReader target action = case target of
+  -- A catalog-owned callback must not keep the managed instance alive.
+  ConnectionTarget connection -> withDatabaseHandle connection (action . readInstanceVariant)
+  ExtensionTarget _ _ -> action readCallbackVariant
+
+-- | The native COPY TO callbacks of the row-oriented functions. The first
+-- argument is the factory of 'targetCastFactory'.
+copyToSide
+  :: forall bindState globalState
+   . Maybe DuckDBV2FactoryHandle
+  -> VectorReader
+  -> (CopyBindInfo -> IO bindState)
+  -> (CopyInitInfo bindState -> IO globalState)
+  -> (CopySinkInfo bindState globalState -> [[Field]] -> IO ())
+  -> (CopyFinalizeInfo bindState globalState -> IO ())
+  -> CopyToCallbacks
+copyToSide casts readVariant bindFn initFn sinkFn finalizeFn =
+  (copyToCallbacks batch flush)
+    { copyToBindCallback = Just bind
+    , copyToInitCallback = Just initialize
+    , copyToFinalizeCallback = Just finalize
+    }
+  where
+    bind info _ = mask \restore -> do
+      count <- output (c_duckdb_v2_copy_to_bind_get_column_count info)
+      types <- acquireItems destroyLogicalType [output (c_duckdb_v2_copy_to_bind_get_column_type info index) | index <- indices count]
+      state <-
+        restore (mapM (\logical -> output (c_duckdb_v2_logical_type_get_id logical) >>= logicalTypeIdFromNative) types >>= bindFn . CopyBindInfo)
+          `onException` releaseItems destroyLogicalType types
+      stable <- newStablePtr (state, types) `onException` releaseItems destroyLogicalType types
+      attachOpaque (c_duckdb_v2_copy_to_bind_set_bind_data info) (castPtr (castStablePtrToPtr stable)) copyBindingDestructor
+        `onException` (freeStablePtr stable >> releaseItems destroyLogicalType types)
+    initialize info _ = do
+      (state, _) <- readCallbackState (c_duckdb_v2_copy_to_init_get_bind_data info)
+      path <- output (c_duckdb_v2_copy_to_init_get_file_path info) >>= readText
+      global <- initFn (CopyInitInfo state (Text.unpack path))
+      transferCallbackState (attachOpaque (c_duckdb_v2_copy_to_init_set_init_data info)) global
+    batch info context = withContextFactory context $ \factory -> do
+      (_, types) <- readCallbackState (c_duckdb_v2_copy_to_batch_get_bind_data info) :: IO (bindState, [DuckDBV2LogicalTypeHandle])
+      rows <-
+        bracket
+          (output (c_duckdb_v2_copy_to_batch_take_input info))
+          (destroy c_duckdb_v2_column_data_collection_destroy)
+          (materializeCollection (callbackReadFactory casts factory) readVariant types)
+      transferCallbackState (attachOpaque (c_duckdb_v2_copy_to_batch_set_batch_data info)) rows
+    flush info context = withTypeScope \scope -> withContextFactory context \factory -> do
+      (state, types) <- readCallbackState (c_duckdb_v2_copy_to_flush_get_bind_data info)
+      global <- readCallbackState (c_duckdb_v2_copy_to_flush_get_init_data info)
+      rows <- readCallbackState (c_duckdb_v2_copy_to_flush_get_batch_data info)
+      -- Bind data owns the types through this callback. Copy them into the
+      -- flush scope. See Note [Scoped field types] in
+      -- "Database.DuckDB.Simple.TypeScope".
+      columnTypes <- mapM (scopedTypeRep scope (pure factory) . output . c_duckdb_v2_logical_type_copy) types
+      let fields = zipWith3 (\index logical value -> Field (Text.pack ("column" <> show index)) index value logical) [0 ..] columnTypes
+      sinkFn (CopySinkInfo state global) (map fields rows)
+    finalize info _ = do
+      (state, _) <- readCallbackState (c_duckdb_v2_copy_to_finalize_get_bind_data info)
+      global <- readCallbackState (c_duckdb_v2_copy_to_finalize_get_init_data info)
+      finalizeFn (CopyFinalizeInfo state global)
+
+-- | Release native bind descriptors before their database closes. See
+-- Note [Callback ownership] in "Database.DuckDB.Simple.Callback" for the rules
+-- of a destructor.
+releaseCopyBinding :: Ptr Void -> IO ()
+releaseCopyBinding raw =
+  mask_
+    $ ignoreCallbackExceptions
+    $ if raw == nullPtr
+      then pure ()
+      else do
+        let stable = castPtrToStablePtr (castPtr raw)
+        (deRefStablePtr stable >>= \(_, types) -> releaseItems destroyLogicalType types)
+          `finally` freeStablePtr stable
+
+foreign export ccall "duckdb_simple_release_copy_binding" releaseCopyBinding :: Ptr Void -> IO ()
+
+foreign import ccall "&duckdb_simple_release_copy_binding" copyBindingDestructorAddress :: FunPtr (Ptr Void -> IO ())
+
+-- | Use a static destructor address for native bind-state ownership.
+copyBindingDestructor :: DuckDBV2OpaqueDestroyFn
+copyBindingDestructor = DuckDBV2OpaqueDestroyFn (castFunPtr copyBindingDestructorAddress)
+
+-- | Copy each scanned chunk before the scan invalidates its borrowed buffers.
+-- The factory makes the chunk and reads GEOMETRY.
+materializeCollection
+  :: ReadFactory -> VectorReader -> [DuckDBV2LogicalTypeHandle] -> DuckDBV2ColumnDataCollectionHandle -> IO [[FieldValue]]
+materializeCollection readFactory readVariant types collection =
+  withArray types \typePtr ->
+    bracket
+      (output (c_duckdb_v2_data_chunk_create (readFactoryHandle readFactory) (ConstPtr typePtr) (fromIntegral (length types))))
+      (destroy c_duckdb_v2_data_chunk_destroy)
+      \chunk ->
+        bracket
+          (output (c_duckdb_v2_column_data_collection_shared_scan_state_create collection))
+          (destroy c_duckdb_v2_column_data_collection_shared_scan_state_destroy)
+          \shared ->
+            bracket
+              (output (c_duckdb_v2_column_data_collection_worker_scan_state_create collection))
+              (destroy c_duckdb_v2_column_data_collection_worker_scan_state_destroy)
+              \worker ->
+                let loop groups = do
+                      produced <- output (c_duckdb_v2_column_data_collection_scan collection shared worker chunk)
+                      if produced == 0
+                        then pure (concat (reverse groups))
+                        else do
+                          rows <-
+                            materializeChunkRows
+                              (FallbackReaders (logicalTypeToRep (readFactoryHandle readFactory)) readVariant (prepareGeometryReader readFactory))
+                              chunk
+                          loop (rows : groups)
+                in  loop []
+
+-- | Copy the values of a complete chunk before its collection scan advances.
+-- The flush callback adds the fields and their scoped type actions.
+materializeChunkRows :: FallbackReaders -> DuckDBV2DataChunkHandle -> IO [[FieldValue]]
+materializeChunkRows readers chunk = do
+  columns <- output (c_duckdb_v2_data_chunk_get_vector_count chunk)
+  columnReaders <- forM [0 .. fromIntegral columns - 1] \index -> do
+    vector <- output (c_duckdb_v2_data_chunk_get_vector chunk (fromIntegral (index :: Int)))
+    prepareVectorReader readers vector
+  rows <- output (c_duckdb_v2_data_chunk_get_size chunk)
+  forM [0 .. fromIntegral rows - 1] \row -> mapM ($ row) columnReaders
+
+-- | The inputs of the COPY FROM side for one statement. The path is the text
+-- of the statement. DuckDB does not expand a glob pattern in it. The names and
+-- the types are the columns of the target table, in order.
+data CopyFromInfo = CopyFromInfo
+  { copyFromPath :: !FilePath
+  , copyFromColumnNames :: ![Text]
+  , copyFromColumnTypes :: ![LogicalTypeId]
+  }
+  deriving (Eq, Show)
+
+-- | Register the COPY FROM side of a format. Use 'registerCopyFunction' for a
+-- format with the two sides. DuckDB keeps the first registration of a format
+-- name. A later registration of the same name has no effect and gives no error.
+--
+-- The function gets the path and the columns of the target table. It gives the
+-- rows to insert. It runs one time for each run of a COPY FROM statement. DuckDB
+-- takes the rows from the list one chunk at a time, so the list can be lazy. A
+-- row must have one column for each column of the table, in the same order. An
+-- exception from the function or from a row fails the statement.
+--
+-- > registerCopyFromFunction conn "lines" \info -> map Only . Text.lines <$> TextIO.readFile (copyFromPath info)
+registerCopyFromFunction :: (TypedRow row) => Connection -> Text -> (CopyFromInfo -> IO [row]) -> IO ()
+registerCopyFromFunction = registerCopyFromFunctionOn . ConnectionTarget
+
+-- | Register the COPY FROM side of a format on a connection or a loading
+-- extension. The rules of 'registerCopyFromFunction' apply.
+registerCopyFromFunctionOn :: (TypedRow row) => RegistrationTarget -> Text -> (CopyFromInfo -> IO [row]) -> IO ()
+registerCopyFromFunctionOn target name readRows = registerCopyOn target name Nothing (Just (copyFromSide name readRows))
+
+-- | The native COPY FROM callbacks of a typed reader. The bind callback reads
+-- the path and the columns of the target table. See
+-- Note [Row lists of typed scans] in "Database.DuckDB.Simple.Typed.Table".
+copyFromSide :: forall row. (TypedRow row) => Text -> (CopyFromInfo -> IO [row]) -> CopyFromCallbacks
+copyFromSide name readRows = (copyFromCallbacks bind execute){copyFromInitGlobalCallback = Just initialize}
+  where
+    width = length (rowColumnDeclarations (Proxy @row))
+    bind info _ = do
+      path <- output (c_duckdb_v2_copy_from_bind_get_file_path info) >>= readText
+      count <- output (c_duckdb_v2_copy_from_bind_get_column_count info)
+      when (fromIntegral count /= width) $
+        throwInvalidArgument
+          ( "the table of COPY FROM has "
+              <> Text.pack (show (fromIntegral count :: Int))
+              <> " columns, but a row of "
+              <> name
+              <> " has "
+              <> Text.pack (show width)
+          )
+      let columns = takeWhile (< count) [0 ..]
+      names <- forM columns \index -> output (c_duckdb_v2_copy_from_bind_get_column_name info index) >>= readIdentifier
+      types <- forM columns \index ->
+        bracket
+          (output (c_duckdb_v2_copy_from_bind_get_column_type info index))
+          destroyLogicalType
+          (\logical -> output (c_duckdb_v2_logical_type_get_id logical) >>= logicalTypeIdFromNative)
+      transferCallbackState
+        (attachOpaque (c_duckdb_v2_copy_from_bind_set_bind_data info))
+        (readRows (CopyFromInfo (Text.unpack path) names types))
+    initialize info _ = do
+      scan <- readCallbackState (c_duckdb_v2_copy_from_init_global_get_bind_data info)
+      remaining <- scan >>= newMVar :: IO (MVar [row])
+      transferCallbackState (attachOpaque (c_duckdb_v2_copy_from_init_global_set_global_state info)) remaining
+    execute info context = withContextFactory context \factory -> do
+      remaining <- readCallbackState (c_duckdb_v2_copy_from_exec_get_global_state info) :: IO (MVar [row])
+      chunk <- output (c_duckdb_v2_copy_from_exec_get_output_chunk info)
+      -- The lock gives each row to one call only. See
+      -- Note [Row lists of typed scans] in "Database.DuckDB.Simple.Typed.Table".
+      modifyMVar_ remaining (writeRows factory chunk (take width [0 ..]))
+
+-- | The COPY TO side of a format. The four functions have the roles of the
+-- four functions of 'registerCopyToFunction'.
+data CopyTo bindState globalState = CopyTo
+  { copyToBind :: CopyBindInfo -> IO bindState
+  , copyToInit :: CopyInitInfo bindState -> IO globalState
+  , copyToSink :: CopySinkInfo bindState globalState -> [[Field]] -> IO ()
+  , copyToFinalize :: CopyFinalizeInfo bindState globalState -> IO ()
+  }
+
+-- | Register a format with a COPY TO side and a COPY FROM side under one
+-- name. The rules of 'registerCopyToFunction' apply to the COPY TO side. The
+-- rules of 'registerCopyFromFunction' apply to the COPY FROM side. Two
+-- registrations of one name do not give a format with the two sides, because
+-- DuckDB keeps the first registration.
+registerCopyFunction :: (TypedRow row) => Connection -> Text -> CopyTo bindState globalState -> (CopyFromInfo -> IO [row]) -> IO ()
+registerCopyFunction = registerCopyFunctionOn . ConnectionTarget
+
+-- | Register a format with the two sides on a connection or a loading
+-- extension. The rules of 'registerCopyFunction' apply.
+registerCopyFunctionOn
+  :: (TypedRow row) => RegistrationTarget -> Text -> CopyTo bindState globalState -> (CopyFromInfo -> IO [row]) -> IO ()
+registerCopyFunctionOn target name (CopyTo bindFn initFn sinkFn finalizeFn) readRows = do
+  checkCopyName name
+  casts <- targetCastFactory target
+  withVariantReader target \readVariant ->
+    registerCopyOn target name (Just (copyToSide casts readVariant bindFn initFn sinkFn finalizeFn)) (Just (copyFromSide name readRows))
+
+-- | Options supplied to DuckDB's multi-file wrapper.
+data MultiFileOptions = MultiFileOptions
+  { multiFileReaderType :: Maybe Text
+  , multiFileExtension :: Maybe Text
+  }
+  deriving (Eq, Show)
+
+-- | Use native defaults for reader descriptions and directory expansion.
+defaultMultiFileOptions :: MultiFileOptions
+defaultMultiFileOptions = MultiFileOptions Nothing Nothing
+
+-- | Register globbing, file lists, filename columns, and hive partition
+-- support for a registered single-file table function. The second name is that
+-- table function. DuckDB can run the exec callback of the single-file function on
+-- more than one thread at the same time for one scan. A function from
+-- 'Database.DuckDB.Simple.Function.createTableFunction' permits that. A table
+-- function with native callbacks must synchronize its scan state.
+registerMultiFileFunction :: Connection -> Text -> Text -> MultiFileOptions -> IO ()
+registerMultiFileFunction connection = registerMultiFileFunctionOn (ConnectionTarget connection)
+
+-- | Register a multi-file wrapper on a connection or a loading extension. The
+-- second name is the registered single-file table function. Both names must not
+-- be empty and must not contain NUL.
+registerMultiFileFunctionOn :: RegistrationTarget -> Text -> Text -> MultiFileOptions -> IO ()
+registerMultiFileFunctionOn target name singleFile MultiFileOptions{multiFileReaderType, multiFileExtension} = do
+  when (any (\value -> Text.null value || Text.any (== '\0') value) [name, singleFile]) $
+    throwInvalidArgument "invalid multi-file function name"
+  registerMultiFileFunctionWith target \function -> do
+    withText name (\(ConstPtr view) -> checked (c_duckdb_v2_multi_file_function_set_name function view))
+    withText singleFile (\(ConstPtr view) -> checked (c_duckdb_v2_multi_file_function_set_single_file_function function view))
+    forM_ multiFileReaderType \value -> withText value (\(ConstPtr view) -> checked (c_duckdb_v2_multi_file_function_set_reader_type function view))
+    forM_ multiFileExtension \value -> withText value (\(ConstPtr view) -> checked (c_duckdb_v2_multi_file_function_set_file_extension function view))
diff --git a/src/Database/DuckDB/Simple/Deprecated/Streaming.hs b/src/Database/DuckDB/Simple/Deprecated/Streaming.hs
deleted file mode 100644
--- a/src/Database/DuckDB/Simple/Deprecated/Streaming.hs
+++ /dev/null
@@ -1,87 +0,0 @@
-{-# LANGUAGE BlockArguments #-}
-
-{- |
-Module      : Database.DuckDB.Simple.Deprecated.Streaming
-Description : Optional native streaming through DuckDB's deprecated execution API.
-
-Import this module qualified to request native streaming. DuckDB can still
-materialize a result, and operators such as sorting can buffer data. Streaming
-reduces result storage when the query supports it; it does not bound all query
-memory. The default @Database.DuckDB.Simple@ API materializes native results.
-
-Rows and Arrow batches use the same decoders and cleanup as the default API.
-Cancellation also interrupts native chunk fetching. Prompt interruption requires
-@-threaded@ and waits for native code and Haskell callbacks to return.
-
-Serialize connection use for the entire cursor or fold. Another query on the
-same connection can invalidate an active stream. Close or reset an abandoned
-statement to release its result.
--}
-module Database.DuckDB.Simple.Deprecated.Streaming
-    {-# DEPRECATED "Uses DuckDB's deprecated streaming execution API. Prefer Database.DuckDB.Simple or Database.DuckDB.Simple.Arrow when materialization is acceptable." #-} (
-    fold,
-    fold_,
-    foldNamed,
-    nextRow,
-    nextRowWith,
-    foldArrow,
-    foldArrow_,
-) where
-
-import Database.DuckDB.FFI (ArrowArray, ArrowSchema)
-import Database.DuckDB.Simple (bind, bindNamed, withStatement)
-import qualified Database.DuckDB.Simple.Arrow.Internal as Arrow
-import Database.DuckDB.Simple.FromRow (FromRow (..), RowParser)
-import Database.DuckDB.Simple.Internal (Connection, Query, ResultMode (StreamingResult), Statement)
-import qualified Database.DuckDB.Simple.Result as Result
-import Database.DuckDB.Simple.ToField (NamedParam)
-import Database.DuckDB.Simple.ToRow (ToRow (..))
-import Foreign.Ptr (Ptr)
-
--- | Fold a parameterized query, requesting native streaming.
-fold :: (FromRow row, ToRow params) => Connection -> Query -> params -> a -> (a -> row -> IO a) -> IO a
-fold conn sql params initial step =
-    withStatement conn sql \stmt -> do
-        bind stmt (toRow params)
-        Result.foldStatementWith StreamingResult fromRow stmt initial step
-
--- | Fold a query without parameters, requesting native streaming.
-fold_ :: (FromRow row) => Connection -> Query -> a -> (a -> row -> IO a) -> IO a
-fold_ conn sql initial step =
-    withStatement conn sql \stmt ->
-        Result.foldStatementWith StreamingResult fromRow stmt initial step
-
--- | Fold a query with named parameters, requesting native streaming.
-foldNamed :: (FromRow row) => Connection -> Query -> [NamedParam] -> a -> (a -> row -> IO a) -> IO a
-foldNamed conn sql params initial step =
-    withStatement conn sql \stmt -> do
-        bindNamed stmt params
-        Result.foldStatementWith StreamingResult fromRow stmt initial step
-
--- | Fetch the next row, requesting native streaming on the first fetch.
-nextRow :: (FromRow r) => Statement -> IO (Maybe r)
-nextRow = nextRowWith fromRow
-
-{- | Fetch a row with a custom parser, requesting streaming on the first fetch.
-  The active result retains its execution mode until reset. Switching between
-  this module and the default @Database.DuckDB.Simple.nextRow@ does not restart
-  or change an active result. EOF remains exhausted until an explicit reset.
--}
-nextRowWith :: RowParser r -> Statement -> IO (Maybe r)
-nextRowWith = Result.nextRowWith StreamingResult
-
-{- | Fold Arrow batches, requesting native streaming.
-  Each batch has a separate schema and array. The callback may read, release,
-  or move them under the Arrow C Data Interface. The pointers themselves are
-  valid during the callback only. See @Database.DuckDB.Simple.Arrow@ for the
-  ownership rules.
-  Arrow conversion uses the supported API; query execution uses the deprecated
-  streaming entry point. The fold releases contents that the consumer has not
-  released or moved. The consumer owns any moved contents.
--}
-foldArrow :: (ToRow params) => Connection -> Query -> params -> a -> (a -> Ptr ArrowSchema -> Ptr ArrowArray -> IO a) -> IO a
-foldArrow = Arrow.foldArrowWith StreamingResult
-
--- | Fold Arrow batches from a query without parameters.
-foldArrow_ :: Connection -> Query -> a -> (a -> Ptr ArrowSchema -> Ptr ArrowArray -> IO a) -> IO a
-foldArrow_ conn sql = foldArrow conn sql ()
diff --git a/src/Database/DuckDB/Simple/Element.hs b/src/Database/DuckDB/Simple/Element.hs
--- a/src/Database/DuckDB/Simple/Element.hs
+++ b/src/Database/DuckDB/Simple/Element.hs
@@ -1,228 +1,316 @@
 {-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE MagicHash #-}
 {-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE TypeApplications #-}
 
-{- | Decoders for one native DuckDB element in vector memory. Result decoding
-uses them for the types whose element needs no logical type metadata.
--}
+-- |
+-- Module      : Database.DuckDB.Simple.Element
+-- Description : Decoders for one native DuckDB element in vector memory.
+--
+-- Result decoding uses them for the types whose element needs no logical type
+-- metadata.
 module Database.DuckDB.Simple.Element (
-    chunkIsRowValid,
-    bitStringFromBytes,
-    chunkDecodeBlob,
-    decodeElement,
-    duckDBHugeIntToInteger,
-    vectorElementType,
-    withVectorType,
+  chunkIsRowValid,
+  containsType,
+  decodeElement,
+  duckDBHugeIntToInteger,
+  timeTzMaxOffsetSeconds,
+  timeTzOffsetBits,
+  valueTypeName,
+  vectorElementType,
+  withVectorType,
 ) where
 
-import Control.Exception (bracket, throwIO)
-import Control.Monad (when)
-import Data.Bits (clearBit, shiftL, xor, (.|.))
+import Control.Exception (bracket, throwIO, try)
+import Data.Bits (clearBit, shiftL, shiftR, testBit, xor, (.&.), (.|.))
 import qualified Data.ByteString as BS
-import Data.Int (Int64)
+import Data.Coerce (coerce)
+import Data.Int (Int32, Int64)
 import Data.Ratio ((%))
+import Data.Text (Text)
+import qualified Data.Text as Text
 import qualified Data.Text.Encoding as TextEncoding
 import Data.Time.Calendar (addDays, fromGregorian)
 import Data.Time.Clock.POSIX (posixSecondsToUTCTime)
-import Data.Time.LocalTime (TimeOfDay (..), minutesToTimeZone, utc, utcToLocalTime)
+import Data.Time.LocalTime (TimeOfDay (..), utc, utcToLocalTime)
 import qualified Data.UUID as UUID
+import Data.Void (Void)
 import Data.Word (Word64, Word8)
-import Database.DuckDB.FFI
 import Database.DuckDB.Simple.FromField (
-    BigNum (..),
-    BitString (..),
-    FieldValue (..),
-    IntervalValue (..),
-    TimeWithZone (..),
-    fromBigNumBytes,
+  BigNum (..),
+  BitString (..),
+  FieldValue (..),
+  IntervalValue (..),
+  TimeWithZone (..),
+  fieldTypeName,
  )
-import Database.DuckDB.Simple.LogicalRep (destroyLogicalType)
+import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep (..), StructField (..), UnionMemberType (..))
+import Database.DuckDB.Simple.Native
 import Database.DuckDB.Simple.Time (Date, LocalTimestamp, UTCTimestamp, Unbounded (..))
-import Foreign.C.Types (CBool (..))
-import Foreign.Marshal.Alloc (alloca)
-import Foreign.Ptr (Ptr, castPtr, nullPtr, plusPtr)
+import Foreign.C.ConstPtr (ConstPtr (..))
+import Foreign.Marshal.Alloc (alloca, allocaBytes)
+import Foreign.Marshal.Array (advancePtr)
+import Foreign.Ptr (Ptr, castPtr, nullPtr)
 import Foreign.Storable (Storable (..), peekElemOff)
+import GHC.Exts (Ptr (..), Word (W#))
+import GHC.Num.Integer (integerFromAddr)
+import GHC.Records (getField)
 
-chunkIsRowValid :: Ptr Word64 -> DuckDBIdx -> IO Bool
-chunkIsRowValid validity rowIdx
-    | validity == nullPtr = pure True
-    | otherwise = do
-        CBool flag <- c_duckdb_validity_row_is_valid validity rowIdx
-        pure (flag /= 0)
+{- Note [Vector memory layouts]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Some readers and writers use the memory of a vector directly. These are the
+layouts that they use.
 
-chunkDecodeBlob :: Ptr () -> DuckDBIdx -> IO BS.ByteString
-chunkDecodeBlob dataPtr rowIdx = do
-    let base = castPtr dataPtr :: Ptr Word8
-        offset = fromIntegral rowIdx * duckdbStringTSize
-        stringPtr = castPtr (base `plusPtr` offset) :: Ptr DuckDBStringT
-    len <- c_duckdb_string_t_length stringPtr
-    if len == 0
-        then pure BS.empty
-        else do
-            ptr <- c_duckdb_string_t_data stringPtr
-            BS.packCStringLen (ptr, fromIntegral len)
+The validity mask. Each uint64_t word covers 64 rows: bit N of word W is row
+W*64+N, and a set bit means valid. The header gives this layout in the comment
+of duckdb_v2_vector_flat_get_validity_mutable.
 
-duckdbStringTSize :: Int
-duckdbStringTSize = 16
+- Read (chunkIsRowValid). The V2 API has no call that reads the validity of
+  one row, so the reader reads the mask memory from duckdb_v2_vector_get_view.
+  The header does not say what a null mask pointer means. In DuckDB 2.0.0 a
+  null pointer means that the vector has no mask, and then every row is valid.
 
-{- | Decode DuckDB's BIT bytes: a padding count, then the data bytes. Clear the
-unused high bits of the first data byte, which DuckDB sets.
+- Write (markValid and markInvalid). The writer sets or clears one bit of the
+  mask from duckdb_v2_vector_flat_get_validity_mutable. The header says that
+  this call allocates the mask on first use, so the pointer is never null. The
+  header also says that a raw mask write marks only the rows of this vector,
+  and that a NULL STRUCT or ARRAY row needs duckdb_v2_vector_set_null. The
+  writer writes a mask bit only for a raw result type. A NULL of each other
+  result type goes through duckdb_v2_vector_set_value. See
+  Note [Result writers] in "Database.DuckDB.Simple.Function.Internal".
+
+The bytes slot. A VARCHAR, BLOB, BIT, or BIGNUM element is a 16-byte
+duckdb_v2_bytes value. The byte length is a uint32_t at byte 0. A value of at
+most DUCKDB_V2_BYTES_INLINE_LENGTH (12) bytes follows the length, at byte 4.
+For a longer value, the slot holds the first 4 bytes of the value at byte 4 and
+the address of the value at byte 8. The header defines the slot in the comment
+of struct duckdb_v2_bytes.
+
+- Read (chunkDecodeBlob). The reader reads the generated fields of the union.
+
+- Write (writeArenaText). The writer needs no factory. It writes the length and
+  the bytes through the generated field pointers, as the reader reads them. A
+  longer value goes to the arena of the vector.
+
+The storage of a DECIMAL or ENUM element depends on the type (decimalStorage and
+enumStorage). The header of duckdb_v2_vector_get_view gives both mappings.
 -}
+
+-- | Read a validity bit of a mask from @duckdb_v2_vector_get_view@. A null
+-- mask pointer gives 'True' for each row. See Note [Vector memory layouts].
+chunkIsRowValid :: Ptr Word64 -> DuckDBIdx -> IO Bool
+chunkIsRowValid validity row
+  | validity == nullPtr = pure True
+  | otherwise = (\word -> testBit word (fromIntegral (row `rem` 64))) <$> peekElemOff validity (fromIntegral (row `div` 64))
+
+-- | Copy one generated V2 byte value, including interior NUL bytes. See
+-- Note [Vector memory layouts].
+chunkDecodeBlob :: Ptr Void -> DuckDBIdx -> IO BS.ByteString
+chunkDecodeBlob dataPtr row = do
+  -- Read each field through its generated field pointer. A getField on the
+  -- union value calls the bindings package. That call copies the union.
+  let ptr = advancePtr @DuckDBV2Bytes (castPtr dataPtr) (fromIntegral row)
+      value = getField @"value" ptr
+  len <- peek (getField @"length" (getField @"inlined" value))
+  source <-
+    if len <= fromIntegral dUCKDB_V2_BYTES_INLINE_LENGTH
+      then pure (coerce (getField @"inlined" (getField @"inlined" value)))
+      else peek (getField @"ptr" (getField @"pointer" value))
+  if len == 0 then pure BS.empty else BS.packCStringLen (source, fromIntegral len)
+
+-- | Decode DuckDB's BIT bytes: a padding count, then the data bytes. Clear the
+-- unused high bits of the first data byte, which DuckDB sets.
 bitStringFromBytes :: BS.ByteString -> BitString
 bitStringFromBytes bytes = case BS.unpack bytes of
-    [] -> BitString 0 BS.empty
-    [padding] -> BitString padding BS.empty
-    padding : first : rest ->
-        BitString padding (BS.pack (foldl clearBit first [8 - fromIntegral padding .. 7] : rest))
+  [] -> BitString 0 BS.empty
+  [padding] -> BitString padding BS.empty
+  padding : first : rest ->
+    BitString padding (BS.pack (foldl clearBit first [8 - fromIntegral padding .. 7] : rest))
 
 -- | Borrow the logical type of a vector. The type is destroyed after the action.
-withVectorType :: DuckDBVector -> (DuckDBLogicalType -> IO a) -> IO a
-withVectorType vector = bracket (c_duckdb_vector_get_column_type vector) destroyLogicalType
+withVectorType :: DuckDBV2VectorHandle -> (DuckDBV2LogicalTypeHandle -> IO a) -> IO a
+withVectorType vector = bracket (output (c_duckdb_v2_vector_get_logical_type vector)) destroyLogicalType
 
-vectorElementType :: DuckDBVector -> IO DuckDBType
-vectorElementType vec =
-    bracket (c_duckdb_vector_get_column_type vec) destroyLogicalType c_duckdb_get_type_id
+-- | Read the native logical type id of a vector.
+vectorElementType :: DuckDBV2VectorHandle -> IO DuckDBV2LogicalTypeId
+vectorElementType vector = withVectorType vector (output . c_duckdb_v2_logical_type_get_id)
 
-{- | Decode the element at an index of a vector's data. The type must not need
-logical type metadata: DECIMAL, ENUM, GEOMETRY, and nested types use their own
-decoders. The caller checks validity.
--}
-decodeElement :: DuckDBType -> Ptr () -> Int -> IO FieldValue
+-- | Decode the element at an index of a vector's data. The type must not need
+-- logical type metadata: DECIMAL, ENUM, GEOMETRY, and nested types use their own
+-- decoders. The caller checks validity.
+decodeElement :: DuckDBV2LogicalTypeId -> Ptr Void -> Int -> IO FieldValue
 decodeElement dtype dataPtr rowIdx = case dtype of
-    DuckDBTypeBoolean -> do
-        raw <- peekElemOff (castPtr dataPtr :: Ptr Word8) rowIdx
-        pure (FieldBool (raw /= 0))
-    DuckDBTypeTinyInt -> FieldInt8 <$> peekElemOff (castPtr dataPtr) rowIdx
-    DuckDBTypeSmallInt -> FieldInt16 <$> peekElemOff (castPtr dataPtr) rowIdx
-    DuckDBTypeInteger -> FieldInt32 <$> peekElemOff (castPtr dataPtr) rowIdx
-    DuckDBTypeBigInt -> FieldInt64 <$> peekElemOff (castPtr dataPtr) rowIdx
-    DuckDBTypeUTinyInt -> FieldWord8 <$> peekElemOff (castPtr dataPtr) rowIdx
-    DuckDBTypeUSmallInt -> FieldWord16 <$> peekElemOff (castPtr dataPtr) rowIdx
-    DuckDBTypeUInteger -> FieldWord32 <$> peekElemOff (castPtr dataPtr) rowIdx
-    DuckDBTypeUBigInt -> FieldWord64 <$> peekElemOff (castPtr dataPtr) rowIdx
-    DuckDBTypeFloat -> FieldFloat <$> peekElemOff (castPtr dataPtr) rowIdx
-    DuckDBTypeDouble -> FieldDouble <$> peekElemOff (castPtr dataPtr) rowIdx
-    DuckDBTypeVarchar -> FieldText . TextEncoding.decodeUtf8 <$> chunkDecodeBlob dataPtr index
-    DuckDBTypeStringLiteral -> FieldText . TextEncoding.decodeUtf8 <$> chunkDecodeBlob dataPtr index
-    DuckDBTypeBlob -> FieldBlob <$> chunkDecodeBlob dataPtr index
-    DuckDBTypeUUID -> do
-        DuckDBUHugeInt lower upperBiased <- peekElemOff (castPtr dataPtr :: Ptr DuckDBUHugeInt) rowIdx
-        let upper = upperBiased `xor` (0x8000000000000000 :: Word64)
-        pure (FieldUUID (UUID.fromWords64 (fromIntegral upper) lower))
-    DuckDBTypeDate -> peekElemOff (castPtr dataPtr) rowIdx >>= fmap FieldDate . decodeDuckDBDate
-    DuckDBTypeTime -> peekElemOff (castPtr dataPtr) rowIdx >>= fmap FieldTime . decodeDuckDBTime
-    DuckDBTypeTimeNs -> FieldTime . decodeDuckDBTimeNs <$> peekElemOff (castPtr dataPtr) rowIdx
-    DuckDBTypeTimeTz -> peekElemOff (castPtr dataPtr) rowIdx >>= fmap FieldTimeTZ . decodeDuckDBTimeTz
-    DuckDBTypeTimestamp -> peekElemOff (castPtr dataPtr) rowIdx >>= fmap FieldTimestamp . decodeDuckDBTimestamp
-    DuckDBTypeTimestampS -> peekElemOff (castPtr dataPtr) rowIdx >>= fmap FieldTimestamp . decodeDuckDBTimestampSeconds
-    DuckDBTypeTimestampMs -> peekElemOff (castPtr dataPtr) rowIdx >>= fmap FieldTimestamp . decodeDuckDBTimestampMilliseconds
-    DuckDBTypeTimestampNs -> peekElemOff (castPtr dataPtr) rowIdx >>= fmap FieldTimestamp . decodeDuckDBTimestampNanoseconds
-    DuckDBTypeTimestampTz -> peekElemOff (castPtr dataPtr) rowIdx >>= fmap FieldTimestampTZ . decodeDuckDBTimestampUTCTime
-    DuckDBTypeInterval -> FieldInterval . intervalValueFromDuckDB <$> peekElemOff (castPtr dataPtr) rowIdx
-    DuckDBTypeHugeInt -> FieldHugeInt . duckDBHugeIntToInteger <$> peekElemOff (castPtr dataPtr) rowIdx
-    DuckDBTypeUHugeInt -> FieldUHugeInt . duckDBUHugeIntToInteger <$> peekElemOff (castPtr dataPtr) rowIdx
-    DuckDBTypeBit -> FieldBit . bitStringFromBytes <$> chunkDecodeBlob dataPtr index
-    DuckDBTypeBigNum -> do
-        bytes <- chunkDecodeBlob dataPtr index
-        pure (FieldBigNum (BigNum (if BS.length bytes < 3 then 0 else fromBigNumBytes (BS.unpack bytes))))
-    DuckDBTypeIntegerLiteral -> FieldInt64 <$> peekElemOff (castPtr dataPtr) rowIdx
-    DuckDBTypeInvalid ->
-        error "duckdb-simple: INVALID type in eager result"
-    DuckDBTypeAny ->
-        error "duckdb-simple: ANY columns should not appear in results"
-    other ->
-        error ("duckdb-simple: UNKNOWN type in eager result: " <> show other)
+  DuckDBV2LogicalTypeIdBoolean -> do
+    raw <- peekElemOff (castPtr dataPtr :: Ptr Word8) rowIdx
+    pure (FieldBool (raw /= 0))
+  DuckDBV2LogicalTypeIdTinyInt -> FieldInt8 <$> peekElemOff (castPtr dataPtr) rowIdx
+  DuckDBV2LogicalTypeIdSmallInt -> FieldInt16 <$> peekElemOff (castPtr dataPtr) rowIdx
+  DuckDBV2LogicalTypeIdInteger -> FieldInt32 <$> peekElemOff (castPtr dataPtr) rowIdx
+  DuckDBV2LogicalTypeIdBigInt -> FieldInt64 <$> peekElemOff (castPtr dataPtr) rowIdx
+  DuckDBV2LogicalTypeIdUTinyInt -> FieldWord8 <$> peekElemOff (castPtr dataPtr) rowIdx
+  DuckDBV2LogicalTypeIdUSmallInt -> FieldWord16 <$> peekElemOff (castPtr dataPtr) rowIdx
+  DuckDBV2LogicalTypeIdUInteger -> FieldWord32 <$> peekElemOff (castPtr dataPtr) rowIdx
+  DuckDBV2LogicalTypeIdUBigInt -> FieldWord64 <$> peekElemOff (castPtr dataPtr) rowIdx
+  DuckDBV2LogicalTypeIdFloat -> FieldFloat <$> peekElemOff (castPtr dataPtr) rowIdx
+  DuckDBV2LogicalTypeIdDouble -> FieldDouble <$> peekElemOff (castPtr dataPtr) rowIdx
+  DuckDBV2LogicalTypeIdVarchar -> FieldText . TextEncoding.decodeUtf8 <$> chunkDecodeBlob dataPtr index
+  DuckDBV2LogicalTypeIdBlob -> FieldBlob <$> chunkDecodeBlob dataPtr index
+  DuckDBV2LogicalTypeIdUUID -> do
+    DuckDBV2HugeintT lower upperBiased <- peekElemOff (castPtr dataPtr :: Ptr DuckDBV2HugeintT) rowIdx
+    let upper = fromIntegral upperBiased `xor` (0x8000000000000000 :: Word64)
+    pure (FieldUUID (UUID.fromWords64 (fromIntegral upper) lower))
+  DuckDBV2LogicalTypeIdDate -> peekElemOff (castPtr dataPtr) rowIdx >>= fmap FieldDate . decodeDuckDBDate
+  DuckDBV2LogicalTypeIdTime -> peekElemOff (castPtr dataPtr) rowIdx >>= fmap FieldTime . decodeDuckDBTime
+  DuckDBV2LogicalTypeIdTimeNs -> FieldTime . decodeDuckDBTimeNs <$> peekElemOff (castPtr dataPtr) rowIdx
+  DuckDBV2LogicalTypeIdTimeTz -> FieldTimeTZ . decodeDuckDBTimeTz <$> peekElemOff (castPtr dataPtr) rowIdx
+  DuckDBV2LogicalTypeIdTimestamp -> peekElemOff (castPtr dataPtr) rowIdx >>= fmap FieldTimestamp . decodeDuckDBTimestamp
+  DuckDBV2LogicalTypeIdTimestampSec -> peekElemOff (castPtr dataPtr) rowIdx >>= fmap FieldTimestamp . decodeDuckDBTimestampSeconds
+  DuckDBV2LogicalTypeIdTimestampMs -> peekElemOff (castPtr dataPtr) rowIdx >>= fmap FieldTimestamp . decodeDuckDBTimestampMilliseconds
+  DuckDBV2LogicalTypeIdTimestampNs -> peekElemOff (castPtr dataPtr) rowIdx >>= fmap FieldTimestamp . decodeDuckDBTimestampNanoseconds
+  DuckDBV2LogicalTypeIdTimestampTz -> peekElemOff (castPtr dataPtr) rowIdx >>= fmap FieldTimestampTZ . decodeDuckDBTimestampUTCTime
+  DuckDBV2LogicalTypeIdTimestampTzNs -> peekElemOff (castPtr dataPtr) rowIdx >>= fmap FieldTimestampTZ . decodeDuckDBTimestampNsUTCTime
+  DuckDBV2LogicalTypeIdInterval -> FieldInterval . intervalValueFromDuckDB <$> peekElemOff (castPtr dataPtr) rowIdx
+  DuckDBV2LogicalTypeIdHugeInt -> FieldHugeInt . duckDBHugeIntToInteger <$> peekElemOff (castPtr dataPtr) rowIdx
+  DuckDBV2LogicalTypeIdUHugeInt -> FieldUHugeInt . duckDBUHugeIntToInteger <$> peekElemOff (castPtr dataPtr) rowIdx
+  DuckDBV2LogicalTypeIdBit -> FieldBit . bitStringFromBytes <$> chunkDecodeBlob dataPtr index
+  DuckDBV2LogicalTypeIdBigNum -> do
+    bytes <- chunkDecodeBlob dataPtr index
+    FieldBigNum . BigNum <$> decodeBigNum bytes
+  DuckDBV2LogicalTypeIdInvalid ->
+    throwInternalError (Text.pack "INVALID type in eager result")
+  DuckDBV2LogicalTypeIdAny ->
+    throwInternalError (Text.pack "ANY columns should not appear in results")
+  other ->
+    throwInternalError (Text.pack ("UNKNOWN type in eager result: " <> show other))
   where
     index = fromIntegral rowIdx :: DuckDBIdx
 
 -- | Decode dates with exact epoch arithmetic and preserve infinity.
-decodeDuckDBDate :: DuckDBDate -> IO Date
-decodeDuckDBDate (DuckDBDate days) =
-    pure (decodeUnbounded (\value -> addDays (toInteger value) (fromGregorian 1970 1 1)) days)
+decodeDuckDBDate :: Int32 -> IO Date
+decodeDuckDBDate = pure . decodeUnbounded (\value -> addDays (toInteger value) (fromGregorian 1970 1 1))
 
-decodeDuckDBTime :: DuckDBTime -> IO TimeOfDay
-decodeDuckDBTime raw =
-    alloca $ \ptr -> do
-        c_duckdb_from_time raw ptr
-        timeStruct <- peek ptr
-        pure (timeStructToTimeOfDay timeStruct)
+decodeDuckDBTime :: Int64 -> IO TimeOfDay
+decodeDuckDBTime = pure . decodeTimeUnits 1000000
 
-decodeDuckDBTimestamp :: DuckDBTimestamp -> IO LocalTimestamp
-decodeDuckDBTimestamp (DuckDBTimestamp micros) = decodeTimestampUnits 1000000 micros
+decodeDuckDBTimestamp :: Int64 -> IO LocalTimestamp
+decodeDuckDBTimestamp = decodeTimestampUnits 1000000
 
 -- | Interpret native infinity sentinels before converting a finite payload.
 decodeUnbounded :: (Integral a, Bounded a) => (a -> b) -> a -> Unbounded b
 decodeUnbounded decode value
-    | value == maxBound = PosInfinity
-    | value == negate maxBound = NegInfinity
-    | otherwise = Finite (decode value)
+  | value == maxBound = PosInfinity
+  | value == negate maxBound = NegInfinity
+  | otherwise = Finite (decode value)
 
 -- | Decode timestamp units without overflowing an intermediate Int64.
 decodeTimestampUnits :: Integer -> Int64 -> IO LocalTimestamp
-decodeTimestampUnits units =
-    pure . decodeUnbounded (utcToLocalTime utc . posixSecondsToUTCTime . fromRational . (% units) . toInteger)
+decodeTimestampUnits units = pure . decodeUnbounded (utcToLocalTime utc . posixSecondsToUTCTime . fromRational . (% units) . toInteger)
 
-decodeDuckDBTimeNs :: DuckDBTimeNs -> TimeOfDay
-decodeDuckDBTimeNs (DuckDBTimeNs nanos) =
-    let (hours, remainderHours) = nanos `divMod` (60 * 60 * 1000000000)
-        (minutes, remainderMinutes) = remainderHours `divMod` (60 * 1000000000)
-        (seconds, fractionalNanos) = remainderMinutes `divMod` 1000000000
-        fractional = fromRational (toInteger fractionalNanos % 1000000000)
-        totalSeconds = fromIntegral seconds + fractional
-     in TimeOfDay
-            (fromIntegral hours)
-            (fromIntegral minutes)
-            totalSeconds
+-- | Decode raw time units with exact fractional seconds.
+decodeTimeUnits :: Int64 -> Int64 -> TimeOfDay
+decodeTimeUnits units value =
+  let (hours, remHours) = value `divMod` (3600 * units)
+      (minutes, remMinutes) = remHours `divMod` (60 * units)
+  in  TimeOfDay (fromIntegral hours) (fromIntegral minutes) (fromRational (toInteger remMinutes % toInteger units))
 
-decodeDuckDBTimeTz :: DuckDBTimeTz -> IO TimeWithZone
+decodeDuckDBTimeNs :: Int64 -> TimeOfDay
+decodeDuckDBTimeNs = decodeTimeUnits 1000000000
+
+-- | The largest UTC offset of a TIMETZ value in seconds: 15:59:59. DuckDB 2.0.0
+-- defines it as @dtime_tz_t::MAX_OFFSET@ in
+-- @src/include/duckdb/common/types/datetime.hpp@. The low 24 bits of a TIMETZ
+-- value hold this maximum minus the offset (@encode_offset@ and
+-- @decode_offset@ in that file). The V2 header says only "micros in the high
+-- 40 bits, a biased offset in the low 24" (the comment of
+-- @duckdb_v2_value_get_time_tz@). The header does not give the value of the
+-- bias.
+timeTzMaxOffsetSeconds :: Int
+timeTzMaxOffsetSeconds = 16 * 60 * 60 - 1
+
+-- | The number of low bits of a TIMETZ value that hold the biased offset. The
+-- high 40 bits hold the time of day in microseconds. DuckDB 2.0.0 names the two
+-- widths @dtime_tz_t::OFFSET_BITS@ and @dtime_tz_t::TIME_BITS@.
+timeTzOffsetBits :: Int
+timeTzOffsetBits = 24
+
+-- | Decode the time of day and the offset in seconds of a TIMETZ value.
+decodeDuckDBTimeTz :: Word64 -> TimeWithZone
 decodeDuckDBTimeTz raw =
-    alloca $ \ptr -> do
-        c_duckdb_from_time_tz raw ptr
-        DuckDBTimeTzStruct{duckDBTimeTzStructTime = timeStruct, duckDBTimeTzStructOffset = offset} <- peek ptr
-        when (offset `rem` 60 /= 0) $
-            throwIO (userError "duckdb-simple: TIMETZ offset cannot be represented in whole minutes")
-        let timeOfDay = timeStructToTimeOfDay timeStruct
-            minutes = fromIntegral offset `div` 60
-            zone = minutesToTimeZone minutes
-        pure TimeWithZone{timeWithZoneTime = timeOfDay, timeWithZoneZone = zone}
+  TimeWithZone
+    { timeWithZoneTime = decodeTimeUnits 1000000 (fromIntegral (raw `shiftR` timeTzOffsetBits))
+    , timeWithZoneOffsetSeconds = fromIntegral (timeTzMaxOffsetSeconds - fromIntegral (raw .&. (1 `shiftL` timeTzOffsetBits - 1)))
+    }
 
-decodeDuckDBTimestampSeconds :: DuckDBTimestampS -> IO LocalTimestamp
-decodeDuckDBTimestampSeconds (DuckDBTimestampS seconds) =
-    decodeTimestampUnits 1 seconds
+decodeDuckDBTimestampSeconds :: Int64 -> IO LocalTimestamp
+decodeDuckDBTimestampSeconds = decodeTimestampUnits 1
 
-decodeDuckDBTimestampMilliseconds :: DuckDBTimestampMs -> IO LocalTimestamp
-decodeDuckDBTimestampMilliseconds (DuckDBTimestampMs millis) =
-    decodeTimestampUnits 1000 millis
+decodeDuckDBTimestampMilliseconds :: Int64 -> IO LocalTimestamp
+decodeDuckDBTimestampMilliseconds = decodeTimestampUnits 1000
 
-decodeDuckDBTimestampNanoseconds :: DuckDBTimestampNs -> IO LocalTimestamp
-decodeDuckDBTimestampNanoseconds (DuckDBTimestampNs nanos) = decodeTimestampUnits 1000000000 nanos
+decodeDuckDBTimestampNanoseconds :: Int64 -> IO LocalTimestamp
+decodeDuckDBTimestampNanoseconds = decodeTimestampUnits 1000000000
 
-decodeDuckDBTimestampUTCTime :: DuckDBTimestamp -> IO UTCTimestamp
-decodeDuckDBTimestampUTCTime (DuckDBTimestamp micros) =
-    pure (decodeUnbounded (posixSecondsToUTCTime . fromRational . (% 1000000) . toInteger) micros)
+decodeDuckDBTimestampUTCTime :: Int64 -> IO UTCTimestamp
+decodeDuckDBTimestampUTCTime = pure . decodeUnbounded (posixSecondsToUTCTime . fromRational . (% 1000000) . toInteger)
 
-intervalValueFromDuckDB :: DuckDBInterval -> IntervalValue
-intervalValueFromDuckDB DuckDBInterval{duckDBIntervalMonths, duckDBIntervalDays, duckDBIntervalMicros} =
-    IntervalValue
-        { intervalMonths = duckDBIntervalMonths
-        , intervalDays = duckDBIntervalDays
-        , intervalMicros = duckDBIntervalMicros
-        }
+-- | Decode UTC nanoseconds and preserve infinity.
+decodeDuckDBTimestampNsUTCTime :: Int64 -> IO UTCTimestamp
+decodeDuckDBTimestampNsUTCTime = pure . decodeUnbounded (posixSecondsToUTCTime . fromRational . (% 1000000000) . toInteger)
 
-duckDBHugeIntToInteger :: DuckDBHugeInt -> Integer
-duckDBHugeIntToInteger DuckDBHugeInt{duckDBHugeIntLower, duckDBHugeIntUpper} =
-    (fromIntegral duckDBHugeIntUpper `shiftL` 64) .|. fromIntegral duckDBHugeIntLower
+intervalValueFromDuckDB :: DuckDBV2IntervalT -> IntervalValue
+intervalValueFromDuckDB (DuckDBV2IntervalT months days micros) = IntervalValue months days micros
 
-duckDBUHugeIntToInteger :: DuckDBUHugeInt -> Integer
-duckDBUHugeIntToInteger DuckDBUHugeInt{duckDBUHugeIntLower, duckDBUHugeIntUpper} =
-    (fromIntegral duckDBUHugeIntUpper `shiftL` 64) .|. fromIntegral duckDBUHugeIntLower
+duckDBHugeIntToInteger :: DuckDBV2HugeintT -> Integer
+duckDBHugeIntToInteger (DuckDBV2HugeintT lower upper) = (fromIntegral upper `shiftL` 64) .|. fromIntegral lower
 
-timeStructToTimeOfDay :: DuckDBTimeStruct -> TimeOfDay
-timeStructToTimeOfDay DuckDBTimeStruct{duckDBTimeStructHour, duckDBTimeStructMinute, duckDBTimeStructSecond, duckDBTimeStructMicros} =
-    let secondsInt = fromIntegral duckDBTimeStructSecond :: Integer
-        micros = fromIntegral duckDBTimeStructMicros :: Integer
-        fractional = fromRational (micros % 1000000)
-        totalSeconds = fromInteger secondsInt + fractional
-     in TimeOfDay
-            (fromIntegral duckDBTimeStructHour)
-            (fromIntegral duckDBTimeStructMinute)
-            totalSeconds
+duckDBUHugeIntToInteger :: DuckDBV2UhugeintT -> Integer
+duckDBUHugeIntToInteger (DuckDBV2UhugeintT lower upper) = (fromIntegral upper `shiftL` 64) .|. fromIntegral lower
+
+-- | Decode opaque BIGNUM storage through the V2 magnitude interface.
+decodeBigNum :: BS.ByteString -> IO Integer
+decodeBigNum bytes = BS.useAsCStringLen bytes \(raw, len) -> alloca \lengthSlot -> alloca \signSlot -> do
+  let decode ptr capacity = checked (c_duckdb_v2_bignum_decode (ConstPtr (castPtr raw)) (fromIntegral len) ptr capacity lengthSlot signSlot)
+      finish magnitude = do
+        count <- peek lengthSlot
+        negative <- peek signSlot
+        value <- bigEndianInteger magnitude count
+        pure $! if negative == 0 then value else negate value
+  -- A buffer of the storage size usually holds the magnitude. If the buffer is
+  -- too short, DuckDB gives the required size, and a second call decodes the value.
+  allocaBytes len \first -> do
+    outcome <- try (decode first (fromIntegral len))
+    case outcome of
+      Right () -> finish first
+      Left err
+        | sqlErrorType err == Just ErrorInputObjectSize -> do
+            count <- peek lengthSlot
+            allocaBytes (fromIntegral count) \magnitude -> decode magnitude count >> finish magnitude
+        | otherwise -> throwIO err
+
+-- | Read an unsigned big-endian magnitude in linear time.
+bigEndianInteger :: Ptr Word8 -> DuckDBIdx -> IO Integer
+bigEndianInteger (Ptr addr) count = case fromIntegral count of W# size -> integerFromAddr size addr 1#
+
+-- | The SQL type name of a decoded value. Errors name the type because a
+-- value can be large.
+valueTypeName :: FieldValue -> Text
+valueTypeName = fieldTypeName (LogicalTypeScalar LogicalTypeIdVariant)
+
+-- | Test whether a type is or contains a type that the predicate accepts. The
+-- test visits the element type of a LIST and an ARRAY, the key type and the
+-- value type of a MAP, the field types of a STRUCT and a TUPLE, the member
+-- types of a UNION, and the base type of an alias. See Note [Type aliases] in
+-- "Database.DuckDB.Simple.LogicalRep".
+containsType :: (LogicalTypeRep -> Bool) -> LogicalTypeRep -> Bool
+containsType accepts rep =
+  accepts rep || case rep of
+    LogicalTypeAlias _ base -> containsType accepts base
+    LogicalTypeList child -> containsType accepts child
+    LogicalTypeArray child _ -> containsType accepts child
+    LogicalTypeMap key value -> containsType accepts key || containsType accepts value
+    LogicalTypeStruct fields -> any (containsType accepts . structFieldValue) fields
+    LogicalTypeTuple fields -> any (containsType accepts) fields
+    LogicalTypeUnion members -> any (containsType accepts . unionMemberType) members
+    _ -> False
diff --git a/src/Database/DuckDB/Simple/Extension.hs b/src/Database/DuckDB/Simple/Extension.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/Extension.hs
@@ -0,0 +1,260 @@
+{-# LANGUAGE BlockArguments #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.Extension
+-- Description : Entry point and typed registrations for a loadable Haskell extension.
+--
+-- A loadable extension is a shared library that DuckDB loads into its own process with @LOAD@. DuckDB calls the
+-- entry point of the extension one time in each database instance. A second @LOAD@ of the same name in that
+-- instance does not call it again.
+-- The entry point registers SQL objects, and DuckDB keeps them in the database after the entry point returns. This
+-- module gives the entry point and the typed registrations of "Database.DuckDB.Simple.Function" and of the other
+-- typed modules for an extension.
+--
+-- An extension needs these items:
+--
+-- - The @extension@ flag of duckdb-ffi and of duckdb-simple. Enable the two flags together. A flag applies to the
+--   complete build plan, so one project cannot build a DuckDB host and an extension. With the flag, the two
+--   packages build only on Linux and macOS.
+-- - A C entry point @NAME_init_c_api_v2@ that calls @duckdb_haskell_extension_load@ with the foreign export of an
+--   'ExtensionEntry' and does nothing else. DuckDB finds the entry point from the file name @NAME.duckdb_extension@.
+-- - The threaded runtime. Link the extension with @-threaded@. Otherwise the load fails with an error.
+--
+-- See @dev\/extensions\/README.md@ in this repo.
+--
+-- The Haskell side of a small extension, from @dev\/extensions\/example\/src\/Demo.hs@:
+--
+-- > {-# LANGUAGE ForeignFunctionInterface #-}
+-- > {-# LANGUAGE OverloadedStrings #-}
+-- >
+-- > module Demo where
+-- >
+-- > import Data.Int (Int64)
+-- > import Data.Text (Text)
+-- > import Database.DuckDB.Simple.Extension (Extension, ExtensionEntry)
+-- > import qualified Database.DuckDB.Simple.Extension as Extension
+-- >
+-- > initialize :: ExtensionEntry
+-- > initialize = Extension.runExtension register
+-- >
+-- > foreign export ccall "duckdb_haskell_demo_register" initialize :: ExtensionEntry
+-- >
+-- > register :: Extension -> IO ()
+-- > register extension = do
+-- >   Extension.createFunction extension "haskell_answer" (42 :: Int64)
+-- >   Extension.createFunction extension "haskell_greet" (("Hello " <>) :: Text -> Text)
+-- >   Extension.registerMacroFunction extension "haskell_table" Extension.MacroFunctionTypeTable [] "SELECT 42::BIGINT AS answer"
+--
+-- The C entry point of the same extension, from @dev\/extensions\/example\/cbits\/entry.c@. The packaged file must
+-- be @haskell_demo.duckdb_extension@:
+--
+-- > #include "duckdb_haskell_extension.h"
+-- >
+-- > extern void duckdb_haskell_demo_register(void *extension, void *context, void *err);
+-- >
+-- > /* DuckDB derives this name from the file name of the packaged extension. */
+-- > DUCKDB_EXTENSION_API void haskell_demo_init_c_api_v2(struct duckdb_v2_extension_input *input) {
+-- >     duckdb_haskell_extension_load(input, duckdb_haskell_demo_register);
+-- > }
+--
+-- The t'Extension' value is valid only while 'runExtension' runs. DuckDB gives a borrowed extension handle and a
+-- borrowed context to the entry point. They are not valid after the entry point returns. Thus do not keep the
+-- t'Extension' value, or the target of 'extensionTarget', in a registered callback or in other state. A registered
+-- function keeps its callback resources after the entry point returns.
+--
+-- The README of the example gives these limits:
+--
+-- - The runtime has one capability (@-N1@). The callbacks of all DuckDB worker threads share it. You cannot change
+--   the runtime options.
+-- - Haskell extensions built with the same GHC share one runtime in the process, and the options of the first
+--   loaded extension apply. Extensions built with different GHC versions in one process are not tested. The runtime
+--   stays until the process ends. Do not call @hs_exit@.
+-- - The process supports one DuckDB implementation.
+-- - The extension loads only into the DuckDB release of the pinned header, 2.0.0.
+-- - In extension mode, duckdb-ffi exposes only "Database.DuckDB.FFI.V2".
+-- - A replacement scan of an extension belongs to the instance, not to one connection.
+-- - The example links the GHC and package libraries dynamically. It loads only on a machine where its run paths
+--   exist.
+--
+-- The complete example is in the directory @dev\/extensions\/example\/@ of the repository.
+-- Its file @src\/Advanced.hs@ registers the other kinds of SQL objects.
+module Database.DuckDB.Simple.Extension (
+  Extension,
+  ExtensionEntry,
+  runExtension,
+  extensionTarget,
+  createFunction,
+  createFunctionWithState,
+  registerReplacementScan,
+  registerCustomType,
+  registerMultiFileFunction,
+  createTableFunction,
+  createAggregate,
+  MacroFunctionType (..),
+  registerMacroFunction,
+  registerPragmaFunction,
+  registerCustomOption,
+  registerLogSink,
+  registerCopyToFunction,
+  registerCopyFromFunction,
+  registerCopyFunction,
+) where
+
+import Data.Text (Text)
+import Database.DuckDB.Simple.Callback (runCallback)
+import Database.DuckDB.Simple.Config.Internal (CustomOption)
+import qualified Database.DuckDB.Simple.Config.Internal as Config
+import Database.DuckDB.Simple.Copy.Internal (
+  CopyBindInfo,
+  CopyFinalizeInfo,
+  CopyFromInfo,
+  CopyInitInfo,
+  CopySinkInfo,
+  CopyTo,
+  MultiFileOptions,
+  registerMultiFileFunctionOn,
+ )
+import qualified Database.DuckDB.Simple.Copy.Internal as Copy
+import Database.DuckDB.Simple.FromField (Field)
+import Database.DuckDB.Simple.FromRow (FromRow)
+import Database.DuckDB.Simple.Function.Internal (Function, FunctionResult, createFunctionOn, createFunctionWithStateOn)
+import Database.DuckDB.Simple.Logging.Internal (LogEntry)
+import qualified Database.DuckDB.Simple.Logging.Internal as Logging
+import Database.DuckDB.Simple.Native
+import Database.DuckDB.Simple.Pragma.Internal (PragmaCallback)
+import qualified Database.DuckDB.Simple.Pragma.Internal as Pragma
+import Database.DuckDB.Simple.Typed (Replacement, TypedRow, replacementScanCallback)
+import Database.DuckDB.Simple.Typed.Aggregate (Aggregate, createAggregateOn)
+import Database.DuckDB.Simple.Typed.Table (createTableFunctionOn)
+import Database.DuckDB.Simple.V2.Registration (
+  FunctionParameter,
+  FunctionSignature (..),
+  RegistrationTarget (ExtensionTarget),
+  TypeDeclaration,
+  configureFunctionSignature,
+  registerCustomTypeOn,
+  registerMacroFunctionWith,
+  registerReplacementScanOn,
+ )
+import Foreign.Ptr (Ptr, castPtr)
+
+-- | The borrowed registration target and context for one extension load.
+-- Use this value only inside the action passed to 'runExtension'. Do not retain it
+-- in registered callbacks or application state.
+data Extension = Extension DuckDBV2ExtensionHandle DuckDBV2ContextHandle
+
+-- | The Haskell entry that @duckdb_haskell_extension_load@ calls. Its arguments
+-- are the extension handle, the borrowed context, and the error slot of the load.
+-- The plain pointers let a @foreign export@ use this type with no other import.
+type ExtensionEntry = Ptr () -> Ptr () -> Ptr () -> IO ()
+
+-- | Run registration and report exceptions through the borrowed load error slot.
+-- The extension is valid only during this call. Registered functions own their
+-- callback resources after this call returns.
+runExtension :: (Extension -> IO ()) -> ExtensionEntry
+runExtension initialize extension context err =
+  runCallback (castPtr err) (initialize (Extension (DuckDBV2ExtensionHandle (castPtr extension)) (DuckDBV2ContextHandle (castPtr context))))
+
+-- | The registration target of the loading extension. Pass it to the
+-- registration functions of the V2 modules, which take a 'RegistrationTarget'.
+-- The typed functions of this module do not need it. The target is valid only
+-- during 'runExtension'.
+extensionTarget :: Extension -> RegistrationTarget
+extensionTarget (Extension extension context) = ExtensionTarget extension context
+
+-- | Register a typed Haskell function with the loading DuckDB host. The rules
+-- of 'Database.DuckDB.Simple.Function.createFunction' apply.
+createFunction :: (Function f) => Extension -> Text -> f -> IO ()
+createFunction = createFunctionOn . extensionTarget
+
+-- | Register a typed function with per-worker state owned by DuckDB. The rules
+-- of 'Database.DuckDB.Simple.Function.createFunctionWithState' apply.
+createFunctionWithState :: (Function f) => Extension -> Text -> IO s -> (s -> f) -> IO ()
+createFunctionWithState = createFunctionWithStateOn . extensionTarget
+
+-- | Register a replacement scan with the loading DuckDB host. The scan belongs
+-- to the instance. Each connection of the instance uses it until the instance
+-- closes. No function removes a scan. DuckDB asks the scans of a connection
+-- before the scans of the instance. It asks the scans of the instance in the
+-- order of registration. The function can run on several connections at the same
+-- time. 'Database.DuckDB.Simple.Registration.registerReplacementScan' gives the
+-- rules for the function.
+registerReplacementScan :: Extension -> ([Text] -> IO (Maybe Replacement)) -> IO ()
+registerReplacementScan extension = registerReplacementScanOn (extensionTarget extension) . replacementScanCallback
+
+-- | Register a custom type with the loading DuckDB host. The rules of
+-- 'Database.DuckDB.Simple.Registration.registerCustomType' apply.
+registerCustomType :: Extension -> Text -> TypeDeclaration -> IO ()
+registerCustomType = registerCustomTypeOn . extensionTarget
+
+-- | Register a multi-file table function with the loading DuckDB host. The
+-- rules of 'Database.DuckDB.Simple.Copy.registerMultiFileFunction' apply.
+registerMultiFileFunction :: Extension -> Text -> Text -> MultiFileOptions -> IO ()
+registerMultiFileFunction = registerMultiFileFunctionOn . extensionTarget
+
+-- | Register a typed table function with the loading DuckDB host. The rules of
+-- 'Database.DuckDB.Simple.Function.createTableFunction' apply.
+createTableFunction :: (FromRow params, TypedRow params, TypedRow row) => Extension -> Text -> [Text] -> (params -> IO [row]) -> IO ()
+createTableFunction = createTableFunctionOn . extensionTarget
+
+-- | Register an aggregate function with the loading DuckDB host. The rules of
+-- 'Database.DuckDB.Simple.Function.createAggregate' apply. SQL type declarations
+-- resolve on the loading host. Result encoders use an instance factory
+-- for built-in types, with no catalog lookup on the host.
+createAggregate :: (FromRow args, TypedRow args, FunctionResult result) => Extension -> Text -> Aggregate state args result -> IO ()
+createAggregate = createAggregateOn . extensionTarget
+
+-- | Register a scalar expression or a table SELECT as a macro of the loading
+-- extension. The V2 API registers a macro only for an extension. Use SQL
+-- @CREATE MACRO@ on a connection. Parameters must use the standard parameter
+-- kind. Use @StructuredType (LogicalTypeScalar LogicalTypeIdAny)@ for an
+-- untyped parameter and 'Database.DuckDB.Simple.Registration.defaultValue' for a
+-- default. DuckDB validates the body and the signature. It resolves the body
+-- when the macro runs.
+registerMacroFunction :: Extension -> Text -> MacroFunctionType -> [FunctionParameter] -> Text -> IO ()
+registerMacroFunction extension@(Extension _ context) name kind parameters body =
+  withContextFactory context \factory ->
+    registerMacroFunctionWith (extensionTarget extension) kind \function -> do
+      withIdentifier name (checked . c_duckdb_v2_macro_function_set_name function)
+      withText body (checked . c_duckdb_v2_macro_function_set_body function)
+      signature <- output (c_duckdb_v2_macro_function_get_signature function)
+      configureFunctionSignature factory (FunctionSignature parameters Nothing) signature
+
+-- | Register a typed PRAGMA callback on the loading extension. The rules of
+-- 'Database.DuckDB.Simple.Pragma.registerPragmaFunction' apply.
+registerPragmaFunction :: (FromRow args) => Extension -> Text -> [FunctionParameter] -> PragmaCallback args -> IO ()
+registerPragmaFunction = Pragma.registerPragmaFunctionOn . extensionTarget
+
+-- | Register a typed option during extension initialization. The rules of
+-- 'Database.DuckDB.Simple.Config.registerCustomOption' apply.
+registerCustomOption :: Extension -> CustomOption -> IO ()
+registerCustomOption = Config.registerCustomOptionOn . extensionTarget
+
+-- | Register a log sink with callback resources owned by DuckDB.
+-- Callbacks can run concurrently. They must not log or change logging settings.
+-- The rules of 'Database.DuckDB.Simple.Logging.registerLogSink' apply.
+registerLogSink :: Extension -> Text -> (LogEntry -> IO ()) -> IO () -> IO ()
+registerLogSink = Logging.registerLogSinkOn . extensionTarget
+
+-- | Register row-oriented COPY TO callbacks with the loading DuckDB host. The
+-- rules of 'Database.DuckDB.Simple.Copy.registerCopyToFunction' apply.
+registerCopyToFunction
+  :: Extension
+  -> Text
+  -> (CopyBindInfo -> IO bindState)
+  -> (CopyInitInfo bindState -> IO globalState)
+  -> (CopySinkInfo bindState globalState -> [[Field]] -> IO ())
+  -> (CopyFinalizeInfo bindState globalState -> IO ())
+  -> IO ()
+registerCopyToFunction = Copy.registerCopyToFunctionOn . extensionTarget
+
+-- | Register the COPY FROM side of a format with the loading DuckDB host. The
+-- rules of 'Database.DuckDB.Simple.Copy.registerCopyFromFunction' apply.
+registerCopyFromFunction :: (TypedRow row) => Extension -> Text -> (CopyFromInfo -> IO [row]) -> IO ()
+registerCopyFromFunction = Copy.registerCopyFromFunctionOn . extensionTarget
+
+-- | Register a format with a COPY TO side and a COPY FROM side with the
+-- loading DuckDB host. The rules of
+-- 'Database.DuckDB.Simple.Copy.registerCopyFunction' apply.
+registerCopyFunction :: (TypedRow row) => Extension -> Text -> CopyTo bindState globalState -> (CopyFromInfo -> IO [row]) -> IO ()
+registerCopyFunction = Copy.registerCopyFunctionOn . extensionTarget
diff --git a/src/Database/DuckDB/Simple/FileSystem.hs b/src/Database/DuckDB/Simple/FileSystem.hs
--- a/src/Database/DuckDB/Simple/FileSystem.hs
+++ b/src/Database/DuckDB/Simple/FileSystem.hs
@@ -1,175 +1,190 @@
 {-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE OverloadedStrings #-}
 
-{- |
-Module      : Database.DuckDB.Simple.FileSystem
-Description : High-level wrappers around DuckDB's file-system API.
--}
+-- |
+-- Module      : Database.DuckDB.Simple.FileSystem
+-- Description : Checked file operations through the V2 file system.
 module Database.DuckDB.Simple.FileSystem (
-    withFileHandle,
-    readFileHandleChunk,
-    writeFileHandleBytes,
-    fileHandleTell,
-    fileHandleSize,
-    fileHandleSeek,
-    fileHandleSync,
+  FileFlag (..),
+  FileHandle,
+  withFileHandle,
+  readFileHandleChunk,
+  writeFileHandleBytes,
+  readFileHandleAt,
+  writeFileHandleAt,
+  fileHandleTell,
+  fileHandleSize,
+  fileHandleSeek,
+  fileHandleSync,
+  pathExists,
+  pathIsRemote,
+  expandPath,
+  globPaths,
+  movePath,
+  removePath,
 ) where
 
-import Control.Exception (bracket, mask_, throwIO)
+import Control.Exception (bracket)
+import Control.Monad (when)
 import qualified Data.ByteString as BS
+import qualified Data.ByteString.Internal as BSI
+import Data.IORef (modifyIORef', newIORef, readIORef)
 import Data.Int (Int64)
-import Data.Text (Text)
 import qualified Data.Text as Text
-import qualified Data.Text.Foreign as TextForeign
-import Database.DuckDB.FFI
-import Database.DuckDB.Simple.Internal (Connection, SQLError (..), peekUtf8CString, withClientContext)
-import Foreign.Marshal.Alloc (alloca, free, mallocBytes)
-import Foreign.Ptr (Ptr, castPtr, nullPtr)
-import Foreign.Storable (peek, poke)
+import Database.DuckDB.Simple.Callback (runCallback)
+import Database.DuckDB.Simple.Internal (Connection, withConnectionHandle)
+import Database.DuckDB.Simple.Native
+import Foreign.C.ConstPtr (ConstPtr (..), unConstPtr)
+import Foreign.Ptr (castPtr, freeHaskellFunPtr, nullPtr)
+import Foreign.Storable (peek)
+import HsBindgen.Runtime.Support.FunPtr (toFunPtr)
 
--- | Open a file through DuckDB's file-system layer for the duration of an action.
-withFileHandle :: Connection -> FilePath -> [DuckDBFileFlag] -> (DuckDBFileHandle -> IO a) -> IO a
+-- | An open file. 'withFileHandle' gives it to one action. Do not use it after that action returns.
+newtype FileHandle = FileHandle DuckDBV2FileHandle
+
+-- | Open a file for one action. Release its handle on every exit path.
+withFileHandle :: Connection -> FilePath -> [FileFlag] -> (FileHandle -> IO a) -> IO a
 withFileHandle conn path flags action
-    | '\0' `elem` path = throwIO (SQLError (Text.pack "duckdb-simple: file path contains NUL") Nothing Nothing)
-    | otherwise =
-        withFileSystem conn \fs ->
-            bracket
-                c_duckdb_create_file_open_options
-                destroyFileOpenOptions
-                \opts -> do
-                    whenNull opts "allocate file-open options"
-                    mapM_ (\flag -> expectState "set file-open flag" (c_duckdb_file_open_options_set_flag opts flag 1)) flags
-                    TextForeign.withCString (Text.pack path) \cPath ->
-                        bracket
-                            ( alloca \filePtr -> do
-                                poke filePtr nullPtr
-                                rc <- c_duckdb_file_system_open fs cPath opts filePtr
-                                if rc /= DuckDBSuccess
-                                    then throwFileSystemError fs path
-                                    else do
-                                        handle <- peek filePtr
-                                        whenNull handle "allocate file handle"
-                                        pure handle
-                            )
-                            destroyFileHandle
-                            action
+  | '\0' `elem` path = throwInvalidArgument "file path contains NUL"
+  | otherwise = withConnectionHandle conn \handle -> do
+      fs <- output (c_duckdb_v2_connection_get_file_system handle)
+      bracket (output (c_duckdb_v2_file_open_options_create fs)) (destroy c_duckdb_v2_file_open_options_destroy) \options -> do
+        mapM_ (checked . c_duckdb_v2_file_open_options_set_flag options . fileFlagToNative) flags
+        withText (Text.pack path) \name ->
+          bracket (output (c_duckdb_v2_file_system_open fs name options)) (destroy c_duckdb_v2_file_destroy) (action . FileHandle)
 
--- | Read up to the requested number of bytes from a file handle.
-readFileHandleChunk :: DuckDBFileHandle -> Int64 -> IO BS.ByteString
-readFileHandleChunk handle requested
-    | requested <= 0 = pure BS.empty
-    | toInteger requested > toInteger (maxBound :: Int) =
-        throwIO (SQLError (Text.pack "duckdb-simple: file read size exceeds Int range") Nothing Nothing)
-    | otherwise =
-        bracket (mallocBytes (fromIntegral requested)) free \raw -> do
-            bytesRead <- c_duckdb_file_handle_read handle raw requested
-            if bytesRead < 0
-                then throwFileHandleError handle (Text.pack "read failed")
-                else
-                    if bytesRead > requested
-                        then throwFileHandleError handle (Text.pack "read size exceeds buffer size")
-                        else BS.packCStringLen (castPtr raw, fromIntegral bytesRead)
+-- | Read up to the requested byte count and advance the file position. The
+-- buffer and the size that the native call gets come from one value. A count
+-- above that size raises an error. The library cannot check that the native
+-- call writes no more than that size: the header of DuckDB states it as the
+-- contract of the call.
+readFileHandleChunk :: FileHandle -> Int64 -> IO BS.ByteString
+readFileHandleChunk (FileHandle handle) requested
+  | requested <= 0 = pure BS.empty
+  | toInteger requested > toInteger (maxBound :: Int) = throwInvalidArgument "file read size exceeds Int range"
+  | otherwise = BSI.createAndTrim size \buffer -> do
+      count <- output (c_duckdb_v2_file_read handle (castPtr buffer) (fromIntegral size))
+      when (toInteger count > toInteger size) $ throwInternalError "native file read exceeds buffer size"
+      pure (fromIntegral count)
+  where
+    size = fromIntegral requested :: Int
 
--- | Write an entire bytestring to a file handle.
-writeFileHandleBytes :: DuckDBFileHandle -> BS.ByteString -> IO Int64
-writeFileHandleBytes handle bytes =
-    BS.useAsCStringLen bytes \(ptr, len) -> do
-        written <- c_duckdb_file_handle_write handle (castPtr ptr) (fromIntegral len)
-        if written < 0
-            then throwFileHandleError handle (Text.pack "write failed")
-            else pure written
+-- | Write bytes and return the byte count. Advance the file position.
+writeFileHandleBytes :: FileHandle -> BS.ByteString -> IO Int64
+writeFileHandleBytes (FileHandle handle) bytes = BS.useAsCStringLen bytes \(ptr, count) ->
+  fromIntegral <$> output (c_duckdb_v2_file_write handle (ConstPtr (castPtr ptr)) (fromIntegral count))
 
--- | Return the current file position.
-fileHandleTell :: DuckDBFileHandle -> IO Int64
-fileHandleTell handle = do
-    pos <- c_duckdb_file_handle_tell handle
-    if pos < 0 then throwFileHandleError handle (Text.pack "tell failed") else pure pos
+-- | Read exactly the requested bytes without changing the file position. A
+-- range whose end exceeds the 'Int64' range raises an error before the native
+-- call. DuckDB checks the range against the size of the file, and a read past
+-- the end raises the error of DuckDB. The function allocates the buffer before
+-- that check. The buffer and the size that the native call gets come from one
+-- value. The library cannot check that the native call writes no more than
+-- that size: the header of DuckDB states it as the contract of the call.
+readFileHandleAt :: FileHandle -> Int64 -> Int64 -> IO BS.ByteString
+readFileHandleAt (FileHandle handle) offset requested
+  | offset < 0 = throwInvalidArgument "file offset is negative"
+  | requested < 0 = throwInvalidArgument "file read size is negative"
+  | toInteger requested > toInteger (maxBound :: Int) = throwInvalidArgument "file read size exceeds Int range"
+  | toInteger offset + toInteger requested > toInteger (maxBound :: Int64) = throwInvalidArgument "file read range exceeds Int64 range"
+  | otherwise = BSI.create size \buffer -> checked (c_duckdb_v2_file_read_at handle (castPtr buffer) (fromIntegral size) (fromIntegral offset))
+  where
+    size = fromIntegral requested :: Int
 
--- | Return the current file size in bytes.
-fileHandleSize :: DuckDBFileHandle -> IO Int64
-fileHandleSize handle = do
-    size <- c_duckdb_file_handle_size handle
-    if size < 0 then throwFileHandleError handle (Text.pack "size failed") else pure size
+-- | Write all bytes at an offset without changing the file position. A range
+-- whose end exceeds the 'Int64' range raises an error.
+writeFileHandleAt :: FileHandle -> Int64 -> BS.ByteString -> IO ()
+writeFileHandleAt (FileHandle handle) offset bytes
+  | offset < 0 = throwInvalidArgument "file offset is negative"
+  | toInteger offset + toInteger (BS.length bytes) > toInteger (maxBound :: Int64) =
+      throwInvalidArgument "file write range exceeds Int64 range"
+  | otherwise = BS.useAsCStringLen bytes \(ptr, count) ->
+      checked (c_duckdb_v2_file_write_at handle (ConstPtr (castPtr ptr)) (fromIntegral count) (fromIntegral offset))
 
--- | Seek to an absolute byte offset.
-fileHandleSeek :: DuckDBFileHandle -> Int64 -> IO ()
-fileHandleSeek handle pos = do
-    rc <- c_duckdb_file_handle_seek handle pos
-    if rc == DuckDBSuccess
-        then pure ()
-        else throwFileHandleError handle (Text.pack "seek failed")
+-- | Return the current byte position.
+fileHandleTell :: FileHandle -> IO Int64
+fileHandleTell (FileHandle handle) = output (c_duckdb_v2_file_tell handle) >>= checkedPosition
 
--- | Flush file-handle writes to stable storage.
-fileHandleSync :: DuckDBFileHandle -> IO ()
-fileHandleSync handle = do
-    rc <- c_duckdb_file_handle_sync handle
-    if rc == DuckDBSuccess
-        then pure ()
-        else throwFileHandleError handle (Text.pack "sync failed")
+-- | Return the file size in bytes.
+fileHandleSize :: FileHandle -> IO Int64
+fileHandleSize (FileHandle handle) = output (c_duckdb_v2_file_size handle) >>= checkedPosition
 
-withFileSystem :: Connection -> (DuckDBFileSystem -> IO a) -> IO a
-withFileSystem conn action =
-    withClientContext conn \ctx ->
-        bracket
-            (c_duckdb_client_context_get_file_system ctx)
-            destroyFileSystem
-            (\fs -> whenNull fs "allocate file system" >> action fs)
+-- | Set the absolute byte position.
+fileHandleSeek :: FileHandle -> Int64 -> IO ()
+fileHandleSeek (FileHandle handle) position
+  | position < 0 = throwInvalidArgument "file offset is negative"
+  | otherwise = checked (c_duckdb_v2_file_seek handle (fromIntegral position))
 
-destroyFileSystem :: DuckDBFileSystem -> IO ()
-destroyFileSystem fs =
-    alloca \ptr -> poke ptr fs >> c_duckdb_destroy_file_system ptr
+-- | Flush pending file writes to storage.
+fileHandleSync :: FileHandle -> IO ()
+fileHandleSync (FileHandle handle) = checked (c_duckdb_v2_file_sync handle)
 
-destroyFileOpenOptions :: DuckDBFileOpenOptions -> IO ()
-destroyFileOpenOptions opts =
-    alloca \ptr -> poke ptr opts >> c_duckdb_destroy_file_open_options ptr
+-- | Test whether a file exists in DuckDB's file system. A directory gives 'False'.
+pathExists :: Connection -> FilePath -> IO Bool
+pathExists conn path = withPath conn path \fs name ->
+  (/= 0) <$> output (c_duckdb_v2_file_system_path_exists fs name)
 
-destroyFileHandle :: DuckDBFileHandle -> IO ()
-destroyFileHandle handle =
-    alloca \ptr -> poke ptr handle >> c_duckdb_destroy_file_handle ptr
+-- | Test whether DuckDB routes a path to a remote file system.
+pathIsRemote :: Connection -> FilePath -> IO Bool
+pathIsRemote conn path = withPath conn path \fs name ->
+  (/= 0) <$> output (c_duckdb_v2_file_system_path_is_remote fs name)
 
-throwFileSystemError :: DuckDBFileSystem -> FilePath -> IO a
-throwFileSystemError fs path = mask_ do
-    err <- c_duckdb_file_system_error_data fs
-    throwErrorData err (Text.concat [Text.pack "duckdb-simple: failed to open file ", Text.pack path])
+-- | Expand a path with DuckDB's file-system rules.
+expandPath :: Connection -> FilePath -> IO FilePath
+expandPath conn path = withPath conn path \fs name -> do
+  pieces <- newIORef []
+  bracket
+    ( toFunPtr
+        ( DuckDBV2TextSinkFn_Aux
+            ( \text _ err -> runCallback err do
+                value <- peek (unConstPtr text) >>= readText
+                modifyIORef' pieces (value :)
+            )
+        )
+    )
+    freeHaskellFunPtr
+    \callback -> checked (c_duckdb_v2_file_system_path_expand fs name (DuckDBV2TextSinkFn callback) nullPtr)
+  Text.unpack . Text.concat . reverse <$> readIORef pieces
 
-throwFileHandleError :: DuckDBFileHandle -> Text -> IO a
-throwFileHandleError handle fallback = mask_ do
-    err <- c_duckdb_file_handle_error_data handle
-    throwErrorData err fallback
+-- | Collect glob matches in the order supplied by DuckDB.
+globPaths :: Connection -> FilePath -> IO [FilePath]
+globPaths conn pattern_ = withPath conn pattern_ \fs name -> do
+  paths <- newIORef []
+  bracket
+    ( toFunPtr
+        ( DuckDBV2FileSystemPathGlobCallbackFn_Aux
+            ( \path _ err -> runCallback err do
+                value <- peek (unConstPtr path) >>= readText
+                modifyIORef' paths (Text.unpack value :)
+            )
+        )
+    )
+    freeHaskellFunPtr
+    \callback -> checked (c_duckdb_v2_file_system_path_glob fs name (DuckDBV2FileSystemPathGlobCallbackFn callback) nullPtr)
+  reverse <$> readIORef paths
 
-throwErrorData :: DuckDBErrorData -> Text -> IO a
-throwErrorData err fallback =
-    bracket (pure err) destroyErrorData \errData -> do
-        msgPtr <- c_duckdb_error_data_message errData
-        errType <- c_duckdb_error_data_error_type errData
-        message <-
-            if msgPtr == nullPtr
-                then pure fallback
-                else peekUtf8CString msgPtr
-        throwIO
-            SQLError
-                { sqlErrorMessage = message
-                , sqlErrorType = Just errType
-                , sqlErrorQuery = Nothing
-                }
+-- | Move a path through DuckDB's file system.
+movePath :: Connection -> FilePath -> FilePath -> IO ()
+movePath conn source target
+  | '\0' `elem` target = throwInvalidArgument "file path contains NUL"
+  | otherwise = withPath conn source \fs name -> withText (Text.pack target) \destination ->
+      checked (c_duckdb_v2_file_system_path_move fs name destination)
 
-destroyErrorData :: DuckDBErrorData -> IO ()
-destroyErrorData err =
-    alloca \ptr -> poke ptr err >> c_duckdb_destroy_error_data ptr
+-- | Remove a file. Return whether DuckDB removed it.
+removePath :: Connection -> FilePath -> IO Bool
+removePath conn path = withPath conn path \fs name ->
+  (/= 0) <$> output (c_duckdb_v2_file_system_path_remove fs name)
 
-expectState :: String -> IO DuckDBState -> IO ()
-expectState label action = do
-    rc <- action
-    if rc == DuckDBSuccess
-        then pure ()
-        else
-            throwIO $
-                SQLError
-                    { sqlErrorMessage = Text.pack ("duckdb-simple: " <> label <> " failed")
-                    , sqlErrorType = Nothing
-                    , sqlErrorQuery = Nothing
-                    }
+-- | Borrow the connection's file system and a checked path.
+withPath :: Connection -> FilePath -> (DuckDBV2FileSystemHandle -> ConstPtr DuckDBV2Str -> IO a) -> IO a
+withPath conn path action
+  | '\0' `elem` path = throwInvalidArgument "file path contains NUL"
+  | otherwise = withConnectionHandle conn \handle -> do
+      fs <- output (c_duckdb_v2_connection_get_file_system handle)
+      withText (Text.pack path) (action fs)
 
--- | Reject a null file-system handle before use.
-whenNull :: Ptr a -> String -> IO ()
-whenNull ptr label =
-    if ptr == nullPtr then expectState label (pure DuckDBError) else pure ()
+-- | Check the public signed range before converting a native byte position.
+checkedPosition :: DuckDBIdx -> IO Int64
+checkedPosition value
+  | toInteger value > toInteger (maxBound :: Int64) = throwInternalError "file position exceeds Int64 range"
+  | otherwise = pure (fromIntegral value)
diff --git a/src/Database/DuckDB/Simple/FromField.hs b/src/Database/DuckDB/Simple/FromField.hs
--- a/src/Database/DuckDB/Simple/FromField.hs
+++ b/src/Database/DuckDB/Simple/FromField.hs
@@ -1,813 +1,1249 @@
-{-# LANGUAGE DerivingVia #-}
-{-# LANGUAGE FlexibleInstances #-}
-{-# LANGUAGE LambdaCase #-}
-{-# LANGUAGE NamedFieldPuns #-}
-{-# LANGUAGE OverloadedStrings #-}
-{-# LANGUAGE PatternSynonyms #-}
-{-# LANGUAGE ScopedTypeVariables #-}
-{-# LANGUAGE StrictData #-}
-{-# LANGUAGE ViewPatterns #-}
-
-{- |
-Module      : Database.DuckDB.Simple.FromField
-Description : Conversion from DuckDB column values to Haskell types.
--}
-module Database.DuckDB.Simple.FromField (
-    Field (..),
-    FieldValue (..),
-    RawGeometry (..),
-    StructField (..),
-    StructValue (..),
-    UnionMemberType (..),
-    UnionValue (..),
-    LogicalTypeRep (..),
-    BitString (..),
-    bsFromBool,
-    BigNum (..),
-    fromBigNumBytes,
-    toBigNumBytes,
-    DecimalValue (..),
-    IntervalValue (..),
-    TimeWithZone (..),
-    ResultError (..),
-    FieldParser,
-    FromField (..),
-    returnError,
-) where
-
-import Control.Exception (Exception, SomeException (..))
-import Data.Array (Array, assocs, bounds, listArray, range, (!))
-import Data.Bits (Bits (..), finiteBitSize)
-import qualified Data.ByteString as BS
-import Data.Data (Typeable, typeRep)
-import qualified Data.Geometry as G
-import Data.Int (Int16, Int32, Int64, Int8)
-import Data.Map.Strict (Map)
-import qualified Data.Map.Strict as Map
-import Data.Proxy (Proxy (..))
-import Data.Text (Text)
-import qualified Data.Text as Text
-import qualified Data.Text.Encoding as TextEncoding
-import Data.Time.Calendar (Day)
-import Data.Time.Clock (UTCTime (..))
-import Data.Time.LocalTime (
-    LocalTime (..),
-    TimeOfDay (..),
-    TimeZone (..),
-    localTimeToUTC,
-    utc,
-    utcToLocalTime,
- )
-import qualified Data.UUID as UUID
-import Data.Word (Word16, Word32, Word64, Word8)
-import Database.DuckDB.Simple.Geometry (RawGeometry (..), fromRawGeometry)
-import Database.DuckDB.Simple.LogicalRep (
-    LogicalTypeRep (..),
-    StructField (..),
-    StructValue (..),
-    UnionMemberType (..),
-    UnionValue (..),
- )
-import Database.DuckDB.Simple.Ok
-import Database.DuckDB.Simple.Time (Date, LocalTimestamp, UTCTimestamp, Unbounded (..))
-import GHC.Float (double2Float, float2Double)
-import GHC.Num.Integer (integerFromWordList)
-import Numeric.Natural (Natural)
-
-{- | Internal representation of a column value.
-'FieldGeometry' contains raw WKB and CRS metadata. Generic parameters that
-contain a non-NULL geometry require explicit SQL import.
--}
-data FieldValue
-    = FieldNull
-    | FieldInt8 Int8
-    | FieldInt16 Int16
-    | FieldInt32 Int32
-    | FieldInt64 Int64
-    | FieldWord8 Word8
-    | FieldWord16 Word16
-    | FieldWord32 Word32
-    | FieldWord64 Word64
-    | FieldUUID UUID.UUID
-    | FieldFloat Float
-    | FieldDouble Double
-    | FieldText Text
-    | FieldBool Bool
-    | FieldBlob BS.ByteString
-    | FieldGeometry RawGeometry
-    | FieldDate Date
-    | FieldTime TimeOfDay
-    | FieldTimestamp LocalTimestamp
-    | FieldInterval IntervalValue
-    | FieldHugeInt Integer
-    | FieldUHugeInt Integer
-    | FieldDecimal DecimalValue
-    | FieldTimestampTZ UTCTimestamp
-    | FieldTimeTZ TimeWithZone
-    | FieldBit BitString
-    | FieldBigNum BigNum
-    | FieldEnum Word32
-    | FieldArray (Array Int FieldValue)
-    | FieldList [FieldValue]
-    | FieldMap [(FieldValue, FieldValue)]
-    | FieldStruct (StructValue FieldValue)
-    | FieldUnion (UnionValue FieldValue)
-    deriving (Eq, Show)
-
--- | Exact-width decimal payload plus its declared width and scale.
-data DecimalValue = DecimalValue
-    { decimalWidth :: !Word8
-    , decimalScale :: !Word8
-    , decimalInteger :: !Integer
-    }
-    deriving (Eq, Show)
-
--- | DuckDB interval payload split into months, days, and microseconds.
-data IntervalValue = IntervalValue
-    { intervalMonths :: !Int32
-    , intervalDays :: !Int32
-    , intervalMicros :: !Int64
-    }
-    deriving (Eq, Show)
-
--- | Arbitrary-precision integer wrapper used for DuckDB's BIGNUM type.
-newtype BigNum = BigNum Integer
-    deriving stock (Eq, Show)
-    deriving (Num) via Integer
-
-{- | Decode DuckDB’s BIGNUM blob (3-byte header + big-endian payload where negative magnitudes are
-bitwise complemented) back into a Haskell @Integer@. We undo the complement when needed, then chunk
-the remaining bytes into machine-word limbs (MSB chunk first) for @integerFromWordList@.
--}
-fromBigNumBytes :: [Word8] -> Integer
-fromBigNumBytes bytes =
-    let header = take 3 bytes
-        payloadRaw = drop 3 bytes
-        isNeg = case header of
-            (h : _) -> h .&. 0x80 == 0
-            [] -> False
-        payload = if isNeg then map complement payloadRaw else payloadRaw
-        bytesPerWord = finiteBitSize (0 :: Word) `div` 8 -- 8 on 64-bit, 4 on 32-bit
-        len = length payload
-        (firstChunk, rest) = splitAt (len `mod` bytesPerWord) payload
-
-        chunkWords [] = []
-        chunkWords xs =
-            let (chunk, remainder) = splitAt bytesPerWord xs
-             in chunk : chunkWords remainder
-
-        toWord = foldl (\acc b -> (acc `shiftL` 8) .|. fromIntegral b) 0
-        limbs = (if null firstChunk then id else (firstChunk :)) (chunkWords rest)
-     in integerFromWordList isNeg (map toWord limbs)
-
-{- | Encode an @Integer@ into DuckDB’s BIGNUM blob layout: emit the 3-byte header
-  (sign bit plus payload length) followed by the magnitude bytes in the same
-  big-endian / complemented-on-negative form that DuckDB stores internally.
--}
-toBigNumBytes :: Integer -> [Word8]
-toBigNumBytes value =
-    let isNeg = value < 0
-        magnitude = if isNeg then negate value else value
-        payloadBE
-            | magnitude == 0 = [0]
-            | otherwise = go magnitude []
-          where
-            go 0 acc = acc
-            go n acc =
-                let (q, r) = quotRem n 256
-                 in go q (fromIntegral r : acc)
-
-        headerBase :: Word32
-        headerBase = (fromIntegral (length payloadBE) .|. 0x00800000)
-        headerVal :: Word32
-        headerVal = if isNeg then complement headerBase else headerBase
-        headerMasked = headerVal .&. 0x00FFFFFF
-        headerBytes =
-            [ fromIntegral ((headerMasked `shiftR` 16) .&. 0xFF)
-            , fromIntegral ((headerMasked `shiftR` 8) .&. 0xFF)
-            , fromIntegral (headerMasked .&. 0xFF)
-            ]
-        payloadBytes = if isNeg then map complement payloadBE else payloadBE
-     in headerBytes <> payloadBytes
-
--- | DuckDB BIT value represented as raw bytes plus left-padding bit count.
-data BitString = BitString
-    { padding :: !Word8
-    , bits :: !BS.ByteString
-    }
-    deriving stock (Eq)
-
-instance Show BitString where
-    show (BitString padding bits) =
-        drop (fromIntegral padding) $ concatMap word8ToString $ BS.unpack bits
-      where
-        word8ToString :: Word8 -> String
-        word8ToString w = map (\n -> if testBit w n then '1' else '0') [7, 6 .. 0]
-
--- | Construct a @BitString@ from a list of @Bool@s, where the first element
-bsFromBool :: [Bool] -> BitString
-bsFromBool bits =
-    let totalBits = length bits
-        padding = (8 - (totalBits `mod` 8)) `mod` 8
-        paddedBits = replicate padding False ++ bits
-        byteChunks = chunk 8 paddedBits
-        byteValues = map bitsToWord8 byteChunks
-     in BitString (fromIntegral padding) (BS.pack byteValues)
-  where
-    chunk _ [] = []
-    chunk n xs = take n xs : chunk n (drop n xs)
-
-    bitsToWord8 :: [Bool] -> Word8
-    bitsToWord8 bs = foldl (\acc (b, i) -> if b then setBit acc i else acc) 0 (zip bs [7, 6 .. 0])
-
--- | Time-of-day paired with its associated timezone offset.
-data TimeWithZone = TimeWithZone
-    { timeWithZoneTime :: !TimeOfDay
-    , timeWithZoneZone :: !TimeZone
-    }
-    deriving (Eq, Show)
-
--- | Match signed values without narrowing to the machine word size.
-pattern FieldInt :: Int64 -> FieldValue
-pattern FieldInt i <- (fieldValueToInt -> Just i)
-  where
-    FieldInt i = FieldInt64 i
-
-fieldValueToInt :: FieldValue -> Maybe Int64
-fieldValueToInt (FieldInt8 i) = Just (fromIntegral i)
-fieldValueToInt (FieldInt16 i) = Just (fromIntegral i)
-fieldValueToInt (FieldInt32 i) = Just (fromIntegral i)
-fieldValueToInt (FieldInt64 i) = Just i
-fieldValueToInt _ = Nothing
-
--- | Match unsigned values without narrowing to the machine word size.
-pattern FieldWord :: Word64 -> FieldValue
-pattern FieldWord i <- (fieldValueToWord -> Just i)
-  where
-    FieldWord i = FieldWord64 i
-
-fieldValueToWord :: FieldValue -> Maybe Word64
-fieldValueToWord (FieldWord8 i) = Just (fromIntegral i)
-fieldValueToWord (FieldWord16 i) = Just (fromIntegral i)
-fieldValueToWord (FieldWord32 i) = Just (fromIntegral i)
-fieldValueToWord (FieldWord64 i) = Just i
-fieldValueToWord _ = Nothing
-
--- | Metadata for a single column in a row.
-data Field = Field
-    { fieldName :: Text
-    , fieldIndex :: Int
-    , fieldValue :: FieldValue
-    }
-    deriving (Eq, Show)
-
-{- | Exception thrown if conversion from a SQL value to a Haskell
-value fails.
--}
-data ResultError
-    = -- | The SQL and Haskell types are not compatible.
-      Incompatible
-        { errSQLType :: Text
-        , errSQLField :: Text
-        , errHaskellType :: Text
-        , errMessage :: Text
-        }
-    | {- | A SQL @NULL@ was encountered when the Haskell
-      type did not permit it.
-      -}
-      UnexpectedNull
-        { errSQLType :: Text
-        , errSQLField :: Text
-        , errHaskellType :: Text
-        , errMessage :: Text
-        }
-    | {- | The SQL value could not be parsed, or could not
-      be represented as a valid Haskell value, or an
-      unexpected low-level error occurred (e.g. mismatch
-      between metadata and actual data in a row).
-      -}
-      ConversionFailed
-        { errSQLType :: Text
-        , errSQLField :: Text
-        , errHaskellType :: Text
-        , errMessage :: Text
-        }
-    deriving (Eq, Show)
-
-instance Exception ResultError
-
-{- | Parser used by @FromField@ instances and utilities such as
-@Database.DuckDB.Simple.FromRow.fieldWith@. The supplied @Field@ contains
-column metadata and an already-decoded @FieldValue@; callers should return
-@Ok@ on success or @Errors@ (typically wrapping a @ResultError@) when the
-conversion fails.
--}
-type FieldParser a = Field -> Ok a
-
--- | Types that can be constructed from a DuckDB column.
-class FromField a where
-    fromField :: FieldParser a
-
-instance FromField FieldValue where
-    fromField Field{fieldValue} = Ok fieldValue
-
-instance FromField RawGeometry where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldGeometry value -> Ok value
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f "expected GEOMETRY"
-
--- | Decode the shape without CRS metadata. Use t'RawGeometry' to retain the CRS.
-instance FromField G.Geometry where
-    fromField f@Field{fieldValue} = case fieldValue of
-        FieldGeometry raw -> either (returnError ConversionFailed f . Text.pack) pure (fromRawGeometry raw)
-        FieldNull -> returnError UnexpectedNull f ""
-        _ -> returnError Incompatible f "expected GEOMETRY"
-
-instance FromField (StructValue FieldValue) where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldStruct structVal -> Ok structVal
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f "expected STRUCT"
-
-instance FromField (UnionValue FieldValue) where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldUnion unionVal -> Ok unionVal
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f "expected UNION"
-
-instance FromField UUID.UUID where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldText t ->
-                case UUID.fromText t of
-                    Just uuid -> Ok uuid
-                    Nothing -> returnError ConversionFailed f "invalid UUID format"
-            FieldUUID uuid -> Ok uuid
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField Bool where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldBool b -> Ok b
-            FieldInt i -> Ok (i /= 0)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField Int8 where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldInt i -> boundedIntegral f i
-            FieldHugeInt value -> boundedFromInteger f value
-            FieldUHugeInt value -> boundedFromInteger f value
-            FieldEnum value -> boundedFromInteger f (fromIntegral value)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField Int64 where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldInt i -> Ok i
-            FieldHugeInt value -> boundedFromInteger f value
-            FieldUHugeInt value -> boundedFromInteger f value
-            FieldEnum value -> Ok (fromIntegral value)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField Int32 where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldInt i -> boundedIntegral f i
-            FieldHugeInt value -> boundedFromInteger f value
-            FieldUHugeInt value -> boundedFromInteger f value
-            FieldEnum value -> boundedFromInteger f (fromIntegral value)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField Int16 where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldInt i -> boundedIntegral f i
-            FieldHugeInt value -> boundedFromInteger f value
-            FieldUHugeInt value -> boundedFromInteger f value
-            FieldEnum value -> boundedFromInteger f (fromIntegral value)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField Int where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldInt i -> boundedIntegral f i
-            FieldHugeInt value -> boundedFromInteger f value
-            FieldUHugeInt value -> boundedFromInteger f value
-            FieldEnum value -> boundedFromInteger f (fromIntegral value)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField Integer where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldInt i -> Ok (fromIntegral i)
-            FieldWord w -> Ok (fromIntegral w)
-            FieldBigNum (BigNum big) -> Ok big
-            FieldHugeInt value -> Ok value
-            FieldUHugeInt value -> Ok value
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField Natural where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldInt i
-                | i >= 0 -> Ok (fromIntegral i)
-                | otherwise ->
-                    returnError ConversionFailed f "negative value cannot be converted to Natural"
-            FieldWord w -> Ok (fromIntegral w)
-            FieldHugeInt value
-                | value >= 0 -> Ok (fromIntegral value)
-                | otherwise ->
-                    returnError ConversionFailed f "negative value cannot be converted to Natural"
-            FieldUHugeInt value -> Ok (fromIntegral value)
-            FieldBigNum (BigNum big) ->
-                if big >= 0
-                    then Ok $ fromIntegral big
-                    else returnError ConversionFailed f "negative value cannot be converted to Natural"
-            FieldEnum value -> Ok (fromIntegral value)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField Word64 where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldInt i
-                | i >= 0 -> Ok (fromIntegral i)
-                | otherwise ->
-                    returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
-            FieldWord w -> Ok w
-            FieldHugeInt value
-                | value >= 0 -> boundedFromInteger f value
-                | otherwise ->
-                    returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
-            FieldUHugeInt value -> boundedFromInteger f value
-            FieldEnum value -> Ok (fromIntegral value)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField Word32 where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldInt i
-                | i >= 0 -> boundedIntegral f i
-                | otherwise ->
-                    returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
-            FieldWord w -> boundedFromInteger f (toInteger w)
-            FieldHugeInt value
-                | value >= 0 -> boundedFromInteger f value
-                | otherwise ->
-                    returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
-            FieldUHugeInt value -> boundedFromInteger f value
-            FieldEnum value -> Ok value
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField Word16 where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldInt i
-                | i >= 0 -> boundedIntegral f i
-                | otherwise ->
-                    returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
-            FieldWord w -> boundedFromInteger f (toInteger w)
-            FieldHugeInt value
-                | value >= 0 -> boundedFromInteger f value
-                | otherwise ->
-                    returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
-            FieldUHugeInt value -> boundedFromInteger f value
-            FieldEnum value -> boundedFromInteger f (fromIntegral value)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField Word8 where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldInt i
-                | i >= 0 -> boundedIntegral f i
-                | otherwise ->
-                    returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
-            FieldWord w -> boundedFromInteger f (toInteger w)
-            FieldHugeInt value
-                | value >= 0 -> boundedFromInteger f value
-                | otherwise ->
-                    returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
-            FieldUHugeInt value -> boundedFromInteger f value
-            FieldEnum value -> boundedFromInteger f (fromIntegral value)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField Word where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldInt i
-                | i >= 0 -> boundedFromInteger f (fromIntegral i)
-                | otherwise ->
-                    returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
-            FieldWord w -> boundedFromInteger f (toInteger w)
-            FieldHugeInt value
-                | value >= 0 -> boundedFromInteger f value
-                | otherwise ->
-                    returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
-            FieldUHugeInt value -> boundedFromInteger f value
-            FieldEnum value -> boundedFromInteger f (fromIntegral value)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField Double where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldDouble d -> Ok d
-            FieldFloat value -> Ok (float2Double value)
-            FieldInt i -> Ok (fromIntegral i)
-            FieldDecimal DecimalValue{decimalInteger, decimalScale} ->
-                Ok (realToFrac decimalInteger / 10 ^ decimalScale)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField Float where
-    fromField field =
-        case (fromField field :: Ok Double) of
-            Errors err -> Errors err
-            Ok d
-                | not (isInfinite d || isNaN d) && isInfinite (double2Float d) ->
-                    returnError ConversionFailed field "floating-point value out of bounds"
-                | otherwise -> Ok (double2Float d)
-
-instance FromField Text where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldText t -> Ok t
-            FieldInt i -> Ok (Text.pack (show i))
-            FieldFloat value -> Ok (Text.pack (show value))
-            FieldDouble d -> Ok (Text.pack (show d))
-            FieldBool b -> Ok (if b then Text.pack "1" else Text.pack "0")
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField String where
-    fromField field = Text.unpack <$> fromField field
-
-instance FromField BS.ByteString where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldBlob bs -> Ok bs
-            FieldGeometry RawGeometry{rawGeometryWKB} -> Ok rawGeometryWKB
-            FieldText t -> Ok (TextEncoding.encodeUtf8 t)
-            FieldBit (BitString _ bits) -> Ok bits
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField BitString where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldBit b -> Ok b
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField BigNum where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldBigNum big -> Ok big
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance {-# OVERLAPPABLE #-} (Typeable a, FromField a) => FromField [a] where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldList entries ->
-                traverse (uncurry parseElement) (zip [0 :: Int ..] entries)
-            FieldArray arr ->
-                traverse (uncurry parseElement) (assocs arr)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-      where
-        parseElement idx value =
-            fromField
-                Field
-                    { fieldName = fieldNameWithIndex idx
-                    , fieldIndex = fieldIndex f
-                    , fieldValue = value
-                    }
-        fieldNameWithIndex idx =
-            let base = fieldName f
-                idxText = Text.pack (show idx)
-             in base <> Text.pack "[" <> idxText <> Text.pack "]"
-
-instance (Typeable a, FromField a) => FromField (Array Int a) where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldArray arr -> do
-                converted <- traverse (traverseElement arr) (range (bounds arr))
-                pure (listArray (bounds arr) converted)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-      where
-        traverseElement arr idx =
-            fromField
-                Field
-                    { fieldName = fieldNameWithIndex idx
-                    , fieldIndex = fieldIndex f
-                    , fieldValue = arr ! idx
-                    }
-        fieldNameWithIndex idx =
-            let idxText = Text.pack (show idx)
-             in fieldName f <> Text.pack "[" <> idxText <> Text.pack "]"
-
-instance (Ord k, Typeable k, Typeable v, FromField k, FromField v) => FromField (Map k v) where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldMap pairs -> Map.fromList <$> traverse (uncurry parsePair) (zip [0 :: Int ..] pairs)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-      where
-        parsePair idx (keyValue, valValue) = do
-            key <-
-                fromField
-                    Field
-                        { fieldName = fieldName f <> suffix idx ".key"
-                        , fieldIndex = fieldIndex f
-                        , fieldValue = keyValue
-                        }
-            value <-
-                fromField
-                    Field
-                        { fieldName = fieldName f <> suffix idx ".value"
-                        , fieldIndex = fieldIndex f
-                        , fieldValue = valValue
-                        }
-            pure (key, value)
-        suffix idx label =
-            let idxText = Text.pack (show idx)
-             in Text.pack "[" <> idxText <> Text.pack "]" <> Text.pack label
-
-instance FromField DecimalValue where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldDecimal dec -> Ok dec
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField Day where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldDate day -> finiteField f day
-            FieldTimestamp timestamp -> finiteField f (localDay <$> timestamp)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField (Unbounded Day) where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldDate day -> Ok day
-            FieldTimestamp timestamp -> Ok (localDay <$> timestamp)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField TimeOfDay where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldTime tod -> Ok tod
-            FieldTimestamp timestamp -> finiteField f (localTimeOfDay <$> timestamp)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField TimeWithZone where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldTimeTZ tz -> Ok tz
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField LocalTime where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldTimestamp ts -> finiteField f ts
-            FieldDate day -> finiteField f ((\value -> LocalTime value midnight) <$> day)
-            FieldTimestampTZ utcTime -> finiteField f (utcToLocalTime utc <$> utcTime)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-      where
-        midnight = TimeOfDay 0 0 0
-
-instance FromField (Unbounded LocalTime) where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldTimestamp ts -> Ok ts
-            FieldDate day -> Ok ((\value -> LocalTime value midnight) <$> day)
-            FieldTimestampTZ utcTime -> Ok (utcToLocalTime utc <$> utcTime)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-      where
-        midnight = TimeOfDay 0 0 0
-
-instance FromField IntervalValue where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldInterval interval -> Ok interval
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-
-instance FromField UTCTime where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldTimestamp ts -> finiteField f (localTimeToUTC utc <$> ts)
-            FieldTimestampTZ utcTime -> finiteField f utcTime
-            FieldDate day -> finiteField f ((\value -> localTimeToUTC utc (LocalTime value midnight)) <$> day)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-      where
-        midnight = TimeOfDay 0 0 0
-
-instance FromField (Unbounded UTCTime) where
-    fromField f@Field{fieldValue} =
-        case fieldValue of
-            FieldTimestamp ts -> Ok (localTimeToUTC utc <$> ts)
-            FieldTimestampTZ utcTime -> Ok utcTime
-            FieldDate day -> Ok ((\value -> localTimeToUTC utc (LocalTime value midnight)) <$> day)
-            FieldNull -> returnError UnexpectedNull f ""
-            _ -> returnError Incompatible f ""
-      where
-        midnight = TimeOfDay 0 0 0
-
--- | Reject infinity when the requested Haskell type holds only finite values.
-finiteField :: (Typeable a) => Field -> Unbounded a -> Ok a
-finiteField _ (Finite value) = Ok value
-finiteField field _ = returnError ConversionFailed field "infinity requires an Unbounded date or timestamp"
-
-instance (FromField a) => FromField (Maybe a) where
-    fromField Field{fieldValue = FieldNull} = Ok Nothing
-    fromField field = Just <$> fromField field
-
--- | Helper for bounded integral conversions.
-boundedIntegral :: forall a. (Integral a, Bounded a, Typeable a) => Field -> Int64 -> Ok a
-boundedIntegral f = boundedFromInteger f . toInteger
-
-boundedFromInteger :: forall a. (Integral a, Bounded a, Typeable a) => Field -> Integer -> Ok a
-boundedFromInteger f@Field{} value
-    | value < toInteger (minBound :: a) =
-        returnError ConversionFailed f "integer value out of bounds"
-    | value > toInteger (maxBound :: a) =
-        returnError ConversionFailed f "integer value out of bounds"
-    | otherwise = Ok (fromInteger value)
-
-{- | Helper to construct a ResultError with field context.
-based on postgresql-simple's implementation
--}
-returnError :: forall b. (Typeable b) => (Text -> Text -> Text -> Text -> ResultError) -> Field -> Text -> Ok b
-returnError mkError Field{fieldValue, fieldName} msg =
-    Errors
-        [ SomeException $
-            mkError
-                (fieldValueTypeName fieldValue)
-                fieldName
-                (Text.pack $ show (typeRep (Proxy :: Proxy b)))
-                msg
-        ]
-
-fieldValueTypeName :: FieldValue -> Text
-fieldValueTypeName = \case
-    FieldNull -> "NULL"
-    FieldInt8{} -> "INT1"
-    FieldInt16{} -> "INT2"
-    FieldInt32{} -> "INT4"
-    FieldInt64{} -> "INT8"
-    FieldWord8{} -> "UTINYINT"
-    FieldWord16{} -> "USMALLINT"
-    FieldWord32{} -> "UINTEGER"
-    FieldWord64{} -> "UBIGINT"
-    FieldFloat{} -> "FLOAT"
-    FieldDouble{} -> "DOUBLE"
-    FieldText{} -> "TEXT"
-    FieldBool{} -> "BOOLEAN"
-    FieldBlob{} -> "BLOB"
-    FieldGeometry{} -> "GEOMETRY"
-    FieldDate{} -> "DATE"
-    FieldTime{} -> "TIME"
-    FieldTimestamp{} -> "TIMESTAMP"
-    FieldInterval{} -> "INTERVAL"
-    FieldHugeInt{} -> "HUGEINT"
-    FieldUHugeInt{} -> "UHUGEINT"
-    FieldDecimal{} -> "DECIMAL"
-    FieldTimestampTZ{} -> "TIMESTAMP_TZ"
-    FieldTimeTZ{} -> "TIME_TZ"
-    FieldBit{} -> "BIT"
-    FieldBigNum{} -> "BIGNUM"
-    FieldEnum{} -> "ENUM"
-    FieldArray{} -> "ARRAY"
-    FieldList{} -> "LIST"
-    FieldMap{} -> "MAP"
-    FieldUUID{} -> "UUID"
-    FieldStruct{} -> "STRUCT"
-    FieldUnion{} -> "UNION"
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE DeriveTraversable #-}
+{-# LANGUAGE DerivingVia #-}
+{-# LANGUAGE FlexibleInstances #-}
+{-# LANGUAGE KindSignatures #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE PatternSynonyms #-}
+{-# LANGUAGE RoleAnnotations #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE StrictData #-}
+{-# LANGUAGE TypeApplications #-}
+{-# LANGUAGE ViewPatterns #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.FromField
+-- Description : Conversion from DuckDB column values to Haskell types.
+module Database.DuckDB.Simple.FromField (
+  Field (..),
+  FieldValue (..),
+  RawGeometry (..),
+  StructField (..),
+  StructValue (..),
+  TupleValue (..),
+  UnionMemberType (..),
+  UnionValue (..),
+  LogicalTypeRep (..),
+  LogicalTypeId (..),
+  BitString (..),
+  bsFromBool,
+  BigNum (..),
+  fromBigNumBytes,
+  toBigNumBytes,
+  DecimalValue (..),
+  IntervalValue (..),
+  TimeWithZone (..),
+  timeWithZone,
+  timeWithZoneZone,
+  SizedArray,
+  sizedArray,
+  sizedArrayFromList,
+  sizedArrayToArray,
+  ResultError (..),
+  FieldParser,
+  FromField (..),
+  returnError,
+  fieldTypeName,
+) where
+
+import Control.Exception (Exception (..))
+import Data.Array (Array, assocs, bounds, elems, listArray, rangeSize)
+import Data.Bits (Bits (..), finiteBitSize)
+import qualified Data.ByteString as BS
+import Data.Data (Typeable, typeRep)
+import qualified Data.Geometry as G
+import Data.Int (Int16, Int32, Int64, Int8)
+import Data.Map.Strict (Map)
+import qualified Data.Map.Strict as Map
+import Data.Ord (clamp)
+import Data.Proxy (Proxy (..))
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Data.Time.Calendar (Day, addDays, diffDays, fromGregorian)
+import Data.Time.Clock (UTCTime (..), diffTimeToPicoseconds)
+import Data.Time.LocalTime (
+  LocalTime (..),
+  TimeOfDay (..),
+  TimeZone,
+  minutesToTimeZone,
+  timeOfDayToTime,
+  timeZoneMinutes,
+ )
+import qualified Data.UUID as UUID
+import Data.Word (Word16, Word32, Word64, Word8)
+import Database.DuckDB.Simple.Conversion (Conversion, conversionErrorWith)
+import Database.DuckDB.Simple.Geometry (RawGeometry (..), fromRawGeometry)
+import Database.DuckDB.Simple.LogicalRep (
+  LogicalTypeId (..),
+  LogicalTypeRep (..),
+  StructField (..),
+  StructValue (..),
+  TupleValue (..),
+  UnionMemberType (..),
+  UnionValue (..),
+  aliasBase,
+  listElementType,
+  logicalTypeSQL,
+  mapEntryTypes,
+ )
+import Database.DuckDB.Simple.Native (arraySizeReason)
+import Database.DuckDB.Simple.Time (Date, LocalTimestamp, UTCTimestamp, Unbounded (..))
+import GHC.Float (double2Float, float2Double, int2Double, int2Float, rationalToDouble, rationalToFloat, word2Double)
+import GHC.Num.Integer (integerFromWordList)
+import GHC.TypeLits (KnownNat, Nat, natVal)
+import Numeric.Natural (Natural)
+
+-- | Internal representation of a column value.
+-- 'FieldGeometry' contains raw WKB and CRS metadata. A STRUCT, TUPLE, or UNION
+-- parameter binds it as a GEOMETRY with the same CRS. A VARIANT parameter
+-- binds it only when it has no CRS. A top-level t'RawGeometry' parameter binds
+-- as a GEOMETRY with its own CRS. See Note [Raw GEOMETRY parameters] in
+-- "Database.DuckDB.Simple.ToField".
+data FieldValue
+  = FieldNull
+  | FieldInt8 Int8
+  | FieldInt16 Int16
+  | FieldInt32 Int32
+  | FieldInt64 Int64
+  | FieldWord8 Word8
+  | FieldWord16 Word16
+  | FieldWord32 Word32
+  | FieldWord64 Word64
+  | FieldUUID UUID.UUID
+  | FieldFloat Float
+  | FieldDouble Double
+  | FieldText Text
+  | FieldBool Bool
+  | FieldBlob BS.ByteString
+  | FieldGeometry RawGeometry
+  | FieldDate Date
+  | FieldTime TimeOfDay
+  | FieldTimestamp LocalTimestamp
+  | FieldInterval IntervalValue
+  | FieldHugeInt Integer
+  | FieldUHugeInt Integer
+  | FieldDecimal DecimalValue
+  | FieldTimestampTZ UTCTimestamp
+  | FieldTimeTZ TimeWithZone
+  | FieldBit BitString
+  | FieldBigNum BigNum
+  | FieldEnum Word32 Text
+  | FieldArray (Array Int FieldValue)
+  | FieldList [FieldValue]
+  | FieldMap [(FieldValue, FieldValue)]
+  | FieldStruct (StructValue FieldValue)
+  | FieldTuple (TupleValue FieldValue)
+  | FieldUnion (UnionValue FieldValue)
+  deriving (Eq, Show)
+
+-- | Exact-width decimal payload plus its declared width and scale. A parameter
+-- of this type binds as a DECIMAL with this width and scale. A @SizedArray@, a
+-- list, or a typed row cannot hold it, because it has no @DuckDBColumnType@
+-- instance: one column type cannot give the width and scale of each value.
+data DecimalValue = DecimalValue
+  { decimalWidth :: Word8
+  , decimalScale :: Word8
+  , decimalInteger :: Integer
+  }
+  deriving (Eq, Show)
+
+-- | DuckDB interval payload split into months, days, and microseconds. A
+-- parameter of this type binds as an INTERVAL, and DuckDB keeps the three
+-- fields.
+data IntervalValue = IntervalValue
+  { intervalMonths :: Int32
+  , intervalDays :: Int32
+  , intervalMicros :: Int64
+  }
+  deriving (Eq, Show)
+
+-- | Arbitrary-precision integer wrapper used for DuckDB's BIGNUM type.
+newtype BigNum = BigNum Integer
+  deriving stock (Eq, Show)
+  deriving (Num) via Integer
+
+-- | Decode a DuckDB BIGNUM blob as a Haskell @Integer@. The blob has a 3-byte
+-- header and a big-endian payload. Negative values have a complemented payload.
+-- Restore that payload, then split it into machine-word limbs for
+-- @integerFromWordList@, with the most significant limb first.
+-- This is the BIGNUM storage of DuckDB 2.0.0. The V2 API does not commit to this
+-- layout, and this library does not use this function.
+fromBigNumBytes :: [Word8] -> Integer
+fromBigNumBytes bytes =
+  let header = take 3 bytes
+      payloadRaw = drop 3 bytes
+      isNeg = case header of
+        (h : _) -> h .&. 0x80 == 0
+        [] -> False
+      payload = if isNeg then map complement payloadRaw else payloadRaw
+      bytesPerWord = finiteBitSize (0 :: Word) `div` 8 -- 8 on 64-bit, 4 on 32-bit
+      len = length payload
+      (firstChunk, rest) = splitAt (len `mod` bytesPerWord) payload
+
+      chunkWords [] = []
+      chunkWords xs =
+        let (chunk, remainder) = splitAt bytesPerWord xs
+        in  chunk : chunkWords remainder
+
+      toWord = foldl (\acc b -> (acc `shiftL` 8) .|. fromIntegral b) 0
+      limbs = (if null firstChunk then id else (firstChunk :)) (chunkWords rest)
+  in  integerFromWordList isNeg (map toWord limbs)
+
+-- | Encode an @Integer@ as a DuckDB BIGNUM blob. Write the 3-byte header
+-- (sign bit and payload length), then the magnitude bytes in big-endian order.
+-- Complement the header and the payload for a negative value.
+-- This is the BIGNUM storage of DuckDB 2.0.0. The V2 API does not commit to
+-- this layout, and this library does not use this function.
+toBigNumBytes :: Integer -> [Word8]
+toBigNumBytes value =
+  let isNeg = value < 0
+      magnitude = if isNeg then negate value else value
+      payloadBE
+        | magnitude == 0 = [0]
+        | otherwise = go magnitude []
+        where
+          go 0 acc = acc
+          go n acc =
+            let (q, r) = quotRem n 256
+            in  go q (fromIntegral r : acc)
+
+      headerBase :: Word32
+      headerBase = (fromIntegral (length payloadBE) .|. 0x00800000)
+      headerVal :: Word32
+      headerVal = if isNeg then complement headerBase else headerBase
+      headerMasked = headerVal .&. 0x00FFFFFF
+      headerBytes =
+        [ fromIntegral ((headerMasked `shiftR` 16) .&. 0xFF)
+        , fromIntegral ((headerMasked `shiftR` 8) .&. 0xFF)
+        , fromIntegral (headerMasked .&. 0xFF)
+        ]
+      payloadBytes = if isNeg then map complement payloadBE else payloadBE
+  in  headerBytes <> payloadBytes
+
+-- | DuckDB BIT value represented as raw bytes plus left-padding bit count.
+data BitString = BitString
+  { padding :: Word8
+  , bits :: BS.ByteString
+  }
+  deriving stock (Eq)
+
+instance Show BitString where
+  show (BitString padding bits) =
+    drop (fromIntegral padding) $ concatMap word8ToString $ BS.unpack bits
+    where
+      word8ToString :: Word8 -> String
+      word8ToString w = map (\n -> if testBit w n then '1' else '0') [7, 6 .. 0]
+
+-- | Construct a @BitString@ from a list of @Bool@ values. The first element is
+-- the first bit, and 'True' is a 1 bit. The function puts 0 bits in front of the
+-- first element to fill the first byte, and stores their count as the padding.
+bsFromBool :: [Bool] -> BitString
+bsFromBool bits =
+  let totalBits = length bits
+      padding = (8 - (totalBits `mod` 8)) `mod` 8
+      paddedBits = replicate padding False ++ bits
+      byteChunks = chunk 8 paddedBits
+      byteValues = map bitsToWord8 byteChunks
+  in  BitString (fromIntegral padding) (BS.pack byteValues)
+  where
+    chunk _ [] = []
+    chunk n xs = take n xs : chunk n (drop n xs)
+
+    bitsToWord8 :: [Bool] -> Word8
+    bitsToWord8 bs = foldl (\acc (b, i) -> if b then setBit acc i else acc) 0 (zip bs [7, 6 .. 0])
+
+-- | Time of day with its offset from UTC in seconds, as a TIMETZ stores it. A
+-- positive offset is east of UTC: @12:00:00+02@ has the offset 7200. DuckDB
+-- stores an offset from -57599 to 57599 seconds (-15:59:59 to +15:59:59) and the
+-- time in microseconds. A value with such an offset reads back equal to the
+-- bound value. A time with digits below one microsecond loses these digits, as
+-- in SQL text. 'timeWithZone' makes a value from a "Data.Time" zone, and
+-- 'timeWithZoneZone' gives the zone of a value.
+data TimeWithZone = TimeWithZone
+  { timeWithZoneTime :: TimeOfDay
+  , timeWithZoneOffsetSeconds :: Int32
+  }
+  deriving (Eq, Show)
+
+-- | Make a t'TimeWithZone' from a time of day and a "Data.Time" zone. The offset
+-- is the minutes of the zone times 60. If the seconds exceed the 'Int32'
+-- range, keep the nearest bound. Binding rejects either bound as an invalid
+-- TIMETZ offset. DuckDB does not store the zone name or the summer flag.
+timeWithZone :: TimeOfDay -> TimeZone -> TimeWithZone
+timeWithZone time zone = TimeWithZone time (fromInteger (clamp bounds32 seconds))
+  where
+    seconds = toInteger (timeZoneMinutes zone) * 60
+    bounds32 = (toInteger (minBound @Int32), toInteger (maxBound @Int32))
+
+-- | Give the "Data.Time" zone of the offset of a t'TimeWithZone'. A 'TimeZone'
+-- holds whole minutes, so the seconds of an offset are dropped: the offset
+-- 3630 seconds of @12:00:00+01:00:30@ gives the zone @+0100@. The zone has no
+-- name.
+timeWithZoneZone :: TimeWithZone -> TimeZone
+timeWithZoneZone value = minutesToTimeZone (fromIntegral (timeWithZoneOffsetSeconds value `quot` 60))
+
+type role SizedArray nominal representational
+
+-- | An 'Array' of exactly @n@ values, with the bounds @(0, n - 1)@. A
+-- parameter of this type binds as the ARRAY type @T[n]@, and a typed
+-- registration declares that type. See Note [Sized arrays] in
+-- "Database.DuckDB.Simple.ToField". Make a value with 'sizedArray' or
+-- 'sizedArrayFromList'.
+newtype SizedArray (n :: Nat) a = SizedArray (Array Int a)
+  deriving stock (Eq, Ord, Show, Functor, Foldable, Traversable)
+
+-- | Make a t'SizedArray' from an 'Array' with any bounds. The result is
+-- 'Nothing' when the array does not have exactly @n@ values. The result has
+-- the values in their order, with the bounds @(0, n - 1)@.
+sizedArray :: forall n a. (KnownNat n) => Array Int a -> Maybe (SizedArray n a)
+sizedArray values
+  | toInteger count == natVal (Proxy @n) = Just (SizedArray (listArray (0, count - 1) (elems values)))
+  | otherwise = Nothing
+  where
+    count = rangeSize (bounds values)
+
+-- | Make a t'SizedArray' from a list. The result is 'Nothing' when the list
+-- does not have exactly @n@ values. The count is checked before the 'Array'
+-- is built, and the check reads at most @n + 1@ elements.
+-- A size above @maxBound :: Int@ gives 'Nothing' without reading the list.
+sizedArrayFromList :: forall n a. (KnownNat n) => [a] -> Maybe (SizedArray n a)
+sizedArrayFromList values
+  | size > toInteger (maxBound :: Int) = Nothing
+  | hasSize size values = Just (SizedArray (listArray (0, fromInteger size - 1) values))
+  | otherwise = Nothing
+  where
+    size = natVal (Proxy @n)
+    hasSize 0 [] = True
+    hasSize 0 (_ : _) = False
+    hasSize _ [] = False
+    hasSize remaining (_ : rest) = hasSize (remaining - 1) rest
+
+-- | Give the 'Array' of a t'SizedArray', with the bounds @(0, n - 1)@.
+sizedArrayToArray :: SizedArray n a -> Array Int a
+sizedArrayToArray (SizedArray values) = values
+
+-- | Match signed values without narrowing to the machine word size.
+pattern FieldInt :: Int64 -> FieldValue
+pattern FieldInt i <- (fieldValueToInt -> Just i)
+  where
+    FieldInt i = FieldInt64 i
+
+fieldValueToInt :: FieldValue -> Maybe Int64
+fieldValueToInt (FieldInt8 i) = Just (fromIntegral i)
+fieldValueToInt (FieldInt16 i) = Just (fromIntegral i)
+fieldValueToInt (FieldInt32 i) = Just (fromIntegral i)
+fieldValueToInt (FieldInt64 i) = Just i
+fieldValueToInt _ = Nothing
+
+-- | Match unsigned values without narrowing to the machine word size.
+pattern FieldWord :: Word64 -> FieldValue
+pattern FieldWord i <- (fieldValueToWord -> Just i)
+  where
+    FieldWord i = FieldWord64 i
+
+fieldValueToWord :: FieldValue -> Maybe Word64
+fieldValueToWord (FieldWord8 i) = Just (fromIntegral i)
+fieldValueToWord (FieldWord16 i) = Just (fromIntegral i)
+fieldValueToWord (FieldWord32 i) = Just (fromIntegral i)
+fieldValueToWord (FieldWord64 i) = Just i
+fieldValueToWord _ = Nothing
+
+-- | Metadata for a single column in a row. The SQL type is an explicit
+-- conversion, so a field has no equality or display instance.
+data Field = Field
+  { fieldName :: Text
+  , fieldIndex :: Int
+  , fieldValue :: FieldValue
+  , fieldType :: Conversion LogicalTypeRep
+  -- ^ Read the SQL type, with each alias. VARIANT means that the type of the
+  -- stored value decides. See Note [Column types].
+  }
+
+{- Note [Column types]
+~~~~~~~~~~~~~~~~~~~~~~
+fieldType reads the SQL type of a Field, with each alias (see
+Note [Type aliases] in "Database.DuckDB.Simple.LogicalRep"). Each place that
+makes a Field supplies a conversion:
+
+- A result column. The query result owns its native logical type. A query
+  parser runs before this metadata scope closes. A cursor retains its scope
+  until exhaustion, reset, or statement closure.
+- A callback argument. The callback owns its native logical type. Its scope
+  closes when the callback invocation returns.
+- A LIST or ARRAY element, or a MAP key or value. The reader maps the type
+  projection over the parent's conversion with listElementType or mapEntryTypes.
+- A synthetic field made from a FieldValue alone. Its conversion returns VARIANT.
+
+VARIANT means that the stored value determines its type. An element of a
+VARIANT column also has type VARIANT. The fieldType action converts no type
+tree or ENUM dictionary until requested. Structured value readers can also
+build type trees. See Note [Type trees] in
+"Database.DuckDB.Simple.Materialize".
+
+The scope caches successful type reads. An interrupted read can retry while
+the scope remains open. Closure releases native types and clears the cache.
+An escaped native conversion raises SQLError with the message
+"duckdb-simple: field type scope is closed", including a cached conversion.
+A LogicalTypeRep snapshot already returned to the caller is pure and remains
+valid after closure. Completed conversion diagnostics are also pure. The
+library resolves them before closing the scope. See Note [Conversion effects]
+in "Database.DuckDB.Simple.Conversion".
+-}
+
+-- | Exception thrown if conversion from a SQL value to a Haskell
+-- value fails.
+data ResultError
+  = -- | The SQL and Haskell types are not compatible.
+    Incompatible
+      { errSQLType :: Text
+      , errSQLField :: Text
+      , errHaskellType :: Text
+      , errMessage :: Text
+      }
+  | -- | A SQL @NULL@ was encountered when the Haskell
+    --       type did not permit it.
+    UnexpectedNull
+      { errSQLType :: Text
+      , errSQLField :: Text
+      , errHaskellType :: Text
+      , errMessage :: Text
+      }
+  | -- | The SQL value could not be parsed, or could not
+    --       be represented as a valid Haskell value, or an
+    --       unexpected low-level error occurred (e.g. mismatch
+    --       between metadata and actual data in a row).
+    ConversionFailed
+      { errSQLType :: Text
+      , errSQLField :: Text
+      , errHaskellType :: Text
+      , errMessage :: Text
+      }
+  deriving (Eq, Show)
+
+-- | The text of the error names the column and the two types.
+instance Exception ResultError where
+  displayException = Text.unpack . renderResultError
+
+-- | Render a conversion error. An error without a column name, for example one
+-- of a field of a generic record, names "a value".
+renderResultError :: ResultError -> Text
+renderResultError = \case
+  Incompatible{errSQLType, errSQLField, errHaskellType, errMessage} ->
+    Text.concat ["duckdb-simple: ", subject errSQLField, " has type ", errSQLType, " but expected ", errHaskellType, detail errMessage]
+  UnexpectedNull{errSQLField, errHaskellType, errMessage} ->
+    Text.concat ["duckdb-simple: ", subject errSQLField, " is NULL but expected ", errHaskellType, detail errMessage]
+  ConversionFailed{errMessage} -> errMessage
+  where
+    subject name = if Text.null name then Text.pack "a value" else Text.pack "column " <> name
+    detail message = if Text.null message then Text.empty else Text.pack ": " <> message
+
+-- | Parser used by @FromField@ instances and utilities such as
+-- @Database.DuckDB.Simple.FromRow.fieldWith@. The supplied @Field@ contains
+-- column metadata and an already-decoded @FieldValue@. Use 'pure' for success
+-- or 'returnError' for a conversion failure.
+type FieldParser a = Field -> Conversion a
+
+-- | Types that can be constructed from a DuckDB column. Each instance says
+-- which SQL types it reads. See Note [Reads of another SQL type].
+--
+-- An instance that cannot read a value fails with a 'ResultError', for example
+-- 'ConversionFailed' or 'Incompatible'. The library does not raise the
+-- 'ResultError'. It puts the text of the 'ResultError' into the @SQLError@
+-- that the statement raises. The section \"Errors\" of the README gives the
+-- type of that @SQLError@.
+class FromField a where
+  fromField :: FieldParser a
+
+{- Note [Reads of another SQL type]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Each FromField instance reads the SQL type of its Haskell type, for example
+BIGINT for Int64 and TIMESTAMP for LocalTime. An instance also reads another
+SQL type only when it gives, for each value, the value of the cast of DuckDB to
+the SQL type of the Haskell type, or an error. For example, Int8 reads the
+BIGINT value 5 as 5, which is the value of 5::BIGINT::TINYINT, and it raises
+ConversionFailed for 300, where the cast raises an error. When the Haskell type
+holds more digits than its SQL type, the comparison is with the cast to the
+narrowest SQL type that holds the value exactly. Thus LocalTime reads a
+TIMESTAMP_NS value with its nanoseconds, as the cast to TIMESTAMP_NS keeps
+them.
+
+The instances do not read a pair whose cast needs data that the decoded value
+does not have, or whose value the library cannot give exactly. A read of such a
+pair raises Incompatible, as for each other pair that an instance does not
+read. The error names the SQL type of the column in the text of DuckDB
+(fieldTypeName), for example TIMESTAMP_NS or DECIMAL(18,3). For a column of the
+type VARIANT, it names the type of the stored value in the same text
+(fieldValueTypeName), and the error of a String names Text. Error diagnostics
+read type metadata only when the final conversion fails. These pairs are:
+
+- UTCTime from TIMESTAMP, TIMESTAMP_S, TIMESTAMP_MS, TIMESTAMP_NS, and DATE, and
+  LocalTime from TIMESTAMPTZ and TIMESTAMPTZ_NS. These casts use the TimeZone
+  setting of the session. To read the value as the other type in UTC, write
+  c::TIMESTAMP AT TIME ZONE 'UTC' in SQL for a TIMESTAMP, TIMESTAMP_S,
+  TIMESTAMP_MS, or DATE value, and c AT TIME ZONE 'UTC' for each other type.
+  Without the cast to TIMESTAMP, DuckDB converts a DATE, TIMESTAMP_S, or
+  TIMESTAMP_MS value to nanoseconds, which fails outside the years 1677 to
+  2262. The cast rounds a TIMESTAMP_NS value to the microsecond.
+- Text and String from FLOAT and DOUBLE. The text of the cast differs from the
+  text of show, for example 0.01 and 1.0e-2. Read a Double, or write c::VARCHAR.
+- ByteString from VARCHAR. The cast to BLOB reads escape sequences such as \x41.
+  Read a Text, or write encode(c) for the UTF-8 bytes.
+- Each integer type from ENUM. The cast to an integer type parses the label,
+  for example '20' gives 20. Write c::INTEGER for that value, or
+  enum_code(c)::BIGINT for the index. enum_code gives an unsigned type, which
+  the signed integer types do not read.
+- Variant from a value that a VARIANT cannot hold (variantShape in
+  "Database.DuckDB.Simple.Variant"): a FieldArray, a FieldTuple, a FieldStruct
+  that is not in the form of a VARIANT object (a field of a type other than
+  VARIANT, or keys out of ascending order), a FieldEnum, a FieldMap, a
+  FieldUnion, or a GEOMETRY with a CRS, at any depth. The cast to VARIANT gives
+  another value. Write c::VARIANT. A VARIANT column decodes only to values of
+  the VARIANT shape. A JSON type at any depth raises Incompatible, because
+  DuckDB parses its text when it casts to VARIANT. Write c::VARIANT for the
+  parsed value. The bind side
+  (variantPayloadType in "Database.DuckDB.Simple.ToField") accepts more: it
+  binds a FieldArray and a FieldTuple as a VARIANT list, and the fields of each
+  FieldStruct as VARIANT values.
+
+Text and String read the label of an ENUM value, which is the text of the cast
+to VARCHAR. See Note [ENUM labels] in "Database.DuckDB.Simple.Materialize".
+
+The rule holds at each depth. A field of a generic record reads the SQL types
+that the FromField instance of its type reads: a scalar field uses that
+instance, and a list field reads a LIST and an ARRAY (the DuckValue instances
+in "Database.DuckDB.Simple.Generic").
+
+See Note [DECIMAL as DOUBLE and FLOAT] for the floating-point value of a DECIMAL.
+-}
+
+-- | Reads each SQL type, and does not convert the value.
+instance FromField FieldValue where
+  fromField Field{fieldValue} = pure fieldValue
+
+-- | Reads GEOMETRY, with its CRS.
+instance FromField RawGeometry where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldGeometry value -> pure value
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f "expected GEOMETRY"
+
+-- | Reads GEOMETRY. The shape has no CRS metadata. Use t'RawGeometry' to retain
+-- the CRS.
+instance FromField G.Geometry where
+  fromField f@Field{fieldValue} = case fieldValue of
+    FieldGeometry raw -> either (returnError ConversionFailed f . Text.pack) pure (fromRawGeometry raw)
+    FieldNull -> returnError UnexpectedNull f ""
+    _ -> returnError Incompatible f "expected GEOMETRY"
+
+-- | Reads STRUCT.
+instance FromField (StructValue FieldValue) where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldStruct structVal -> pure structVal
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f "expected STRUCT"
+
+-- | Reads UNION.
+instance FromField (UnionValue FieldValue) where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldUnion unionVal -> pure unionVal
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f "expected UNION"
+
+-- | Reads UUID, and VARCHAR in the form of 36 characters with dashes. Each
+-- other text fails with 'ConversionFailed'.
+instance FromField UUID.UUID where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldText t ->
+        case UUID.fromText t of
+          Just uuid -> pure uuid
+          Nothing -> returnError ConversionFailed f "invalid UUID format"
+      FieldUUID uuid -> pure uuid
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads TUPLE.
+instance FromField (TupleValue FieldValue) where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldTuple tuple -> pure tuple
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f "expected TUPLE"
+
+-- | Reads BOOLEAN, and TINYINT, SMALLINT, INTEGER, and BIGINT. An integer other
+-- than 0 is True, as in the cast to BOOLEAN.
+instance FromField Bool where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldBool b -> pure b
+      FieldInt i -> pure (i /= 0)
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads TINYINT, SMALLINT, INTEGER, BIGINT, HUGEINT, and UHUGEINT. A value
+-- out of range fails with 'ConversionFailed'. It does not read ENUM.
+instance FromField Int8 where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldInt i -> boundedIntegral f i
+      FieldHugeInt value -> boundedFromInteger f value
+      FieldUHugeInt value -> boundedFromInteger f value
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads BIGINT, TINYINT, SMALLINT, INTEGER, HUGEINT, and UHUGEINT. A value
+-- out of range fails with 'ConversionFailed'. It does not read ENUM.
+instance FromField Int64 where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldInt i -> pure i
+      FieldHugeInt value -> boundedFromInteger f value
+      FieldUHugeInt value -> boundedFromInteger f value
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads INTEGER, TINYINT, SMALLINT, BIGINT, HUGEINT, and UHUGEINT. A value
+-- out of range fails with 'ConversionFailed'. It does not read ENUM.
+instance FromField Int32 where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldInt i -> boundedIntegral f i
+      FieldHugeInt value -> boundedFromInteger f value
+      FieldUHugeInt value -> boundedFromInteger f value
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads SMALLINT, TINYINT, INTEGER, BIGINT, HUGEINT, and UHUGEINT. A value
+-- out of range fails with 'ConversionFailed'. It does not read ENUM.
+instance FromField Int16 where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldInt i -> boundedIntegral f i
+      FieldHugeInt value -> boundedFromInteger f value
+      FieldUHugeInt value -> boundedFromInteger f value
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads BIGINT, TINYINT, SMALLINT, INTEGER, HUGEINT, and UHUGEINT. A value
+-- out of range fails with 'ConversionFailed'. It does not read ENUM.
+instance FromField Int where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldInt i -> boundedIntegral f i
+      FieldHugeInt value -> boundedFromInteger f value
+      FieldUHugeInt value -> boundedFromInteger f value
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads BIGNUM, TINYINT to BIGINT, UTINYINT to UBIGINT, HUGEINT, and UHUGEINT.
+instance FromField Integer where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldInt i -> pure (fromIntegral i)
+      FieldWord w -> pure (fromIntegral w)
+      FieldBigNum (BigNum big) -> pure big
+      FieldHugeInt value -> pure value
+      FieldUHugeInt value -> pure value
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads BIGNUM, TINYINT to BIGINT, UTINYINT to UBIGINT, HUGEINT, and
+-- UHUGEINT. A negative value fails with 'ConversionFailed'. It does not read
+-- ENUM.
+instance FromField Natural where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldInt i
+        | i >= 0 -> pure (fromIntegral i)
+        | otherwise ->
+            returnError ConversionFailed f "negative value cannot be converted to Natural"
+      FieldWord w -> pure (fromIntegral w)
+      FieldHugeInt value
+        | value >= 0 -> pure (fromIntegral value)
+        | otherwise ->
+            returnError ConversionFailed f "negative value cannot be converted to Natural"
+      FieldUHugeInt value -> pure (fromIntegral value)
+      FieldBigNum (BigNum big) ->
+        if big >= 0
+          then pure $ fromIntegral big
+          else returnError ConversionFailed f "negative value cannot be converted to Natural"
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads UTINYINT to UBIGINT, TINYINT to BIGINT, HUGEINT, and UHUGEINT. A
+-- negative value or a value out of range fails with 'ConversionFailed'. It does
+-- not read ENUM.
+instance FromField Word64 where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldInt i
+        | i >= 0 -> pure (fromIntegral i)
+        | otherwise ->
+            returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
+      FieldWord w -> pure w
+      FieldHugeInt value
+        | value >= 0 -> boundedFromInteger f value
+        | otherwise ->
+            returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
+      FieldUHugeInt value -> boundedFromInteger f value
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads UTINYINT to UBIGINT, TINYINT to BIGINT, HUGEINT, and UHUGEINT. A
+-- negative value or a value out of range fails with 'ConversionFailed'. It does
+-- not read ENUM.
+instance FromField Word32 where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldInt i
+        | i >= 0 -> boundedIntegral f i
+        | otherwise ->
+            returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
+      FieldWord w -> boundedFromInteger f (toInteger w)
+      FieldHugeInt value
+        | value >= 0 -> boundedFromInteger f value
+        | otherwise ->
+            returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
+      FieldUHugeInt value -> boundedFromInteger f value
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads UTINYINT to UBIGINT, TINYINT to BIGINT, HUGEINT, and UHUGEINT. A
+-- negative value or a value out of range fails with 'ConversionFailed'. It does
+-- not read ENUM.
+instance FromField Word16 where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldInt i
+        | i >= 0 -> boundedIntegral f i
+        | otherwise ->
+            returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
+      FieldWord w -> boundedFromInteger f (toInteger w)
+      FieldHugeInt value
+        | value >= 0 -> boundedFromInteger f value
+        | otherwise ->
+            returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
+      FieldUHugeInt value -> boundedFromInteger f value
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads UTINYINT to UBIGINT, TINYINT to BIGINT, HUGEINT, and UHUGEINT. A
+-- negative value or a value out of range fails with 'ConversionFailed'. It does
+-- not read ENUM.
+instance FromField Word8 where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldInt i
+        | i >= 0 -> boundedIntegral f i
+        | otherwise ->
+            returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
+      FieldWord w -> boundedFromInteger f (toInteger w)
+      FieldHugeInt value
+        | value >= 0 -> boundedFromInteger f value
+        | otherwise ->
+            returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
+      FieldUHugeInt value -> boundedFromInteger f value
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads UTINYINT to UBIGINT, TINYINT to BIGINT, HUGEINT, and UHUGEINT. A
+-- negative value or a value out of range fails with 'ConversionFailed'. It does
+-- not read ENUM.
+instance FromField Word where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldInt i
+        | i >= 0 -> boundedFromInteger f (fromIntegral i)
+        | otherwise ->
+            returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
+      FieldWord w -> boundedFromInteger f (toInteger w)
+      FieldHugeInt value
+        | value >= 0 -> boundedFromInteger f value
+        | otherwise ->
+            returnError ConversionFailed f "negative value cannot be converted to unsigned integer"
+      FieldUHugeInt value -> boundedFromInteger f value
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads DOUBLE, FLOAT, TINYINT to BIGINT, and DECIMAL. A BIGINT above 2^53
+-- rounds as the cast to DOUBLE. See Note [DECIMAL as DOUBLE and FLOAT].
+instance FromField Double where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldDouble d -> pure d
+      FieldFloat value -> pure (float2Double value)
+      FieldInt i -> pure (fromIntegral i)
+      FieldDecimal value -> pure (decimalToDouble value)
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads FLOAT, DOUBLE, TINYINT to BIGINT, and DECIMAL. A finite DOUBLE out of
+-- the range of FLOAT fails with 'ConversionFailed'. See
+-- Note [DECIMAL as DOUBLE and FLOAT].
+instance FromField Float where
+  fromField field@Field{fieldValue} =
+    case fieldValue of
+      -- DuckDB casts an integer to FLOAT with static_cast<float>, which
+      -- rounds one time to the nearest value, ties to even. int2Float rounds
+      -- in the same way. As seen in CI, the DuckDB 2.0.0 build for macOS on
+      -- Apple Silicon rounds some BIGINT values above 2^53 two times in its
+      -- cast to FLOAT, and the library gives the nearest value there.
+      FieldInt i -> pure (int2Float (fromIntegral i))
+      FieldDecimal value -> pure (decimalToFloat value)
+      _ -> do
+        d <- fromField field :: Conversion Double
+        if not (isInfinite d || isNaN d) && isInfinite (double2Float d)
+          then returnError ConversionFailed field "floating-point value out of bounds"
+          else pure (double2Float d)
+
+{- Note [DECIMAL as DOUBLE and FLOAT]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A DECIMAL that a Double or a Float reads gives the value of the cast of DuckDB
+2.0.0 to DOUBLE or FLOAT. The cast is TryCastDecimalToFloatingPoint in
+src/common/operator/cast_operators.cpp of DuckDB. decimalToDouble and
+decimalToFloat use the same three paths:
+
+1. Scale 0 and width 19 to 38. DuckDB stores the value as a HUGEINT and casts
+   it with CastBigintToFloating in src/common/types/hugeint.cpp:
+
+     case -1: result = -REAL_T(NumericLimits<uint64_t>::Maximum() - input.lower) - 1;
+     default: result = REAL_T(input.lower) + REAL_T(input.upper) * (REAL_T(NumericLimits<uint64_t>::Maximum()) + 1);
+
+   The case is the value of input.upper. A FLOAT result is this DOUBLE value
+   cast to float (Hugeint::TryCast for float). hugeIntToDouble copies the
+   formula. The formula rounds more than one time, so it does not always give
+   the nearest value. DuckDB casts -9007199254740994::DECIMAL(19,0) to
+   -9007199254740992.0, and 3356951675583485076575379654993209529::DECIMAL(38,0)
+   to 3.356951675583485e36. The nearest values are -9007199254740994.0 and
+   3.3569516755834854e36. This path exists only to give the value of the cast.
+2. Scale 0 with a width of at most 18, or an integer of at most 2^53 (2^24
+   for FLOAT) with a scale of at most 22 (10 for FLOAT). DuckDB converts the
+   integer to the floating-point type and divides it by the power of ten in
+   that type. Under the limits, the integer and the power of ten are exact in
+   the type, so only the division rounds. With scale 0, the division by 1 is
+   exact, so only the conversion of the integer rounds. Each step rounds one
+   time to the nearest value.
+3. Each other value. DuckDB converts the decimal digits with fast_float, which
+   gives the nearest value.
+
+Thus paths 2 and 3 give the nearest value, with ties to even. In path 2 the
+library does the same steps. With scale 0 and a width of at most 18, the
+integer is an Int64 value, and fromInteger converts it with int2Double or
+int2Float, which round one time as the C++ conversion of int64_t does. In path
+3 the library uses rationalToDouble or rationalToFloat. fromRational uses these
+functions too. They give the nearest value with ties to even, and they do not
+reduce the fraction first.
+
+Path 3 is slower than path 2. It applies to a Double with a scale above 0 when
+the unscaled integer is above 2^53 or the scale is above 22: at scale 2 for an
+absolute value above 9.0e13, and at scale 10 above 9.0e5. It applies to a Float
+with a scale above 0 when the unscaled integer is above 2^24 or the scale is
+above 10.
+-}
+
+-- | The value of the cast of DuckDB from a DECIMAL to DOUBLE.
+-- See Note [DECIMAL as DOUBLE and FLOAT].
+decimalToDouble :: DecimalValue -> Double
+decimalToDouble DecimalValue{decimalWidth, decimalScale, decimalInteger}
+  | decimalScale == 0 && decimalWidth > 18 = hugeIntToDouble decimalInteger
+  | decimalScale == 0 = fromInteger decimalInteger
+  | decimalScale <= 22 && abs decimalInteger <= 9007199254740992 = fromInteger decimalInteger / 10 ^ decimalScale
+  | otherwise = rationalToDouble decimalInteger (10 ^ decimalScale)
+
+-- | The value of the cast of DuckDB from a DECIMAL to FLOAT.
+-- See Note [DECIMAL as DOUBLE and FLOAT].
+decimalToFloat :: DecimalValue -> Float
+decimalToFloat DecimalValue{decimalWidth, decimalScale, decimalInteger}
+  | decimalScale == 0 && decimalWidth > 18 = double2Float (hugeIntToDouble decimalInteger)
+  | decimalScale == 0 = fromInteger decimalInteger
+  | decimalScale <= 10 && abs decimalInteger <= 16777216 = fromInteger decimalInteger / 10 ^ decimalScale
+  | otherwise = rationalToFloat decimalInteger (10 ^ decimalScale)
+
+-- | The cast of DuckDB from a HUGEINT to DOUBLE. It is not always the nearest
+-- value. See Note [DECIMAL as DOUBLE and FLOAT].
+hugeIntToDouble :: Integer -> Double
+hugeIntToDouble value
+  | upper == -1 = negate (word2Double (maxBound - lower)) - 1
+  | otherwise = word2Double lower + int2Double upper * 18446744073709551616
+  where
+    -- The two 64-bit halves of the HUGEINT in two's complement. word2Double
+    -- and int2Double round one time to the nearest value, ties to even, as
+    -- the C++ conversions of uint64_t and int64_t to double do. The C++
+    -- factor is 2^64 after its rounding, so the product is exact. The sum or
+    -- the difference rounds one time, as in C++.
+    upper = fromInteger (value `shiftR` 64) :: Int
+    lower = fromInteger value :: Word
+
+-- | Reads VARCHAR, TINYINT to BIGINT as decimal digits, BOOLEAN as @true@ or
+-- @false@, and the label of an ENUM value. It does not read FLOAT or DOUBLE. See
+-- Note [Reads of another SQL type].
+instance FromField Text where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldText t -> pure t
+      FieldInt i -> pure (Text.pack (show i))
+      FieldBool b -> pure (if b then Text.pack "true" else Text.pack "false")
+      FieldEnum _ label -> pure label
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads the SQL types that 'Text' reads.
+instance FromField String where
+  fromField field = Text.unpack <$> fromField field
+
+-- | Reads BLOB, the WKB bytes of a GEOMETRY, and the data bytes of a BIT, as the
+-- casts to BLOB give them. It does not read VARCHAR. See
+-- Note [Reads of another SQL type].
+instance FromField BS.ByteString where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldBlob bs -> pure bs
+      FieldGeometry RawGeometry{rawGeometryWKB} -> pure rawGeometryWKB
+      FieldBit (BitString _ bits) -> pure bits
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads BIT.
+instance FromField BitString where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldBit b -> pure b
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads BIGNUM.
+instance FromField BigNum where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldBigNum big -> pure big
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads LIST and ARRAY. Each element reads as @a@.
+instance {-# OVERLAPPABLE #-} (Typeable a, FromField a) => FromField [a] where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldList entries -> traverse fromField (elementFields f (zip [0 ..] entries))
+      FieldArray arr -> traverse fromField (elementFields f (assocs arr))
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Give the fields of the elements of a LIST or an ARRAY field, from the index
+-- and the value of each element. An element has the name @name[index]@ and the
+-- element type of the field.
+elementFields :: Field -> [(Int, FieldValue)] -> [Field]
+elementFields f = map element
+  where
+    element (idx, value) =
+      Field
+        { fieldName = fieldName f <> Text.pack "[" <> Text.pack (show idx) <> Text.pack "]"
+        , fieldIndex = fieldIndex f
+        , fieldValue = value
+        , fieldType = elementType
+        }
+    -- The elements share the parent type conversion.
+    elementType = listElementType <$> fieldType f
+
+-- | Reads ARRAY and LIST, as a list does. A size @n@ with no DuckDB ARRAY type
+-- or a value with another count raises 'Incompatible'. See Note [Sized arrays] in
+-- "Database.DuckDB.Simple.ToField".
+instance (KnownNat n, Typeable a, FromField a) => FromField (SizedArray n a) where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldList entries -> sized (zip [0 ..] entries)
+      FieldArray arr -> sized (assocs arr)
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+    where
+      size = natVal (Proxy @n)
+      sized elements
+        | Just reason <- arraySizeReason size = returnError Incompatible f reason
+        | toInteger count == size = SizedArray . listArray (0, count - 1) <$> traverse fromField (elementFields f elements)
+        | otherwise = returnError Incompatible f (Text.pack ("the value has " <> show count <> " elements"))
+        where
+          count = length elements
+
+-- | Reads MAP. Each key reads as @k@, and each value reads as @v@.
+-- Keys must remain distinct after conversion.
+instance (Ord k, Typeable k, Typeable v, FromField k, FromField v) => FromField (Map k v) where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldMap pairs -> do
+        result <- Map.fromList <$> traverse (uncurry parsePair) (zip [0 :: Int ..] pairs)
+        if Map.size result == length pairs
+          then pure result
+          else returnError ConversionFailed f "duplicate MAP key after conversion"
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+    where
+      parsePair idx (keyValue, valValue) = do
+        key <-
+          fromField
+            Field
+              { fieldName = fieldName f <> suffix idx ".key"
+              , fieldIndex = fieldIndex f
+              , fieldValue = keyValue
+              , fieldType = keyType
+              }
+        value <-
+          fromField
+            Field
+              { fieldName = fieldName f <> suffix idx ".value"
+              , fieldIndex = fieldIndex f
+              , fieldValue = valValue
+              , fieldType = valueType
+              }
+        pure (key, value)
+      entryTypes = mapEntryTypes <$> fieldType f
+      keyType = fst <$> entryTypes
+      valueType = snd <$> entryTypes
+      suffix idx label =
+        let idxText = Text.pack (show idx)
+        in  Text.pack "[" <> idxText <> Text.pack "]" <> Text.pack label
+
+-- | Reads DECIMAL.
+instance FromField DecimalValue where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldDecimal dec -> pure dec
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+{- Note [Temporal casts]
+~~~~~~~~~~~~~~~~~~~~~
+DuckDB converts TIMESTAMP_S, TIMESTAMP_MS, and TIMESTAMP_NS to microseconds
+before a cast to DATE. The S/MS conversion can overflow even when the date
+fits DATE. The NS conversion rounds to the nearest microsecond, with ties away
+from the epoch. Both Day readers use this intermediate. A DATE-to-timestamp
+cast checks midnight in the same microsecond range. Both LocalTime readers
+check this range for a DATE input. For a timestamp input, they keep the wider
+range and the nanoseconds. Unbounded readers also keep infinity.
+
+A TIMESTAMP_S or TIMESTAMP_MS cast to TIME checks the same microsecond range.
+The TimeOfDay reader checks this range for a timestamp input. It reads
+TIMESTAMP_NS at nanosecond precision, as a cast to TIME_NS.
+-}
+
+-- | Get the checked microsecond intermediate of a temporal cast.
+-- Round to the nearest microsecond, with ties away from the epoch. See
+-- Note [Temporal casts].
+localTimeMicros :: LocalTime -> Maybe Integer
+localTimeMicros LocalTime{localDay, localTimeOfDay} =
+  let epoch = fromGregorian 1970 1 1
+      picoseconds =
+        diffDays localDay epoch * 86400000000000000
+          + diffTimeToPicoseconds (timeOfDayToTime localTimeOfDay)
+      micros
+        | picoseconds < 0 = negate ((negate picoseconds + 500000) `div` 1000000)
+        | otherwise = (picoseconds + 500000) `div` 1000000
+  in  if micros < toInteger (minBound :: Int64) || micros > toInteger (maxBound :: Int64)
+        then Nothing
+        else Just micros
+
+-- | Convert a timestamp as the native cast to DATE does. See
+-- Note [Temporal casts].
+timestampDate :: LocalTimestamp -> Maybe Date
+timestampDate (Finite timestamp) = do
+  micros <- localTimeMicros timestamp
+  pure (Finite (addDays (micros `div` 86400000000) (fromGregorian 1970 1 1)))
+timestampDate NegInfinity = Just NegInfinity
+timestampDate PosInfinity = Just PosInfinity
+
+-- | Convert a date to midnight in the TIMESTAMP range. See
+-- Note [Temporal casts].
+dateTimestamp :: Date -> Maybe LocalTimestamp
+dateTimestamp (Finite day) =
+  let timestamp = LocalTime day (TimeOfDay 0 0 0)
+  in  Finite timestamp <$ localTimeMicros timestamp
+dateTimestamp NegInfinity = Just NegInfinity
+dateTimestamp PosInfinity = Just PosInfinity
+
+-- | Reads DATE, and the date of TIMESTAMP, TIMESTAMP_S, TIMESTAMP_MS, and
+-- TIMESTAMP_NS. Infinity and a timestamp outside the range of a DATE cast fail
+-- with 'ConversionFailed'. See Note [Temporal casts].
+instance FromField Day where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldDate day -> finiteField f day
+      FieldTimestamp timestamp -> case timestampDate timestamp of
+        Just day -> finiteField f day
+        Nothing -> returnError ConversionFailed f "timestamp is outside the range of a DATE cast"
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads the SQL types that 'Day' reads, also infinity. See
+-- Note [Temporal casts].
+instance FromField (Unbounded Day) where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldDate day -> pure day
+      FieldTimestamp timestamp -> case timestampDate timestamp of
+        Just day -> pure day
+        Nothing -> returnError ConversionFailed f "timestamp is outside the range of a DATE cast"
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads TIME, TIME_NS, and the time of TIMESTAMP, TIMESTAMP_S, TIMESTAMP_MS,
+-- and TIMESTAMP_NS. Infinity and a timestamp outside the range of a TIME cast
+-- fail with 'ConversionFailed'. See Note [Temporal casts].
+instance FromField TimeOfDay where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldTime tod -> pure tod
+      FieldTimestamp (Finite timestamp)
+        | Nothing <- localTimeMicros timestamp ->
+            returnError ConversionFailed f "timestamp is outside the range of a TIME cast"
+      FieldTimestamp timestamp -> finiteField f (localTimeOfDay <$> timestamp)
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads TIMETZ.
+instance FromField TimeWithZone where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldTimeTZ tz -> pure tz
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads TIMESTAMP, TIMESTAMP_S, TIMESTAMP_MS, TIMESTAMP_NS, and DATE at
+-- midnight. It does not read TIMESTAMPTZ. Infinity and a DATE outside the
+-- TIMESTAMP range fail with 'ConversionFailed'. See Note [Temporal casts]
+-- and Note [Reads of another SQL type].
+instance FromField LocalTime where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldTimestamp ts -> finiteField f ts
+      FieldDate day -> case dateTimestamp day of
+        Just timestamp -> finiteField f timestamp
+        Nothing -> returnError ConversionFailed f "date is outside the TIMESTAMP range"
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads the SQL types that t'LocalTime' reads, also infinity. See
+-- Note [Temporal casts].
+instance FromField (Unbounded LocalTime) where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldTimestamp ts -> pure ts
+      FieldDate day -> case dateTimestamp day of
+        Just timestamp -> pure timestamp
+        Nothing -> returnError ConversionFailed f "date is outside the TIMESTAMP range"
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads INTERVAL.
+instance FromField IntervalValue where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldInterval interval -> pure interval
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads TIMESTAMPTZ and TIMESTAMPTZ_NS. It does not read TIMESTAMP or DATE.
+-- Infinity fails with 'ConversionFailed'. See Note [Reads of another SQL type].
+instance FromField UTCTime where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldTimestampTZ utcTime -> finiteField f utcTime
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reads the SQL types that t'UTCTime' reads, also infinity.
+instance FromField (Unbounded UTCTime) where
+  fromField f@Field{fieldValue} =
+    case fieldValue of
+      FieldTimestampTZ utcTime -> pure utcTime
+      FieldNull -> returnError UnexpectedNull f ""
+      _ -> returnError Incompatible f ""
+
+-- | Reject infinity when the requested Haskell type holds only finite values.
+finiteField :: (Typeable a) => Field -> Unbounded a -> Conversion a
+finiteField _ (Finite value) = pure value
+finiteField field _ = returnError ConversionFailed field "infinity requires an Unbounded date or timestamp"
+
+-- | Reads NULL as Nothing, and each other value as @a@.
+instance (FromField a) => FromField (Maybe a) where
+  fromField Field{fieldValue = FieldNull} = pure Nothing
+  fromField field = Just <$> fromField field
+
+-- | Helper for bounded integral conversions.
+boundedIntegral :: forall a. (Integral a, Bounded a, Typeable a) => Field -> Int64 -> Conversion a
+boundedIntegral f = boundedFromInteger f . toInteger
+
+boundedFromInteger :: forall a. (Integral a, Bounded a, Typeable a) => Field -> Integer -> Conversion a
+boundedFromInteger f@Field{} value
+  | value < toInteger (minBound :: a) =
+      returnError ConversionFailed f "integer value out of bounds"
+  | value > toInteger (maxBound :: a) =
+      returnError ConversionFailed f "integer value out of bounds"
+  | otherwise = pure (fromInteger value)
+
+-- | Construct a conversion failure with field context when diagnostics are needed.
+-- See Note [Conversion effects] in "Database.DuckDB.Simple.Conversion".
+returnError :: forall b. (Typeable b) => (Text -> Text -> Text -> Text -> ResultError) -> Field -> Text -> Conversion b
+returnError mkError Field{fieldValue, fieldName, fieldType} msg =
+  conversionErrorWith $ do
+    logical <- fieldType
+    pure $
+      mkError
+        (fieldTypeName logical fieldValue)
+        fieldName
+        (Text.pack $ show (typeRep (Proxy @b)))
+        msg
+
+-- | The SQL type name of a field in an error: the text of its type, or the type
+-- of the stored value when the type is VARIANT. See
+-- Note [Reads of another SQL type].
+fieldTypeName :: LogicalTypeRep -> FieldValue -> Text
+fieldTypeName logical value = case aliasBase logical of
+  LogicalTypeScalar LogicalTypeIdVariant -> fieldValueTypeName value
+  _ -> logicalTypeSQL logical
+
+-- | The SQL type name of a decoded value, in the type text of DuckDB
+-- (logicalTypeSQL), for example TIMESTAMP WITH TIME ZONE or DECIMAL(18,3). A
+-- value that does not hold its full type (a LIST, an ARRAY, a MAP, an ENUM, a
+-- STRUCT, a TUPLE, or a UNION) gives the name of its kind. See
+-- Note [Reads of another SQL type].
+fieldValueTypeName :: FieldValue -> Text
+fieldValueTypeName = \case
+  FieldNull -> scalar LogicalTypeIdSQLNull
+  FieldInt8{} -> scalar LogicalTypeIdTinyInt
+  FieldInt16{} -> scalar LogicalTypeIdSmallInt
+  FieldInt32{} -> scalar LogicalTypeIdInteger
+  FieldInt64{} -> scalar LogicalTypeIdBigInt
+  FieldWord8{} -> scalar LogicalTypeIdUTinyInt
+  FieldWord16{} -> scalar LogicalTypeIdUSmallInt
+  FieldWord32{} -> scalar LogicalTypeIdUInteger
+  FieldWord64{} -> scalar LogicalTypeIdUBigInt
+  FieldFloat{} -> scalar LogicalTypeIdFloat
+  FieldDouble{} -> scalar LogicalTypeIdDouble
+  FieldText{} -> scalar LogicalTypeIdVarchar
+  FieldBool{} -> scalar LogicalTypeIdBoolean
+  FieldBlob{} -> scalar LogicalTypeIdBlob
+  FieldGeometry RawGeometry{rawGeometryCRS} -> logicalTypeSQL (LogicalTypeGeometry rawGeometryCRS)
+  FieldDate{} -> scalar LogicalTypeIdDate
+  FieldTime{} -> scalar LogicalTypeIdTime
+  FieldTimestamp{} -> scalar LogicalTypeIdTimestamp
+  FieldInterval{} -> scalar LogicalTypeIdInterval
+  FieldHugeInt{} -> scalar LogicalTypeIdHugeInt
+  FieldUHugeInt{} -> scalar LogicalTypeIdUHugeInt
+  FieldDecimal DecimalValue{decimalWidth, decimalScale} -> logicalTypeSQL (LogicalTypeDecimal decimalWidth decimalScale)
+  FieldTimestampTZ{} -> scalar LogicalTypeIdTimestampTz
+  FieldTimeTZ{} -> scalar LogicalTypeIdTimeTz
+  FieldBit{} -> scalar LogicalTypeIdBit
+  FieldBigNum{} -> scalar LogicalTypeIdBigNum
+  FieldEnum{} -> "ENUM"
+  FieldArray{} -> "ARRAY"
+  FieldList{} -> "LIST"
+  FieldMap{} -> "MAP"
+  FieldUUID{} -> scalar LogicalTypeIdUUID
+  FieldStruct{} -> "STRUCT"
+  FieldTuple{} -> "TUPLE"
+  FieldUnion{} -> "UNION"
+  where
+    scalar = logicalTypeSQL . LogicalTypeScalar
diff --git a/src/Database/DuckDB/Simple/FromRow.hs b/src/Database/DuckDB/Simple/FromRow.hs
--- a/src/Database/DuckDB/Simple/FromRow.hs
+++ b/src/Database/DuckDB/Simple/FromRow.hs
@@ -3,278 +3,251 @@
 {-# LANGUAGE DerivingStrategies #-}
 {-# LANGUAGE FlexibleContexts #-}
 {-# LANGUAGE GeneralizedNewtypeDeriving #-}
-{-# LANGUAGE LambdaCase #-}
 {-# LANGUAGE NamedFieldPuns #-}
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE TypeOperators #-}
 
-{- |
-Module      : Database.DuckDB.Simple.FromRow
-Description : Convert rows of @Field@s into Haskell values using a parser-style interface.
--}
+-- |
+-- Module      : Database.DuckDB.Simple.FromRow
+-- Description : Parse rows of @Field@s as Haskell values.
 module Database.DuckDB.Simple.FromRow (
-    -- * Row parsing
-    RowParser (..),
-    field,
-    fieldWith,
-    numFieldsRemaining,
-    parseRow,
+  -- * Row parsing
+  RowParser (..),
+  field,
+  fieldWith,
+  numFieldsRemaining,
+  parseRow,
 
-    -- * Generic derivation
-    GFromRow (..),
-    FromRow (..),
+  -- * Generic derivation
+  GFromRow (..),
+  FromRow (..),
 
-    -- * Error conversion
-    resultErrorToSqlError,
-    rowErrorsToSqlError,
+  -- * Error conversion
+  resultErrorToSqlError,
+  rowErrorsToSqlError,
 ) where
 
 import Control.Applicative (Alternative (..))
-import Control.Exception (Exception, SomeException (SomeException), fromException, toException)
+import Control.Exception (Exception (..), SomeException, fromException)
 import Control.Monad (MonadPlus, replicateM)
 import Control.Monad.Trans.Class (lift)
 import Control.Monad.Trans.Reader (ReaderT, ask, runReaderT)
 import Control.Monad.Trans.State.Strict (StateT, get, put, runStateT)
 import Data.Maybe (listToMaybe, mapMaybe)
-import Data.Text (Text)
 import qualified Data.Text as Text
-import GHC.Generics
-
+import Database.DuckDB.Simple.Conversion (Conversion, conversionError)
 import Database.DuckDB.Simple.FromField
 import Database.DuckDB.Simple.Internal (SQLError (..))
-import Database.DuckDB.Simple.Ok (Ok (..))
 import Database.DuckDB.Simple.Types (Only (..), Query, (:.) (..))
+import GHC.Generics
 
 -- | Row parsing environment (read-only data available to the parser).
 newtype RowParseRO = RowParseRO
-    { rowParseColumnCount :: Int
-    }
+  { rowParseColumnCount :: Int
+  }
 
 -- | Column-out-of-bounds sentinel used internally to map parser failures.
 newtype ColumnOutOfBounds = ColumnOutOfBounds {columnOutOfBoundsIndex :: Int}
-    deriving stock (Eq, Show)
+  deriving stock (Eq, Show)
 
 instance Exception ColumnOutOfBounds
 
 -- | Parser used by @FromRow@ implementations.
 newtype RowParser a = RowParser
-    { runRowParser :: ReaderT RowParseRO (StateT (Int, [Field]) Ok) a
-    }
-    deriving stock (Functor)
-    deriving newtype (Applicative, Alternative, Monad, MonadPlus)
+  { runRowParser :: ReaderT RowParseRO (StateT (Int, [Field]) Conversion) a
+  }
+  deriving stock (Functor)
+  deriving newtype (Applicative, Alternative, Monad, MonadPlus)
 
 -- | Generic derivation helper mirroring @sqlite-simple@.
 class GFromRow f where
-    gFromRow :: RowParser (f p)
+  gFromRow :: RowParser (f p)
 
 instance GFromRow U1 where
-    gFromRow = pure U1
+  gFromRow = pure U1
 
 instance (GFromRow a) => GFromRow (M1 i c a) where
-    gFromRow = M1 <$> gFromRow
+  gFromRow = M1 <$> gFromRow
 
 instance (FromField a) => GFromRow (K1 i a) where
-    gFromRow = K1 <$> field
+  gFromRow = K1 <$> field
 
 instance (GFromRow a, GFromRow b) => GFromRow (a :*: b) where
-    gFromRow = (:*:) <$> gFromRow <*> gFromRow
+  gFromRow = (:*:) <$> gFromRow <*> gFromRow
 
 -- | Types that can be constructed from database rows.
 class FromRow a where
-    fromRow :: RowParser a
-    default fromRow :: (Generic a, GFromRow (Rep a)) => RowParser a
-    fromRow = to <$> gFromRow
+  fromRow :: RowParser a
+  default fromRow :: (Generic a, GFromRow (Rep a)) => RowParser a
+  fromRow = to <$> gFromRow
 
--- | Pull the next field using the provided @FieldParser@.
+-- | Read the next field with the supplied @FieldParser@.
 fieldWith :: FieldParser a -> RowParser a
+{-# INLINE fieldWith #-}
 fieldWith fieldParser = RowParser $ do
-    RowParseRO{rowParseColumnCount} <- ask
-    (columnIndex, remaining) <- lift get
-    case remaining of
-        [] -> do
-            lift (put (columnIndex + 1, []))
-            lift (lift (Errors [toException (ColumnOutOfBounds (columnIndex + 1))]))
-        (f : rest) -> do
-            lift (put (columnIndex + 1, rest))
-            if columnIndex >= rowParseColumnCount
-                then lift (lift (Errors [toException (ColumnOutOfBounds (columnIndex + 1))]))
-                else case fieldParser f of
-                    Errors err -> lift $ lift $ Errors err
-                    Ok value -> pure value
+  RowParseRO{rowParseColumnCount} <- ask
+  (columnIndex, remaining) <- lift get
+  case remaining of
+    [] -> do
+      lift (put (columnIndex + 1, []))
+      lift (lift (conversionError (ColumnOutOfBounds (columnIndex + 1))))
+    (f : rest) -> do
+      lift (put (columnIndex + 1, rest))
+      if columnIndex >= rowParseColumnCount
+        then lift (lift (conversionError (ColumnOutOfBounds (columnIndex + 1))))
+        else lift (lift (fieldParser f))
 
--- | Pull the next field and parse it using its @FromField@ instance.
+-- | Read the next field with its @FromField@ instance.
 field :: (FromField a) => RowParser a
+{-# INLINE field #-}
 field = fieldWith fromField
 
 -- | Report how many columns remain unread in the current row.
 numFieldsRemaining :: RowParser Int
 numFieldsRemaining = RowParser $ do
-    RowParseRO{rowParseColumnCount} <- ask
-    (columnIndex, _) <- lift get
-    pure (rowParseColumnCount - columnIndex)
+  RowParseRO{rowParseColumnCount} <- ask
+  (columnIndex, _) <- lift get
+  pure (rowParseColumnCount - columnIndex)
 
 -- | Execute a @RowParser@ against the provided row.
-parseRow :: RowParser a -> [Field] -> Ok a
+parseRow :: RowParser a -> [Field] -> Conversion a
+{-# INLINE parseRow #-}
 parseRow parser fields =
-    let context = RowParseRO (length fields)
-        initialState = (0, fields)
-     in case runStateT (runReaderT (runRowParser parser) context) initialState of
-            Ok (value, (columnCount, _))
-                | columnCount == length fields -> Ok value
-                | otherwise -> Errors [SomeException $ ColumnOutOfBounds (columnCount + 1)]
-            Errors errs -> Errors errs
+  let context = RowParseRO (length fields)
+      initialState = (0, fields)
+  in  do
+        (value, (columnCount, _)) <- runStateT (runReaderT (runRowParser parser) context) initialState
+        if columnCount == length fields
+          then pure value
+          else conversionError (ColumnOutOfBounds (columnCount + 1))
 
 instance FromRow () where
-    fromRow = pure ()
+  fromRow = pure ()
 
 instance (FromField a) => FromRow (Only a) where
-    fromRow = Only <$> field
+  fromRow = Only <$> field
 
 instance (FromRow a, FromRow b) => FromRow (a :. b) where
-    fromRow = (:.) <$> fromRow <*> fromRow
+  fromRow = (:.) <$> fromRow <*> fromRow
 
 instance (FromField a, FromField b) => FromRow (a, b) where
-    fromRow = (,) <$> field <*> field
+  fromRow = (,) <$> field <*> field
 
 instance (FromField a, FromField b, FromField c) => FromRow (a, b, c) where
-    fromRow = (,,) <$> field <*> field <*> field
+  fromRow = (,,) <$> field <*> field <*> field
 
 instance (FromField a, FromField b, FromField c, FromField d) => FromRow (a, b, c, d) where
-    fromRow = (,,,) <$> field <*> field <*> field <*> field
+  fromRow = (,,,) <$> field <*> field <*> field <*> field
 
 instance (FromField a, FromField b, FromField c, FromField d, FromField e) => FromRow (a, b, c, d, e) where
-    fromRow = (,,,,) <$> field <*> field <*> field <*> field <*> field
+  fromRow = (,,,,) <$> field <*> field <*> field <*> field <*> field
 
 instance (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f) => FromRow (a, b, c, d, e, f) where
-    fromRow = (,,,,,) <$> field <*> field <*> field <*> field <*> field <*> field
+  fromRow = (,,,,,) <$> field <*> field <*> field <*> field <*> field <*> field
 
 instance
-    (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g) =>
-    FromRow (a, b, c, d, e, f, g)
-    where
-    fromRow = (,,,,,,) <$> field <*> field <*> field <*> field <*> field <*> field <*> field
+  (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g)
+  => FromRow (a, b, c, d, e, f, g)
+  where
+  fromRow = (,,,,,,) <$> field <*> field <*> field <*> field <*> field <*> field <*> field
 
 instance
-    (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g, FromField h) =>
-    FromRow (a, b, c, d, e, f, g, h)
-    where
-    fromRow = (,,,,,,,) <$> field <*> field <*> field <*> field <*> field <*> field <*> field <*> field
+  (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g, FromField h)
+  => FromRow (a, b, c, d, e, f, g, h)
+  where
+  fromRow = (,,,,,,,) <$> field <*> field <*> field <*> field <*> field <*> field <*> field <*> field
 
 instance
-    ( FromField a
-    , FromField b
-    , FromField c
-    , FromField d
-    , FromField e
-    , FromField f
-    , FromField g
-    , FromField h
-    , FromField i
-    ) =>
-    FromRow (a, b, c, d, e, f, g, h, i)
-    where
-    fromRow =
-        (,,,,,,,,)
-            <$> field
-            <*> field
-            <*> field
-            <*> field
-            <*> field
-            <*> field
-            <*> field
-            <*> field
-            <*> field
+  ( FromField a
+  , FromField b
+  , FromField c
+  , FromField d
+  , FromField e
+  , FromField f
+  , FromField g
+  , FromField h
+  , FromField i
+  )
+  => FromRow (a, b, c, d, e, f, g, h, i)
+  where
+  fromRow =
+    (,,,,,,,,)
+      <$> field
+      <*> field
+      <*> field
+      <*> field
+      <*> field
+      <*> field
+      <*> field
+      <*> field
+      <*> field
 
 instance
-    ( FromField a
-    , FromField b
-    , FromField c
-    , FromField d
-    , FromField e
-    , FromField f
-    , FromField g
-    , FromField h
-    , FromField i
-    , FromField j
-    ) =>
-    FromRow (a, b, c, d, e, f, g, h, i, j)
-    where
-    fromRow =
-        (,,,,,,,,,)
-            <$> field
-            <*> field
-            <*> field
-            <*> field
-            <*> field
-            <*> field
-            <*> field
-            <*> field
-            <*> field
-            <*> field
+  ( FromField a
+  , FromField b
+  , FromField c
+  , FromField d
+  , FromField e
+  , FromField f
+  , FromField g
+  , FromField h
+  , FromField i
+  , FromField j
+  )
+  => FromRow (a, b, c, d, e, f, g, h, i, j)
+  where
+  fromRow =
+    (,,,,,,,,,)
+      <$> field
+      <*> field
+      <*> field
+      <*> field
+      <*> field
+      <*> field
+      <*> field
+      <*> field
+      <*> field
+      <*> field
 
 instance (FromField a) => FromRow [a] where
-    fromRow = do
-        remaining <- numFieldsRemaining
-        replicateM remaining field
+  fromRow = do
+    remaining <- numFieldsRemaining
+    replicateM remaining field
 
 -- | Convert a @ResultError@ into a user-facing @SQLError@.
 resultErrorToSqlError :: Query -> ResultError -> SQLError
 resultErrorToSqlError query err =
-    SQLError
-        { sqlErrorMessage = renderError err
-        , sqlErrorType = Nothing
-        , sqlErrorQuery = Just query
-        }
+  SQLError
+    { sqlErrorMessage = Text.pack (displayException err)
+    , sqlErrorType = Nothing
+    , sqlErrorQuery = Just query
+    , sqlErrorBody = Nothing
+    }
 
--- | Collapse parser failure diagnostics into an @SQLError@ while preserving the query.
+-- | Convert parser errors to an @SQLError@ that retains the query.
 rowErrorsToSqlError :: Query -> [SomeException] -> SQLError
 rowErrorsToSqlError query errs =
-    case listToMaybe (mapMaybe (fromException :: SomeException -> Maybe ResultError) errs) of
-        Just resultErr -> resultErrorToSqlError query resultErr
+  case listToMaybe (mapMaybe (fromException :: SomeException -> Maybe ResultError) errs) of
+    Just resultErr -> resultErrorToSqlError query resultErr
+    Nothing ->
+      case listToMaybe (mapMaybe (fromException :: SomeException -> Maybe ColumnOutOfBounds) errs) of
+        Just (ColumnOutOfBounds idx) ->
+          SQLError
+            { sqlErrorMessage =
+                Text.concat
+                  [ "duckdb-simple: column index "
+                  , Text.pack (show idx)
+                  , " out of bounds"
+                  ]
+            , sqlErrorType = Nothing
+            , sqlErrorQuery = Just query
+            , sqlErrorBody = Nothing
+            }
         Nothing ->
-            case listToMaybe (mapMaybe (fromException :: SomeException -> Maybe ColumnOutOfBounds) errs) of
-                Just (ColumnOutOfBounds idx) ->
-                    SQLError
-                        { sqlErrorMessage =
-                            Text.concat
-                                [ "duckdb-simple: column index "
-                                , Text.pack (show idx)
-                                , " out of bounds"
-                                ]
-                        , sqlErrorType = Nothing
-                        , sqlErrorQuery = Just query
-                        }
-                Nothing ->
-                    SQLError
-                        { sqlErrorMessage =
-                            Text.pack $ "duckdb-simple: row-parsing failed:" <> show errs
-                        , sqlErrorType = Nothing
-                        , sqlErrorQuery = Just query
-                        }
-
-renderError :: ResultError -> Text
-renderError = \case
-    Incompatible{errSQLType, errSQLField, errHaskellType, errMessage} ->
-        Text.concat
-            [ "duckdb-simple: column "
-            , errSQLField
-            , " has type "
-            , errSQLType
-            , " but expected "
-            , errHaskellType
-            , if Text.null errMessage
-                then ""
-                else ": " <> errMessage
-            ]
-    UnexpectedNull{errHaskellType, errSQLField, errMessage} ->
-        Text.concat
-            [ "duckdb-simple: column "
-            , errSQLField
-            , " is NULL but expected "
-            , errHaskellType
-            , if Text.null errMessage
-                then ""
-                else ": " <> errMessage
-            ]
-    ConversionFailed{errMessage} ->
-        errMessage
+          SQLError
+            { sqlErrorMessage =
+                Text.pack $ "duckdb-simple: row-parsing failed:" <> show errs
+            , sqlErrorType = Nothing
+            , sqlErrorQuery = Just query
+            , sqlErrorBody = Nothing
+            }
diff --git a/src/Database/DuckDB/Simple/Function.hs b/src/Database/DuckDB/Simple/Function.hs
--- a/src/Database/DuckDB/Simple/Function.hs
+++ b/src/Database/DuckDB/Simple/Function.hs
@@ -1,456 +1,246 @@
 {-# LANGUAGE BlockArguments #-}
-{-# LANGUAGE FlexibleInstances #-}
-{-# LANGUAGE LambdaCase #-}
-{-# LANGUAGE NamedFieldPuns #-}
 {-# LANGUAGE OverloadedStrings #-}
-{-# LANGUAGE RankNTypes #-}
 {-# LANGUAGE ScopedTypeVariables #-}
-{-# LANGUAGE UndecidableInstances #-}
 
-{- |
-Module      : Database.DuckDB.Simple.Function
-Description : Register scalar Haskell functions with DuckDB connections.
-
-This module mirrors the high-level API provided by @sqlite-simple@ for user
-defined functions, adapted to DuckDB's chunked execution model.  It allows
-pure and 'IO'-based Haskell functions to be exposed to SQL while reusing the
-existing field-decoding and result-marshalling machinery for arguments and
-return values.
--}
+-- |
+-- Module      : Database.DuckDB.Simple.Function
+-- Description : Register Haskell scalar functions, table functions, and aggregate functions with DuckDB connections.
+--
+-- Register pure and IO scalar functions with the managed argument and result
+-- conversions. Register table functions and aggregate functions that convert
+-- their arguments with 'FromRow'.
+--
+-- A program that registers a callback must be linked with @-threaded@. DuckDB
+-- can call a callback from several of its threads at the same time, and the
+-- runtime of GHC without @-threaded@ does not support that: the program can
+-- crash. Without @-threaded@, the registration of a function in this module
+-- raises an t'Database.DuckDB.Simple.SQLError' of
+-- the type 'Database.DuckDB.Simple.ErrorInputInvalid' when the setting
+-- @threads@ is above 1. The section \"User-Defined Functions\" of the README
+-- gives the rule.
+--
+-- A callback must not run a statement on the connection that runs the callback.
+-- Use another connection of the same instance. This rule applies to each
+-- registered callback, for example of a scalar function, a cast, an aggregate
+-- function, a table function, a COPY format, a replacement scan, a pragma, or a
+-- log sink. The library holds the lock of a connection while it prepares a
+-- statement, while 'Database.DuckDB.Simple.query',
+-- 'Database.DuckDB.Simple.execute', or a default fold runs a statement, and
+-- while it fetches a chunk of an explicit stream. DuckDB can run a callback in
+-- each of these steps. The lock is not reentrant. Thus a statement in the
+-- callback waits for the lock. With more than one DuckDB thread, DuckDB can also
+-- run a callback of an explicit stream between two fetches, while no fetch holds
+-- the lock. Then a statement in the callback on the same connection fails at
+-- once with the error of DuckDB for a connection with an open result.
+--
+-- The wait has the bound 'Database.DuckDB.Simple.connectionCallbackLockWait' of
+-- the connection: 10 seconds by default, and no bound for 'Nothing'. After the
+-- bound, the statement raises an t'Database.DuckDB.Simple.SQLError' of the type
+-- 'Database.DuckDB.Simple.ErrorResourceInUse'. For most callbacks, the outer
+-- statement then fails. DuckDB ignores the error of a log sink. The bound
+-- applies to each wait of a callback for a connection lock, also for a second
+-- connection that another statement uses. The bound does not apply to
+-- a callback that DuckDB runs while the library holds no lock of the
+-- connection, for example a log sink for a message of
+-- 'Database.DuckDB.Simple.Logging.logConnectionMessage'. It also does not apply
+-- to a statement in a thread that the callback starts, to a statement inside
+-- 'Control.Exception.uninterruptibleMask', and to a statement in the flush
+-- function of a log sink when DuckDB destroys the sink.
+--
+-- A callback that refers to a connection keeps that connection and its instance
+-- reachable while DuckDB keeps the callback, possibly until the database closes.
+-- Thus the garbage collector does not close them, and the program must close
+-- them.
 module Database.DuckDB.Simple.Function (
-    ScalarType,
-    ScalarValue,
-    FunctionArg (),
-    FunctionResult (),
-    Function (..),
-    createFunction,
-    createFunctionWithState,
-    deleteFunction,
+  ScalarValue,
+  FunctionResult (),
+  Function (..),
+  LogicalTypeId (..),
+  createFunction,
+  createFunctionWithState,
+  deleteFunction,
+  TypeDeclaration (..),
+  TypedRow,
+  createTableFunction,
+  Aggregate (..),
+  createAggregate,
 ) where
 
-import Control.Exception (
-    SomeException,
-    bracket,
-    throwIO,
-    try,
- )
-import Control.Monad (forM, forM_, when)
-import Data.Int (Int16, Int32, Int64)
-import Data.Proxy (Proxy (..))
+import Control.Exception (bracket)
+import Control.Monad (forM)
 import Data.Text (Text)
 import qualified Data.Text as Text
-import qualified Data.Text.Foreign as TextForeign
-import Data.Word (Word16, Word32, Word64, Word8)
-import Database.DuckDB.FFI
-import Database.DuckDB.Simple.Callback (runCallback, transferCallbackState, withCallbackResources)
-import Database.DuckDB.Simple.FromField (
-    Field (..),
-    FromField (..),
+import Database.DuckDB.Simple.Callback (RegistrationTarget (ConnectionTarget))
+import Database.DuckDB.Simple.FromRow (FromRow)
+import Database.DuckDB.Simple.Function.Internal (
+  Function (..),
+  FunctionResult,
+  ScalarValue,
+  createFunctionOn,
+  createFunctionWithStateOn,
  )
 import Database.DuckDB.Simple.Internal (
-    Connection,
-    Query (..),
-    SQLError (..),
-    destroyLogicalType,
-    withConnectionHandle,
-    withQueryCString,
-    withResult,
+  Connection,
+  executeParsedStatement,
+  withParsedStatements,
  )
-import Database.DuckDB.Simple.Materialize (prepareVectorReader)
-import Database.DuckDB.Simple.Ok (Ok (..))
-import Foreign.Marshal.Alloc (alloca)
-import Foreign.Ptr (FunPtr, Ptr, castPtr, nullPtr)
-import Foreign.StablePtr (StablePtr, castPtrToStablePtr, deRefStablePtr)
-import Foreign.Storable (poke, pokeElemOff)
-import GHC.Float (float2Double)
-
-data ScalarFunctionResources = ScalarFunctionResources
-    { scalarFunctionExecPtr :: !DuckDBScalarFunctionFun
-    , scalarFunctionInitPtr :: !(Maybe DuckDBScalarFunctionInitFun)
-    }
-
--- | Tag DuckDB logical types we support for scalar return values.
-data ScalarType
-    = ScalarTypeBoolean
-    | ScalarTypeBigInt
-    | ScalarTypeUBigInt
-    | ScalarTypeDouble
-    | ScalarTypeVarchar
-
--- | Runtime representation of values returned to DuckDB.
-data ScalarValue
-    = ScalarNull
-    | ScalarBoolean !Bool
-    | ScalarInteger !Int64
-    | ScalarUnsigned !Word64
-    | ScalarDouble !Double
-    | ScalarText !Text
-
--- | Class of scalar results that can be produced by user-defined functions.
-class FunctionResult a where
-    scalarReturnType :: Proxy a -> ScalarType
-    toScalarValue :: a -> IO ScalarValue
-
-instance FunctionResult Int where
-    scalarReturnType _ = ScalarTypeBigInt
-    toScalarValue value = pure (ScalarInteger (fromIntegral value))
-
-instance FunctionResult Int16 where
-    scalarReturnType _ = ScalarTypeBigInt
-    toScalarValue value = pure (ScalarInteger (fromIntegral value))
-
-instance FunctionResult Int32 where
-    scalarReturnType _ = ScalarTypeBigInt
-    toScalarValue value = pure (ScalarInteger (fromIntegral value))
-
-instance FunctionResult Int64 where
-    scalarReturnType _ = ScalarTypeBigInt
-    toScalarValue value = pure (ScalarInteger value)
-
-instance FunctionResult Word where
-    scalarReturnType _ = ScalarTypeUBigInt
-    toScalarValue value = pure (ScalarUnsigned (fromIntegral value))
-
-instance FunctionResult Word16 where
-    scalarReturnType _ = ScalarTypeBigInt
-    toScalarValue value = pure (ScalarInteger (fromIntegral value))
-
-instance FunctionResult Word32 where
-    scalarReturnType _ = ScalarTypeBigInt
-    toScalarValue value = pure (ScalarInteger (fromIntegral value))
-
-instance FunctionResult Word64 where
-    scalarReturnType _ = ScalarTypeUBigInt
-    toScalarValue value = pure (ScalarUnsigned (fromIntegral value))
-
-instance FunctionResult Double where
-    scalarReturnType _ = ScalarTypeDouble
-    toScalarValue value = pure (ScalarDouble value)
-
-instance FunctionResult Float where
-    scalarReturnType _ = ScalarTypeDouble
-    toScalarValue value = pure (ScalarDouble (float2Double value))
-
-instance FunctionResult Bool where
-    scalarReturnType _ = ScalarTypeBoolean
-    toScalarValue value = pure (ScalarBoolean value)
-
-instance FunctionResult Text where
-    scalarReturnType _ = ScalarTypeVarchar
-    toScalarValue value = pure (ScalarText value)
-
-instance FunctionResult String where
-    scalarReturnType _ = ScalarTypeVarchar
-    toScalarValue value = pure (ScalarText (Text.pack value))
-
-instance (FunctionResult a) => FunctionResult (Maybe a) where
-    scalarReturnType _ = scalarReturnType (Proxy :: Proxy a)
-    toScalarValue Nothing = pure ScalarNull
-    toScalarValue (Just value) = toScalarValue value
-
--- | Argument types supported by the scalar function machinery.
-class FunctionArg a where
-    argumentType :: Proxy a -> DuckDBType
-
-instance FunctionArg Int where
-    argumentType _ = DuckDBTypeBigInt
-
-instance FunctionArg Int16 where
-    argumentType _ = DuckDBTypeSmallInt
-
-instance FunctionArg Int32 where
-    argumentType _ = DuckDBTypeInteger
-
-instance FunctionArg Int64 where
-    argumentType _ = DuckDBTypeBigInt
-
-instance FunctionArg Word where
-    argumentType _ = DuckDBTypeUBigInt
-
-instance FunctionArg Word16 where
-    argumentType _ = DuckDBTypeUSmallInt
-
-instance FunctionArg Word32 where
-    argumentType _ = DuckDBTypeUInteger
-
-instance FunctionArg Word64 where
-    argumentType _ = DuckDBTypeUBigInt
-
-instance FunctionArg Double where
-    argumentType _ = DuckDBTypeDouble
-
-instance FunctionArg Float where
-    argumentType _ = DuckDBTypeFloat
-
-instance FunctionArg Bool where
-    argumentType _ = DuckDBTypeBoolean
-
-instance FunctionArg Text where
-    argumentType _ = DuckDBTypeVarchar
-
-instance FunctionArg String where
-    argumentType _ = DuckDBTypeVarchar
-
-instance (FunctionArg a) => FunctionArg (Maybe a) where
-    argumentType _ = argumentType (Proxy :: Proxy a)
-
--- | Typeclass describing Haskell functions that can be exposed to DuckDB.
-class Function a where
-    argumentTypes :: Proxy a -> [DuckDBType]
-    returnType :: Proxy a -> ScalarType
-    isVolatile :: Proxy a -> Bool
-    applyFunction :: [Field] -> a -> IO ScalarValue
-
-instance {-# OVERLAPPABLE #-} (FunctionResult a) => Function a where
-    argumentTypes _ = []
-    returnType _ = scalarReturnType (Proxy :: Proxy a)
-    isVolatile _ = False
-    applyFunction [] value = toScalarValue value
-    applyFunction _ _ = throwIO (functionInvocationError (Text.pack "unexpected arguments supplied"))
-
-instance {-# OVERLAPPING #-} (FunctionResult a) => Function (IO a) where
-    argumentTypes _ = []
-    returnType _ = scalarReturnType (Proxy :: Proxy a)
-    isVolatile _ = True
-    applyFunction [] action = action >>= toScalarValue
-    applyFunction _ _ = throwIO (functionInvocationError (Text.pack "unexpected arguments supplied"))
-
-instance {-# OVERLAPPABLE #-} (FromField a, FunctionArg a, Function r) => Function (a -> r) where
-    argumentTypes _ = argumentType (Proxy :: Proxy a) : argumentTypes (Proxy :: Proxy r)
-    returnType _ = returnType (Proxy :: Proxy r)
-    isVolatile _ = isVolatile (Proxy :: Proxy r)
-    applyFunction [] _ =
-        throwIO (functionInvocationError (Text.pack "insufficient arguments supplied"))
-    applyFunction (field : rest) fn =
-        case fromField field of
-            Errors err -> throwIO (argumentConversionError (fieldIndex field) err)
-            Ok value -> applyFunction rest (fn value)
+import Database.DuckDB.Simple.Native
+import Database.DuckDB.Simple.Typed (TypedRow)
+import Database.DuckDB.Simple.Typed.Aggregate (Aggregate (..), createAggregateOn)
+import Database.DuckDB.Simple.Typed.Table (createTableFunctionOn)
+import Database.DuckDB.Simple.V2.Registration (TypeDeclaration (..))
 
 -- | Register a Haskell function under the supplied name.
-createFunction :: forall f. (Function f) => Connection -> Text -> f -> IO ()
-createFunction conn name fn =
-    registerScalarFunction conn name (Proxy :: Proxy f) \allocate -> do
-        scalarFunctionExecPtr <- allocate (mkScalarFun (scalarFunctionHandler fn))
-        pure ScalarFunctionResources{scalarFunctionExecPtr, scalarFunctionInitPtr = Nothing}
-
--- | Register a scalar function with per-worker thread-local state.
-createFunctionWithState :: forall s f. (Function f) => Connection -> Text -> IO s -> (s -> f) -> IO ()
-createFunctionWithState conn name initState mkFn =
-    registerScalarFunction conn name (Proxy :: Proxy f) \allocate -> do
-        scalarFunctionExecPtr <- allocate (mkScalarFun (scalarFunctionHandlerWithState mkFn))
-        initPtr <- allocate (mkScalarInitFun (scalarFunctionInitHandler initState))
-        pure ScalarFunctionResources{scalarFunctionExecPtr, scalarFunctionInitPtr = Just initPtr}
-
--- | Configure a scalar function and transfer its callbacks to DuckDB.
-registerScalarFunction :: (Function f) => Connection -> Text -> Proxy f -> ((forall a. IO (FunPtr a) -> IO (FunPtr a)) -> IO ScalarFunctionResources) -> IO ()
-registerScalarFunction conn name proxy acquire = do
-    when (Text.null name || Text.any (== '\0') name) $
-        throwIO (functionInvocationError "duckdb-simple: invalid scalar function name")
-    bracket c_duckdb_create_scalar_function cleanupScalarFunction \scalarFun -> do
-        when (scalarFun == nullPtr) $
-            throwIO (functionInvocationError "duckdb-simple: failed to allocate scalar function")
-        withCallbackResources
-            acquire
-            (c_duckdb_scalar_function_set_extra_info scalarFun)
-            \ScalarFunctionResources{scalarFunctionExecPtr, scalarFunctionInitPtr} -> do
-                TextForeign.withCString name $ c_duckdb_scalar_function_set_name scalarFun
-                forM_ (argumentTypes proxy) \dtype ->
-                    withLogicalType dtype $ c_duckdb_scalar_function_add_parameter scalarFun
-                withLogicalType (duckTypeForScalar (returnType proxy)) $ c_duckdb_scalar_function_set_return_type scalarFun
-                when (isVolatile proxy) $ c_duckdb_scalar_function_set_volatile scalarFun
-                c_duckdb_scalar_function_set_special_handling scalarFun
-                c_duckdb_scalar_function_set_function scalarFun scalarFunctionExecPtr
-                forM_ scalarFunctionInitPtr $ c_duckdb_scalar_function_set_init scalarFun
-                withConnectionHandle conn \connPtr -> do
-                    rc <- c_duckdb_register_scalar_function connPtr scalarFun
-                    when (rc /= DuckDBSuccess) $
-                        throwIO (functionInvocationError "duckdb-simple: registering function failed")
-
--- | Drop a previously registered scalar function by issuing a DROP FUNCTION statement.
-deleteFunction :: Connection -> Text -> IO ()
-deleteFunction conn name =
-    do
-        outcome <-
-            try $
-                withConnectionHandle conn \connPtr -> do
-                    let dropQuery =
-                            Query $
-                                Text.concat
-                                    [ Text.pack "DROP FUNCTION IF EXISTS "
-                                    , qualifyIdentifier name
-                                    ]
-                    withQueryCString dropQuery \sql ->
-                        withResult conn dropQuery (c_duckdb_query connPtr sql) (const (pure ()))
-        case outcome of
-            Right () -> pure ()
-            Left err
-                -- DuckDB does not allow dropping scalar functions registered via the C API,
-                -- so we ignore that specific error here.
-                -- TODO: Update this when DuckDB adds support for dropping such functions.
-                | Text.isInfixOf (Text.pack "Cannot drop internal catalog entry") (sqlErrorMessage err) -> return ()
-                | otherwise -> throwIO err
-
-cleanupScalarFunction :: DuckDBScalarFunction -> IO ()
-cleanupScalarFunction scalarFun =
-    alloca \ptr -> do
-        poke ptr scalarFun
-        c_duckdb_destroy_scalar_function ptr
-
-withLogicalType :: DuckDBType -> (DuckDBLogicalType -> IO a) -> IO a
-withLogicalType dtype =
-    bracket
-        ( do
-            logical <- c_duckdb_create_logical_type dtype
-            when (logical == nullPtr)
-                $ throwIO
-                $ functionInvocationError (Text.pack "duckdb-simple: failed to allocate logical type")
-            pure logical
-        )
-        destroyLogicalType
-
-duckTypeForScalar :: ScalarType -> DuckDBType
-duckTypeForScalar = \case
-    ScalarTypeBoolean -> DuckDBTypeBoolean
-    ScalarTypeBigInt -> DuckDBTypeBigInt
-    ScalarTypeUBigInt -> DuckDBTypeUBigInt
-    ScalarTypeDouble -> DuckDBTypeDouble
-    ScalarTypeVarchar -> DuckDBTypeVarchar
-
-scalarFunctionHandler :: forall f. (Function f) => f -> DuckDBFunctionInfo -> DuckDBDataChunk -> DuckDBVector -> IO ()
-scalarFunctionHandler fn info chunk outVec =
-    runCallback (c_duckdb_scalar_function_set_error info) do
-        rawColumnCount <- c_duckdb_data_chunk_get_column_count chunk
-        let columnCount = fromIntegral rawColumnCount :: Int
-            expected = length (argumentTypes (Proxy :: Proxy f))
-        when (columnCount /= expected)
-            $ throwIO
-            $ functionInvocationError
-            $ Text.concat
-                [ Text.pack "duckdb-simple: function expected "
-                , Text.pack (show expected)
-                , Text.pack " arguments but received "
-                , Text.pack (show columnCount)
-                ]
-        rawRowCount <- c_duckdb_data_chunk_get_size chunk
-        let rowCount = fromIntegral rawRowCount :: Int
-        readers <- mapM (makeColumnReader chunk) [0 .. expected - 1]
-        rows <-
-            forM [0 .. rowCount - 1] \row ->
-                forM readers \reader ->
-                    reader (fromIntegral row)
-        results <- mapM (`applyFunction` fn) rows
-        writeResults (returnType (Proxy :: Proxy f)) results outVec
-
-scalarFunctionHandlerWithState :: forall s f. (Function f) => (s -> f) -> DuckDBFunctionInfo -> DuckDBDataChunk -> DuckDBVector -> IO ()
-scalarFunctionHandlerWithState mkFn info chunk outVec =
-    runCallback (c_duckdb_scalar_function_set_error info) do
-        statePtr <- c_duckdb_scalar_function_get_state info
-        when (statePtr == nullPtr) $
-            throwIO (functionInvocationError "duckdb-simple: scalar function state was not initialised")
-        state <- deRefStablePtr (castPtrToStablePtr statePtr :: StablePtr s)
-        scalarFunctionHandler (mkFn state) info chunk outVec
-
-scalarFunctionInitHandler :: IO s -> DuckDBInitInfo -> IO ()
-scalarFunctionInitHandler initState info =
-    runCallback (c_duckdb_scalar_function_init_set_error info) do
-        state <- initState
-        transferCallbackState (c_duckdb_scalar_function_init_set_state info) state
-
-type ColumnReader = DuckDBIdx -> IO Field
-
-makeColumnReader :: DuckDBDataChunk -> Int -> IO ColumnReader
-makeColumnReader chunk columnIndex = do
-    readValue <- c_duckdb_data_chunk_get_vector chunk (fromIntegral columnIndex) >>= prepareVectorReader
-    let name = Text.pack ("arg" <> show columnIndex)
-    pure \rowIdx -> do
-        value <- readValue (fromIntegral rowIdx)
-        pure
-            Field
-                { fieldName = name
-                , fieldIndex = columnIndex
-                , fieldValue = value
-                }
-writeResults :: ScalarType -> [ScalarValue] -> DuckDBVector -> IO ()
-writeResults resultType values outVec = do
-    let hasNulls = any isNullValue values
-    when hasNulls $
-        c_duckdb_vector_ensure_validity_writable outVec
-    dataPtr <- c_duckdb_vector_get_data outVec
-    validityPtr <- c_duckdb_vector_get_validity outVec
-    forM_ (zip [0 ..] values) \(idx, val) ->
-        case (resultType, val) of
-            (_, ScalarNull) ->
-                markInvalid validityPtr idx
-            (ScalarTypeBoolean, ScalarBoolean flag) -> do
-                markValid validityPtr idx
-                pokeElemOff (castPtr dataPtr :: Ptr Word8) idx (if flag then 1 else 0)
-            (ScalarTypeBigInt, ScalarInteger intval) -> do
-                markValid validityPtr idx
-                pokeElemOff (castPtr dataPtr :: Ptr Int64) idx intval
-            (ScalarTypeUBigInt, ScalarUnsigned intval) -> do
-                markValid validityPtr idx
-                pokeElemOff (castPtr dataPtr :: Ptr Word64) idx intval
-            (ScalarTypeDouble, ScalarDouble dbl) -> do
-                markValid validityPtr idx
-                pokeElemOff (castPtr dataPtr :: Ptr Double) idx dbl
-            (ScalarTypeVarchar, ScalarText txt) -> do
-                markValid validityPtr idx
-                TextForeign.withCStringLen txt \(ptr, len) ->
-                    c_duckdb_vector_assign_string_element_len outVec (fromIntegral idx) ptr (fromIntegral len)
-            _ ->
-                throwIO
-                    $ functionInvocationError
-                    $ Text.pack "duckdb-simple: result type mismatch when materialising scalar function output"
-
-markInvalid :: Ptr Word64 -> Int -> IO ()
-markInvalid validity idx
-    | validity == nullPtr = pure ()
-    | otherwise = c_duckdb_validity_set_row_invalid validity (fromIntegral idx)
-
-markValid :: Ptr Word64 -> Int -> IO ()
-markValid validity idx
-    | validity == nullPtr = pure ()
-    | otherwise = c_duckdb_validity_set_row_valid validity (fromIntegral idx)
-
-isNullValue :: ScalarValue -> Bool
-isNullValue = \case
-    ScalarNull -> True
-    _ -> False
-
-argumentConversionError :: Int -> [SomeException] -> SQLError
-argumentConversionError idx err =
-    let message =
-            Text.concat
-                [ Text.pack "duckdb-simple: unable to convert argument #"
-                , Text.pack (show (idx + 1))
-                , Text.pack ": "
-                , Text.pack (show err)
-                ]
-     in functionInvocationError message
+--
+-- The result type needs a t'Database.DuckDB.Simple.ToField.ToDuckValue'
+-- instance, and the SQL type of the result is its
+-- 'Database.DuckDB.Simple.ToField.duckdbTypeDeclaration'. Thus an
+-- 'Data.Int.Int16' result is SMALLINT and a 'Float' result is FLOAT. DuckDB
+-- computes with that type: the product of two SMALLINT values is SMALLINT, so
+-- @f(x) * f(y)@ of an 'Data.Int.Int16' function raises an Out of Range Error
+-- when the product does not fit. Cast a result to a wider type first, for
+-- example @f(x)::INTEGER * f(y)@. A 'Bool', an integer of 8 to 64 bits, a
+-- 'Float', a 'Double', a 'Text', or a 'String' result goes to the memory of the
+-- result vector. Each other result type gives a native value for each row
+-- through the context of the call. DuckDB casts that value to the declared
+-- type, as a SQL @CAST@ does: it rounds a value to the scale of a DECIMAL type
+-- text, and it raises an error for a value that does not fit.
+--
+-- Each argument type needs t'Database.DuckDB.Simple.FromField.FromField' and
+-- t'Database.DuckDB.Simple.ToField.DuckDBColumnType' instances. The SQL type of
+-- an argument is the 'Database.DuckDB.Simple.ToField.duckdbTypeDeclaration' of
+-- its type. An argument type with no declaration raises an @SQLError@ at
+-- registration. Arguments use the same conversion as query results, including
+-- nested values.
+createFunction :: (Function f) => Connection -> Text -> f -> IO ()
+createFunction conn = createFunctionOn (ConnectionTarget conn)
 
-functionInvocationError :: Text -> SQLError
-functionInvocationError message =
-    SQLError
-        { sqlErrorMessage = message
-        , sqlErrorType = Nothing
-        , sqlErrorQuery = Nothing
-        }
+-- | Register a scalar function with per-worker thread-local state. The
+-- arguments have the rules of 'createFunction'.
+createFunctionWithState :: (Function f) => Connection -> Text -> IO s -> (s -> f) -> IO ()
+createFunctionWithState conn = createFunctionWithStateOn (ConnectionTarget conn)
 
-qualifyIdentifier :: Text -> Text
-qualifyIdentifier rawName =
-    let parts = Text.splitOn "." rawName
-     in Text.intercalate (Text.pack ".") (map quoteIdent parts)
+-- | Register a table function. The function gives the rows of one scan as a
+-- list. The list of names gives the names of the result columns. 'TypedRow' of
+-- @row@ gives the column types. A different number of names and columns, or a
+-- row with no column, is an error at registration. A @Maybe@ column gives NULL
+-- for 'Nothing'. The SQL type of each parameter and each column is the
+-- 'Database.DuckDB.Simple.ToField.duckdbTypeDeclaration' of its type. A record
+-- or a sum type with 'Database.DuckDB.Simple.Generic.ViaDuckDB' instances is a
+-- STRUCT or a UNION column. A type with no declaration, for example
+-- 'Database.DuckDB.Simple.LogicalRep.StructValue', is an error at registration.
+--
+-- 'TypedRow' of @params@ gives the parameter types. Use @()@ for no parameter.
+-- The parameters are positional only. DuckDB casts each argument to its
+-- parameter type. Then 'FromRow' converts the arguments. An argument that does
+-- not convert is an SQL error that names the function. A NULL argument converts
+-- only to a @Maybe@ field.
+--
+-- DuckDB converts the arguments when it plans the query. Thus an argument that
+-- does not convert also fails the preparation of a statement. The function runs
+-- one time for each scan, when the execution of the statement starts. It does not
+-- run at preparation. A query that reads the function two times runs it two
+-- times. A prepared statement runs it at each execution.
+--
+-- DuckDB reads the list one chunk at a time. It can run two exec callbacks of
+-- one scan at the same time, for example for a multi-file function. Each exec
+-- callback takes its rows from the list under a lock, so two exec callbacks never
+-- read the list at the same time. DuckDB stops when the query needs no more rows,
+-- so the list can be long or infinite, for example with @LIMIT@. It reads a full
+-- chunk, and it can read more chunks than the query needs. Thus it can read rows
+-- after the @LIMIT@. DuckDB asks only for the columns that the query uses, also
+-- in @WHERE@ and @ORDER BY@. When the query uses no column, as in
+-- @SELECT count(*)@, DuckDB asks for the first column. The library evaluates
+-- only the columns that DuckDB asks for, so an exception in another column does
+-- not fail the query. But the library evaluates each row that it writes to its
+-- constructor, and this evaluates each strict field of the row (a field with
+-- @!@, or each field with @StrictData@). Thus an exception in a strict field
+-- fails the query, also when the query does not use the column. An exception
+-- in the function, in the list, in a row, or in a column that the query uses
+-- is an SQL error. DuckDB releases the list when the scan ends.
+--
+-- > createTableFunction conn "haskell_squares" ["n", "square"] \(Only count) ->
+-- >     pure [(n, n * n) | n <- [0 .. count - 1 :: Int64]]
+createTableFunction :: (FromRow params, TypedRow params, TypedRow row) => Connection -> Text -> [Text] -> (params -> IO [row]) -> IO ()
+createTableFunction conn = createTableFunctionOn (ConnectionTarget conn)
 
-quoteIdent :: Text -> Text
-quoteIdent ident =
-    Text.concat
-        [ Text.pack "\""
-        , Text.replace (Text.pack "\"") (Text.pack "\"\"") ident
-        , Text.pack "\""
-        ]
+-- | Register an aggregate function. The function folds the rows of each group
+-- into a state.
+--
+-- 'aggregateStep' adds one row to a state. The step does not run for a row that
+-- has NULL in an argument. A group with no other rows gets the result of
+-- 'aggregateInitial'. DuckDB can split a group into partial states, for example
+-- over threads or for a window frame. 'aggregateCombine' merges two partial
+-- states. DuckDB also merges a partial state into a new state, so
+-- 'aggregateCombine' must give the other state when one state is
+-- 'aggregateInitial'. Each new state is evaluated to weak head normal form.
+--
+-- The arguments decode with t'Database.DuckDB.Simple.FromRow.FromRow'. The SQL
+-- type of each argument is the
+-- 'Database.DuckDB.Simple.ToField.duckdbTypeDeclaration' of its column in
+-- 'TypedRow'. A type with no declaration is an error at registration, as for
+-- 'createTableFunction'. Arguments use the same conversion as query results,
+-- also when DuckDB runs the update callback on several threads. The SQL return
+-- type is the
+-- 'Database.DuckDB.Simple.ToField.duckdbTypeDeclaration' of the result type,
+-- for example SMALLINT for 'Data.Int.Int16' and FLOAT for 'Float'. A 'Maybe'
+-- result has the SQL type of its value, and 'Nothing' gives NULL.
+--
+-- The result needs a static SQL type declaration. Lists, maps, and records
+-- through 'Database.DuckDB.Simple.Generic.ViaDuckDB' can supply one.
+-- DuckDB resolves the declaration on the database that registers the function.
+--
+-- 'Bool', 8- to 64-bit integers, 'Float', 'Double', 'Text', 'String', and
+-- 'Maybe' of these types write directly into the result vector. A newtype
+-- can inherit that writer with @deriving newtype (FunctionResult)@.
+-- For other results, 'Database.DuckDB.Simple.ToField.toDuckValue' receives
+-- an instance factory that can construct built-in types. For a catalog type,
+-- the encoder can return its underlying value. DuckDB casts that value to
+-- the declared result type.
+--
+-- An exception in a function fails the query. DuckDB can run the functions on
+-- more than one thread at one time, but not on the same state. The aggregate
+-- function works with GROUP BY, with DISTINCT, FILTER, and ORDER BY, and as a
+-- window function.
+--
+-- > createAggregate conn "haskell_sum" Aggregate
+-- >     { aggregateInitial = 0 :: Int64
+-- >     , aggregateStep = \total (Only value) -> pure (total + value)
+-- >     , aggregateCombine = \a b -> pure (a + b)
+-- >     , aggregateResult = pure
+-- >     }
+createAggregate :: (FromRow args, TypedRow args, FunctionResult result) => Connection -> Text -> Aggregate state args result -> IO ()
+createAggregate conn = createAggregateOn (ConnectionTarget conn)
 
-foreign import ccall "wrapper"
-    mkScalarFun :: (DuckDBFunctionInfo -> DuckDBDataChunk -> DuckDBVector -> IO ()) -> IO DuckDBScalarFunctionFun
+-- | Run @DROP FUNCTION IF EXISTS@ and report native errors.
+-- DuckDB does not permit deletion of functions registered through the C API.
+-- For a function from 'createFunction', this call raises t'SQLError' and the
+-- function stays registered. Register the name again to replace the function.
+-- GHC reports a warning at each use of this function. A build with @-Werror@
+-- must allow that warning, for example with @-Wno-error=deprecations@.
+--
+-- The name follows the rules of DuckDB for a qualified name, as in
+-- 'Database.DuckDB.Simple.Catalog.describeTable'. A dot separates two parts,
+-- and a part in double quotes can contain a dot. Thus @\"a.b\"@ names the
+-- function @a.b@, and @s.f@ names the function @f@ in the schema @s@. A name
+-- with a quote inside a part that has no quotes, with an unterminated quote, or
+-- with more than three parts raises the t'SQLError' of the parser.
+deleteFunction :: Connection -> Text -> IO ()
+deleteFunction conn name = do
+  qualified <- qualifyIdentifier name
+  -- See Note [SQL text of the library] in "Database.DuckDB.Simple.Native".
+  let dropQuery = Query ("DROP FUNCTION IF EXISTS " <> qualified)
+  withParsedStatements conn dropQuery (mapM_ (executeParsedStatement conn dropQuery))
+{-# WARNING
+  deleteFunction
+  "DuckDB cannot drop a function that its C API registered. deleteFunction raises SQLError for a function from createFunction. Register the name again to replace the function."
+  #-}
 
-foreign import ccall "wrapper"
-    mkScalarInitFun :: (DuckDBInitInfo -> IO ()) -> IO DuckDBScalarFunctionInitFun
+-- | Parse a qualified function name with @duckdb_v2_qname_parse@, and quote
+-- each part with 'quoteIdentifier'.
+qualifyIdentifier :: Text -> IO Text
+qualifyIdentifier name = withText name \text ->
+  bracket (output (c_duckdb_v2_qname_parse text)) (destroy c_duckdb_v2_qname_destroy) \qname -> do
+    count <- output (c_duckdb_v2_qname_get_part_count qname)
+    parts <- forM (indices count) \index -> output (c_duckdb_v2_qname_get_part qname index) >>= readIdentifier
+    pure (Text.intercalate "." (map quoteIdentifier parts))
diff --git a/src/Database/DuckDB/Simple/Function/Internal.hs b/src/Database/DuckDB/Simple/Function/Internal.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/Function/Internal.hs
@@ -0,0 +1,523 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE FlexibleInstances #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE RankNTypes #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE StrictData #-}
+{-# LANGUAGE TypeApplications #-}
+{-# LANGUAGE UndecidableInstances #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.Function.Internal
+-- Description : Share typed scalar registration for connections and extensions.
+--
+-- The cabal file lists this hidden module in @other-modules@.
+-- "Database.DuckDB.Simple.Function" exports the forms for a connection.
+-- The forms that take a registration target,
+-- 'createFunctionOn' and 'createFunctionWithStateOn', are for the module of
+-- the loadable extensions. Both forms use the same argument conversion, result
+-- conversion, and callback resources.
+module Database.DuckDB.Simple.Function.Internal (
+  ScalarValue,
+  FunctionResult (..),
+  Function (..),
+  createFunctionOn,
+  createFunctionWithStateOn,
+  prepareAggregateResultWriter,
+) where
+
+import Control.Exception (
+  SomeException,
+  bracket,
+  throwIO,
+ )
+import Control.Monad (forM, forM_, when)
+import Data.Bits (clearBit, setBit)
+import Data.Int (Int16, Int32, Int64, Int8)
+import Data.Proxy (Proxy (..))
+import Data.Text (Text)
+import qualified Data.Text as Text
+import qualified Data.Text.Foreign as TextForeign
+import Data.Void (Void)
+import Data.Word (Word16, Word32, Word64, Word8)
+import Database.DuckDB.Simple.Callback (
+  Allocator,
+  RegistrationTarget,
+  attachOpaque,
+  checkTargetThreads,
+  install,
+  installAll,
+  runCallback,
+  transferCallbackState,
+  withCallbackResourcesFinally,
+  withRegistrationFactory,
+  withTarget,
+ )
+import Database.DuckDB.Simple.Conversion (runConversion)
+import Database.DuckDB.Simple.Element (vectorElementType)
+import Database.DuckDB.Simple.FromField (
+  Field,
+  FromField (..),
+ )
+import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep (..), TypeDeclaration, logicalTypeSQL)
+import Database.DuckDB.Simple.Native
+import Database.DuckDB.Simple.Ok (Ok (..))
+import Database.DuckDB.Simple.ToField (DuckDBColumnType (..), ToDuckValue (..))
+import Database.DuckDB.Simple.TypeScope (withTypeScope)
+import Database.DuckDB.Simple.Typed (
+  ArgumentReader,
+  argumentName,
+  conversionMessage,
+  newArgumentReader,
+  positionalSignature,
+  rowDeclarations,
+ )
+import Database.DuckDB.Simple.V2.Registration (configureFunctionSignature)
+import Foreign.Marshal.Array (advancePtr, allocaArray, peekArray)
+import Foreign.Marshal.Utils (copyBytes, fillBytes)
+import Foreign.Ptr (Ptr, castPtr, nullPtr)
+import Foreign.StablePtr (StablePtr, castPtrToStablePtr, deRefStablePtr)
+import Foreign.Storable (Storable, peekElemOff, poke, pokeElemOff)
+import GHC.Records (getField)
+import HsBindgen.Runtime.Marshal (staticSizeOf)
+
+{- Note [Result writers]
+~~~~~~~~~~~~~~~~~~~~~~~~
+The FunctionResult instance of a scalar or aggregate result type selects one
+of two paths.
+
+- A raw result (rawResult gives Just): Bool, Int, Int8 to Int64, Word, Word8 to
+  Word64, Float, Double, Text, String, and Maybe of one of them. The writer
+  writes the value to the memory of the vector, with no native call. A VARCHAR
+  value of more than 12 bytes needs 2 native calls for the arena of the vector
+  (writeArenaText).
+- For other results, toDuckValue constructs an owned value and vector_set_value
+  copies it into the output vector. DuckDB casts it to the declared result
+  type. A scalar callback uses its context factory. An aggregate finalize
+  callback has no context and borrows the registration's instance factory.
+  This factory resolves built-in types. The registration declares the SQL
+  result type on the host, where catalog types are visible.
+
+A raw writer checks the logical type before writing a value so the width of
+the write matches the vector. It writes at the offset supplied by DuckDB.
+An ordered window can supply a result vector with logical size zero, even
+when there are rows to finalize. vector_set_value checks this size. Before
+writing native values, grow the vector to cover offset + count. Keep the
+existing size when it is larger, since other groups can occupy later rows.
+The native writer borrows no data or validity pointer across a resize.
+-}
+
+-- | The value of one result row. See Note [Result writers].
+data ScalarValue
+  = ScalarNull
+  | ScalarBoolean Bool
+  | ScalarInt8 Int8
+  | ScalarInt16 Int16
+  | ScalarInt32 Int32
+  | ScalarInt64 Int64
+  | ScalarWord8 Word8
+  | ScalarWord16 Word16
+  | ScalarWord32 Word32
+  | ScalarWord64 Word64
+  | ScalarFloat Float
+  | ScalarDouble Double
+  | ScalarText Text
+  | ScalarNative (DuckDBV2FactoryHandle -> IO DuckDBV2ValueHandle)
+
+-- | A result type of a scalar function or of a typed aggregate function. Each
+-- type with a 'ToDuckValue' instance is a result type. Its SQL type is its
+-- 'duckdbTypeDeclaration'. A newtype over a type with a raw writer gets that
+-- writer with @deriving newtype (FunctionResult)@. See Note [Result writers].
+class (ToDuckValue a) => FunctionResult a where
+  -- | The raw value of a result, or 'Nothing' when 'toDuckValue' writes the
+  -- result.
+  rawResult :: Maybe (a -> ScalarValue)
+  rawResult = Nothing
+
+-- | A result that 'toDuckValue' writes.
+instance {-# OVERLAPPABLE #-} (ToDuckValue a) => FunctionResult a
+
+instance FunctionResult Bool where
+  rawResult = Just ScalarBoolean
+
+instance FunctionResult Int where
+  rawResult = Just (ScalarInt64 . fromIntegral)
+
+instance FunctionResult Int8 where
+  rawResult = Just ScalarInt8
+
+instance FunctionResult Int16 where
+  rawResult = Just ScalarInt16
+
+instance FunctionResult Int32 where
+  rawResult = Just ScalarInt32
+
+instance FunctionResult Int64 where
+  rawResult = Just ScalarInt64
+
+instance FunctionResult Word where
+  rawResult = Just (ScalarWord64 . fromIntegral)
+
+instance FunctionResult Word8 where
+  rawResult = Just ScalarWord8
+
+instance FunctionResult Word16 where
+  rawResult = Just ScalarWord16
+
+instance FunctionResult Word32 where
+  rawResult = Just ScalarWord32
+
+instance FunctionResult Word64 where
+  rawResult = Just ScalarWord64
+
+instance FunctionResult Float where
+  rawResult = Just ScalarFloat
+
+instance FunctionResult Double where
+  rawResult = Just ScalarDouble
+
+instance FunctionResult Text where
+  rawResult = Just ScalarText
+
+instance FunctionResult String where
+  rawResult = Just (ScalarText . Text.pack)
+
+instance (FunctionResult a) => FunctionResult (Maybe a) where
+  rawResult = maybe ScalarNull <$> (rawResult :: Maybe (a -> ScalarValue))
+
+-- | Give the value of one result row. See Note [Result writers].
+scalarValue :: (FunctionResult a) => a -> ScalarValue
+scalarValue value = case rawResult of
+  Just raw -> raw value
+  Nothing -> ScalarNative (`toDuckValue` value)
+
+-- | A Haskell function that DuckDB can call as a scalar function: a result
+-- value, an 'IO' action that gives a result, or a function of one more
+-- argument. 'ScalarValue' is abstract, so an instance outside the library can
+-- only use 'applyFunction' of another instance.
+class Function a where
+  -- | The SQL type of each argument, in order, or the reason why an argument
+  -- type has no SQL type. See Note [Type declarations] in
+  -- "Database.DuckDB.Simple.ToField".
+  argumentTypes :: Proxy a -> [Either Text TypeDeclaration]
+
+  -- | The SQL type of the result, or the reason why the result type has no SQL
+  -- type.
+  returnType :: Proxy a -> Either Text TypeDeclaration
+
+  -- | 'True' for an 'IO' result. The registration then sets the stability of
+  -- the function to VOLATILE: the result can be different for each row, and
+  -- DuckDB calls the function one time for each row. 'False' keeps the
+  -- default stability CONSISTENT: the function always gives the same result
+  -- for the same arguments. DuckDB then calls a function with constant
+  -- arguments one time for each call site, when it prepares the statement. It
+  -- calls the function one time for each row in each other case, also for an
+  -- argument with few different values.
+  isVolatile :: Proxy a -> Bool
+
+  -- | Convert the fields of one row to the arguments, and give the result of
+  -- the function. A field that does not convert raises an error that names
+  -- the argument.
+  applyFunction :: [Field] -> a -> IO ScalarValue
+
+-- | A result value: a function with no argument. It is not volatile.
+instance {-# OVERLAPPABLE #-} (FunctionResult a) => Function a where
+  argumentTypes _ = []
+  returnType _ = duckdbTypeDeclaration (Proxy @a)
+  isVolatile _ = False
+  applyFunction [] value = pure (scalarValue value)
+  applyFunction _ _ = throwInternalError (Text.pack "unexpected arguments supplied")
+
+-- | An 'IO' action that gives a result: a function with no argument. It is
+-- volatile, so DuckDB runs the action one time for each row.
+instance {-# OVERLAPPING #-} (FunctionResult a) => Function (IO a) where
+  argumentTypes _ = []
+  returnType _ = duckdbTypeDeclaration (Proxy @a)
+  isVolatile _ = True
+  applyFunction [] action = scalarValue <$> action
+  applyFunction _ _ = throwInternalError (Text.pack "unexpected arguments supplied")
+
+-- | A function of one more argument. The argument has the SQL type of
+-- 'duckdbTypeDeclaration'. The function is volatile when its result is
+-- volatile. See Note [Type declarations] in "Database.DuckDB.Simple.ToField".
+instance {-# OVERLAPPABLE #-} (FromField a, DuckDBColumnType a, Function r) => Function (a -> r) where
+  argumentTypes _ = duckdbTypeDeclaration (Proxy @a) : argumentTypes (Proxy @r)
+  returnType _ = returnType (Proxy @r)
+  isVolatile _ = isVolatile (Proxy @r)
+  applyFunction [] _ =
+    throwInternalError (Text.pack "insufficient arguments supplied")
+  applyFunction (field : rest) fn =
+    runConversion (fromField field) >>= \case
+      Errors err -> throwIO (argumentConversionError err)
+      Ok value -> applyFunction rest (fn value)
+
+-- | Register a typed function on a connection or a loading extension.
+createFunctionOn :: forall f. (Function f) => RegistrationTarget -> Text -> f -> IO ()
+createFunctionOn target name fn =
+  registerScalarFunction target name (Proxy @f) \readArgument allocate function ->
+    [ install
+        allocate
+        DuckDBV2ScalarFunctionExecCallbackFn
+        (DuckDBV2ScalarFunctionExecCallbackFn_Aux (scalarFunctionHandler readArgument fn))
+        (c_duckdb_v2_scalar_function_set_exec_callback function)
+    ]
+
+-- | Register a typed function with per-worker state on a connection or extension.
+createFunctionWithStateOn :: forall s f. (Function f) => RegistrationTarget -> Text -> IO s -> (s -> f) -> IO ()
+createFunctionWithStateOn target name initState mkFn =
+  registerScalarFunction target name (Proxy @f) \readArgument allocate function ->
+    [ install
+        allocate
+        DuckDBV2ScalarFunctionExecCallbackFn
+        (DuckDBV2ScalarFunctionExecCallbackFn_Aux (scalarFunctionHandlerWithState readArgument mkFn))
+        (c_duckdb_v2_scalar_function_set_exec_callback function)
+    , install
+        allocate
+        DuckDBV2ScalarFunctionInitCallbackFn
+        (DuckDBV2ScalarFunctionInitCallbackFn_Aux (scalarFunctionInitHandler initState))
+        (c_duckdb_v2_scalar_function_set_init_callback function)
+    ]
+
+-- | Configure a scalar function and transfer its callbacks to DuckDB. An
+-- argument type or a result type with no declaration raises an error at registration. The check of the
+-- name and the declarations of the arguments and the result come before the
+-- read of the state of the target, so their input errors win over a closed
+-- connection. The last argument gives the install actions of the
+-- callbacks for the builder, with the reader for this registration. Their
+-- setters run after the properties. See 'installAll'.
+registerScalarFunction
+  :: (Function f)
+  => RegistrationTarget
+  -> Text
+  -> Proxy f
+  -> (ArgumentReader -> Allocator -> DuckDBV2ScalarFunctionHandle -> [IO (IO ())])
+  -> IO ()
+registerScalarFunction target name proxy installers = do
+  when (Text.null name || Text.any (== '\0') name) $
+    throwInvalidArgument "invalid scalar function name"
+  -- See Note [Type declarations] in "Database.DuckDB.Simple.ToField".
+  parameters <- rowDeclarations name ["argument " <> argumentName index | index <- [0 ..]] (argumentTypes proxy)
+  [result] <- rowDeclarations name ["result"] [returnType proxy]
+  (readArgument, _, closeReader) <- newArgumentReader target
+  -- withTarget keeps its factory private. Borrow another one for the signature types.
+  withRegistrationFactory target \factory ->
+    withTarget
+      target
+      c_duckdb_v2_scalar_function_create
+      c_duckdb_v2_scalar_function_destroy
+      c_duckdb_v2_connection_register_scalar_function
+      c_duckdb_v2_extension_register_scalar_function
+      \scalarFun register ->
+        withCallbackResourcesFinally
+          (checkTargetThreads target)
+          closeReader
+          (\allocate -> installAll (installers readArgument allocate scalarFun))
+          (attachOpaque (c_duckdb_v2_scalar_function_set_user_data scalarFun))
+          \installCallbacks -> do
+            withIdentifier name $ checked . c_duckdb_v2_scalar_function_set_name scalarFun
+            signature <- output (c_duckdb_v2_scalar_function_get_signature scalarFun)
+            configureFunctionSignature factory (positionalSignature parameters (Just result)) signature
+            when (isVolatile proxy) $
+              checked (c_duckdb_v2_scalar_function_set_property scalarFun DuckDBV2FunctionPropertyStability DuckDBV2FunctionPropertyStabilityVolatile)
+            checked
+              (c_duckdb_v2_scalar_function_set_property scalarFun DuckDBV2FunctionPropertyNullHandling DuckDBV2FunctionPropertyNullHandlingSpecial)
+            checked (c_duckdb_v2_scalar_function_set_property scalarFun DuckDBV2FunctionPropertyFallibility DuckDBV2FunctionPropertyFallibilityFallible)
+            installCallbacks
+            register
+
+scalarFunctionHandler
+  :: forall f
+   . (Function f)
+  => ArgumentReader -> f -> DuckDBV2ScalarFunctionExecInfoHandle -> DuckDBV2ContextHandle -> Ptr DuckDBV2ErrorInfoHandle -> IO ()
+scalarFunctionHandler readArgument fn info context err = runCallback err (executeScalarFunction readArgument fn info context)
+
+-- | Run one call of a scalar function.
+executeScalarFunction
+  :: forall f. (Function f) => ArgumentReader -> f -> DuckDBV2ScalarFunctionExecInfoHandle -> DuckDBV2ContextHandle -> IO ()
+executeScalarFunction readArgument fn info context = withTypeScope \scope -> do
+  let expected = length (argumentTypes (Proxy @f))
+  columnCount <- allocaArray 4 $ \counts -> do
+    checked (c_duckdb_v2_scalar_function_exec_get_arg_count info counts (advancePtr counts 1) (advancePtr counts 2) (advancePtr counts 3))
+    fromIntegral . sum <$> peekArray 4 counts
+  when (columnCount /= expected) $
+    throwInternalError (Text.pack ("function expected " <> show expected <> " arguments but received " <> show columnCount))
+  rawRowCount <- output (c_duckdb_v2_scalar_function_exec_get_row_count info)
+  let rowCount = fromIntegral rawRowCount :: Int
+  readers <- forM [0 .. expected - 1] \index ->
+    output (c_duckdb_v2_scalar_function_exec_get_arg info (fromIntegral index)) >>= readArgument scope index
+  rows <- forM [0 .. rowCount - 1] $ \row -> forM readers ($ row)
+  results <- mapM (`applyFunction` fn) rows
+  outVec <- output (c_duckdb_v2_scalar_function_exec_get_result info)
+  writeResults context results outVec
+
+scalarFunctionHandlerWithState
+  :: forall s f
+   . (Function f)
+  => ArgumentReader
+  -> (s -> f)
+  -> DuckDBV2ScalarFunctionExecInfoHandle
+  -> DuckDBV2ContextHandle
+  -> Ptr DuckDBV2ErrorInfoHandle
+  -> IO ()
+scalarFunctionHandlerWithState readArgument mkFn info context err = runCallback err do
+  statePtr <- output (c_duckdb_v2_scalar_function_exec_get_init_data info)
+  when (statePtr == nullPtr) $
+    throwInternalError "scalar function state was not initialised"
+  -- The cast has no type check, and it is safe. createFunctionWithStateOn has
+  -- one signature for initState :: IO s and mkFn :: s -> f. Thus the init
+  -- callback stores a StablePtr of the same type s that this cast gives.
+  state <- deRefStablePtr (castPtrToStablePtr (castPtr statePtr) :: StablePtr s)
+  executeScalarFunction readArgument (mkFn state) info context
+
+scalarFunctionInitHandler :: IO s -> DuckDBV2ScalarFunctionInitInfoHandle -> DuckDBV2ContextHandle -> Ptr DuckDBV2ErrorInfoHandle -> IO ()
+scalarFunctionInitHandler initState info _context err = runCallback err do
+  state <- initState
+  transferCallbackState (attachOpaque (c_duckdb_v2_scalar_function_init_set_init_data info)) state
+
+-- | Write the results of one call to the result vector. Set the size, then
+-- flatten, then read the pointers. A row of a result that is not raw borrows
+-- the factory of the context. See Note [Vector flatten] in
+-- "Database.DuckDB.Simple.Materialize" and Note [Result writers].
+writeResults :: DuckDBV2ContextHandle -> [ScalarValue] -> DuckDBV2VectorHandle -> IO ()
+writeResults context values outVec = do
+  checked (c_duckdb_v2_vector_set_size outVec (fromIntegral (length values)))
+  checked (c_duckdb_v2_vector_flatten outVec)
+  let native = \case
+        ScalarNative _ -> True
+        _ -> False
+      withFactory action
+        | any native values = withContextFactory context (action . Just)
+        | otherwise = action Nothing
+  withFactory \factory -> do
+    write <- prepareResultWriter factory outVec
+    forM_ (zip [0 ..] values) (uncurry write)
+
+-- | Write aggregate results into a borrowed vector. The end is the exclusive
+-- upper bound of this finalize call. See Note [Result writers].
+prepareAggregateResultWriter
+  :: (FunctionResult a) => IO DuckDBV2FactoryHandle -> DuckDBV2VectorHandle -> DuckDBIdx -> IO (Int -> a -> IO ())
+prepareAggregateResultWriter acquireFactory vector end = case rawResult of
+  Just raw -> do
+    write <- prepareResultWriter Nothing vector
+    pure (\row -> write row . raw)
+  Nothing -> do
+    size <- output (c_duckdb_v2_vector_get_size vector)
+    when (size < end) (checked (c_duckdb_v2_vector_set_size vector end))
+    factory <- acquireFactory
+    pure (\row -> writeNativeResult vector row . toDuckValue factory)
+
+-- | Copy an owned value into a result row, then release it even if the cast fails.
+writeNativeResult :: DuckDBV2VectorHandle -> Int -> IO DuckDBV2ValueHandle -> IO ()
+writeNativeResult vector row create = bracket create destroyValue (checked . c_duckdb_v2_vector_set_value vector (fromIntegral row))
+
+-- | Prepare a writer for the rows of a flat result vector. The writer does not
+-- change the size of the vector. It reads the logical type of the vector one
+-- time, and it raises an error for a raw value of another type. It writes a
+-- value of 'ScalarNative' with the factory, and raises an error without a
+-- factory. A vector that is not flat raises an error. See
+-- Note [Result writers] and Note [Vector flatten] in
+-- "Database.DuckDB.Simple.Materialize".
+prepareResultWriter :: Maybe DuckDBV2FactoryHandle -> DuckDBV2VectorHandle -> IO (Int -> ScalarValue -> IO ())
+prepareResultWriter factory vector = do
+  kind <- output (c_duckdb_v2_vector_get_vector_type vector)
+  when (kind /= DuckDBV2VectorTypeFlat) $
+    throwInternalError (Text.pack ("the result vector is not flat: " <> show kind))
+  vectorType <- vectorElementType vector
+  dataPtr <- output (c_duckdb_v2_vector_get_data_mutable vector)
+  validityPtr <- output (c_duckdb_v2_vector_flat_get_validity_mutable vector)
+  pure (writeScalarValue factory vector vectorType dataPtr validityPtr)
+
+-- | Write one value at a row of a flat vector. The data and validity pointers
+-- belong to the vector. A raw value must have the logical type of the vector.
+-- See Note [Result writers].
+writeScalarValue
+  :: Maybe DuckDBV2FactoryHandle -> DuckDBV2VectorHandle -> DuckDBV2LogicalTypeId -> Ptr Void -> Ptr Word64 -> Int -> ScalarValue -> IO ()
+writeScalarValue factory vector vectorType dataPtr validityPtr idx = \case
+  ScalarNull -> markInvalid validityPtr idx
+  -- A BOOLEAN value has one byte.
+  ScalarBoolean flag -> raw DuckDBV2LogicalTypeIdBoolean (if flag then 1 else 0 :: Word8)
+  ScalarInt8 value -> raw DuckDBV2LogicalTypeIdTinyInt value
+  ScalarInt16 value -> raw DuckDBV2LogicalTypeIdSmallInt value
+  ScalarInt32 value -> raw DuckDBV2LogicalTypeIdInteger value
+  ScalarInt64 value -> raw DuckDBV2LogicalTypeIdBigInt value
+  ScalarWord8 value -> raw DuckDBV2LogicalTypeIdUTinyInt value
+  ScalarWord16 value -> raw DuckDBV2LogicalTypeIdUSmallInt value
+  ScalarWord32 value -> raw DuckDBV2LogicalTypeIdUInteger value
+  ScalarWord64 value -> raw DuckDBV2LogicalTypeIdUBigInt value
+  ScalarFloat value -> raw DuckDBV2LogicalTypeIdFloat value
+  ScalarDouble value -> raw DuckDBV2LogicalTypeIdDouble value
+  ScalarText text -> do
+    expect DuckDBV2LogicalTypeIdVarchar
+    markValid validityPtr idx
+    writeArenaText vector dataPtr idx text
+  ScalarNative make -> case factory of
+    Just valueFactory -> writeNativeResult vector idx (make valueFactory)
+    Nothing -> throwInternalError "the result writer has no factory for a value of this result type"
+  where
+    raw :: (Storable s) => DuckDBV2LogicalTypeId -> s -> IO ()
+    raw expected value = do
+      expect expected
+      markValid validityPtr idx
+      pokeElemOff (castPtr dataPtr) idx value
+    expect expected = when (vectorType /= expected) do
+      actualName <- logicalTypeSQL . LogicalTypeScalar <$> logicalTypeIdFromNative vectorType
+      expectedName <- logicalTypeSQL . LogicalTypeScalar <$> logicalTypeIdFromNative expected
+      throwInternalError ("the result vector has the type " <> actualName <> ", but the result value has the type " <> expectedName)
+
+-- | Write a VARCHAR value at a row of a flat vector without a factory. A value
+-- of more than @DUCKDB_V2_BYTES_INLINE_LENGTH@ (12) bytes goes to the arena of
+-- the vector. See Note [Vector memory layouts] in "Database.DuckDB.Simple.Element".
+writeArenaText :: DuckDBV2VectorHandle -> Ptr Void -> Int -> Text -> IO ()
+writeArenaText vector dataPtr idx txt = do
+  -- Write each field through its generated field pointer, as chunkDecodeBlob
+  -- in "Database.DuckDB.Simple.Element" reads it.
+  let len = TextForeign.lengthWord8 txt
+      slot = advancePtr @DuckDBV2Bytes (castPtr dataPtr) idx
+      inlined = getField @"inlined" (getField @"value" slot)
+      pointer = getField @"pointer" (getField @"value" slot)
+  when (len > fromIntegral (maxBound :: Word32)) $
+    throwIO (functionInvocationError "duckdb-simple: a VARCHAR result is longer than 4 GiB")
+  -- DuckDB compares the unused inline bytes. They must be zero.
+  fillBytes slot 0 (staticSizeOf (Proxy @DuckDBV2Bytes))
+  if len <= fromIntegral dUCKDB_V2_BYTES_INLINE_LENGTH
+    then do
+      poke (getField @"length" inlined) (fromIntegral len)
+      TextForeign.unsafeCopyToPtr txt (castPtr (getField @"inlined" inlined))
+    else do
+      arena <- output (c_duckdb_v2_vector_get_arena vector)
+      bytes <- output (c_duckdb_v2_arena_allocate arena (fromIntegral len))
+      TextForeign.unsafeCopyToPtr txt bytes
+      poke (getField @"length" pointer) (fromIntegral len)
+      copyBytes (castPtr (getField @"prefix" pointer)) bytes 4
+      poke (getField @"ptr" pointer) (castPtr bytes)
+
+-- | Clear the validity bit of a row. See Note [Vector memory layouts] in
+-- "Database.DuckDB.Simple.Element".
+markInvalid :: Ptr Word64 -> Int -> IO ()
+markInvalid validity idx = do
+  let (wordIndex, bitIndex) = idx `divMod` 64
+  word <- peekElemOff validity wordIndex
+  pokeElemOff validity wordIndex (clearBit word bitIndex)
+
+-- | Set the validity bit of a row. See Note [Vector memory layouts] in
+-- "Database.DuckDB.Simple.Element".
+markValid :: Ptr Word64 -> Int -> IO ()
+markValid validity idx = do
+  let (wordIndex, bitIndex) = idx `divMod` 64
+  word <- peekElemOff validity wordIndex
+  pokeElemOff validity wordIndex (setBit word bitIndex)
+
+argumentConversionError :: [SomeException] -> SQLError
+argumentConversionError err = functionInvocationError (Text.pack ("duckdb-simple: " <> conversionMessage err))
+
+functionInvocationError :: Text -> SQLError
+functionInvocationError message =
+  SQLError
+    { sqlErrorMessage = message
+    , sqlErrorType = Nothing
+    , sqlErrorQuery = Nothing
+    , sqlErrorBody = Nothing
+    }
diff --git a/src/Database/DuckDB/Simple/Generic.hs b/src/Database/DuckDB/Simple/Generic.hs
--- a/src/Database/DuckDB/Simple/Generic.hs
+++ b/src/Database/DuckDB/Simple/Generic.hs
@@ -8,736 +8,877 @@
 {-# LANGUAGE MultiParamTypeClasses #-}
 {-# LANGUAGE NamedFieldPuns #-}
 {-# LANGUAGE ScopedTypeVariables #-}
-{-# LANGUAGE TypeFamilies #-}
-{-# LANGUAGE TypeOperators #-}
-{-# LANGUAGE UndecidableInstances #-}
-
-{- |
-Module      : Database.DuckDB.Simple.Generic
-Description : Generic helpers for encoding Haskell ADTs as DuckDB structs/unions.
-
-This module provides the glue needed to reuse the existing @ToField@/@FromField@
-machinery with algebraic data types via GHC generics.  The supported mapping is
-currently intentionally conservative:
-
-* /Product types/ (records or tuples) whose fields already satisfy @DuckValue@
-  are encoded as STRUCT values.  Record fields retain their selector name;
-  positional products fall back to @field1@, @field2@, …
-* /Sum types/ (:+:) become UNION values.  Each constructor becomes a union
-  member; payloads are encoded as structs (or @NULL@ for nullary constructors).
-
-Recursive types are supported as long as every payload is itself encodable
-through @DuckValue@. Note that sum types must have constructor fields that are
-structural products (i.e. we do not yet expose mixed union/record nesting for
-non-record constructors).
-
-Typical usage looks like:
-
-> data User = User { userId :: Int64, userName :: Text }
->   deriving stock (Generic)
->
-> instance DuckValue User
->
-> toField (genericToFieldValue user) -- Struct {"userId" := ..., ...}
-
-For sum types:
-
-> data Shape
->   = Circle Double
->   | Rectangle Double Double
->   | Origin
->   deriving stock (Generic)
->
-> instance DuckValue Shape
-
-Constructors are turned into a union with members @Circle{radius}@,
-@Rectangle{width,height}@, and @Origin@ (null payload).
-
-You can also lean on @DerivingVia@ using the exported @ViaDuckDB@ newtype:
-
-> data User = User { userId :: Int64, userName :: Text }
->   deriving stock (Generic)
->   deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB User)
-
-The derived instances automatically encode/decode via STRUCT/UNION representations.
-
-=== Extending this module
-
-The rest of this file is organised so that each building block is reusable:
-
-* @DuckValue@ covers leaf-level conversions between Haskell values, DuckDB
-  @FieldValue@s, and logical type metadata.
-* @GToField@ and friends walk the generic representation to assemble structs or
-  unions and carry around the logical type information we later need when
-  binding parameters.
-* @ViaDuckDB@ wires everything together for deriving via.
-
-When adding new features, mimic the structure used here (and document new
-classes the way the existing ones are documented) so other backends can take
-inspiration from this implementation.
--}
-module Database.DuckDB.Simple.Generic (
-    -- * Field-level primitives
-    DuckValue (..),
-    GToField (),
-    GFromField (),
-
-    -- * Generic encoding/decoding for ADTs
-    genericToFieldValue,
-    genericFromFieldValue,
-    genericLogicalType,
-    genericToStructValue,
-    genericToUnionValue,
-
-    -- * DerivingVia helper
-    ViaDuckDB (..),
-) where
-
-import Control.Exception (displayException)
-import Control.Monad (unless)
-import Data.Array (Array, elems, listArray)
-import qualified Data.ByteString as BS
-import Data.Int (Int16, Int32, Int64, Int8)
-import qualified Data.Map.Strict as Map
-import Data.Proxy (Proxy (..))
-import Data.Text (Text)
-import qualified Data.Text as Text
-import Data.Time (UTCTime)
-import Data.Time.Calendar (Day)
-import Data.Time.LocalTime (LocalTime, TimeOfDay)
-import Data.Typeable (Typeable)
-import qualified Data.UUID as UUID
-import Data.Word (Word16, Word32, Word64, Word8)
-import GHC.Generics
-import Numeric.Natural (Natural)
-
-import Database.DuckDB.FFI
-import Database.DuckDB.Simple.FromField (
-    Field (..),
-    FieldValue (..),
-    FromField (..),
-    IntervalValue (..),
-    ResultError (..),
-    TimeWithZone (..),
-    returnError,
- )
-import Database.DuckDB.Simple.Internal (duckDBTypeToName)
-import Database.DuckDB.Simple.LogicalRep (
-    LogicalTypeRep (..),
-    StructField (..),
-    StructValue (..),
-    UnionMemberType (..),
-    UnionValue (..),
- )
-import Database.DuckDB.Simple.Ok (Ok (..))
-import Database.DuckDB.Simple.Time (Unbounded (..))
-import Database.DuckDB.Simple.ToField (DuckDBColumnType (..), ToField (..))
-import Database.DuckDB.Simple.Variant (Variant (..))
-
---------------------------------------------------------------------------------
--- DuckValue: bridge between Haskell scalars and FieldValue/LogicalTypeRep
-
-{- | Types that can appear inside generated structs/unions.
-
-A @DuckValue@ instance must provide:
-
-* encoding to @FieldValue@
-* logical type metadata (@duckLogicalType@)
-* decoding from @FieldValue@
-
-The primitive instances below are the canonical source for how scalar types
-should be represented; both the generic implementation and the manual
-`ToField`/`FromField` instances rely on them.
--}
-class DuckValue a where
-    duckToField :: a -> FieldValue
-    duckFromField :: FieldValue -> Either String a
-    duckLogicalType :: Proxy a -> LogicalTypeRep
-
-    default duckFromField :: (FromField a, Show a) => FieldValue -> Either String a
-    duckFromField fv =
-        case fromField Field{fieldName = Text.empty, fieldIndex = 0, fieldValue = fv} of
-            Ok x -> Right x
-            Errors errs -> Left (unlines (map displayException errs))
-
-instance DuckValue Variant where
-    duckToField = variantPayload
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeVariant
-
-instance DuckValue Bool where
-    duckToField = FieldBool
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeBoolean
-
-instance DuckValue Int where
-    duckToField = FieldInt64 . fromIntegral
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeBigInt
-
-instance DuckValue Int8 where
-    duckToField = FieldInt8
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeTinyInt
-
-instance DuckValue Int16 where
-    duckToField = FieldInt16
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeSmallInt
-
-instance DuckValue Int32 where
-    duckToField = FieldInt32
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeInteger
-
-instance DuckValue Int64 where
-    duckToField = FieldInt64
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeBigInt
-
-instance DuckValue Integer where
-    duckToField = FieldHugeInt
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeHugeInt
-
-instance DuckValue Natural where
-    duckToField = FieldUHugeInt . toInteger
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeUHugeInt
-
-instance DuckValue Word where
-    duckToField = FieldWord64 . fromIntegral
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeUBigInt
-
-instance DuckValue Word8 where
-    duckToField = FieldWord8
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeUTinyInt
-
-instance DuckValue Word16 where
-    duckToField = FieldWord16
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeUSmallInt
-
-instance DuckValue Word32 where
-    duckToField = FieldWord32
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeUInteger
-
-instance DuckValue Word64 where
-    duckToField = FieldWord64
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeUBigInt
-
-instance DuckValue Float where
-    duckToField = FieldFloat
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeFloat
-
-instance DuckValue Double where
-    duckToField = FieldDouble
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeDouble
-
-instance DuckValue Text where
-    duckToField = FieldText
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeVarchar
-
-instance DuckValue String where
-    duckToField = FieldText . Text.pack
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeVarchar
-    duckFromField fv = Text.unpack <$> duckFromField fv
-
-instance DuckValue BS.ByteString where
-    duckToField = FieldBlob
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeBlob
-
-instance DuckValue Day where
-    duckToField = FieldDate . Finite
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeDate
-
-instance DuckValue TimeOfDay where
-    duckToField = FieldTime
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeTime
-
-instance DuckValue LocalTime where
-    duckToField = FieldTimestamp . Finite
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeTimestamp
-
-instance DuckValue UTCTime where
-    duckToField = FieldTimestampTZ . Finite
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeTimestampTz
-
-instance DuckValue (Unbounded Day) where
-    duckToField = FieldDate
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeDate
-
-instance DuckValue (Unbounded LocalTime) where
-    duckToField = FieldTimestamp
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeTimestamp
-
-instance DuckValue (Unbounded UTCTime) where
-    duckToField = FieldTimestampTZ
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeTimestampTz
-
-instance DuckValue UUID.UUID where
-    duckToField = FieldUUID
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeUUID
-
-instance DuckValue IntervalValue where
-    duckToField = FieldInterval
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeInterval
-
-instance DuckValue TimeWithZone where
-    duckToField = FieldTimeTZ
-    duckLogicalType _ = LogicalTypeScalar DuckDBTypeTimeTz
-
-instance (DuckValue a) => DuckValue (Maybe a) where
-    duckToField (Just x) = duckToField x
-    duckToField Nothing = FieldNull
-    duckLogicalType _ = duckLogicalType (Proxy :: Proxy a)
-    duckFromField FieldNull = Right Nothing
-    duckFromField other = Just <$> duckFromField other
-
--- | List values encode as DuckDB LIST (variable-length).
-instance (DuckValue a) => DuckValue [a] where
-    duckToField xs = FieldList (map duckToField xs)
-    duckLogicalType _ = LogicalTypeList (duckLogicalType (Proxy :: Proxy a))
-    duckFromField (FieldList fvs) = traverse duckFromField fvs
-    duckFromField other = Left ("duckdb-simple: expected LIST, got " <> show other)
-
-{- | Array values encode as DuckDB ARRAY (fixed-length).
-Note: Arrays must have consistent bounds to work correctly with DuckDB.
--}
-instance (DuckValue a) => DuckValue (Array Int a) where
-    duckToField arr =
-        let values = elems arr
-            (low, high) = (0, length values - 1)
-         in FieldArray (listArray (low, high) (map duckToField values))
-    duckLogicalType _ =
-        -- We can't determine array size at the type level, so this is approximate.
-        -- The actual size will be determined at runtime from the array bounds.
-        LogicalTypeArray (duckLogicalType (Proxy :: Proxy a)) 0
-    duckFromField (FieldArray arr) = do
-        let values = elems arr
-        decoded <- traverse duckFromField values
-        let (low, high) = (0, length decoded - 1)
-        pure (listArray (low, high) decoded)
-    duckFromField other = Left ("duckdb-simple: expected ARRAY, got " <> show other)
-
--- | Map values encode as DuckDB MAP.
-instance (Ord k, DuckValue k, DuckValue v) => DuckValue (Map.Map k v) where
-    duckToField m =
-        let pairs = Map.toList m
-         in FieldMap [(duckToField k, duckToField v) | (k, v) <- pairs]
-    duckLogicalType _ =
-        LogicalTypeMap
-            (duckLogicalType (Proxy :: Proxy k))
-            (duckLogicalType (Proxy :: Proxy v))
-    duckFromField (FieldMap pairs) = do
-        decodedPairs <- traverse decodePair pairs
-        pure (Map.fromList decodedPairs)
-      where
-        decodePair (kfv, vfv) = do
-            k <- duckFromField kfv
-            v <- duckFromField vfv
-            pure (k, v)
-    duckFromField other = Left ("duckdb-simple: expected MAP, got " <> show other)
-
---------------------------------------------------------------------------------
--- Generic machinery
-
-{- | Internal representation used while traversing the generic structure.  We
-keep both the encoded value and its logical type so we can re-use the same
-traversal when generating metadata (@genericLogicalType@) and when producing
-concrete values (@genericToFieldValue@).
--}
-data Encoded
-    = EncodedStruct (StructValue FieldValue) (Array Int (StructField LogicalTypeRep))
-    | EncodedUnion (UnionValue FieldValue)
-    | EncodedNull
-
-encodedValue :: Encoded -> FieldValue
-encodedValue = \case
-    EncodedStruct sv _ -> FieldStruct sv
-    EncodedUnion uv -> FieldUnion uv
-    EncodedNull -> FieldNull
-
--- | Convert a Haskell value (using its generic representation) into a DuckDB @FieldValue@.
-genericToFieldValue :: forall a. (Generic a, GToField (Rep a)) => a -> FieldValue
-genericToFieldValue = encodedValue . gToField . from
-
--- | Extract the logical DuckDB type corresponding to a Haskell value.
-genericLogicalType :: forall a. (Generic a, GToField (Rep a)) => Proxy a -> LogicalTypeRep
-genericLogicalType _ = gLogicalType (Proxy :: Proxy (Rep a ()))
-
--- | Decode a DuckDB @FieldValue@ back into a Haskell value using its generic representation.
-genericFromFieldValue :: forall a. (Generic a, GFromField (Rep a)) => FieldValue -> Either String a
-genericFromFieldValue fv = to <$> gFromField fv
-
--- | Convenience helpers that project out structured values directly.
-genericToStructValue :: forall a. (Generic a, GToField (Rep a)) => a -> Maybe (StructValue FieldValue)
-genericToStructValue value =
-    case gToField (from value) of
-        EncodedStruct sv _ -> Just sv
-        EncodedNull -> Just emptyStruct
-        _ -> Nothing
-  where
-    emptyStruct =
-        StructValue
-            { structValueFields = listArray (0, -1) []
-            , structValueTypes = listArray (0, -1) []
-            , structValueIndex = Map.empty
-            }
-
--- | Extract a UNION-shaped generic encoding directly when one is produced.
-genericToUnionValue :: forall a. (Generic a, GToField (Rep a)) => a -> Maybe (UnionValue FieldValue)
-genericToUnionValue value =
-    case gToField (from value) of
-        EncodedUnion uv -> Just uv
-        _ -> Nothing
-
-{- | Wrapper for deriving-via so that @instance ToField (ViaDuckDB a)@ picks up
-the generic encoding provided by this module.
--}
-newtype ViaDuckDB a = ViaDuckDB {getViaDuckDB :: a}
-
--- Type family to decide whether a representation is a sum.
-
-{- | Type family evaluating to @'True@ for sum-of-constructors generic
-representations.  We use this to select the appropriate encoding strategy.
--}
-type family IsSum f :: Bool where
-    IsSum (f :+: g) = 'True
-    IsSum (M1 D _ f) = IsSum f
-    IsSum (M1 C _ f) = IsSum f
-    IsSum _ = 'False
-
-{- | Generic encoding to the intermediate @Encoded@ representation. Every
-instance must also supply the corresponding logical type description.
--}
-class GToField f where
-    gToField :: f p -> Encoded
-    gLogicalType :: Proxy (f p) -> LogicalTypeRep
-
-instance (GToField' (IsSum f) f) => GToField f where
-    gToField = gToField' (Proxy :: Proxy (IsSum f))
-    gLogicalType _ = gLogicalType' (Proxy :: Proxy (IsSum f)) (Proxy :: Proxy f)
-
-{- | Helper class that splits the product and sum handling using the @IsSum@
-type family. We specialise on products (@'False@) and sums (@'True@) to keep
-the core logic small and easy to reason about.
--}
-class GToField' (isSum :: Bool) f where
-    gToField' :: Proxy isSum -> f p -> Encoded
-    gLogicalType' :: Proxy isSum -> Proxy f -> LogicalTypeRep
-
--- Products (single constructor records)
-
--- | Product encoding: single-constructor datatypes become STRUCT values.
-instance (GStruct f) => GToField' 'False (M1 D meta (M1 C c f)) where
-    gToField' _ (M1 (M1 inner)) =
-        let comps = gStructValues inner
-            typeComps = gStructTypes (Proxy :: Proxy (f p))
-         in case comps of
-                [] -> EncodedNull
-                _ ->
-                    let names = resolveNames (zip progIndices (map fcName comps))
-                        valueArray = listArrayFrom names (map fcValue comps)
-                        typeArray = listArrayFrom names (map fcValue typeComps)
-                        indexMap = Map.fromList (zip names [0 ..])
-                     in EncodedStruct
-                            StructValue
-                                { structValueFields = valueArray
-                                , structValueTypes = typeArray
-                                , structValueIndex = indexMap
-                                }
-                            typeArray
-      where
-        progIndices = [0 :: Int ..]
-    gLogicalType' _ _ =
-        let typeComps = gStructTypes (Proxy :: Proxy (f p))
-            names = resolveNames (zip [0 :: Int ..] (map fcName typeComps))
-            typeArray = listArrayFrom names (map fcValue typeComps)
-         in LogicalTypeStruct typeArray
-
--- Sums (encode as union)
-
--- | Sum encoding: multi-constructor datatypes become UNION values.
-instance (GSum f) => GToField' 'True (M1 D meta f) where
-    gToField' _ (M1 value) =
-        let members = gSumMembers (Proxy :: Proxy (f p))
-            membersArray = listArray (0, length members - 1) members
-            (idx, payload) = gSumEncode value
-            label = unionMemberName (members !! idx)
-         in EncodedUnion
-                UnionValue
-                    { unionValueIndex = fromIntegral idx
-                    , unionValueLabel = label
-                    , unionValuePayload = payload
-                    , unionValueMembers = membersArray
-                    }
-    gLogicalType' _ _ =
-        let members = gSumMembers (Proxy :: Proxy (f p))
-            membersArray = listArray (0, length members - 1) members
-         in LogicalTypeUnion membersArray
-
---------------------------------------------------------------------------------
--- GStruct: products
-
-data FieldComponent a = FieldComponent
-    { fcName :: Maybe Text
-    , fcValue :: a
-    }
-
-resolveNames :: [(Int, Maybe Text)] -> [Text]
-
-{- | Assign canonical names to struct fields.  We preserve any selector names
-provided by GHC.Generics and fall back to @fieldN@ for positional products.
--}
-resolveNames =
-    map pick
-  where
-    pick (_, Just n) = n
-    pick (idx, Nothing) = Text.pack ("field" <> show (idx + 1))
-
-{- | Helper that builds an @Array@ of struct fields from parallel lists of names
-and payloads.
--}
-listArrayFrom :: [Text] -> [b] -> Array Int (StructField b)
-listArrayFrom names values =
-    listArray
-        (0, length values - 1)
-        (zipWith (\n v -> StructField{structFieldName = n, structFieldValue = v}) names values)
-
-{- | Collect the components (values and types) of a product.  Implementations
-produce parallel lists so we can zip them during encoding and decoding.
--}
-class GStruct f where
-    gStructValues :: f p -> [FieldComponent FieldValue]
-    gStructTypes :: Proxy (f p) -> [FieldComponent LogicalTypeRep]
-
-instance GStruct U1 where
-    gStructValues _ = []
-    gStructTypes _ = []
-
-instance (GStruct a, GStruct b) => GStruct (a :*: b) where
-    gStructValues (a :*: b) = gStructValues a ++ gStructValues b
-    gStructTypes _ = gStructTypes (Proxy :: Proxy (a p)) ++ gStructTypes (Proxy :: Proxy (b p))
-
-instance (Selector s, DuckValue a) => GStruct (M1 S s (K1 i a)) where
-    gStructValues m@(M1 (K1 x)) =
-        let name = toMaybe (selName m)
-         in [FieldComponent name (duckToField x)]
-    gStructTypes _ =
-        let raw = selName (undefined :: M1 S s (K1 i a) ())
-            name = toMaybe raw
-         in [FieldComponent name (duckLogicalType (Proxy :: Proxy a))]
-
-instance (GStruct f) => GStruct (M1 C c f) where
-    gStructValues (M1 x) = gStructValues x
-    gStructTypes _ = gStructTypes (Proxy :: Proxy (f p))
-
-toMaybe :: String -> Maybe Text
-toMaybe name
-    | null name = Nothing
-    | otherwise = Just (Text.pack name)
-
---------------------------------------------------------------------------------
--- Sums (unions)
-
-{- | Sum type encoding. We gather the metadata (@gSumMembers@), convert a value
-to its discriminant and payload (@gSumEncode@), and provide the inverse
-(@gSumDecode@).
--}
-class GSum f where
-    gSumMembers :: Proxy (f p) -> [UnionMemberType]
-    gSumEncode :: f p -> (Int, FieldValue)
-    gSumDecode :: Int -> FieldValue -> Either String (f p)
-
-instance (GSum a, GSum b) => GSum (a :+: b) where
-    gSumMembers _ = gSumMembers (Proxy :: Proxy (a p)) ++ gSumMembers (Proxy :: Proxy (b p))
-    gSumEncode (L1 x) = gSumEncode x
-    gSumEncode (R1 x) =
-        let leftCount = length (gSumMembers (Proxy :: Proxy (a p)))
-            (idx, payload) = gSumEncode x
-         in (idx + leftCount, payload)
-    gSumDecode idx payload =
-        let leftCount = length (gSumMembers (Proxy :: Proxy (a p)))
-         in if idx < leftCount
-                then L1 <$> gSumDecode idx payload
-                else R1 <$> gSumDecode (idx - leftCount) payload
-
-instance (Constructor c, GStruct f, GStructDecode f) => GSum (M1 C c f) where
-    gSumMembers _ =
-        [ UnionMemberType
-            { unionMemberName = Text.pack (conName (undefined :: M1 C c f p))
-            , unionMemberType =
-                let typeComps = gStructTypes (Proxy :: Proxy (f p))
-                    names = resolveNames (zip [0 :: Int ..] (map fcName typeComps))
-                 in LogicalTypeStruct (listArrayFrom names (map fcValue typeComps))
-            }
-        ]
-    gSumEncode (M1 x) =
-        case gStructValues x of
-            [] -> (0, FieldNull)
-            comps ->
-                let typeComps = gStructTypes (Proxy :: Proxy (f p))
-                    names = resolveNames (zip [0 :: Int ..] (map fcName comps))
-                    valueArray = listArrayFrom names (map fcValue comps)
-                    typeArray = listArrayFrom names (map fcValue typeComps)
-                    indexMap = Map.fromList (zip names [0 ..])
-                 in (0, FieldStruct StructValue{structValueFields = valueArray, structValueTypes = typeArray, structValueIndex = indexMap})
-    gSumDecode idx payload
-        | idx /= 0 = Left ("duckdb-simple: union tag mismatch (expected 0, got " <> show idx <> ")")
-        | otherwise =
-            case payload of
-                FieldNull -> M1 . fst <$> gStructDecodeList (Proxy :: Proxy (f p)) []
-                FieldStruct structVal -> do
-                    ordered <- orderStructFields (gStructTypes (Proxy :: Proxy (f p))) structVal
-                    M1 <$> gStructDecodeStruct (Proxy :: Proxy (f p)) ordered
-                other -> Left ("duckdb-simple: expected STRUCT payload for union member, got " <> show other)
-
--- | Match decoded fields to their selector names before product decoding.
-orderStructFields :: [FieldComponent LogicalTypeRep] -> StructValue FieldValue -> Either String (StructValue FieldValue)
-orderStructFields components sv = do
-    let names = resolveNames (zip [0 ..] (map fcName components))
-        fields = elems (structValueFields sv)
-        byName = Map.fromList [(structFieldName field, field) | field <- fields]
-    unless (length fields <= length names) $
-        Left "duckdb-simple: extra fields when decoding struct"
-    unless (length fields == length names && Map.size byName == length names) $
-        Left "duckdb-simple: struct field names or count mismatch"
-    ordered <- traverse (\name -> maybe (Left ("duckdb-simple: missing struct field " <> Text.unpack name)) Right (Map.lookup name byName)) names
-    pure sv{structValueFields = listArray (0, length ordered - 1) ordered}
-
---------------------------------------------------------------------------------
--- GStructDecode: inverse of GStruct for decoding
-
--- | Inverse of @GStruct@: decode struct payloads back into a generic product.
-class GStructDecode f where
-    gStructDecodeStruct :: Proxy (f p) -> StructValue FieldValue -> Either String (f p)
-
-    {- | Consume a prefix of fields from left to right while decoding, returning
-    the reconstructed value and any remaining fields.
-    -}
-    gStructDecodeList :: Proxy (f p) -> [FieldValue] -> Either String (f p, [FieldValue])
-
-instance GStructDecode U1 where
-    gStructDecodeStruct _ structVal =
-        if null (elems (structValueFields structVal))
-            then Right U1
-            else Left ("duckdb-simple: expected empty struct, but got " <> show (length (elems (structValueFields structVal))) <> " field(s)")
-    gStructDecodeList _ xs = Right (U1, xs)
-
-instance (GStructDecode a, GStructDecode b) => GStructDecode (a :*: b) where
-    gStructDecodeStruct _ structVal = do
-        let values = map structFieldValue (elems (structValueFields structVal))
-        (leftVal, rest) <- gStructDecodeList (Proxy :: Proxy (a p)) values
-        (rightVal, rest') <- gStructDecodeList (Proxy :: Proxy (b p)) rest
-        unless (null rest') $
-            Left ("duckdb-simple: extra " <> show (length rest') <> " field(s) when decoding struct (too many fields provided)")
-        pure (leftVal :*: rightVal)
-    gStructDecodeList _ xs = do
-        (leftVal, rest) <- gStructDecodeList (Proxy :: Proxy (a p)) xs
-        (rightVal, rest') <- gStructDecodeList (Proxy :: Proxy (b p)) rest
-        pure (leftVal :*: rightVal, rest')
-
-instance (Selector s, DuckValue a) => GStructDecode (M1 S s (K1 i a)) where
-    gStructDecodeStruct _ structVal =
-        case map structFieldValue (elems (structValueFields structVal)) of
-            [fv] -> M1 . K1 <$> duckFromField fv
-            [] -> Left "duckdb-simple: missing struct field (expected 1, got 0)"
-            xs -> Left ("duckdb-simple: expected single field struct, but got " <> show (length xs) <> " fields")
-
-    gStructDecodeList _ [] = Left "duckdb-simple: missing struct field (expected field but list is empty)"
-    gStructDecodeList _ (fv : rest) = do
-        val <- duckFromField fv
-        pure (M1 (K1 val), rest)
-
-instance (GStructDecode f) => GStructDecode (M1 C c f) where
-    gStructDecodeStruct _ structVal = M1 <$> gStructDecodeStruct (Proxy :: Proxy (f p)) structVal
-    gStructDecodeList _ values = do
-        (inner, rest) <- gStructDecodeList (Proxy :: Proxy (f p)) values
-        pure (M1 inner, rest)
-
---------------------------------------------------------------------------------
--- GFromField (inverse generic)
-
-{- | Generic decoding entry point mirroring @GToField@. This is used both by
-@genericFromFieldValue@ and the @Generically@ deriving helper.
--}
-class GFromField f where
-    gFromField :: FieldValue -> Either String (f p)
-
-instance (GFromField' (IsSum f) f) => GFromField f where
-    gFromField = gFromField' (Proxy :: Proxy (IsSum f))
-
-class GFromField' (isSum :: Bool) f where
-    gFromField' :: Proxy isSum -> FieldValue -> Either String (f p)
-
-instance (GStruct f, GStructDecode f) => GFromField' 'False (M1 D meta (M1 C c f)) where
-    gFromField' _ = \case
-        FieldNull -> M1 . M1 . fst <$> gStructDecodeList (Proxy :: Proxy (f p)) []
-        FieldStruct sv -> do
-            ordered <- orderStructFields (gStructTypes (Proxy :: Proxy (f p))) sv
-            M1 . M1 <$> gStructDecodeStruct (Proxy :: Proxy (f p)) ordered
-        other -> Left ("duckdb-simple: expected STRUCT value for product type, got " <> show other)
-
-instance (GSum f) => GFromField' 'True (M1 D meta f) where
-    gFromField' _ = \case
-        FieldUnion uv -> do
-            let actualMembers = elems (unionValueMembers uv)
-                actualIndex = fromIntegral (unionValueIndex uv)
-            unless (actualIndex < length actualMembers) $
-                Left "duckdb-simple: union tag out of range"
-            unless (unionMemberName (actualMembers !! actualIndex) == unionValueLabel uv) $
-                Left "duckdb-simple: union tag and member name mismatch"
-            let members = gSumMembers (Proxy :: Proxy (f p))
-                indexed = zip [0 ..] members
-                matching = [idx | (idx, member) <- indexed, unionMemberName member == unionValueLabel uv]
-            case matching of
-                [idx] -> M1 <$> gSumDecode idx (unionValuePayload uv)
-                _ -> Left "duckdb-simple: unknown union member name"
-        other -> Left ("duckdb-simple: expected UNION value for sum type, got " <> show other)
-
-instance GFromField' 'False (M1 D meta U1) where
-    gFromField' _ _ = Right (M1 U1)
-
---------------------------------------------------------------------------------
--- ViaDuckDB instances
-
-{- | The deriving-via version of @DuckDBColumnType@. We look at the generic
-logical type and map it back to a textual name.  The textual names are only
-used for diagnostics (errors and column metadata).
--}
-instance (Generic a, GToField (Rep a)) => DuckDBColumnType (ViaDuckDB a) where
-    duckdbColumnTypeFor _ =
-        case genericLogicalType (Proxy :: Proxy a) of
-            LogicalTypeStruct{} -> Text.pack "STRUCT"
-            LogicalTypeUnion{} -> Text.pack "UNION"
-            LogicalTypeList{} -> Text.pack "LIST"
-            LogicalTypeArray{} -> Text.pack "ARRAY"
-            LogicalTypeMap{} -> Text.pack "MAP"
-            LogicalTypeScalar dtype -> duckDBTypeToName dtype
-            LogicalTypeDecimal{} -> Text.pack "DECIMAL"
-            LogicalTypeEnum{} -> Text.pack "ENUM"
-            LogicalTypeGeometry{} -> Text.pack "GEOMETRY"
-
-{- | Deriving-via @ToField@ instance. We reuse the helpers above to decide
-whether the top-level representation is a union, struct, or scalar and then
-delegate to the existing @ToField@ instances for those composite types.
--}
-instance (Generic a, GToField (Rep a)) => ToField (ViaDuckDB a) where
-    toField (ViaDuckDB x) =
-        case genericToUnionValue x of
-            Just unionVal -> toField unionVal
-            Nothing ->
-                case genericToStructValue x of
-                    Just structVal -> toField structVal
-                    Nothing ->
-                        case genericToFieldValue x of
-                            FieldUnion uv -> toField uv
-                            FieldStruct sv -> toField sv
-                            FieldNull -> toField (Nothing :: Maybe Int)
-                            other -> error ("duckdb-simple: unsupported generic encoding " <> show other)
-
-{- | Deriving-via @FromField@ instance. Errors are rewrapped using the existing
-@returnError@ helper so callers receive a proper @ResultError@.
--}
-instance (Generic a, GFromField (Rep a), Typeable a) => FromField (ViaDuckDB a) where
-    fromField f@Field{fieldValue} =
-        case genericFromFieldValue fieldValue of
-            Right value -> pure (ViaDuckDB value)
-            Left err ->
-                returnError ConversionFailed f (Text.pack err)
-
---------------------------------------------------------------------------------
--- DuckDB type constructors (re-exported patterns)
-
--- These pattern synonyms come from duckdb-ffi; re-exporting to avoid users having to import it.
+{-# LANGUAGE TypeApplications #-}
+{-# LANGUAGE TypeFamilies #-}
+{-# LANGUAGE TypeOperators #-}
+{-# LANGUAGE UndecidableInstances #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.Generic
+-- Description : Generic helpers for encoding Haskell ADTs as DuckDB structs/unions.
+--
+-- Encode and decode algebraic data types through @ToField@/@FromField@ with
+-- GHC generics. The mapping is:
+--
+-- * /Product types/ (records or tuples) whose fields already satisfy @DuckValue@
+--   are encoded as STRUCT values. Record fields retain their selector name;
+--   positional products fall back to @field1@, @field2@, …
+-- * /Sum types/ (:+:) become UNION values. Each constructor becomes a union
+--   member; payloads are encoded as structs (a STRUCT without fields for a
+--   constructor without fields).
+--
+-- Each field needs a @DuckValue@ instance with a finite logical type. A nested
+-- user-defined type needs its own instance.
+--
+-- Encode a product:
+--
+-- > data User = User { userId :: Int64, userName :: Text }
+-- >   deriving stock (Generic)
+-- >
+-- > genericToFieldValue (User 1 "alice")
+-- > -- A FieldStruct with the fields userId = FieldInt64 1 and userName = FieldText "alice".
+--
+-- For sum types:
+--
+-- > data Shape
+-- >   = Circle Double
+-- >   | Rectangle Double Double
+-- >   | Origin
+-- >   deriving stock (Generic)
+--
+-- Constructors are turned into a union with the members @Circle@ (a STRUCT with
+-- the field @field1@), @Rectangle@ (a STRUCT with the fields @field1@ and
+-- @field2@), and @Origin@ (a STRUCT without fields).
+--
+-- Derive instances with @DerivingVia@ and the @ViaDuckDB@ newtype:
+--
+-- > data User = User { userId :: Int64, userName :: Text }
+-- >   deriving stock (Generic)
+-- >   deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB User)
+--
+-- The derived instances encode and decode STRUCT/UNION representations.
+-- Also derive @ToDuckValue@ to use the type as a column of a typed table function,
+-- as an argument or result of a typed aggregate function, or as the result of
+-- a scalar function.
+--
+-- === Extending this module
+--
+-- The implementation has these parts:
+--
+-- * @DuckValue@ covers leaf-level conversions between Haskell values, DuckDB
+--   @FieldValue@s, and logical type metadata.
+-- * @GToField@ and the related classes convert the generic representation to
+--   structs or unions. They keep the logical type information for parameter
+--   binding.
+-- * @ViaDuckDB@ supplies the deriving-via instances.
+--
+-- Follow this structure when you add a feature, and document each new class.
+module Database.DuckDB.Simple.Generic (
+  -- * Field-level primitives
+  DuckValue (..),
+  typedFromField,
+  GToField (),
+  GFromField (),
+
+  -- * Generic encoding/decoding for ADTs
+  genericToFieldValue,
+  genericFromFieldValue,
+  genericLogicalType,
+  genericToStructValue,
+  genericToUnionValue,
+
+  -- * DerivingVia helper
+  ViaDuckDB (..),
+) where
+
+import Control.Exception (toException)
+import Control.Monad (unless)
+import Data.Array (Array, elems, listArray)
+import qualified Data.ByteString as BS
+import Data.Int (Int16, Int32, Int64, Int8)
+import Data.List (intercalate, stripPrefix)
+import qualified Data.Map.Strict as Map
+import Data.Maybe (fromMaybe, isJust)
+import Data.Proxy (Proxy (..))
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Data.Time (UTCTime)
+import Data.Time.Calendar (Day)
+import Data.Time.LocalTime (LocalTime, TimeOfDay)
+import Data.Typeable (Typeable)
+import qualified Data.UUID as UUID
+import Data.Word (Word16, Word32, Word64, Word8)
+import Database.DuckDB.Simple.Conversion (
+  Conversion,
+  conversionError,
+  mapConversionErrors,
+  mapConversionErrorsWith,
+ )
+import Database.DuckDB.Simple.Element (containsType, valueTypeName)
+import Database.DuckDB.Simple.FromField (
+  Field (..),
+  FieldValue (..),
+  FromField (..),
+  IntervalValue (..),
+  ResultError (..),
+  SizedArray,
+  TimeWithZone (..),
+  fieldTypeName,
+  returnError,
+  sizedArrayFromList,
+  sizedArrayToArray,
+ )
+import Database.DuckDB.Simple.Internal (duckDBTypeToName)
+import Database.DuckDB.Simple.LogicalRep (
+  LogicalTypeRep (..),
+  StructField (..),
+  StructValue (..),
+  TypeDeclaration (..),
+  UnionMemberType (..),
+  UnionValue (..),
+  listElementType,
+  mapEntryTypes,
+ )
+import Database.DuckDB.Simple.Native
+import Database.DuckDB.Simple.Time (Unbounded (..))
+import Database.DuckDB.Simple.ToField (DuckDBColumnType (..), ToDuckValue (..), ToField (..))
+import Database.DuckDB.Simple.Variant (Variant (..))
+import GHC.Generics
+import GHC.TypeLits (KnownNat, natVal)
+import Numeric.Natural (Natural)
+
+--------------------------------------------------------------------------------
+-- DuckValue: bridge between Haskell scalars and FieldValue/LogicalTypeRep
+
+-- | Types that can appear inside generated structs/unions.
+--
+-- A @DuckValue@ instance must provide:
+--
+-- * encoding to @FieldValue@
+-- * logical type metadata (@duckLogicalType@)
+-- * decoding from @FieldValue@
+--
+-- The primitive instances define the scalar representations for generic
+-- conversion. The default decoder uses the @FromField@ instance of the type.
+-- See Note [Generic decoding].
+class DuckValue a where
+  -- | Encode a field value.
+  duckToField :: a -> FieldValue
+
+  -- | Decode a field value. Run it with @runConversion@.
+  duckFromField :: FieldValue -> Conversion a
+
+  -- | Give the SQL type used to encode the field.
+  duckLogicalType :: Proxy a -> LogicalTypeRep
+
+  -- | Decode a value with the SQL type of its place, for example the type of a
+  -- field of a STRUCT or of an element of a LIST. The default runs
+  -- 'duckFromField' and ignores the supplied type. An instance that reads
+  -- through 'FromField' can use
+  -- 'typedFromField', so that 'fieldType' returns the type. See
+  -- Note [Column types] in "Database.DuckDB.Simple.FromField".
+  duckFromTypedField :: LogicalTypeRep -> FieldValue -> Conversion a
+  duckFromTypedField _ = duckFromField
+
+  default duckFromField :: (FromField a) => FieldValue -> Conversion a
+  duckFromField = typedFromField (LogicalTypeScalar LogicalTypeIdVariant)
+
+{- Note [Generic decoding]
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Generic decoding uses Conversion because a FromField instance can request SQL
+metadata. Encoding and logical type declarations remain pure. Error context is
+added only when a conversion's failure is selected. A discarded Alternative
+branch does not request metadata for its diagnostic.
+-}
+
+-- | Decode a value through 'FromField', with a t'Field' of the given SQL type.
+-- See Note [Generic decoding] and Note [Column types] in
+-- "Database.DuckDB.Simple.FromField".
+typedFromField :: (FromField a) => LogicalTypeRep -> FieldValue -> Conversion a
+typedFromField logical fv =
+  fromField Field{fieldName = Text.empty, fieldIndex = 0, fieldValue = fv, fieldType = pure logical}
+
+instance DuckValue Variant where
+  duckToField = variantPayload
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdVariant
+  duckFromTypedField = typedFromField
+
+instance DuckValue Bool where
+  duckToField = FieldBool
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdBoolean
+  duckFromTypedField = typedFromField
+
+instance DuckValue Int where
+  duckToField = FieldInt64 . fromIntegral
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdBigInt
+  duckFromTypedField = typedFromField
+
+instance DuckValue Int8 where
+  duckToField = FieldInt8
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdTinyInt
+  duckFromTypedField = typedFromField
+
+instance DuckValue Int16 where
+  duckToField = FieldInt16
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdSmallInt
+  duckFromTypedField = typedFromField
+
+instance DuckValue Int32 where
+  duckToField = FieldInt32
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdInteger
+  duckFromTypedField = typedFromField
+
+instance DuckValue Int64 where
+  duckToField = FieldInt64
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdBigInt
+  duckFromTypedField = typedFromField
+
+-- | A field of a generic record has the type HUGEINT. A value outside that range
+-- raises an error. A top-level parameter of this type also binds as HUGEINT
+-- when the value is in that range. See Note [Integer parameters] in
+-- "Database.DuckDB.Simple.ToField".
+instance DuckValue Integer where
+  duckToField = FieldHugeInt
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdHugeInt
+  duckFromTypedField = typedFromField
+
+-- | A field of a generic record has the type UHUGEINT. A value outside that range
+-- raises an error. A top-level parameter of this type binds as HUGEINT when the
+-- value is in the HUGEINT range. See Note [Integer parameters] in
+-- "Database.DuckDB.Simple.ToField".
+instance DuckValue Natural where
+  duckToField = FieldUHugeInt . toInteger
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdUHugeInt
+  duckFromTypedField = typedFromField
+
+instance DuckValue Word where
+  duckToField = FieldWord64 . fromIntegral
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdUBigInt
+  duckFromTypedField = typedFromField
+
+instance DuckValue Word8 where
+  duckToField = FieldWord8
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdUTinyInt
+  duckFromTypedField = typedFromField
+
+instance DuckValue Word16 where
+  duckToField = FieldWord16
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdUSmallInt
+  duckFromTypedField = typedFromField
+
+instance DuckValue Word32 where
+  duckToField = FieldWord32
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdUInteger
+  duckFromTypedField = typedFromField
+
+instance DuckValue Word64 where
+  duckToField = FieldWord64
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdUBigInt
+  duckFromTypedField = typedFromField
+
+instance DuckValue Float where
+  duckToField = FieldFloat
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdFloat
+  duckFromTypedField = typedFromField
+
+instance DuckValue Double where
+  duckToField = FieldDouble
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdDouble
+  duckFromTypedField = typedFromField
+
+instance DuckValue Text where
+  duckToField = FieldText
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdVarchar
+  duckFromTypedField = typedFromField
+
+instance DuckValue String where
+  duckToField = FieldText . Text.pack
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdVarchar
+  duckFromField fv = Text.unpack <$> duckFromField fv
+  duckFromTypedField logical fv = Text.unpack <$> duckFromTypedField logical fv
+
+instance DuckValue BS.ByteString where
+  duckToField = FieldBlob
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdBlob
+  duckFromTypedField = typedFromField
+
+instance DuckValue Day where
+  duckToField = FieldDate . Finite
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdDate
+  duckFromTypedField = typedFromField
+
+instance DuckValue TimeOfDay where
+  duckToField = FieldTime
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdTime
+  duckFromTypedField = typedFromField
+
+instance DuckValue LocalTime where
+  duckToField = FieldTimestamp . Finite
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdTimestamp
+  duckFromTypedField = typedFromField
+
+instance DuckValue UTCTime where
+  duckToField = FieldTimestampTZ . Finite
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdTimestampTz
+  duckFromTypedField = typedFromField
+
+instance DuckValue (Unbounded Day) where
+  duckToField = FieldDate
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdDate
+  duckFromTypedField = typedFromField
+
+instance DuckValue (Unbounded LocalTime) where
+  duckToField = FieldTimestamp
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdTimestamp
+  duckFromTypedField = typedFromField
+
+instance DuckValue (Unbounded UTCTime) where
+  duckToField = FieldTimestampTZ
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdTimestampTz
+  duckFromTypedField = typedFromField
+
+instance DuckValue UUID.UUID where
+  duckToField = FieldUUID
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdUUID
+  duckFromTypedField = typedFromField
+
+instance DuckValue IntervalValue where
+  duckToField = FieldInterval
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdInterval
+  duckFromTypedField = typedFromField
+
+instance DuckValue TimeWithZone where
+  duckToField = FieldTimeTZ
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdTimeTz
+  duckFromTypedField = typedFromField
+
+instance (DuckValue a) => DuckValue (Maybe a) where
+  duckToField (Just x) = duckToField x
+  duckToField Nothing = FieldNull
+  duckLogicalType _ = duckLogicalType (Proxy @a)
+  duckFromField FieldNull = pure Nothing
+  duckFromField other = Just <$> duckFromField other
+  duckFromTypedField _ FieldNull = pure Nothing
+  duckFromTypedField logical other = Just <$> duckFromTypedField logical other
+
+-- | List values encode as DuckDB LIST (variable-length). A field reads a LIST
+-- and an ARRAY, as the top-level @FromField@ instance of a list does. 'String'
+-- keeps its own instance.
+instance {-# OVERLAPPABLE #-} (DuckValue a) => DuckValue [a] where
+  duckToField xs = FieldList (map duckToField xs)
+  duckLogicalType _ = LogicalTypeList (duckLogicalType (Proxy @a))
+  duckFromField = duckFromTypedField (LogicalTypeScalar LogicalTypeIdVariant)
+  duckFromTypedField logical (FieldList fvs) = traverse (duckFromTypedField (listElementType logical)) fvs
+  duckFromTypedField logical (FieldArray arr) = traverse (duckFromTypedField (listElementType logical)) (elems arr)
+  duckFromTypedField logical other = unexpectedTypedValue logical "LIST or ARRAY" other
+
+-- | A 'SizedArray' field is an ARRAY of size @n@. It reads an ARRAY and a LIST of
+-- @n@ elements, as the 'FromField' instance does. See Note [Sized arrays] in
+-- "Database.DuckDB.Simple.ToField".
+instance (KnownNat n, DuckValue a) => DuckValue (SizedArray n a) where
+  duckToField values = FieldArray (fmap duckToField (sizedArrayToArray values))
+
+  -- See Note [Sized ARRAY bounds] in "Database.DuckDB.Simple.Native".
+  duckLogicalType _ = LogicalTypeArray (duckLogicalType (Proxy @a)) (fromInteger (min (natVal (Proxy @n)) (toInteger (maxBound :: Word64))))
+  duckFromField = duckFromTypedField (LogicalTypeScalar LogicalTypeIdVariant)
+  duckFromTypedField logical value = case value of
+    FieldArray arr -> sized (elems arr)
+    FieldList entries -> sized entries
+    other -> unexpectedTypedValue logical "ARRAY" other
+    where
+      size = natVal (Proxy @n)
+      sized entries
+        | Just reason <- arraySizeReason size = conversionError (sizeError reason)
+        | otherwise = case sizedArrayFromList entries of
+            Nothing -> conversionError (sizeError (Text.pack ("the value has " <> show (length entries) <> " elements")))
+            Just values -> traverse (duckFromTypedField (listElementType logical)) values
+      sizeError reason =
+        Incompatible
+          (fieldTypeName logical value)
+          Text.empty
+          (Text.pack ("SizedArray " <> show size))
+          reason
+
+-- | Map values encode as DuckDB MAP.
+instance (Ord k, DuckValue k, DuckValue v) => DuckValue (Map.Map k v) where
+  duckToField m =
+    let pairs = Map.toList m
+    in  FieldMap [(duckToField k, duckToField v) | (k, v) <- pairs]
+  duckLogicalType _ =
+    LogicalTypeMap
+      (duckLogicalType (Proxy @k))
+      (duckLogicalType (Proxy @v))
+  duckFromField = duckFromTypedField (LogicalTypeScalar LogicalTypeIdVariant)
+  duckFromTypedField logical (FieldMap pairs) = do
+    result <- Map.fromList <$> traverse decodePair pairs
+    if Map.size result == length pairs
+      then pure result
+      else decodingError "duplicate MAP key after conversion"
+    where
+      (keyType, valueType) = mapEntryTypes logical
+      decodePair (kfv, vfv) = do
+        k <- duckFromTypedField keyType kfv
+        v <- duckFromTypedField valueType vfv
+        pure (k, v)
+  duckFromTypedField logical other = unexpectedTypedValue logical "MAP" other
+
+-- | The error of a decoder that does not read a value. The text has the form of
+-- each other read error: it names the SQL type of the value, not the value,
+-- because a value can be large.
+unexpectedValue :: String -> FieldValue -> Conversion a
+unexpectedValue expected value = conversionError (Incompatible (valueTypeName value) Text.empty (Text.pack expected) Text.empty)
+
+-- | The error of a decoder that cannot read a value with the given SQL type.
+-- It names the type as 'returnError' does.
+unexpectedTypedValue :: LogicalTypeRep -> String -> FieldValue -> Conversion a
+unexpectedTypedValue logical expected value = conversionError (Incompatible (fieldTypeName logical value) Text.empty (Text.pack expected) Text.empty)
+
+--------------------------------------------------------------------------------
+-- Generic machinery
+
+-- | A STRUCT or UNION value with its logical type metadata, produced by the
+-- generic traversal for @genericToFieldValue@. @genericLogicalType@ produces
+-- the type metadata without a value.
+data Encoded
+  = EncodedStruct (StructValue FieldValue)
+  | EncodedUnion (UnionValue FieldValue)
+
+encodedValue :: Encoded -> FieldValue
+encodedValue = \case
+  EncodedStruct sv -> FieldStruct sv
+  EncodedUnion uv -> FieldUnion uv
+
+-- | Convert a Haskell value (using its generic representation) into a DuckDB @FieldValue@.
+genericToFieldValue :: forall a. (Generic a, GToField (Rep a)) => a -> FieldValue
+genericToFieldValue = encodedValue . gToField . from
+
+-- | Give the logical DuckDB type of a Haskell type.
+genericLogicalType :: forall a. (Generic a, GToField (Rep a)) => Proxy a -> LogicalTypeRep
+genericLogicalType _ = gLogicalType (Proxy @(Rep a ()))
+
+-- | Decode a DuckDB @FieldValue@ with its generic representation. Run the
+-- result with @runConversion@. See Note [Generic decoding].
+genericFromFieldValue :: forall a. (Generic a, GFromField (Rep a)) => FieldValue -> Conversion a
+genericFromFieldValue fv = to <$> gFromField fv
+
+-- | Extract the STRUCT encoding when the value produces one.
+genericToStructValue :: forall a. (Generic a, GToField (Rep a)) => a -> Maybe (StructValue FieldValue)
+genericToStructValue value =
+  case gToField (from value) of
+    EncodedStruct sv -> Just sv
+    _ -> Nothing
+
+-- | Extract a UNION-shaped generic encoding directly when one is produced.
+genericToUnionValue :: forall a. (Generic a, GToField (Rep a)) => a -> Maybe (UnionValue FieldValue)
+genericToUnionValue value =
+  case gToField (from value) of
+    EncodedUnion uv -> Just uv
+    _ -> Nothing
+
+-- | Wrapper for deriving-via so that @instance ToField (ViaDuckDB a)@ picks up
+-- the generic encoding provided by this module.
+newtype ViaDuckDB a = ViaDuckDB {getViaDuckDB :: a}
+
+-- Type family to decide whether a representation is a sum.
+
+-- | Select sum encoding with @'True@ and product encoding with @'False@.
+type family IsSum f :: Bool where
+  IsSum (f :+: g) = 'True
+  IsSum (M1 D _ f) = IsSum f
+  IsSum (M1 C _ f) = IsSum f
+  IsSum _ = 'False
+
+-- | Generic encoding to the intermediate @Encoded@ representation. Every
+-- instance must also supply the corresponding logical type description.
+class GToField f where
+  gToField :: f p -> Encoded
+  gLogicalType :: Proxy (f p) -> LogicalTypeRep
+
+instance (GToField' (IsSum f) f) => GToField f where
+  gToField = gToField' (Proxy @(IsSum f))
+  gLogicalType _ = gLogicalType' (Proxy @(IsSum f)) (Proxy @f)
+
+-- | Select product (@'False@) or sum (@'True@) encoding with the @IsSum@ type
+-- family.
+class GToField' (isSum :: Bool) f where
+  gToField' :: Proxy isSum -> f p -> Encoded
+  gLogicalType' :: Proxy isSum -> Proxy f -> LogicalTypeRep
+
+-- Products (single constructor records)
+
+{- Note [Types without fields]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A product type with no fields encodes as the STRUCT without fields. The payload
+of a constructor with no fields in a sum type is also the STRUCT without fields,
+and the type of its UNION member is the STRUCT type without fields. DuckDB shows
+this value as {}. The value is not NULL.
+
+- Why not NULL. NULL is the encoding of Nothing in a field of the type Maybe a.
+  If a value without fields encodes as NULL, then Just x and Nothing are the
+  same value in a field.
+
+- The decoders also accept NULL for a product type with no fields and for the
+  payload of a constructor with no fields. NULL decodes as the value with
+  no fields.
+-}
+
+-- | Product encoding: single-constructor datatypes become STRUCT values. See
+-- Note [Types without fields].
+instance (GStruct f) => GToField' 'False (M1 D meta (M1 C c f)) where
+  gToField' _ (M1 (M1 inner)) =
+    let comps = gStructValues inner
+        typeComps = gStructTypes (Proxy @(f _))
+        names = resolveNames (zip progIndices (map fcName comps))
+        valueArray = listArrayFrom names (map fcValue comps)
+        typeArray = listArrayFrom names (map fcValue typeComps)
+        indexMap = Map.fromList (zip names [0 ..])
+    in  EncodedStruct
+          StructValue
+            { structValueFields = valueArray
+            , structValueTypes = typeArray
+            , structValueIndex = indexMap
+            }
+    where
+      progIndices = [0 :: Int ..]
+  gLogicalType' _ _ =
+    let typeComps = gStructTypes (Proxy @(f _))
+        names = resolveNames (zip [0 :: Int ..] (map fcName typeComps))
+        typeArray = listArrayFrom names (map fcValue typeComps)
+    in  LogicalTypeStruct typeArray
+
+-- Sums (encode as union)
+
+-- | Sum encoding: multi-constructor datatypes become UNION values.
+instance (GSum f) => GToField' 'True (M1 D meta f) where
+  gToField' _ (M1 value) =
+    let members = gSumMembers (Proxy @(f _))
+        membersArray = listArray (0, length members - 1) members
+        (idx, payload) = gSumEncode value
+        label = unionMemberName (members !! idx)
+    in  EncodedUnion
+          UnionValue
+            { unionValueIndex = fromIntegral idx
+            , unionValueLabel = label
+            , unionValuePayload = payload
+            , unionValueMembers = membersArray
+            }
+  gLogicalType' _ _ =
+    let members = gSumMembers (Proxy @(f _))
+        membersArray = listArray (0, length members - 1) members
+    in  LogicalTypeUnion membersArray
+
+--------------------------------------------------------------------------------
+-- GStruct: products
+
+data FieldComponent a = FieldComponent
+  { fcName :: Maybe Text
+  , fcValue :: a
+  }
+
+-- | Keep the selector names from GHC.Generics. Use @fieldN@ for positional
+-- products.
+resolveNames :: [(Int, Maybe Text)] -> [Text]
+resolveNames =
+  map pick
+  where
+    pick (_, Just n) = n
+    pick (idx, Nothing) = Text.pack ("field" <> show (idx + 1))
+
+-- | Helper that builds an @Array@ of struct fields from parallel lists of names
+-- and payloads.
+listArrayFrom :: [Text] -> [b] -> Array Int (StructField b)
+listArrayFrom names values =
+  listArray
+    (0, length values - 1)
+    (zipWith (\n v -> StructField{structFieldName = n, structFieldValue = v}) names values)
+
+-- | Collect the values and types of a product in parallel lists for encoding
+-- and decoding.
+class GStruct f where
+  gStructValues :: f p -> [FieldComponent FieldValue]
+  gStructTypes :: Proxy (f p) -> [FieldComponent LogicalTypeRep]
+
+instance GStruct U1 where
+  gStructValues _ = []
+  gStructTypes _ = []
+
+instance (GStruct a, GStruct b) => GStruct (a :*: b) where
+  gStructValues (a :*: b) = gStructValues a ++ gStructValues b
+  gStructTypes _ = gStructTypes (Proxy @(a _)) ++ gStructTypes (Proxy @(b _))
+
+instance (Selector s, DuckValue a) => GStruct (M1 S s (K1 i a)) where
+  gStructValues m@(M1 (K1 x)) =
+    let name = toMaybe (selName m)
+    in  [FieldComponent name (duckToField x)]
+  gStructTypes _ =
+    let raw = selName (undefined :: M1 S s (K1 i a) ())
+        name = toMaybe raw
+    in  [FieldComponent name (duckLogicalType (Proxy @a))]
+
+instance (GStruct f) => GStruct (M1 C c f) where
+  gStructValues (M1 x) = gStructValues x
+  gStructTypes _ = gStructTypes (Proxy @(f _))
+
+toMaybe :: String -> Maybe Text
+toMaybe name
+  | null name = Nothing
+  | otherwise = Just (Text.pack name)
+
+--------------------------------------------------------------------------------
+-- Sums (unions)
+
+-- | Describe the members of a sum type (@gSumMembers@). Encode a value as its
+-- tag and payload (@gSumEncode@), or decode them (@gSumDecode@).
+class GSum f where
+  gSumMembers :: Proxy (f p) -> [UnionMemberType]
+  gSumEncode :: f p -> (Int, FieldValue)
+  gSumDecode :: Int -> FieldValue -> Conversion (f p)
+
+instance (GSum a, GSum b) => GSum (a :+: b) where
+  gSumMembers _ = gSumMembers (Proxy @(a _)) ++ gSumMembers (Proxy @(b _))
+  gSumEncode (L1 x) = gSumEncode x
+  gSumEncode (R1 x) =
+    let leftCount = length (gSumMembers (Proxy @(a _)))
+        (idx, payload) = gSumEncode x
+    in  (idx + leftCount, payload)
+  gSumDecode idx payload =
+    let leftCount = length (gSumMembers (Proxy @(a _)))
+    in  if idx < leftCount
+          then L1 <$> gSumDecode idx payload
+          else R1 <$> gSumDecode (idx - leftCount) payload
+
+instance (Constructor c, GStruct f, GStructDecode f) => GSum (M1 C c f) where
+  gSumMembers _ =
+    [ UnionMemberType
+        { unionMemberName = Text.pack (conName (undefined :: M1 C c f p))
+        , unionMemberType =
+            let typeComps = gStructTypes (Proxy @(f _))
+                names = resolveNames (zip [0 :: Int ..] (map fcName typeComps))
+            in  LogicalTypeStruct (listArrayFrom names (map fcValue typeComps))
+        }
+    ]
+
+  -- See Note [Types without fields].
+  gSumEncode (M1 x) =
+    let comps = gStructValues x
+        typeComps = gStructTypes (Proxy @(f _))
+        names = resolveNames (zip [0 :: Int ..] (map fcName comps))
+        valueArray = listArrayFrom names (map fcValue comps)
+        typeArray = listArrayFrom names (map fcValue typeComps)
+        indexMap = Map.fromList (zip names [0 ..])
+    in  (0, FieldStruct StructValue{structValueFields = valueArray, structValueTypes = typeArray, structValueIndex = indexMap})
+  gSumDecode idx payload
+    | idx /= 0 = decodingError ("duckdb-simple: union tag mismatch (expected 0, got " <> show idx <> ")")
+    | otherwise =
+        case payload of
+          -- NULL also decodes as a value with no fields. See Note [Types without fields].
+          FieldNull -> M1 . fst <$> gStructDecodeList (Proxy @(f _)) []
+          FieldStruct structVal -> do
+            ordered <- either decodingError pure (orderStructFields (gStructTypes (Proxy @(f _))) structVal)
+            M1 <$> gStructDecodeStruct (Proxy @(f _)) ordered
+          other -> unexpectedValue "STRUCT for a member of a sum type" other
+
+-- | Match decoded fields to their selector names before product decoding.
+orderStructFields :: [FieldComponent LogicalTypeRep] -> StructValue FieldValue -> Either String (StructValue FieldValue)
+orderStructFields components sv
+  -- The fields have the order of the selectors, so the names are unique.
+  | map structFieldName fields == names = Right sv
+  | otherwise = reorder
+  where
+    names = resolveNames (zip [0 ..] (map fcName components))
+    fields = elems (structValueFields sv)
+    reorder = do
+      let byName = Map.fromList [(structFieldName field, field) | field <- fields]
+      unless (length fields <= length names) $
+        Left "duckdb-simple: extra fields when decoding struct"
+      unless (length fields == length names && Map.size byName == length names) $
+        Left "duckdb-simple: struct field names or count mismatch"
+      ordered <-
+        traverse (\name -> maybe (Left ("duckdb-simple: missing struct field " <> Text.unpack name)) Right (Map.lookup name byName)) names
+      -- The types keep the order of the fields. See Note [Column types] in
+      -- "Database.DuckDB.Simple.FromField".
+      let typeByName = Map.fromList [(structFieldName field, field) | field <- elems (structValueTypes sv)]
+          variant name = StructField name (LogicalTypeScalar LogicalTypeIdVariant)
+          orderedTypes = [fromMaybe (variant name) (Map.lookup name typeByName) | name <- names]
+      pure
+        sv{structValueFields = listArray (0, length ordered - 1) ordered, structValueTypes = listArray (0, length orderedTypes - 1) orderedTypes}
+
+--------------------------------------------------------------------------------
+-- GStructDecode: inverse of GStruct for decoding
+
+-- | Inverse of @GStruct@: decode struct payloads back into a generic product.
+class GStructDecode f where
+  gStructDecodeStruct :: Proxy (f p) -> StructValue FieldValue -> Conversion (f p)
+
+  -- | Consume a prefix of fields from left to right while decoding, returning
+  --     the reconstructed value and any remaining fields. Each field has its
+  --     type and its value.
+  gStructDecodeList :: Proxy (f p) -> [(LogicalTypeRep, FieldValue)] -> Conversion (f p, [(LogicalTypeRep, FieldValue)])
+
+instance GStructDecode U1 where
+  gStructDecodeStruct _ structVal =
+    if null (elems (structValueFields structVal))
+      then pure U1
+      else decodingError ("duckdb-simple: expected empty struct, but got " <> show (length (elems (structValueFields structVal))) <> " field(s)")
+  gStructDecodeList _ xs = pure (U1, xs)
+
+instance (GStructDecode a, GStructDecode b) => GStructDecode (a :*: b) where
+  gStructDecodeStruct proxy structVal = do
+    (decoded, rest) <- gStructDecodeList proxy (typedFields structVal)
+    unless (null rest) $
+      decodingError ("duckdb-simple: extra " <> show (length rest) <> " field(s) when decoding struct (too many fields provided)")
+    pure decoded
+  gStructDecodeList _ xs = do
+    (leftVal, rest) <- gStructDecodeList (Proxy @(a _)) xs
+    (rightVal, rest') <- gStructDecodeList (Proxy @(b _)) rest
+    pure (leftVal :*: rightVal, rest')
+
+instance (Selector s, DuckValue a) => GStructDecode (M1 S s (K1 i a)) where
+  gStructDecodeStruct _ structVal =
+    case typedFields structVal of
+      [(logical, fv)] -> M1 . K1 <$> namedField (selName (undefined :: M1 S s (K1 i a) ())) (duckFromTypedField logical fv)
+      [] -> decodingError "duckdb-simple: missing struct field (expected 1, got 0)"
+      xs -> decodingError ("duckdb-simple: expected single field struct, but got " <> show (length xs) <> " fields")
+
+  gStructDecodeList _ [] = decodingError "duckdb-simple: missing struct field (expected field but list is empty)"
+  gStructDecodeList _ ((logical, fv) : rest) = do
+    val <- namedField (selName (undefined :: M1 S s (K1 i a) ())) (duckFromTypedField logical fv)
+    pure (M1 (K1 val), rest)
+
+-- | The type and the value of each field of a STRUCT value, in order. A field
+-- with no type in the value has the type VARIANT. See Note [Column types] in
+-- "Database.DuckDB.Simple.FromField".
+typedFields :: StructValue FieldValue -> [(LogicalTypeRep, FieldValue)]
+typedFields StructValue{structValueFields, structValueTypes} =
+  zip
+    (map structFieldValue (elems structValueTypes) <> repeat (LogicalTypeScalar LogicalTypeIdVariant))
+    (map structFieldValue (elems structValueFields))
+
+-- | Name the record field in the error of its decoder, after the prefix of the
+-- library. A positional field has no name. See Note [Generic decoding].
+namedField :: String -> Conversion a -> Conversion a
+namedField name
+  | null name = id
+  | otherwise = mapConversionErrors \errors ->
+      [ toException
+          ( ConversionFailed
+              Text.empty
+              Text.empty
+              Text.empty
+              (Text.pack ("duckdb-simple: field " <> name <> ": " <> withoutPrefix (intercalate "; " (map exceptionText errors))))
+          )
+      ]
+  where
+    withoutPrefix message = fromMaybe message (stripPrefix "duckdb-simple: " message)
+
+-- | Fail a generic decoder with the supplied diagnostic text.
+decodingError :: String -> Conversion a
+decodingError = conversionError . ConversionFailed Text.empty Text.empty Text.empty . Text.pack
+
+instance (GStructDecode f) => GStructDecode (M1 C c f) where
+  gStructDecodeStruct _ structVal = M1 <$> gStructDecodeStruct (Proxy @(f _)) structVal
+  gStructDecodeList _ values = do
+    (inner, rest) <- gStructDecodeList (Proxy @(f _)) values
+    pure (M1 inner, rest)
+
+--------------------------------------------------------------------------------
+-- GFromField (inverse generic)
+
+-- | Generic decoding entry point mirroring @GToField@. This is used both by
+-- @genericFromFieldValue@ and the @ViaDuckDB@ deriving helper.
+class GFromField f where
+  gFromField :: FieldValue -> Conversion (f p)
+
+instance (GFromField' (IsSum f) f) => GFromField f where
+  gFromField = gFromField' (Proxy @(IsSum f))
+
+class GFromField' (isSum :: Bool) f where
+  gFromField' :: Proxy isSum -> FieldValue -> Conversion (f p)
+
+instance (GStruct f, GStructDecode f) => GFromField' 'False (M1 D meta (M1 C c f)) where
+  gFromField' _ = \case
+    -- NULL also decodes as a value with no fields. See Note [Types without fields].
+    FieldNull -> M1 . M1 . fst <$> gStructDecodeList (Proxy @(f _)) []
+    FieldStruct sv -> do
+      ordered <- either decodingError pure (orderStructFields (gStructTypes (Proxy @(f _))) sv)
+      M1 . M1 <$> gStructDecodeStruct (Proxy @(f _)) ordered
+    other -> unexpectedValue "STRUCT for a product type" other
+
+instance (GSum f) => GFromField' 'True (M1 D meta f) where
+  gFromField' _ = \case
+    FieldUnion uv -> do
+      let actualMembers = elems (unionValueMembers uv)
+          actualIndex = fromIntegral (unionValueIndex uv)
+      unless (actualIndex < length actualMembers) $
+        decodingError "duckdb-simple: union tag out of range"
+      unless (unionMemberName (actualMembers !! actualIndex) == unionValueLabel uv) $
+        decodingError "duckdb-simple: union tag and member name mismatch"
+      let members = gSumMembers (Proxy @(f _))
+          indexed = zip [0 ..] members
+          matching = [idx | (idx, member) <- indexed, unionMemberName member == unionValueLabel uv]
+      case matching of
+        [idx] -> M1 <$> gSumDecode idx (unionValuePayload uv)
+        _ -> decodingError "duckdb-simple: unknown union member name"
+    other -> unexpectedValue "UNION for a sum type" other
+
+instance GFromField' 'False (M1 D meta U1) where
+  gFromField' _ _ = pure (M1 U1)
+
+--------------------------------------------------------------------------------
+-- ViaDuckDB instances
+
+-- | The deriving-via version of @DuckDBColumnType@. The text is the bare name
+-- of the generic logical type, for diagnostics. The declaration is the
+-- structured generic logical type. Each field type comes from 'DuckValue'.
+-- See Note [Type declarations] in "Database.DuckDB.Simple.ToField".
+-- See Note [Sized ARRAY bounds] in
+-- <src/Database.DuckDB.Simple.Native.html Database.DuckDB.Simple.Native>.
+instance (Generic a, GToField (Rep a)) => DuckDBColumnType (ViaDuckDB a) where
+  duckdbTypeDeclaration _
+    | containsType invalidArray logical =
+        Left (Text.pack ("a generic field has no ARRAY type, because a DuckDB ARRAY must have 1 to " <> show maxArraySize <> " elements"))
+    | otherwise = Right (StructuredType logical)
+    where
+      logical = genericLogicalType (Proxy @a)
+      invalidArray (LogicalTypeArray _ size) = isJust (arraySizeReason (toInteger size))
+      invalidArray _ = False
+  duckdbColumnTypeFor _ =
+    case genericLogicalType (Proxy @a) of
+      LogicalTypeStruct{} -> Text.pack "STRUCT"
+      LogicalTypeTuple{} -> Text.pack "TUPLE"
+      LogicalTypeUnion{} -> Text.pack "UNION"
+      LogicalTypeList{} -> Text.pack "LIST"
+      LogicalTypeArray{} -> Text.pack "ARRAY"
+      LogicalTypeMap{} -> Text.pack "MAP"
+      LogicalTypeScalar dtype -> duckDBTypeToName dtype
+      LogicalTypeDecimal{} -> Text.pack "DECIMAL"
+      LogicalTypeEnum{} -> Text.pack "ENUM"
+      LogicalTypeGeometry{} -> Text.pack "GEOMETRY"
+      LogicalTypeCollatedVarchar{} -> Text.pack "VARCHAR"
+      LogicalTypeAlias name _ -> name
+
+-- | Deriving-via @ToField@ instance. A sum type binds as a UNION and a product
+-- type as a STRUCT, through the @ToField@ instances of those values. A product
+-- type with no fields binds as a STRUCT without fields. See
+-- Note [Types without fields].
+instance (Generic a, GToField (Rep a)) => ToField (ViaDuckDB a) where
+  toField (ViaDuckDB x) = case gToField (from x) of
+    EncodedUnion unionVal -> toField unionVal
+    EncodedStruct structVal -> toField structVal
+
+-- | Deriving-via @ToDuckValue@ instance. A sum type gives a UNION value and a
+-- product type a STRUCT value, through the @ToDuckValue@ instances of those
+-- values. See Note [Types without fields].
+instance (Generic a, GToField (Rep a)) => ToDuckValue (ViaDuckDB a) where
+  toDuckValue factory (ViaDuckDB x) = case gToField (from x) of
+    EncodedUnion unionVal -> toDuckValue factory unionVal
+    EncodedStruct structVal -> toDuckValue factory structVal
+
+-- | Deriving-via @FromField@ instance. It reads a STRUCT for a product type and
+-- a UNION for a sum type. Convert decoder errors to @ResultError@ with
+-- @returnError@. See Note [Generic decoding].
+instance (Generic a, GFromField (Rep a), Typeable a) => FromField (ViaDuckDB a) where
+  fromField f@Field{fieldValue} =
+    mapConversionErrorsWith
+      (\errors -> [] <$ returnError @(ViaDuckDB a) ConversionFailed f (Text.pack (intercalate "; " (map exceptionText errors))))
+      (ViaDuckDB <$> genericFromFieldValue fieldValue)
diff --git a/src/Database/DuckDB/Simple/Geometry.hs b/src/Database/DuckDB/Simple/Geometry.hs
--- a/src/Database/DuckDB/Simple/Geometry.hs
+++ b/src/Database/DuckDB/Simple/Geometry.hs
@@ -1,8 +1,12 @@
--- | Raw geometry values and conversion to 'G.Geometry' from @geometry-simple@.
+{-# LANGUAGE StrictData #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.Geometry
+-- Description : Raw geometry values and conversion to 'G.Geometry' from @geometry-simple@.
 module Database.DuckDB.Simple.Geometry (
-    RawGeometry (..),
-    fromRawGeometry,
-    toRawGeometry,
+  RawGeometry (..),
+  fromRawGeometry,
+  toRawGeometry,
 ) where
 
 import Data.ByteString (ByteString)
@@ -10,31 +14,40 @@
 import Data.Geometry.WKB (decodeWKB, encodeWKB)
 import Data.Text (Text)
 
-{- | ISO WKB bytes with an optional CRS definition.
-The definition can be an identifier, a custom name, or WKT2\/PROJJSON text.
-Reading this type copies the bytes without decoding the coordinates.
-This type has no @ToField@ instance. Bind 'rawGeometryWKB' with
-@ST_GeomFromWKB(?)@. Apply 'rawGeometryCRS' with @ST_SetCRS(..., ?)@.
-Omit @ST_SetCRS@ when the CRS is 'Nothing'. SQL NULL propagates to the geometry.
-DuckDB can normalize the byte order and CRS definition during import.
-Derived equality compares the bytes and CRS, not spatial equivalence.
--}
+-- | ISO WKB bytes with an optional CRS definition.
+-- The definition can be an identifier, a custom name, or WKT2\/PROJJSON text.
+-- Reading this type copies the bytes without decoding the coordinates.
+-- A parameter of this type binds as a GEOMETRY value with the CRS
+-- 'rawGeometryCRS'. DuckDB then casts it to the type of the parameter. A value
+-- without a CRS takes the CRS of the target. A target without a CRS removes the
+-- CRS of the value. A target with another CRS raises an error. Use
+-- @Maybe RawGeometry@ for SQL NULL. A @SizedArray@, a list, or a typed row cannot
+-- hold this type. A STRUCT, TUPLE, or UNION parameter binds a @FieldGeometry@
+-- value with its CRS. A VARIANT parameter binds one only when it has no CRS. See
+-- Note [Raw GEOMETRY parameters] in "Database.DuckDB.Simple.ToField".
+-- Parameters accept custom CRS labels, including in composite types. Binding a
+-- blank label or a label containing NUL raises an @SQLError@. Typed registrations
+-- require a recognized name or a full definition.
+-- DuckDB can normalize the byte order and CRS definition during import.
+-- The pinned native API requires the same Z/M dimensions for all collection
+-- members, including empty members. Native import rejects mixed member layouts.
+-- The standalone WKB codec preserves these layouts.
+-- Derived equality compares the bytes and CRS, not spatial equivalence.
 data RawGeometry = RawGeometry
-    { rawGeometryWKB :: !ByteString
-    , rawGeometryCRS :: !(Maybe Text)
-    }
-    deriving (Eq, Show, Read)
+  { rawGeometryWKB :: ByteString
+  , rawGeometryCRS :: Maybe Text
+  }
+  deriving (Eq, Show, Read)
 
-{- | Decode owned WKB with the standalone codec. The shape does not store CRS
-metadata. Empty multi-geometries and collections have no layout tag in the
-decoded representation. Keep the raw value when these details are needed.
--}
+-- | Decode owned WKB with the standalone codec. The shape does not store CRS
+-- metadata. Empty multi-geometries and collections have no layout tag in the
+-- decoded representation. Keep the raw value when these details are needed.
 fromRawGeometry :: RawGeometry -> Either String G.Geometry
 fromRawGeometry = decodeWKB . rawGeometryWKB
 
-{- | Encode a shape as ISO WKB with no CRS. Set 'rawGeometryCRS' on the result
-to supply a CRS definition for explicit SQL import. This does not transform
-the coordinates.
--}
+-- | Encode a shape as ISO WKB with no CRS. Set 'rawGeometryCRS' on the result
+-- to give the value a CRS definition. This does not transform
+-- the coordinates. The standalone codec can encode mixed collection layouts
+-- that the pinned native API rejects during import.
 toRawGeometry :: G.Geometry -> Either String RawGeometry
 toRawGeometry shape = (`RawGeometry` Nothing) <$> encodeWKB shape
diff --git a/src/Database/DuckDB/Simple/Internal.hs b/src/Database/DuckDB/Simple/Internal.hs
--- a/src/Database/DuckDB/Simple/Internal.hs
+++ b/src/Database/DuckDB/Simple/Internal.hs
@@ -1,453 +1,1403 @@
-{-# LANGUAGE DerivingStrategies #-}
-{-# LANGUAGE MagicHash #-}
-{-# LANGUAGE NamedFieldPuns #-}
-{-# LANGUAGE PatternSynonyms #-}
-{-# LANGUAGE StrictData #-}
-{-# OPTIONS_GHC -Wno-deprecations #-}
-
-{- |
-Module      : Database.DuckDB.Simple.Internal
-Description : Internal machinery backing the duckdb-simple API surface.
-
-This module provides access to the opaque data constructors and helper
-utilities required by the high-level API.  It is not part of the supported
-public interface; consumers should depend on @Database.DuckDB.Simple@ instead.
--}
-module Database.DuckDB.Simple.Internal (
-    -- * Data constructors (internal use only)
-    Query (..),
-    Connection (..),
-    ConnectionState (..),
-    Statement (..),
-    StatementState (..),
-    StatementStreamState (..),
-    StatementStream (..),
-    ResultMode (..),
-    StatementStreamColumn (..),
-    StatementStreamChunk (..),
-    SQLError (..),
-    toSQLError,
-
-    -- * Helpers
-    connectionClosedError,
-    statementClosedError,
-    keepAlive,
-    withDatabaseHandle,
-    withConnectionHandle,
-    withTypeCache,
-    withStatementHandle,
-    withQueryCString,
-    peekUtf8CString,
-    fetchPrepareError,
-    duckDBTypeFromName,
-    duckDBTypeToName,
-    withResult,
-    runInterruptibleQuery,
-    executePreparedResult,
-    fetchResultChunk,
-    destroyDataChunk,
-    fetchResultError,
-    throwResultError,
-    mkExecuteError,
-    withClientContext,
-    destroyClientContext,
-    destroyValue,
-    destroyLogicalType,
-    throwRegistrationError,
-) where
-
-import Control.Concurrent (forkIO, newEmptyMVar, putMVar, readMVar, threadDelay, tryReadMVar)
-import Control.Exception (Exception, SomeException, bracket, bracket_, mask, mask_, onException, throwIO, try, uninterruptibleMask_)
-import Control.Monad (when)
-import qualified Data.ByteString as BS
-import Data.IORef (IORef, readIORef)
-import Data.List (find)
-import Data.String (IsString (..))
-import Data.Text (Text)
-import qualified Data.Text as Text
-import qualified Data.Text.Encoding as TextEncoding
-import qualified Data.Text.Foreign as TextForeign
-import Database.DuckDB.FFI (
-    DuckDBClientContext,
-    DuckDBConnection,
-    DuckDBDataChunk,
-    DuckDBDatabase,
-    DuckDBErrorType,
-    DuckDBPreparedStatement,
-    DuckDBResult,
-    DuckDBState,
-    DuckDBType,
-    DuckDBValue,
-    c_duckdb_connection_get_client_context,
-    c_duckdb_destroy_client_context,
-    c_duckdb_destroy_data_chunk,
-    c_duckdb_destroy_result,
-    c_duckdb_destroy_value,
-    c_duckdb_execute_prepared,
-    c_duckdb_fetch_chunk,
-    c_duckdb_interrupt,
-    c_duckdb_prepare_error,
-    c_duckdb_result_error,
-    c_duckdb_result_error_type,
-    pattern DuckDBErrorInvalid,
-    pattern DuckDBSuccess,
- )
-import qualified Database.DuckDB.FFI as FFI
-import Database.DuckDB.FFI.Deprecated (c_duckdb_execute_prepared_streaming)
-import Database.DuckDB.Simple.FromField (FieldValue)
-import Database.DuckDB.Simple.LogicalRep (destroyLogicalType)
-import Database.DuckDB.Simple.TypeCache (TypeCache)
-import Foreign.C.String (CString)
-import Foreign.Marshal.Alloc (alloca)
-import Foreign.Marshal.Utils (fillBytes)
-import Foreign.Ptr (Ptr, nullPtr)
-import Foreign.Storable (peek, poke, sizeOf)
-import GHC.Exts (keepAlive#)
-import GHC.IO (IO (..))
-
--- | Represents a textual SQL query with UTF-8 encoding semantics.
-newtype Query = Query
-    { fromQuery :: Text
-    -- ^ Extract the underlying textual representation of the query.
-    }
-    deriving stock (Eq, Ord, Show)
-
-instance Semigroup Query where
-    Query a <> Query b = Query (a <> b)
-
-instance IsString Query where
-    fromString = Query . Text.pack
-
--- | Tracks the lifetime of a DuckDB database and connection pair.
-newtype Connection = Connection {connectionState :: IORef ConnectionState}
-
--- | Internal connection lifecycle state.
-data ConnectionState
-    = ConnectionClosed
-    | ConnectionOpen
-        { connectionDatabase :: DuckDBDatabase
-        , connectionHandle :: DuckDBConnection
-        , connectionTypeCache :: TypeCache
-        }
-
--- | Tracks the lifetime of a prepared statement.
-data Statement = Statement
-    { statementState :: IORef StatementState
-    , statementConnection :: Connection
-    , statementQuery :: Query
-    , statementStream :: IORef StatementStreamState
-    }
-
--- | Internal statement lifecycle state.
-data StatementState
-    = StatementClosed
-    | StatementOpen
-        { statementHandle :: DuckDBPreparedStatement
-        }
-
--- | Streaming execution state for prepared statements.
-data StatementStreamState
-    = StatementStreamIdle
-    | StatementStreamExhausted
-    | StatementStreamActive !StatementStream
-
--- | Streaming cursor backing an active result set.
-data StatementStream = StatementStream
-    { statementStreamResult :: Ptr DuckDBResult
-    , statementStreamColumns :: [StatementStreamColumn]
-    , statementStreamChunk :: Maybe StatementStreamChunk
-    , statementStreamMode :: ResultMode
-    }
-
--- | Select native execution. DuckDB can materialize a streaming request.
-data ResultMode = MaterializedResult | StreamingResult
-
--- | Metadata describing a result column surfaced through streaming.
-data StatementStreamColumn = StatementStreamColumn
-    { statementStreamColumnIndex :: Int
-    , statementStreamColumnName :: Text
-    , statementStreamColumnType :: DuckDBType
-    }
-
--- | Currently loaded data chunk plus iteration cursor.
-data StatementStreamChunk = StatementStreamChunk
-    { statementStreamChunkPtr :: DuckDBDataChunk
-    , statementStreamChunkSize :: Int
-    , statementStreamChunkIndex :: Int
-    , statementStreamChunkReaders :: [Int -> IO FieldValue]
-    -- ^ One reader for each column. A reader must not outlive its chunk.
-    }
-
--- | Represents an error reported by DuckDB or by duckdb-simple itself.
-data SQLError = SQLError
-    { sqlErrorMessage :: Text
-    , sqlErrorType :: Maybe DuckDBErrorType
-    , sqlErrorQuery :: Maybe Query
-    }
-    deriving stock (Eq, Show)
-
-instance Exception SQLError
-
--- | Convert an arbitrary exception into an untyped @SQLError@.
-toSQLError :: (Exception e) => e -> SQLError
-toSQLError ex =
-    SQLError
-        { sqlErrorMessage = Text.pack (show ex)
-        , sqlErrorType = Nothing
-        , sqlErrorQuery = Nothing
-        }
-
--- | Shared error value used when an operation targets a closed connection.
-connectionClosedError :: SQLError
-connectionClosedError =
-    SQLError
-        { sqlErrorMessage = Text.pack "duckdb-simple: connection is closed"
-        , sqlErrorType = Nothing
-        , sqlErrorQuery = Nothing
-        }
-
--- | Shared error value used when an operation targets a closed statement.
-statementClosedError :: Statement -> SQLError
-statementClosedError Statement{statementQuery} =
-    SQLError
-        { sqlErrorMessage = Text.pack "duckdb-simple: statement is closed"
-        , sqlErrorType = Nothing
-        , sqlErrorQuery = Just statementQuery
-        }
-
--- | Provide a UTF-8 encoded C string view of the query text.
-withQueryCString :: Query -> (CString -> IO a) -> IO a
-withQueryCString query@(Query txt) action
-    | Text.any (== '\0') txt =
-        throwIO (SQLError (Text.pack "duckdb-simple: SQL contains NUL") Nothing (Just query))
-    | otherwise = TextForeign.withCString txt action
-
--- | Copy a NUL-terminated UTF-8 string from DuckDB.
-peekUtf8CString :: CString -> IO Text
-peekUtf8CString ptr = TextEncoding.decodeUtf8 <$> BS.packCString ptr
-
--- | Execute a query and destroy its result after success or failure.
-withResult :: Connection -> Query -> (Ptr DuckDBResult -> IO DuckDBState) -> (Ptr DuckDBResult -> IO a) -> IO a
-withResult conn queryText executeResult action =
-    alloca $ \resPtr ->
-        bracket_
-            (fillBytes resPtr 0 (sizeOf (undefined :: DuckDBResult)))
-            (c_duckdb_destroy_result resPtr)
-            $ do
-                rc <- runInterruptibleQuery conn (executeResult resPtr)
-                when (rc /= DuckDBSuccess) $ do
-                    (message, errorType) <- fetchResultError resPtr
-                    throwIO (mkExecuteError queryText message errorType)
-                action resPtr
-
--- | Execute a prepared statement with the requested native result mode.
-executePreparedResult :: ResultMode -> DuckDBPreparedStatement -> Ptr DuckDBResult -> IO DuckDBState
-executePreparedResult MaterializedResult = c_duckdb_execute_prepared
-executePreparedResult StreamingResult = c_duckdb_execute_prepared_streaming
-
-{- | Fetch an owned chunk. The caller must remain masked until it records ownership.
-  Streaming fetches can execute SQL. Keep their output in a caller-owned slot
-  so cancellation can destroy a chunk that the worker has already fetched.
--}
-fetchResultChunk :: ResultMode -> Connection -> Ptr DuckDBResult -> IO DuckDBDataChunk
-fetchResultChunk MaterializedResult conn result =
-    withConnectionHandle conn $ \_ -> c_duckdb_fetch_chunk result
-fetchResultChunk StreamingResult conn result =
-    alloca $ \chunkPtr -> mask_ $ do
-        poke chunkPtr nullPtr
-        let fetch = do
-                chunk <- c_duckdb_fetch_chunk result
-                poke chunkPtr chunk
-                pure DuckDBSuccess
-        (runInterruptibleQuery conn fetch >> peek chunkPtr)
-            `onException` c_duckdb_destroy_data_chunk chunkPtr
-
--- | Destroy an owned native data chunk. A null chunk is allowed.
-destroyDataChunk :: DuckDBDataChunk -> IO ()
-destroyDataChunk chunk = alloca $ \ptr -> poke ptr chunk >> c_duckdb_destroy_data_chunk ptr
-
-{- | Run a native query while the caller can receive asynchronous exceptions.
-  Prompt cancellation requires the threaded RTS. Cleanup interrupts DuckDB and
-  waits for the worker before the caller can release native storage.
--}
-runInterruptibleQuery :: Connection -> IO DuckDBState -> IO DuckDBState
-runInterruptibleQuery conn action =
-    withConnectionHandle conn $ \handle ->
-        mask $ \restore -> do
-            done <- newEmptyMVar
-            _ <- forkIO $ do
-                outcome <- try action :: IO (Either SomeException DuckDBState)
-                putMVar done outcome
-            let cancelAndWait = do
-                    finished <- tryReadMVar done
-                    case finished of
-                        Just _ -> pure ()
-                        Nothing -> do
-                            -- DuckDB clears the interrupt flag at query entry.
-                            -- Repeat the interrupt to cover cancellation before entry.
-                            c_duckdb_interrupt handle
-                            threadDelay interruptRetryDelayMicros
-                            cancelAndWait
-            -- A second exception must not release storage still used by the worker.
-            -- Native code and Haskell callbacks must return before cleanup can finish.
-            outcome <- restore (readMVar done) `onException` uninterruptibleMask_ cancelAndWait
-            either throwIO pure outcome
-
-{- | Retry cancellation at most 100 times per second while native work finishes.
-DuckDB can clear an earlier interrupt at query entry. This interval avoids
-busy-spinning and can add up to one interval to completion detection.
--}
-interruptRetryDelayMicros :: Int
-interruptRetryDelayMicros = 10 * 1000
-
-{- | The column type names that 'Database.DuckDB.Simple.ToField.DuckDBColumnType'
-instances use, and the types they denote. Each type has one name.
--}
-duckDBTypeNames :: [(Text, DuckDBType)]
-duckDBTypeNames =
-    map
-        (\(name, dtype) -> (Text.pack name, dtype))
-        [ ("BOOLEAN", FFI.DuckDBTypeBoolean)
-        , ("TINYINT", FFI.DuckDBTypeTinyInt)
-        , ("SMALLINT", FFI.DuckDBTypeSmallInt)
-        , ("INTEGER", FFI.DuckDBTypeInteger)
-        , ("BIGINT", FFI.DuckDBTypeBigInt)
-        , ("HUGEINT", FFI.DuckDBTypeHugeInt)
-        , ("UTINYINT", FFI.DuckDBTypeUTinyInt)
-        , ("USMALLINT", FFI.DuckDBTypeUSmallInt)
-        , ("UINTEGER", FFI.DuckDBTypeUInteger)
-        , ("UBIGINT", FFI.DuckDBTypeUBigInt)
-        , ("UHUGEINT", FFI.DuckDBTypeUHugeInt)
-        , ("FLOAT", FFI.DuckDBTypeFloat)
-        , ("DOUBLE", FFI.DuckDBTypeDouble)
-        , ("DATE", FFI.DuckDBTypeDate)
-        , ("TIME", FFI.DuckDBTypeTime)
-        , ("TIMETZ", FFI.DuckDBTypeTimeTz)
-        , ("TIMESTAMP", FFI.DuckDBTypeTimestamp)
-        , ("TIMESTAMPTZ", FFI.DuckDBTypeTimestampTz)
-        , ("INTERVAL", FFI.DuckDBTypeInterval)
-        , ("TEXT", FFI.DuckDBTypeVarchar)
-        , ("BLOB", FFI.DuckDBTypeBlob)
-        , ("GEOMETRY", FFI.DuckDBTypeGeometry)
-        , ("VARIANT", FFI.DuckDBTypeVariant)
-        , ("UUID", FFI.DuckDBTypeUUID)
-        , ("BIT", FFI.DuckDBTypeBit)
-        , ("BIGNUM", FFI.DuckDBTypeBigNum)
-        , -- NULL gives an element type to Maybe values without data.
-          ("NULL", FFI.DuckDBTypeSQLNull)
-        ]
-
--- | Find the type that a column type name denotes.
-duckDBTypeFromName :: Text -> Maybe DuckDBType
-duckDBTypeFromName name = lookup name duckDBTypeNames
-
--- | Find the column type name of a type. Other types use their 'Show' text.
-duckDBTypeToName :: DuckDBType -> Text
-duckDBTypeToName dtype =
-    maybe (Text.pack (show dtype)) fst (find ((== dtype) . snd) duckDBTypeNames)
-
-{- | Read the error message of a prepared statement as UTF-8. Use the fallback
-when DuckDB reports no message.
--}
-fetchPrepareError :: Text -> DuckDBPreparedStatement -> IO Text
-fetchPrepareError fallback statement = do
-    messagePtr <- c_duckdb_prepare_error statement
-    if messagePtr == nullPtr then pure fallback else peekUtf8CString messagePtr
-
--- | Copy a result error while its native result remains alive.
-fetchResultError :: Ptr DuckDBResult -> IO (Text, Maybe DuckDBErrorType)
-fetchResultError resultPtr = do
-    msgPtr <- c_duckdb_result_error resultPtr
-    message <-
-        if msgPtr == nullPtr
-            then pure (Text.pack "duckdb-simple: query failed")
-            else peekUtf8CString msgPtr
-    errorType <- c_duckdb_result_error_type resultPtr
-    pure (message, if errorType == DuckDBErrorInvalid then Nothing else Just errorType)
-
--- | Attach the query and native error category to an execution error.
-mkExecuteError :: Query -> Text -> Maybe DuckDBErrorType -> SQLError
-mkExecuteError queryText message errorType =
-    SQLError
-        { sqlErrorMessage = message
-        , sqlErrorType = errorType
-        , sqlErrorQuery = Just queryText
-        }
-
--- | Report a fetch failure before treating a null chunk as end of input.
-throwResultError :: Query -> Ptr DuckDBResult -> IO ()
-throwResultError queryText resPtr = do
-    errorPtr <- c_duckdb_result_error resPtr
-    when (errorPtr /= nullPtr) $ do
-        (message, errorType) <- fetchResultError resPtr
-        throwIO (mkExecuteError queryText message errorType)
-
--- | Keep the weak-finalizer owner alive until the native operation returns.
-keepAlive :: a -> IO b -> IO b
-keepAlive owner (IO action) = IO (\state -> keepAlive# owner state action)
-
--- | Internal helper for safely accessing the underlying prepared statement.
-withStatementHandle :: Statement -> (DuckDBPreparedStatement -> IO a) -> IO a
-withStatementHandle stmt@Statement{statementState, statementConnection} action =
-    keepAlive stmt $
-        withConnectionHandle statementConnection $ \_ -> do
-            state <- readIORef statementState
-            case state of
-                StatementClosed -> throwIO (statementClosedError stmt)
-                StatementOpen{statementHandle} -> action statementHandle
-
--- | Internal helper for safely accessing the underlying connection handle.
-withConnectionHandle :: Connection -> (DuckDBConnection -> IO a) -> IO a
-withConnectionHandle conn@Connection{connectionState} action =
-    keepAlive conn $ do
-        state <- readIORef connectionState
-        case state of
-            ConnectionClosed -> throwIO connectionClosedError
-            ConnectionOpen{connectionHandle} -> action connectionHandle
-
--- | Borrow the type cache of an open connection.
-withTypeCache :: Connection -> (TypeCache -> IO a) -> IO a
-withTypeCache conn@Connection{connectionState} action =
-    keepAlive conn $ do
-        state <- readIORef connectionState
-        case state of
-            ConnectionClosed -> throwIO connectionClosedError
-            ConnectionOpen{connectionTypeCache} -> action connectionTypeCache
-
--- | Internal helper for safely accessing the underlying database handle.
-withDatabaseHandle :: Connection -> (DuckDBDatabase -> IO a) -> IO a
-withDatabaseHandle conn@Connection{connectionState} action =
-    keepAlive conn $ do
-        state <- readIORef connectionState
-        case state of
-            ConnectionClosed -> throwIO connectionClosedError
-            ConnectionOpen{connectionDatabase} -> action connectionDatabase
-
--- | Acquire the client context for the connection, destroying it after the action.
-withClientContext :: Connection -> (DuckDBClientContext -> IO a) -> IO a
-withClientContext conn action =
-    withConnectionHandle conn $ \connPtr ->
-        bracket
-            (alloca $ \ctxPtr -> c_duckdb_connection_get_client_context connPtr ctxPtr >> peek ctxPtr)
-            destroyClientContext
-            action
-
--- | Destroy a client context handle.
-destroyClientContext :: DuckDBClientContext -> IO ()
-destroyClientContext ctx =
-    alloca $ \ptr -> poke ptr ctx >> c_duckdb_destroy_client_context ptr
-
--- | Destroy a value handle.
-destroyValue :: DuckDBValue -> IO ()
-destroyValue value =
-    alloca $ \ptr -> poke ptr value >> c_duckdb_destroy_value ptr
-
--- | Throw a standardised registration error.
-throwRegistrationError :: String -> IO a
-throwRegistrationError label =
-    throwIO
-        SQLError
-            { sqlErrorMessage = Text.pack ("duckdb-simple: " <> label <> " failed")
-            , sqlErrorType = Nothing
-            , sqlErrorQuery = Nothing
-            }
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE FlexibleContexts #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE MagicHash #-}
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE StrictData #-}
+{-# LANGUAGE TupleSections #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.Internal
+-- Description : Native V2 ownership and execution used by the public API.
+module Database.DuckDB.Simple.Internal (
+  module Database.DuckDB.Simple.Native,
+  Environment (..),
+  EnvironmentState (..),
+  Instance (..),
+  InstanceState (..),
+  Connection (..),
+  ConnectionOptions (..),
+  defaultConnectionOptions,
+  defaultCallbackLockWait,
+  defaultAggregateStripes,
+  defaultArrowBatchSize,
+  ConnectionState (..),
+  Statement (..),
+  StatementState (..),
+  StatementStreamState (..),
+  StatementStream (..),
+  ResultMode (..),
+  StatementStreamColumn (..),
+  StatementStreamChunk (..),
+  createEnvironment,
+  closeEnvironment,
+  createInstance,
+  closeInstance,
+  createConnection,
+  closeConnection,
+  closeStatementState,
+  createStatementWithCollections,
+  createStatementFromParsed,
+  createStatementFromParsedWithCollections,
+  withParsedStatements,
+  withCollectionStatement,
+  statementSchemas,
+  withStatementSchemas,
+  clearStatementSchemas,
+  withKeptParameterTypes,
+  preparedParameterType,
+  storeBoundValue,
+  clearBoundValues,
+  cleanupStatementStreamRef,
+  finalizeStream,
+  finalizeChunk,
+  connectionClosedError,
+  statementClosedError,
+  keepAlive,
+  withInstanceHandle,
+  withDatabaseHandle,
+  withConnectionHandle,
+  withConnectionLock,
+  withResultWindow,
+  instanceCastFactory,
+  readConnectionVariant,
+  withStatementHandle,
+  withQueryCString,
+  withQueryError,
+  peekUtf8CString,
+  duckDBTypeFromName,
+  duckDBTypeToName,
+  withResult,
+  runInterruptibleQuery,
+  executePreparedResult,
+  executeParsedResult,
+  executeParsedStatement,
+  executePreparedArrowResult,
+  withArrowResult,
+  clearArrowResult,
+  fetchResultChunk,
+  destroyDataChunk,
+) where
+
+import Control.Concurrent (
+  MVar,
+  ThreadId,
+  forkIO,
+  modifyMVarMasked,
+  myThreadId,
+  newEmptyMVar,
+  newMVar,
+  putMVar,
+  readMVar,
+  swapMVar,
+  takeMVar,
+  threadDelay,
+  tryReadMVar,
+  tryTakeMVar,
+  withMVar,
+ )
+import Control.Exception (
+  SomeException,
+  allowInterrupt,
+  bracket,
+  bracketOnError,
+  bracket_,
+  catch,
+  finally,
+  mask,
+  mask_,
+  onException,
+  throwIO,
+  try,
+  uninterruptibleMask_,
+ )
+import Control.Monad (foldM, forM, forM_, join, unless, void, when)
+import Data.Array (Array, bounds, inRange, listArray, (!))
+import qualified Data.ByteString as BS
+import Data.Coerce (Coercible, coerce)
+import Data.IORef (IORef, atomicModifyIORef', atomicWriteIORef, mkWeakIORef, modifyIORef', newIORef, readIORef, writeIORef)
+import qualified Data.IntMap.Strict as IntMap
+import Data.List (dropWhileEnd, find, intercalate, partition)
+import Data.Maybe (fromMaybe, isJust)
+import Data.Text (Text)
+import qualified Data.Text as Text
+import qualified Data.Text.Encoding as Text
+import qualified Data.Text.Foreign as TextForeign
+import Database.DuckDB.Simple.CallbackMark (hasCallbackMark)
+import Database.DuckDB.Simple.Conversion (Conversion)
+import Database.DuckDB.Simple.FromField (FieldValue)
+import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep)
+import Database.DuckDB.Simple.Materialize (prepareVariantReader)
+import Database.DuckDB.Simple.Native hiding (arraySizeReason, maxArraySize)
+import Database.DuckDB.Simple.TypeScope (TypeScope, closeTypeScope)
+import Database.DuckDB.Simple.V2.LogicalRep (logicalTypeToBaseRep)
+import Database.DuckDB.Simple.VariantCodec (VariantState, destroyVariantState, newVariantState, variantConnection)
+import Foreign.C.ConstPtr (ConstPtr (..))
+import Foreign.C.String (CString)
+import Foreign.C.Types (CChar)
+import Foreign.Marshal.Alloc (alloca)
+import Foreign.Marshal.Array (withArray)
+import Foreign.Ptr (nullPtr)
+import Foreign.Storable (peek, poke)
+import GHC.Exts (keepAlive#)
+import GHC.IO (IO (..))
+import GHC.Weak.Finalize (getFinalizerExceptionHandler)
+import System.Mem.Weak (Weak, deRefWeak, finalize)
+import System.Timeout (timeout)
+
+{- Note [Native handle ownership]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The native handles form a tree. An environment owns its instances, an instance
+owns its connections, and a connection owns its prepared statements. The open
+state of each parent holds a registry of its children (Children). Each child
+value also holds its parent: instanceEnvironment, connectionInstance, and
+statementConnection.
+
+A registry entry is a weak pointer and an MVar. The key of the weak pointer is
+the state IORef of the child, so the registry does not keep a live child
+reachable. The finalizer of the weak pointer runs the cleanup of the child, and
+then it puts the MVar (registerChild). The cleanup closes the state of the
+child, and it keeps the parent alive until the cleanup ends (keepAlive). A
+child thus closes in one of three ways: by an explicit close, by the close of
+its parent, or by the finalizer after the child becomes unreachable. A close
+first replaces the state with the closed state
+(joinCleanup). A close of a closed state has no effect. Thus a finalizer after
+an explicit close has no effect.
+
+A parent closes its children before it destroys its own native handle
+(closeChildren). Thus the close order is statement, connection, instance, and
+environment. finishChild runs the finalizer of one child, and it waits for the
+MVar of that child. The MVar tells that the cleanup is complete, also when the
+cleanup runs in another thread. A parent marks its state closed before it
+closes its children. A create function raises an error when the state of its
+parent is closed. A close must not start while the parent creates a child (see
+closeEnvironment and closeInstance).
+
+The garbage collector releases a child first. The finalizer of a parent runs
+after the references to the parent drop. The collector runs the finalizers of
+one collection in sequence in one thread, and a parent waits for its children.
+A cleanup in that thread can wait for a child finalizer that is behind it.
+Thus the finalizers of instances and connections run in new threads
+(forkFinalizer). A statement has no children, so its finalizer runs in the
+thread of the collector.
+
+The environment has no parent and no registry entry. createEnvironment gives
+its state a weak pointer of its own, with a finalizer in a new thread.
+
+openWithOptions makes a private environment and instance for one connection.
+The connection keeps an action that closes them (connectionReleaseParent). An
+explicit close of the connection runs this action, and the finalizer of the
+connection does not. Then the finalizers of the private instance and
+environment close them.
+
+A function that borrows a native handle, for example withConnectionHandle, runs
+its action under keepAlive of the owner. Thus the finalizer of the owner does
+not destroy the handle while the action uses it.
+-}
+
+-- | Track child finalizers without retaining live children. See
+-- Note [Native handle ownership].
+newtype Children a = Children (IORef [(Weak (IORef a), MVar ())])
+
+-- | Create an empty child registry.
+newChildren :: IO (Children a)
+newChildren = Children <$> newIORef []
+
+-- | Register a child and remove completed entries. The first argument runs
+-- the finalizer of the child. Use 'forkFinalizer' for a child that has children.
+-- See Note [Native handle ownership].
+registerChild :: (IO () -> IO ()) -> (a -> Bool) -> Children a -> IORef a -> IO () -> IO ()
+registerChild runFinalizer isOpen (Children children) child cleanup = mask_ do
+  previous <- readIORef children
+  finished <- fmap concat $ forM previous \entry@(weak, done) ->
+    deRefWeak weak >>= \case
+      Nothing -> finishChild entry >> pure [done]
+      Just ref -> do
+        state <- readIORef ref
+        if isOpen state then pure [] else finishChild entry >> pure [done]
+  -- Finish stale cleanup before transferring ownership of the new child.
+  done <- newEmptyMVar
+  weak <- mkWeakIORef child (runFinalizer (cleanup `finally` putMVar done ()))
+  -- Remove only finished snapshot entries. Keep concurrent registrations.
+  atomicModifyIORef' children $ \current ->
+    ((weak, done) : filter (\(_, completed) -> completed `notElem` finished) current, ())
+
+-- | Run a finalizer in a new thread. Report an exception as the collector
+-- reports it for a finalizer. See Note [Native handle ownership].
+forkFinalizer :: IO () -> IO ()
+forkFinalizer cleanup =
+  void . forkIO $
+    cleanup `catch` \(err :: SomeException) -> getFinalizerExceptionHandler >>= ($ err)
+
+-- | Run a child finalizer and wait for its completion. See
+-- Note [Native handle ownership].
+finishChild :: (Weak (IORef a), MVar ()) -> IO ()
+finishChild (weak, done) = uninterruptibleMask_ (finalize weak `finally` readMVar done)
+
+-- | Complete child finalizers before their parent closes. See
+-- Note [Native handle ownership].
+closeChildren :: Children a -> IO ()
+closeChildren (Children children) = atomicModifyIORef' children ([],) >>= cleanupAll . map finishChild
+
+-- | Run every cleanup action in order, even when an earlier action throws.
+cleanupAll :: [IO ()] -> IO ()
+cleanupAll = foldr finally (pure ())
+
+-- | A native environment shared by one or more instances.
+newtype Environment = Environment {environmentState :: IORef EnvironmentState}
+
+-- | Internal environment state.
+data EnvironmentState = EnvironmentClosed | EnvironmentOpen DuckDBV2EnvironmentHandle (Children InstanceState)
+
+-- | An instance with catalogs and configuration shared by its connections.
+data Instance = Instance {instanceState :: IORef InstanceState, instanceEnvironment :: Environment}
+
+-- | Internal instance state.
+data InstanceState = InstanceClosed | InstanceOpen DuckDBV2InstanceHandle DuckDBV2FactoryHandle (Children ConnectionState)
+
+-- | A connection that retains its instance until it closes.
+data Connection = Connection
+  { connectionState :: IORef ConnectionState
+  , connectionInstance :: Instance
+  , connectionLock :: MVar ()
+  -- ^ Held while a native result of this connection runs, and for each fetch
+  -- of an explicit stream. A DuckDB callback waits for it at most
+  -- 'connectionCallbackLockWait'. See 'withConnectionLock' and
+  -- Note [Connection lock].
+  , connectionWindow :: IORef (Maybe ThreadId)
+  -- ^ The helper thread that runs the current result. See 'withResultWindow'
+  -- and Note [Result window].
+  , connectionOptions :: ConnectionOptions
+  -- ^ The checked options of the open. 'withConnectionLock' reads
+  -- 'connectionCallbackLockWait', a typed aggregate reads
+  -- 'connectionAggregateStripes', and 'executePreparedArrowResult' reads
+  -- 'connectionArrowBatchSize'.
+  }
+
+-- | Settings that duckdb-simple applies when it opens a connection.
+data ConnectionOptions = ConnectionOptions
+  { connectionConfig :: [(Text, Text)]
+  -- ^ DuckDB configuration flags. 'Database.DuckDB.Simple.openWithOptions'
+  --     applies them when it creates the instance, as
+  --     'Database.DuckDB.Simple.openWithConfig' does.
+  --     'Database.DuckDB.Simple.connectWithOptions' applies them to a new
+  --     connection of a running instance, so options that DuckDB accepts only
+  --     at startup fail there. 'Database.DuckDB.Simple.connectWithOptions'
+  --     writes each option with its default scope. An option whose default
+  --     scope is GLOBAL thus changes the instance. This change applies to all
+  --     connections of the instance.
+  , connectionCallbackLockWait :: Maybe Int
+  -- ^ The longest time in microseconds that a DuckDB callback waits for the
+  --     lock of this connection. A statement of a callback on the connection
+  --     that runs the callback waits for this lock. After the bound, the
+  --     statement raises an t'SQLError' of the type 'ErrorResourceInUse'. For
+  --     most callbacks, the outer statement then fails. The bound applies
+  --     also to a callback that uses this connection while another statement
+  --     runs on it. 'Nothing' sets no bound. The default is
+  --     'defaultCallbackLockWait'. The open rejects a negative value.
+  --     "Database.DuckDB.Simple.Function" gives the cases that the bound does
+  --     not cover.
+  , connectionAggregateStripes :: Int
+  -- ^ The number of stripes in the state table of each typed aggregate
+  --     function that 'Database.DuckDB.Simple.createAggregate' registers
+  --     through this connection. The registration keeps the number, also when
+  --     another connection calls the aggregate. The table holds the live
+  --     aggregate states. Two DuckDB threads that change the table wait for
+  --     each other only when they change the same stripe. No result depends on
+  --     the number. The default is 'defaultAggregateStripes'. The open rejects
+  --     a number that is not positive. The library sets no upper limit. Each
+  --     bind of each call site (a call of the aggregate in a query) makes one
+  --     IORef for each stripe.
+  , connectionArrowBatchSize :: Int
+  -- ^ The largest number of rows in one Arrow array of an Arrow fold on this
+  --     connection ("Database.DuckDB.Simple.Arrow" and
+  --     "Database.DuckDB.Simple.Streaming"). DuckDB can give shorter arrays.
+  --     The default is 'defaultArrowBatchSize'. The open rejects a value that is
+  --     not positive. For the batch size of DuckDB, write 131072.
+  }
+  deriving (Eq, Show)
+
+-- | Open without configuration flags and use the default callback lock wait,
+-- aggregate stripe count, and Arrow batch size.
+defaultConnectionOptions :: ConnectionOptions
+defaultConnectionOptions =
+  ConnectionOptions
+    { connectionConfig = []
+    , connectionCallbackLockWait = Just defaultCallbackLockWait
+    , connectionAggregateStripes = defaultAggregateStripes
+    , connectionArrowBatchSize = defaultArrowBatchSize
+    }
+
+-- | The default of 'connectionCallbackLockWait': 10 seconds, in microseconds.
+defaultCallbackLockWait :: Int
+defaultCallbackLockWait = 10000000
+
+-- | The default of 'connectionAggregateStripes': 64 stripes. See
+-- Note [State table stripes] in
+-- <src/Database.DuckDB.Simple.Typed.Aggregate.html Database.DuckDB.Simple.Typed.Aggregate>.
+defaultAggregateStripes :: Int
+defaultAggregateStripes = 64
+
+-- | The default of 'connectionArrowBatchSize': 2048 rows.
+defaultArrowBatchSize :: Int
+defaultArrowBatchSize = 2048
+
+-- | Internal connection state.
+data ConnectionState
+  = ConnectionClosed
+  | ConnectionOpen
+      { connectionHandle :: DuckDBV2ConnectionHandle
+      , connectionDecoder :: MVar (Maybe VariantState)
+      , connectionStatements :: Children StatementState
+      , connectionReleaseParent :: IO ()
+      }
+
+-- | A prepared statement and its owned bindings and cursor.
+data Statement = Statement
+  { statementState :: IORef StatementState
+  , statementConnection :: Connection
+  , statementQuery :: Query
+  , statementStream :: IORef StatementStreamState
+  , statementArrowResult :: IORef DuckDBV2ArrowResultHandle
+  , statementBindings :: IORef (IntMap.IntMap DuckDBV2ValueHandle)
+  , statementParameterNames :: Array Int Text
+  -- ^ The parameter names in binding order. The first index is 1.
+  , statementParameterTypes :: IORef (Maybe (IntMap.IntMap (Maybe LogicalTypeRep)))
+  -- ^ The kept parameter types while 'withKeptParameterTypes' runs. Otherwise
+  -- Nothing. See Note [Statement schemas].
+  }
+
+-- | Internal prepared statement state.
+data StatementState
+  = StatementClosed
+  | StatementOpen
+      { statementHandle :: DuckDBV2PreparedStatementHandle
+      , statementParsed :: DuckDBV2SqlStatementHandle
+      , statementSchemaCache :: IORef (Maybe (DuckDBV2SchemaHandle, DuckDBV2SchemaHandle))
+      }
+
+{- Note [Statement cursor]
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+The cursor of a statement (statementStream) is in one of three states.
+
+- StatementStreamIdle. The statement has no result. The next fetch
+  (nextRowWith in "Database.DuckDB.Simple.Result") executes the statement in
+  the mode of that fetch, and the cursor becomes active. A result that is not a
+  query result or a count of changed rows gives no rows, and the cursor becomes
+  exhausted.
+
+- StatementStreamActive. The cursor owns a result. Each next fetch reads from
+  this result in the mode of the result, also when the fetch asks for the
+  other mode. A materialized result has all its chunks in
+  statementStreamPendingChunks, and its result handle is null. A streaming
+  result keeps its result handle open, and it fetches each next chunk from
+  DuckDB.
+
+- StatementStreamExhausted. The cursor has no result, and each fetch gives no
+  row. A fetch that raises an error while it reads from an active cursor also
+  makes the cursor exhausted.
+
+Only a reset makes the cursor idle again: resetStatementStream, or the close of
+the statement (closeStatementState). Both release an active result with
+cleanupStatementStreamRef.
+
+The cursor owns each native chunk that it holds. fetchChunk writes a new chunk
+to the cursor before it reads the metadata of the chunk or makes the readers.
+Thus a release of the cursor also releases the chunk. finalizeStream closes the metadata scope, then releases
+the current chunk, the pending chunks, and the result.
+
+An effectful decoder can fetch again, reset the statement, or close it.
+consumeStream copies the field values and advances the cursor before it runs
+the decoder. It releases the chunk at its last row. Field metadata belongs to
+the result, not the chunk, and a reset or close invalidates that metadata.
+The decoder can also start a new execution and then fail. Error cleanup
+compares the metadata scopes by identity: each execution owns a distinct
+scope, so cleanup cannot release a replacement result.
+-}
+
+-- | Cursor state. Exhaustion persists until the caller resets the statement.
+-- See Note [Statement cursor].
+data StatementStreamState = StatementStreamIdle | StatementStreamExhausted | StatementStreamActive StatementStream
+
+-- | An execution cursor or an owned collection of materialized chunks. See
+-- Note [Statement cursor].
+data StatementStream = StatementStream
+  { statementStreamResult :: DuckDBV2ResultHandle
+  , statementStreamTypes :: TypeScope
+  , statementStreamColumns :: [StatementStreamColumn]
+  , statementStreamPendingChunks :: [DuckDBV2DataChunkHandle]
+  , statementStreamChunk :: Maybe StatementStreamChunk
+  }
+
+-- | Select materialization before decoding or incremental native execution.
+data ResultMode = MaterializedResult | StreamingResult deriving (Eq, Show)
+
+-- | Metadata for one result column.
+data StatementStreamColumn = StatementStreamColumn
+  { statementStreamColumnIndex :: Int
+  , statementStreamColumnName :: Text
+  , statementStreamColumnType :: Conversion LogicalTypeRep
+  -- ^ The scoped type of the column, converted on demand through
+  -- 'Database.DuckDB.Simple.FromField.fieldType'.
+  -- See Note [Column types] in "Database.DuckDB.Simple.FromField".
+  , statementStreamColumnTree :: IORef (Maybe LogicalTypeRep)
+  -- ^ The type tree of the column, converted from the vector of the first chunk
+  -- that needs it. Each execution makes new columns, so the tree lives for one
+  -- execution. See Note [Type trees] in
+  -- <src/Database.DuckDB.Simple.Materialize.html Database.DuckDB.Simple.Materialize>.
+  , statementStreamColumnLabels :: IORef (IntMap.IntMap Text)
+  -- ^ The ENUM labels that the readers of the column read, by index. They live
+  -- for one execution, as the tree. See Note [ENUM labels] in
+  -- <src/Database.DuckDB.Simple.Materialize.html Database.DuckDB.Simple.Materialize>.
+  }
+
+-- | One owned chunk and the readers that borrow its vectors.
+data StatementStreamChunk = StatementStreamChunk
+  { statementStreamChunkPtr :: DuckDBV2DataChunkHandle
+  , statementStreamChunkSize :: Int
+  , statementStreamChunkIndex :: Int
+  , statementStreamChunkReaders :: [Int -> IO FieldValue]
+  }
+
+-- | Create an environment. Close it after all related work finishes. See
+-- Note [Native handle ownership].
+createEnvironment :: IO Environment
+createEnvironment = mask_ do
+  checkLibraryVersion
+  raw <- output c_duckdb_v2_environment_create
+  children <- newChildren
+  ref <- newIORef (EnvironmentOpen raw children)
+  _ <- mkWeakIORef ref (forkFinalizer (closeEnvironmentState ref))
+  pure (Environment ref)
+
+-- | Require the DuckDB release that the V2 bindings describe. Upstream marks
+-- the V2 API as unstable, so another release can change its functions.
+checkLibraryVersion :: IO ()
+checkLibraryVersion = do
+  actual <- output c_duckdb_v2_library_version >>= readText
+  unless (actual == expected) $
+    throwIO
+      ( SQLError
+          ( "duckdb-simple: the V2 API requires DuckDB "
+              <> expected
+              <> ", but the loaded library is "
+              <> actual
+              <> ". DuckDB marks the V2 API as unstable, so each DuckDB release needs its own release of duckdb-ffi and duckdb-simple."
+          )
+          Nothing
+          Nothing
+          Nothing
+      )
+  where
+    expected = Text.pack ('v' : intercalate "." (map show [dUCKDB_V2_API_VERSION_MAJOR, dUCKDB_V2_API_VERSION_MINOR, dUCKDB_V2_API_VERSION_PATCH]))
+
+-- | Close an environment and its instances and connections.
+-- Wait for child creation and all descendant operations to finish before closing.
+-- DuckDB refuses to destroy the environment while an instance is alive that
+-- 'createInstance' did not create. In this case, this function closes the
+-- instances from 'createInstance' and their connections, raises an t'SQLError'
+-- with the type 'ErrorResourceInUse', and keeps the environment open.
+-- Destroy the other instance, then close the environment again.
+-- After a successful close, a second close has no effect.
+closeEnvironment :: Environment -> IO ()
+closeEnvironment Environment{environmentState} = closeEnvironmentState environmentState
+
+-- | Mark the environment closed before releasing its native state, so that a
+-- 'createInstance' that starts after the mark raises an error. A
+-- 'createInstance' that read the open state before the mark can still register
+-- its instance. Thus the caller must wait for child creation before the close
+-- (see 'closeEnvironment'). If the native destroy refuses with
+-- @ERROR_RESOURCE_IN_USE@, the native environment is still alive. In this case,
+-- put back the open state with the same child registry, and raise the error.
+-- 'closeChildren' empties the registry, and a later 'createInstance' can register
+-- in it. After a different error, the state stays closed, because the header does
+-- not say that the handle stays valid.
+closeEnvironmentState :: IORef EnvironmentState -> IO ()
+closeEnvironmentState ref = mask_ $ joinCleanup ref \case
+  EnvironmentClosed -> (EnvironmentClosed, pure ())
+  EnvironmentOpen raw children ->
+    ( EnvironmentClosed
+    , cleanupAll
+        [ closeChildren children
+        , destroy c_duckdb_v2_environment_destroy raw `catch` \(err :: SQLError) -> do
+            when (sqlErrorType err == Just ErrorResourceInUse) (atomicWriteIORef ref (EnvironmentOpen raw children))
+            throwIO err
+        ]
+    )
+
+-- | Create an instance with configuration applied before its first connection.
+createInstance :: Environment -> [(Text, Text)] -> IO Instance
+createInstance environment@Environment{environmentState} settings = keepAlive environment $ mask_ do
+  (rawEnvironment, children) <-
+    readIORef environmentState >>= \case
+      EnvironmentClosed -> throwIO (SQLError "duckdb-simple: environment is closed" Nothing Nothing Nothing)
+      EnvironmentOpen raw children -> pure (raw, children)
+  when (any (\(name, value) -> Text.any (== '\0') name || Text.any (== '\0') value) settings) $
+    throwInvalidArgument "configuration contains NUL"
+  let hasWhitelist = any ((`elem` ["allowed_directories", "allowed_paths"]) . Text.toLower . fst) settings
+      needsInstance (name, _) = Text.toLower name `elem` runtimeOptions || (hasWhitelist && Text.toLower name == "enable_external_access")
+      (deferredSettings, startupSettings) = partition needsInstance settings
+      (runtimeSettings, externalAccessSettings) = partition ((/= "enable_external_access") . Text.toLower . fst) deferredSettings
+  raw <- withTextArray (map fst startupSettings) \names -> withTextArray (map snd startupSettings) \values ->
+    output
+      ( c_duckdb_v2_instance_create_with_options
+          rawEnvironment
+          (ConstPtr (if null startupSettings then nullPtr else names))
+          (ConstPtr (if null startupSettings then nullPtr else values))
+          (fromIntegral (length startupSettings))
+      )
+  flip onException (destroy c_duckdb_v2_instance_destroy raw) do
+    config <- output (c_duckdb_v2_instance_get_config raw)
+    -- Set the whitelist before external access can be disabled.
+    forM_ (runtimeSettings ++ externalAccessSettings) \(name, value) -> withIdentifier name \key -> withText value \text ->
+      checked (c_duckdb_v2_config_set_option_text config key text DuckDBV2SettingScopeDefault)
+    connections <- newChildren
+    casts <- withInstanceFactory raw pure
+    ref <- newIORef (InstanceOpen raw casts connections)
+    registerChild forkFinalizer (\case InstanceOpen{} -> True; _ -> False) children ref (keepAlive environment (closeInstanceState ref))
+    pure (Instance ref environment)
+  where
+    -- These options require the native instance and its file system or logger.
+    runtimeOptions =
+      [ "enable_logging"
+      , "logging_mode"
+      , "logging_level"
+      , "logging_storage"
+      , "enabled_log_types"
+      , "disabled_log_types"
+      , "allowed_directories"
+      , "allowed_paths"
+      , "disabled_filesystems"
+      ]
+
+-- | Close an instance and all its connections. This is idempotent.
+-- Wait for connection creation and all descendant operations to finish before closing.
+closeInstance :: Instance -> IO ()
+closeInstance Instance{instanceState} = closeInstanceState instanceState
+
+-- | Mark the instance closed before releasing its native state.
+closeInstanceState :: IORef InstanceState -> IO ()
+closeInstanceState ref = mask_ $ joinCleanup ref \case
+  InstanceClosed -> (InstanceClosed, pure ())
+  InstanceOpen raw _ children -> (InstanceClosed, cleanupAll [closeChildren children, destroy c_duckdb_v2_instance_destroy raw])
+
+-- | Create a connection with checked options. The final action releases the
+-- private instance and environment used by the convenience open functions.
+createConnection :: Instance -> ConnectionOptions -> IO () -> IO Connection
+createConnection parent@Instance{instanceState} options releaseParent = keepAlive parent $ mask_ do
+  (rawInstance, children) <-
+    readIORef instanceState >>= \case
+      InstanceClosed -> throwIO (SQLError "duckdb-simple: instance is closed" Nothing Nothing Nothing)
+      InstanceOpen raw _ children -> pure (raw, children)
+  raw <- output (c_duckdb_v2_connection_create rawInstance)
+  flip onException (destroy c_duckdb_v2_connection_destroy raw) do
+    decoder <- newMVar Nothing
+    statements <- newChildren
+    ref <- newIORef (ConnectionOpen raw decoder statements releaseParent)
+    registerChild forkFinalizer (\case ConnectionOpen{} -> True; _ -> False) children ref (keepAlive parent (closeConnectionState False ref))
+    Connection ref parent <$> newMVar () <*> newIORef Nothing <*> pure options
+
+-- | Close a connection and every prepared statement that belongs to it.
+closeConnection :: Connection -> IO ()
+closeConnection Connection{connectionState} = closeConnectionState True connectionState
+
+-- | Close the state of a connection. The first argument tells whether to run
+-- 'connectionReleaseParent'. An explicit close gives 'True', and the finalizer
+-- gives 'False'. See Note [Native handle ownership].
+closeConnectionState :: Bool -> IORef ConnectionState -> IO ()
+closeConnectionState releaseParents ref = mask_ $ joinCleanup ref \case
+  ConnectionClosed -> (ConnectionClosed, pure ())
+  ConnectionOpen{connectionHandle, connectionDecoder, connectionStatements, connectionReleaseParent} ->
+    ( ConnectionClosed
+    , cleanupAll
+        [ closeChildren connectionStatements
+        , uninterruptibleMask_ do
+            decoder <- swapMVar connectionDecoder Nothing
+            forM_ decoder \state -> destroyVariantState state `finally` destroy c_duckdb_v2_connection_destroy (variantConnection state)
+        , destroy c_duckdb_v2_connection_destroy connectionHandle
+        , when releaseParents connectionReleaseParent
+        ]
+    )
+
+-- | Replace lifecycle state before running its cleanup action. See
+-- Note [Native handle ownership].
+joinCleanup :: IORef a -> (a -> (a, IO ())) -> IO ()
+joinCleanup ref action = join (atomicModifyIORef' ref action)
+
+-- | Close all native state owned by one statement.
+closeStatementState :: Statement -> IO ()
+closeStatementState Statement{statementState, statementStream, statementArrowResult, statementBindings} = mask_ $ joinCleanup statementState \case
+  StatementClosed -> (StatementClosed, pure ())
+  StatementOpen{statementHandle, statementParsed, statementSchemaCache} ->
+    ( StatementClosed
+    , cleanupAll
+        [ cleanupStatementStreamRef statementStream
+        , clearArrowResultRef statementArrowResult
+        , clearBoundValues statementBindings
+        , releaseSchemas statementSchemaCache
+        , destroy c_duckdb_v2_prepared_statement_destroy statementHandle
+        , destroy c_duckdb_v2_sql_statement_destroy statementParsed
+        ]
+    )
+
+-- | Release both owned statement schemas.
+releaseSchemas :: IORef (Maybe (DuckDBV2SchemaHandle, DuckDBV2SchemaHandle)) -> IO ()
+releaseSchemas ref =
+  atomicModifyIORef' ref (Nothing,) >>= mapM_ \(result, parameters) ->
+    destroy c_duckdb_v2_schema_destroy result `finally` destroy c_duckdb_v2_schema_destroy parameters
+
+-- | Release cached metadata before binding or executing the statement again.
+-- See Note [Statement schemas].
+clearStatementSchemas :: Statement -> IO ()
+clearStatementSchemas Statement{statementState} = mask_ do
+  readIORef statementState >>= \case
+    StatementClosed -> pure ()
+    StatementOpen{statementSchemaCache} -> releaseSchemas statementSchemaCache
+
+-- | Keep the parameter types that the action reads until the action ends. The
+-- first read of a parameter type runs the binder. Each later read of that type
+-- in the action uses the kept type, also after a column type changes. See
+-- Note [Statement schemas].
+withKeptParameterTypes :: Statement -> IO a -> IO a
+withKeptParameterTypes Statement{statementParameterTypes} =
+  bracket_ (writeIORef statementParameterTypes (Just IntMap.empty)) (writeIORef statementParameterTypes Nothing)
+
+-- | Parse SQL and borrow the resulting statements for one action.
+withParsedStatements :: Connection -> Query -> ([DuckDBV2SqlStatementHandle] -> IO a) -> IO a
+withParsedStatements conn query action = withQueryError query $ withConnectionHandle conn \raw ->
+  bracket (parseStatements raw query) releaseParsed (action . reverse)
+
+-- | Parse SQL into owned handles, most recent first for cleanup. The caller
+-- must transfer or release them under a mask.
+parseStatements :: DuckDBV2ConnectionHandle -> Query -> IO [DuckDBV2SqlStatementHandle]
+parseStatements raw query = mask_ $ withQueryCString query \sql -> do
+  iterator <- output (c_duckdb_v2_parse_sql raw sql)
+  let destroyIterator = destroy c_duckdb_v2_statement_iterator_destroy iterator
+      gather owned = do
+        parsed <- flip onException (releaseParsed owned) do
+          -- Accept cancellation between acquisitions, while every handle has
+          -- an owner. Native output acquisition remains masked.
+          allowInterrupt
+          output (c_duckdb_v2_statement_iterator_next iterator)
+        if parsed == nullHandle then pure owned else gather (parsed : owned)
+  parsed <- gather [] `onException` destroyIterator
+  destroyIterator `onException` releaseParsed parsed
+  pure parsed
+
+-- | Release the handles from 'parseStatements' in reverse acquisition order.
+releaseParsed :: [DuckDBV2SqlStatementHandle] -> IO ()
+releaseParsed = releaseItems (destroy c_duckdb_v2_sql_statement_destroy)
+
+-- | Prepare a borrowed parsed statement. The native handle copies its SQL.
+createStatementFromParsed :: Connection -> Query -> DuckDBV2SqlStatementHandle -> IO Statement
+createStatementFromParsed parent query parsed = createStatementFromParsedWithCollections parent query parsed []
+
+-- | Prepare a borrowed parsed statement with named input collections. A
+-- collection is a DuckDB column data collection: rows in memory that the caller
+-- owns. @duckdb_v2_statement_add_collection@ binds a collection to a statement
+-- under a name, and the SQL of the statement reads it as a table with that name.
+-- Each triple is the name, the collection handle, and the column names. An empty
+-- list of column names selects the default names @col1@ to @colN@.
+-- The function binds the collections to the parsed statement that it prepares,
+-- and to the copy that it keeps for parameter names and schemas. The caller must
+-- keep each collection alive and unchanged until the statement closes and the
+-- caller destroys the parsed statement.
+createStatementFromParsedWithCollections
+  :: Connection -> Query -> DuckDBV2SqlStatementHandle -> [(Text, DuckDBV2ColumnDataCollectionHandle, [Text])] -> IO Statement
+createStatementFromParsedWithCollections parent query parsed collections = withQueryError query $ withConnectionHandle parent \raw -> mask_ do
+  addStatementCollections query collections parsed
+  handle <- prepareStatementHandle parent raw parsed
+  flip onException (destroy c_duckdb_v2_prepared_statement_destroy handle) do
+    -- The caller retains its parsed handle, so keep a separate metadata copy.
+    text <- output (c_duckdb_v2_sql_statement_get_text parsed) >>= readText
+    copied <- withQueryCString (Query text) \sql -> bracket (output (c_duckdb_v2_parse_sql raw sql)) (destroy c_duckdb_v2_statement_iterator_destroy) \iterator ->
+      output (c_duckdb_v2_statement_iterator_next iterator)
+    flip onException (destroy c_duckdb_v2_sql_statement_destroy copied) do
+      addStatementCollections query collections copied
+      managedStatement parent query handle copied
+
+-- | Parse one statement and retain its owned parsed handle for metadata.
+-- Collections remain borrowed until the managed statement closes.
+createStatementWithCollections
+  :: Connection -> Query -> [(Text, DuckDBV2ColumnDataCollectionHandle, [Text])] -> IO Statement
+createStatementWithCollections parent query collections = withQueryError query $ withConnectionHandle parent \raw -> mask_ do
+  -- Parse all SQL before selecting one statement. A later syntax error has
+  -- precedence over the empty or multiple-statement diagnostics.
+  parsed <- parseStatements raw query
+  flip onException (releaseParsed parsed) $
+    case parsed of
+      [statement] -> do
+        addStatementCollections query collections statement
+        handle <- prepareStatementHandle parent raw statement
+        managedStatement parent query handle statement
+          `onException` destroy c_duckdb_v2_prepared_statement_destroy handle
+      [] -> throwInvalidArgument "SQL query contains no statement"
+      _ -> throwInvalidArgument "prepared SQL contains more than one statement"
+
+-- | Prepare a borrowed AST. Keep its connection locked until native work ends.
+prepareStatementHandle :: Connection -> DuckDBV2ConnectionHandle -> DuckDBV2SqlStatementHandle -> IO DuckDBV2PreparedStatementHandle
+prepareStatementHandle parent raw parsed = alloca \slot -> do
+  poke slot nullHandle
+  flip onException (peek slot >>= destroy c_duckdb_v2_prepared_statement_destroy) do
+    -- DuckDB also rejects preparation while another result is open. See
+    -- Note [Connection lock].
+    withConnectionLock parent (runInterruptibleQuery parent (checked (c_duckdb_v2_prepared_statement_create raw parsed 0 slot)))
+    peek slot
+
+-- | Build a managed statement. Take both native handles only on success.
+managedStatement :: Connection -> Query -> DuckDBV2PreparedStatementHandle -> DuckDBV2SqlStatementHandle -> IO Statement
+managedStatement parent query handle parsed = do
+  count <- fromIntegral <$> output (c_duckdb_v2_sql_statement_get_parameter_count parsed)
+  names <- parameterNames parsed count
+  schemas <- newIORef Nothing
+  bindings <- newIORef IntMap.empty
+  stream <- newIORef StatementStreamIdle
+  arrow <- newIORef nullHandle
+  kept <- newIORef Nothing
+  ref <- newIORef (StatementOpen handle parsed schemas)
+  let statement = Statement ref parent query stream arrow bindings (listArray (1, count) names) kept
+  children <-
+    readIORef (connectionState parent) >>= \case
+      ConnectionClosed -> throwIO connectionClosedError
+      ConnectionOpen{connectionStatements} -> pure connectionStatements
+  -- The finalizer does not keep its weak key alive through this closure.
+  -- See Note [Native handle ownership].
+  registerChild id (\case StatementOpen{} -> True; _ -> False) children ref (keepAlive parent (closeStatementState statement))
+  pure statement
+
+-- | Attach borrowed collections to one parsed statement.
+addStatementCollections :: Query -> [(Text, DuckDBV2ColumnDataCollectionHandle, [Text])] -> DuckDBV2SqlStatementHandle -> IO ()
+addStatementCollections query collections statement = forM_ collections \(name, collection, columns) -> do
+  when (any (Text.any (== '\0')) (name : columns)) $
+    withQueryError query (throwInvalidArgument "collection name or column name contains NUL")
+  withIdentifier name \nativeName -> withIdentifierArray columns \nativeColumns ->
+    checked
+      ( c_duckdb_v2_statement_add_collection
+          statement
+          nativeName
+          collection
+          (ConstPtr (if null columns then nullPtr else nativeColumns))
+          (fromIntegral (length columns))
+      )
+
+-- | Prepare SQL with borrowed column collections as named input tables.
+-- The caller must keep each collection alive and unchanged until the callback
+-- returns. An empty column-name list selects DuckDB's default column names.
+-- The statement and all its results close before this function returns.
+withCollectionStatement :: Connection -> Query -> [(Text, DuckDBV2ColumnDataCollectionHandle, [Text])] -> (Statement -> IO a) -> IO a
+withCollectionStatement conn queryText collections action =
+  withQueryError queryText $
+    bracket (createStatementWithCollections conn queryText collections) closeStatementState action
+
+-- | Read the authoritative parameter names in binding order.
+parameterNames :: DuckDBV2SqlStatementHandle -> Int -> IO [Text]
+parameterNames statement count = reverse <$> foldM readName [] [0 .. count - 1]
+  where
+    -- V2 has no bulk accessor. A parser extension can supply names that
+    -- differ from the statement text. Read the names in binding order.
+    readName names index = do
+      name <- output (c_duckdb_v2_sql_statement_get_parameter_name statement (fromIntegral index)) >>= readIdentifier
+      pure (name : names)
+
+-- | Error raised when an operation targets a closed connection.
+connectionClosedError :: SQLError
+connectionClosedError = SQLError "duckdb-simple: connection is closed" Nothing Nothing Nothing
+
+-- | Error raised when an operation targets a closed statement.
+statementClosedError :: Statement -> SQLError
+statementClosedError Statement{statementQuery} = SQLError "duckdb-simple: statement is closed" Nothing (Just statementQuery) Nothing
+
+-- | Keep a Haskell owner reachable until an action finishes. See
+-- Note [Native handle ownership].
+keepAlive :: a -> IO b -> IO b
+keepAlive owner (IO action) = IO \state -> keepAlive# owner state action
+
+-- | Borrow a live instance handle.
+withInstanceHandle :: Instance -> (DuckDBV2InstanceHandle -> IO a) -> IO a
+withInstanceHandle owner action = withOpenInstance owner (\raw _ -> action raw)
+
+-- | Borrow the factory for DuckDB's built-in casts. All connections on the
+-- instance use this factory.
+instanceCastFactory :: Instance -> IO DuckDBV2FactoryHandle
+instanceCastFactory owner = withOpenInstance owner (\_ casts -> pure casts)
+
+-- | Borrow the instance and its factory while the managed owner is live.
+withOpenInstance :: Instance -> (DuckDBV2InstanceHandle -> DuckDBV2FactoryHandle -> IO a) -> IO a
+withOpenInstance owner@Instance{instanceState} action =
+  keepAlive owner $
+    readIORef instanceState >>= \case
+      InstanceClosed -> throwIO (SQLError "duckdb-simple: instance is closed" Nothing Nothing Nothing)
+      InstanceOpen raw casts _ -> action raw casts
+
+-- | Borrow the instance that owns a live connection.
+withDatabaseHandle :: Connection -> (DuckDBV2InstanceHandle -> IO a) -> IO a
+withDatabaseHandle conn action = withConnectionHandle conn \_ -> withInstanceHandle (connectionInstance conn) action
+
+-- | Borrow a live connection handle.
+withConnectionHandle :: Connection -> (DuckDBV2ConnectionHandle -> IO a) -> IO a
+withConnectionHandle owner@Connection{connectionState} action =
+  keepAlive owner $
+    readIORef connectionState >>= \case
+      ConnectionClosed -> throwIO connectionClosedError
+      ConnectionOpen{connectionHandle} -> action connectionHandle
+
+{- Note [Connection lock]
+~~~~~~~~~~~~~~~~~~~~~~~~~
+DuckDB permits one open result for each connection, and it rejects a second
+execution. DuckDB also rejects a preparation while another result is open.
+Thus connectionLock serializes these native calls of a connection, and the
+threads that share a connection wait for each other. withConnectionLock takes
+the lock.
+
+These calls take the lock:
+
+- The preparation of a statement (prepareStatementHandle).
+
+- The metadata bind of a statement (statementSchemas).
+
+- The native calls of one result in the result window (withResultWindow). A
+  materialized result holds the lock from its execution until it closes. See
+  Note [Result window].
+
+- Each fetch of an explicit stream after the result window (fetchChunk in
+  "Database.DuckDB.Simple.Result").
+
+- The execution of an explicit Arrow stream, and each fetch of a batch
+  (foldArrowWith in "Database.DuckDB.Simple.Arrow.Internal").
+
+An explicit stream keeps its result open between two fetches. It holds the
+lock for its execution and for each fetch, but not between two fetches. A
+statement of another thread on the connection can then take the lock, and
+DuckDB rejects that statement while the result is open.
+
+Each fetch of an explicit stream holds the lock for this reason. The header
+says that a result has a single consumer, and that a bind runs at the same time
+only on a second connection. Without the lock, another thread can start a
+statement when the stream is finished in DuckDB but still has buffered chunks.
+A cancellation of the fetch then interrupts the query that runs on the
+connection, which is the query of the other thread.
+
+The lock is not reentrant. A thread that holds the lock must not take it again.
+Thus:
+
+- A call in the result window does not take the lock. A fetch of an explicit
+  stream after the result window takes the lock, because its thread does not
+  hold the lock then.
+
+- No step function runs under the lock. A step function is a function of the
+  user that a fold calls for each row or for each Arrow batch. It can run a
+  statement on the same connection, and that statement takes the lock. The
+  folds call a step function after the fetch, or after the result closes.
+
+DuckDB callbacks run while a native call holds the lock. withConnectionLock
+gives a bound to the wait of a thread that is inside a callback. See
+Note [Callback marks] in "Database.DuckDB.Simple.CallbackMark".
+-}
+
+-- | Run an action with the lock of the connection. The lock is not reentrant.
+-- Do not run a function of the user, such as the step of a fold, in the
+-- action. A thread with a callback mark waits for the lock at most the bound
+-- of the connection ('connectionCallbackLockWait'), and then raises an t'SQLError' of
+-- the type 'ErrorResourceInUse'. Each other thread waits without a bound. See
+-- Note [Connection lock], and Note [Callback marks] in
+-- <src/Database.DuckDB.Simple.CallbackMark.html Database.DuckDB.Simple.CallbackMark>.
+--
+-- The take of the lock is masked. The timeout of the bound can thus arrive only
+-- while 'takeMVar' blocks, and then the take has not occurred. After the take,
+-- the same handlers as in 'withMVar' put the lock back.
+withConnectionLock :: Connection -> IO a -> IO a
+withConnectionLock Connection{connectionLock, connectionOptions} action = do
+  bound <- case connectionCallbackLockWait connectionOptions of
+    Nothing -> pure Nothing
+    Just micros -> do
+      inside <- hasCallbackMark
+      pure (if inside then Just micros else Nothing)
+  case bound of
+    Nothing -> withMVar connectionLock (const action)
+    Just micros -> mask \restore -> do
+      -- A free lock needs no timer. 'timeout' with a bound of 0 does not run
+      -- its action, so the bound 0 also takes a free lock.
+      taken <-
+        tryTakeMVar connectionLock >>= \case
+          Just () -> pure True
+          Nothing -> isJust <$> timeout micros (takeMVar connectionLock)
+      unless taken $ throwIO (callbackLockWaitError micros)
+      result <- restore action `onException` putMVar connectionLock ()
+      putMVar connectionLock ()
+      pure result
+
+-- | The error of a callback that waited for a connection lock for its bound.
+callbackLockWaitError :: Int -> SQLError
+callbackLockWaitError micros =
+  SQLError
+    ( Text.pack
+        ( "duckdb-simple: a callback waited "
+            <> seconds
+            <> " s for a connection that runs a statement. A callback must not run a statement on the connection that runs the callback. Use another connection of the same instance, or change connectionCallbackLockWait."
+        )
+    )
+    (Just ErrorResourceInUse)
+    Nothing
+    Nothing
+  where
+    (whole, fraction) = micros `quotRem` 1000000
+    digits = dropWhileEnd (== '0') (let text = show fraction in replicate (6 - length text) '0' <> text)
+    seconds = show whole <> (if null digits then "" else '.' : digits)
+
+{- Note [Result window]
+~~~~~~~~~~~~~~~~~~~~~~~
+Each interruptible native call uses a helper thread. A bound caller, such as
+the main thread, changes operating system threads to wait for one. A result
+needs several native calls, for example its execution and its fetches. Thus
+withResultWindow runs the native calls of one result as one unit, in one helper
+thread. The caller changes threads once for the result, and not once for each
+call. The result window is the time in which this helper thread runs the
+action.
+
+withResultWindow takes the connection lock, and it runs the action with
+runInterruptible. The helper thread writes its ThreadId to connectionWindow
+before the action, and it writes Nothing after the action. runInterruptible
+compares connectionWindow with the current thread. If they are equal, it runs
+the work directly. Thus each interruptible call in the action, for example in
+executePreparedResult or fetchResultChunk, runs in the helper thread of the
+window. The connection lock lets a connection have at most one window at a
+time.
+
+The helper thread is interruptible as one unit. A cancellation interrupts
+DuckDB until the whole action returns. The caller can be cancelled after the
+helper thread has made its result. The release action of withResultWindow then
+releases that result. See Note [Interruptible native calls].
+
+These functions use a result window:
+
+- executeParsedStatement.
+
+- executeStatement in "Database.DuckDB.Simple".
+
+- startStatementStream and withParsedRows in "Database.DuckDB.Simple.Result".
+
+- foldArrowWith in "Database.DuckDB.Simple.Arrow.Internal", for a materialized
+  result.
+
+A row stream runs its execution and its first fetch in the window. Each later
+fetch is outside the window: it takes the connection lock and a helper thread
+of its own. An Arrow stream does not use a window. See Note [Connection lock].
+
+The action holds the connection lock. Thus no step function runs in the action.
+-}
+
+-- | Run the native calls of one result in one helper thread, and hold the
+-- connection lock. The release action runs when the caller is cancelled after
+-- the helper thread has made its result. Do not
+-- run a function of the user in the action. See Note [Result window].
+withResultWindow :: Connection -> (a -> IO ()) -> IO a -> IO a
+withResultWindow conn@Connection{connectionWindow} release action =
+  withConnectionLock conn . runInterruptible conn release $ do
+    self <- myThreadId
+    bracket_ (writeIORef connectionWindow (Just self)) (writeIORef connectionWindow Nothing) action
+
+{- Note [Concurrent VARIANT decoding]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+DuckDB permits one active result per connection. The VARIANT decoder runs SQL
+while a caller can still be streaming rows, so it needs its own connection.
+Each caller opens one helper on its instance at the first VARIANT read and
+reuses the helper's prepared statements. Two callers on the same instance can
+therefore decode in parallel.
+
+The decoder mutates its statements and cast types while it copies a vector.
+The MVar gives one thread exclusive use until the copy finishes. Closing the
+caller takes the same MVar before destroying the decoder and its helper.
+A reader that finds the slot empty checks that the caller is still open under
+the lock. This prevents it from opening a new helper after close.
+-}
+
+-- | Copy a VARIANT vector with this connection's decoder. See
+-- Note [Concurrent VARIANT decoding].
+readConnectionVariant :: Connection -> DuckDBV2VectorHandle -> IO (Int -> IO FieldValue)
+readConnectionVariant owner@Connection{connectionState, connectionInstance} vector = keepAlive owner $ mask \restore -> do
+  readIORef connectionState >>= \case
+    ConnectionClosed -> throwIO connectionClosedError
+    ConnectionOpen{connectionDecoder} -> do
+      outcome <- modifyMVarMasked connectionDecoder \current -> do
+        state <- case current of
+          Just state -> pure state
+          Nothing -> withConnectionHandle owner \_ -> withOpenInstance connectionInstance \raw casts ->
+            bracketOnError (output (c_duckdb_v2_connection_create raw)) (destroy c_duckdb_v2_connection_destroy) \helper ->
+              newVariantState helper casts
+        result <- try (restore (prepareVariantReader state vector))
+        pure (Just state, result)
+      either (throwIO :: SomeException -> IO a) pure outcome
+
+-- | Borrow a live prepared statement handle.
+withStatementHandle :: Statement -> (DuckDBV2PreparedStatementHandle -> IO a) -> IO a
+withStatementHandle owner@Statement{statementState, statementConnection, statementQuery} action = keepAlive owner $
+  withQueryError statementQuery $ withConnectionHandle statementConnection \_ ->
+    readIORef statementState >>= \case
+      StatementClosed -> throwIO (statementClosedError owner)
+      StatementOpen{statementHandle} -> action statementHandle
+
+-- | Attach the SQL text to errors from native calls. An error that already has
+-- SQL text keeps it, so an error from a nested query reports that query.
+withQueryError :: Query -> IO a -> IO a
+withQueryError query action = action `catch` \err -> throwIO err{sqlErrorQuery = Just (fromMaybe query (sqlErrorQuery err))}
+
+-- | Borrow SQL as a NUL-terminated UTF-8 string.
+withQueryCString :: Query -> (ConstPtr CChar -> IO a) -> IO a
+withQueryCString query@(Query text) action = do
+  when (Text.any (== '\0') text) $ withQueryError query (throwInvalidArgument "query contains NUL")
+  TextForeign.withCString text (action . ConstPtr)
+
+-- | Copy a UTF-8 C string.
+peekUtf8CString :: (Coercible a CString) => a -> IO Text
+peekUtf8CString ptr = Text.decodeUtf8 <$> BS.packCString (coerce ptr)
+
+{- Note [Interruptible native calls]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Native work that can run for a long time runs in a helper thread, so that an
+asynchronous exception can interrupt it. An asynchronous exception does not
+interrupt a thread that is in a foreign call: the documentation of throwTo says
+that the exception is not raised until the call has completed. Thus the caller
+does not make the call itself. runInterruptible starts the helper thread, and
+the caller waits for the outcome of the work. An asynchronous exception that
+the caller gets during this wait is a cancellation.
+
+On a cancellation, the caller does these steps:
+
+- It interrupts DuckDB with duckdb_v2_connection_interrupt until the work
+  returns. The header says that the interrupt is "A no-op when no query is
+  active". An interrupt that arrives before the query starts is thus lost, and
+  the caller repeats the interrupt.
+
+- It waits interruptRetryDelayMicros between two interrupts, so that the loop
+  is not a busy loop.
+
+- If the work gives a result, the caller releases it with the release action
+  of runInterruptible, because the caller does not return that result. If the
+  work raises an error, the caller ignores that error.
+
+- It raises the cancellation again.
+
+These steps are uninterruptible (uninterruptibleMask_). Thus the caller
+releases its inputs, such as the arrays that withBoundValues lends, only after
+the native work returns. Cancellation is cooperative: the native code, and each
+DuckDB callback that it runs, must return before the cleanup can finish.
+
+runInterruptibleQuery gives no release action. Its work must keep each native
+result in storage that the caller releases. For example, executeParsedResult
+gives the work a slot for the result handle. If an exception occurs, the caller
+destroys the handle in the slot.
+
+A call from the helper thread of the result window runs the work directly,
+without a new helper thread. See Note [Result window].
+-}
+
+-- | Run native work with cancellation. Wait for the work before releasing inputs.
+-- The work must keep its native results in storage that the caller releases.
+-- See Note [Interruptible native calls].
+runInterruptibleQuery :: Connection -> IO a -> IO a
+runInterruptibleQuery conn = runInterruptible conn (const (pure ()))
+
+-- | Run native work in a helper thread. On cancellation, interrupt DuckDB
+-- until the work returns, and release a result that the caller does not receive.
+-- A call from the helper thread of 'withResultWindow' runs the work directly.
+-- See Note [Interruptible native calls] and Note [Result window].
+runInterruptible :: forall a. Connection -> (a -> IO ()) -> IO a -> IO a
+runInterruptible conn release action = do
+  self <- myThreadId
+  window <- readIORef (connectionWindow conn)
+  if window == Just self then action else interruptible
+  where
+    interruptible = withConnectionHandle conn \handle -> mask \restore -> do
+      done <- newEmptyMVar
+      _ <- forkIO do
+        outcome <- try action :: IO (Either SomeException a)
+        putMVar done outcome
+      let wait =
+            tryReadMVar done >>= \case
+              Just outcome -> pure outcome
+              -- Repeat the interrupt until the work returns. See
+              -- Note [Interruptible native calls].
+              Nothing -> void (c_duckdb_v2_connection_interrupt handle nullPtr) >> threadDelay interruptRetryDelayMicros >> wait
+          stop = uninterruptibleMask_ (wait >>= either (const (pure ())) release)
+      outcome <- restore (readMVar done) `onException` stop
+      either throwIO pure outcome
+
+-- | Repeat the interrupt at most 100 times each second while the native work
+-- finishes. The interval prevents a busy loop. It can add up to one interval to
+-- the time at which the caller sees the end of the work. See
+-- Note [Interruptible native calls].
+interruptRetryDelayMicros :: Int
+interruptRetryDelayMicros = 10 * 1000
+
+-- | Execute a borrowed parsed statement. The caller owns the returned cursor.
+-- See Note [Interruptible native calls].
+executeParsedResult :: Connection -> Query -> DuckDBV2SqlStatementHandle -> IO DuckDBV2ResultHandle
+executeParsedResult conn query parsed = withQueryError query $ withConnectionHandle conn \raw -> mask_ $ alloca \slot -> do
+  poke slot nullHandle
+  flip onException (peek slot >>= destroy c_duckdb_v2_result_destroy) do
+    runInterruptibleQuery conn $
+      checked (c_duckdb_v2_statement_execute raw parsed (ConstPtr nullPtr) (ConstPtr nullPtr) 0 slot)
+    peek slot
+
+-- | Execute a parsed statement directly and drain all its side effects. See
+-- Note [Result window].
+executeParsedStatement :: Connection -> Query -> DuckDBV2SqlStatementHandle -> IO Int
+executeParsedStatement conn queryText parsed = withQueryError queryText . withResultWindow conn (const (pure ())) $
+  bracket (executeParsedResult conn queryText parsed) (destroy c_duckdb_v2_result_destroy) \result ->
+    fromIntegral <$> runInterruptibleQuery conn (output (c_duckdb_v2_result_drain result))
+
+-- | Execute a prepared statement. The caller owns the returned result. See
+-- Note [Interruptible native calls].
+executePreparedResult :: Statement -> IO DuckDBV2ResultHandle
+executePreparedResult stmt = withStatementHandle stmt \handle -> mask_ $ alloca \slot -> do
+  poke slot nullHandle
+  flip onException (peek slot >>= destroy c_duckdb_v2_result_destroy) $
+    withBoundValues stmt \names values count -> do
+      runInterruptibleQuery (statementConnection stmt) $
+        checked (c_duckdb_v2_prepared_statement_execute handle names values count slot)
+      peek slot
+
+-- | Borrow parameter names and values until native execution returns.
+withBoundValues :: Statement -> (ConstPtr DuckDBV2IdentifierT -> ConstPtr DuckDBV2ValueHandle -> DuckDBIdx -> IO a) -> IO a
+withBoundValues stmt action = do
+  bindings <- IntMap.toAscList <$> readIORef (statementBindings stmt)
+  let names = map (\(idx, _) -> statementParameterNames stmt ! idx) bindings
+      values = map snd bindings
+  withIdentifierArray names \namesPtr -> withArray values \valuesPtr ->
+    action (ConstPtr namesPtr) (ConstPtr valuesPtr) (fromIntegral (length bindings))
+
+-- | Execute a prepared Arrow result and register it for statement cleanup.
+-- Each array of the result has at most 'connectionArrowBatchSize' rows of the
+-- connection. See Note [Interruptible native calls].
+executePreparedArrowResult :: Statement -> IO DuckDBV2ArrowResultHandle
+executePreparedArrowResult stmt = withStatementHandle stmt \handle -> mask_ $ alloca \slot -> do
+  poke slot nullHandle
+  flip onException (peek slot >>= destroy c_duckdb_v2_arrow_result_destroy) $
+    withBoundValues stmt \names values count -> do
+      let batch = fromIntegral (connectionArrowBatchSize (connectionOptions (statementConnection stmt)))
+      runInterruptibleQuery (statementConnection stmt) $
+        checked (c_duckdb_v2_prepared_statement_execute_arrow handle names values count batch slot)
+      result <- peek slot
+      writeIORef (statementArrowResult stmt) result
+      pure result
+
+-- | Execute an Arrow result and release it on every exit path.
+withArrowResult :: Statement -> (DuckDBV2ArrowResultHandle -> IO a) -> IO a
+withArrowResult stmt = bracket (executePreparedArrowResult stmt) (const (clearArrowResult stmt))
+
+-- | Release an Arrow result before callbacks use materialized batches.
+clearArrowResult :: Statement -> IO ()
+clearArrowResult = clearArrowResultRef . statementArrowResult
+
+-- | Remove the owned Arrow cursor before releasing it.
+clearArrowResultRef :: IORef DuckDBV2ArrowResultHandle -> IO ()
+clearArrowResultRef ref =
+  mask_ $
+    atomicModifyIORef' ref (nullHandle,) >>= destroy c_duckdb_v2_arrow_result_destroy
+
+-- | Execute and release one result on every exit path.
+withResult :: Statement -> (DuckDBV2ResultHandle -> IO a) -> IO a
+withResult stmt = bracket (executePreparedResult stmt) (destroy c_duckdb_v2_result_destroy)
+
+-- | Fetch one owned chunk. A null handle denotes completion. See
+-- Note [Interruptible native calls].
+fetchResultChunk :: Connection -> DuckDBV2ResultHandle -> IO DuckDBV2DataChunkHandle
+fetchResultChunk conn result = mask_ $ alloca \slot -> do
+  poke slot nullHandle
+  flip onException (peek slot >>= destroyDataChunk) do
+    runInterruptibleQuery conn (checked (c_duckdb_v2_result_fetch_chunk result slot))
+    peek slot
+
+-- | Release an owned native data chunk.
+destroyDataChunk :: DuckDBV2DataChunkHandle -> IO ()
+destroyDataChunk = destroy c_duckdb_v2_data_chunk_destroy
+
+-- | Release the active cursor and return to the idle state. See
+-- Note [Statement cursor].
+cleanupStatementStreamRef :: IORef StatementStreamState -> IO ()
+cleanupStatementStreamRef ref = mask_ do
+  state <- atomicModifyIORef' ref (StatementStreamIdle,)
+  case state of
+    StatementStreamActive stream -> finalizeStream stream
+    _ -> pure ()
+
+-- | Close metadata access, then release the current chunk, pending chunks,
+-- and result. Each release runs even if an earlier release raises an error.
+finalizeStream :: StatementStream -> IO ()
+finalizeStream StatementStream{statementStreamTypes, statementStreamResult, statementStreamChunk, statementStreamPendingChunks} =
+  closeTypeScope statementStreamTypes
+    `finally` ( maybe (pure ()) finalizeChunk statementStreamChunk
+                  `finally` (releaseItems destroyDataChunk statementStreamPendingChunks `finally` destroy c_duckdb_v2_result_destroy statementStreamResult)
+              )
+
+-- | Release the native chunk of a stream chunk.
+finalizeChunk :: StatementStreamChunk -> IO ()
+finalizeChunk StatementStreamChunk{statementStreamChunkPtr} = destroyDataChunk statementStreamChunkPtr
+
+-- | Transfer ownership of one successfully constructed parameter value.
+storeBoundValue :: Statement -> DuckDBIdx -> DuckDBV2ValueHandle -> IO ()
+storeBoundValue stmt index value = withStatementHandle stmt \_ -> mask_ do
+  let idx = fromIntegral index
+  unless (inRange (bounds (statementParameterNames stmt)) idx) $
+    withQueryError (statementQuery stmt) (throwInvalidArgument "parameter index is out of bounds")
+  previous <- IntMap.lookup idx <$> readIORef (statementBindings stmt)
+  mapM_ destroyValue previous
+  atomicModifyIORef' (statementBindings stmt) \values -> (IntMap.insert idx value values, ())
+
+-- | Release all owned parameter values.
+clearBoundValues :: IORef (IntMap.IntMap DuckDBV2ValueHandle) -> IO ()
+clearBoundValues ref = mask_ $ atomicModifyIORef' ref (IntMap.empty,) >>= releaseItems destroyValue . IntMap.elems
+
+{- Note [Statement schemas]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+An open statement keeps a cache of two schemas (statementSchemaCache): the
+schema of its result and the schema of its parameters. statementSchemas fills
+the cache on its first call. It runs the metadata bind
+(duckdb_v2_statement_bind) on the retained parsed statement under the
+connection lock, and it stores both handles. The next calls give the same
+handles until the cache is empty again. columnCount and columnName in
+"Database.DuckDB.Simple" read the result schema, and preparedParameterType
+reads the type of one parameter.
+
+The SQL constructors retain the owned parsed handle from the iterator. Native
+preparation copies its AST. The constructors for borrowed parsed handles keep a
+separate metadata copy, because the caller owns the input handle.
+
+The statement owns both schemas. withStatementSchemas keeps the statement alive
+while an action reads a schema and copies its borrowed names and types. Keeping
+only a schema handle or another field of the statement does not keep the state
+IORef alive. The finalizer can then close the statement and destroy the schemas.
+
+clearStatementSchemas releases both handles and empties the cache.
+resetStatementStream in "Database.DuckDB.Simple.Result" calls it. Thus each
+call of bind, bindNamed, clearStatementBindings, and executeStatement clears
+the cache first. Each fold of "Database.DuckDB.Simple" clears it before its
+first row and after its last row. closeStatementState releases the handles
+when the statement closes.
+
+- Why each bind clears the cache. A statement that the caller keeps must see a
+  change of the catalog between two binds, for example an ALTER TABLE that
+  changes the type of a column. A binding that depends on the type of its
+  parameter then builds its value for the new type. With a type from before the
+  change, a UTCTime for a column that became TIMESTAMPTZ_NS loses its
+  nanoseconds.
+
+- The cost. The first read of a parameter type after a bind runs the binder of
+  DuckDB again. Only a binding that reads the type of its parameter has this
+  cost: a TimeOfDay, a LocalTime, or a UTCTime (or an Unbounded form) with
+  digits below a microsecond (see Note [Nanosecond parameters] in
+  "Database.DuckDB.Simple.ToField"), a SizedArray, a list, a Map, a manual STRUCT,
+  TUPLE, or UNION value, a FieldList, a FieldArray, or a FieldMap value, and an
+  Integer or a Natural outside the HUGEINT range
+  (see Note [Integer parameters] in "Database.DuckDB.Simple.ToField").
+
+- The exception is executeMany. One executeMany call binds many rows on one
+  statement that no caller can reach. withKeptParameterTypes keeps the decoded
+  type of each parameter (statementParameterTypes) from the first row that
+  reads it to the end of the call. Thus the binder runs one time for the call,
+  and not one time for each row. The schemas are still cleared for each row.
+  If the type of a column changes during the call, the later rows of the call
+  bind for the old type. Another connection can make such a change, and also
+  another thread that uses the same connection.
+-}
+
+-- | Bind SQL metadata and borrow the cached output and parameter schemas.
+-- The statement owns the handles. They remain valid until the statement resets,
+-- rebinds, or closes. Use 'withStatementSchemas' to keep the statement alive
+-- while reading them. See Note [Statement schemas].
+statementSchemas :: Statement -> IO (DuckDBV2SchemaHandle, DuckDBV2SchemaHandle)
+statementSchemas stmt = withStatementHandle stmt \_ -> mask_ do
+  state <- readIORef (statementState stmt)
+  case state of
+    StatementClosed -> throwIO (statementClosedError stmt)
+    StatementOpen{statementParsed, statementSchemaCache} ->
+      readIORef statementSchemaCache >>= \case
+        Just schemas -> pure schemas
+        Nothing -> withConnectionHandle (statementConnection stmt) \conn -> alloca \result -> alloca \parameters -> do
+          poke result nullHandle
+          poke parameters nullHandle
+          let release = (peek result >>= destroy c_duckdb_v2_schema_destroy) `finally` (peek parameters >>= destroy c_duckdb_v2_schema_destroy)
+          flip onException release do
+            withConnectionLock
+              (statementConnection stmt)
+              (runInterruptibleQuery (statementConnection stmt) (checked (c_duckdb_v2_statement_bind conn statementParsed result parameters)))
+            schemas <- (,) <$> peek result <*> peek parameters
+            writeIORef statementSchemaCache (Just schemas)
+            pure schemas
+
+-- | Borrow both schemas and keep their statement alive until the action ends.
+-- Copy borrowed names and types in the action. See Note [Statement schemas].
+withStatementSchemas :: Statement -> (DuckDBV2SchemaHandle -> DuckDBV2SchemaHandle -> IO a) -> IO a
+withStatementSchemas stmt action = keepAlive stmt (statementSchemas stmt >>= uncurry action)
+
+-- | Read a parameter type when the binder can determine it without values.
+-- While 'withKeptParameterTypes' runs, read each type one time. See
+-- Note [Statement schemas].
+preparedParameterType :: Statement -> DuckDBIdx -> IO (Maybe LogicalTypeRep)
+preparedParameterType stmt idx = do
+  kept <- readIORef (statementParameterTypes stmt)
+  case kept >>= IntMap.lookup (fromIntegral idx) of
+    Just rep -> pure rep
+    Nothing -> do
+      rep <- readParameterType
+      -- Outside 'withKeptParameterTypes' the value is Nothing, and the insert does nothing.
+      modifyIORef' (statementParameterTypes stmt) (fmap (IntMap.insert (fromIntegral idx) rep))
+      pure rep
+  where
+    readParameterType = withStatementSchemas stmt \_ schema ->
+      alloca \name -> do
+        dtype <- output (c_duckdb_v2_schema_get_field schema (idx - 1) name)
+        ident <- output (c_duckdb_v2_logical_type_get_id dtype)
+        -- The binding uses the base type. See Note [Type aliases] in
+        -- "Database.DuckDB.Simple.LogicalRep".
+        if ident == DuckDBV2LogicalTypeIdUnknown || ident == DuckDBV2LogicalTypeIdSQLNull
+          then pure Nothing
+          else Just <$> logicalTypeToBaseRep dtype
+
+-- | Column type names and the logical types that they denote. When a type has
+-- more than one name, 'duckDBTypeToName' gives the first name.
+duckDBTypeNames :: [(Text, LogicalTypeId)]
+duckDBTypeNames =
+  [ ("BOOLEAN", LogicalTypeIdBoolean)
+  , ("TINYINT", LogicalTypeIdTinyInt)
+  , ("SMALLINT", LogicalTypeIdSmallInt)
+  , ("INTEGER", LogicalTypeIdInteger)
+  , ("BIGINT", LogicalTypeIdBigInt)
+  , ("HUGEINT", LogicalTypeIdHugeInt)
+  , ("UTINYINT", LogicalTypeIdUTinyInt)
+  , ("USMALLINT", LogicalTypeIdUSmallInt)
+  , ("UINTEGER", LogicalTypeIdUInteger)
+  , ("UBIGINT", LogicalTypeIdUBigInt)
+  , ("UHUGEINT", LogicalTypeIdUHugeInt)
+  , ("FLOAT", LogicalTypeIdFloat)
+  , ("DOUBLE", LogicalTypeIdDouble)
+  , ("DATE", LogicalTypeIdDate)
+  , ("TIME", LogicalTypeIdTime)
+  , ("TIMETZ", LogicalTypeIdTimeTz)
+  , ("TIMESTAMP", LogicalTypeIdTimestamp)
+  , ("TIMESTAMPTZ", LogicalTypeIdTimestampTz)
+  , ("TIMESTAMPTZ_NS", LogicalTypeIdTimestampTzNs)
+  , ("TIMESTAMP_NS WITH TIME ZONE", LogicalTypeIdTimestampTzNs)
+  , ("INTERVAL", LogicalTypeIdInterval)
+  , ("VARCHAR", LogicalTypeIdVarchar)
+  , ("TEXT", LogicalTypeIdVarchar)
+  , ("BLOB", LogicalTypeIdBlob)
+  , ("GEOMETRY", LogicalTypeIdGeometry)
+  , ("VARIANT", LogicalTypeIdVariant)
+  , ("UUID", LogicalTypeIdUUID)
+  , ("BIT", LogicalTypeIdBit)
+  , ("BIGNUM", LogicalTypeIdBigNum)
+  , -- NULL gives an element type to Maybe values without data.
+    ("NULL", LogicalTypeIdSQLNull)
+  ]
+
+-- | Find the type that a column type name denotes.
+duckDBTypeFromName :: Text -> Maybe LogicalTypeId
+duckDBTypeFromName name = lookup name duckDBTypeNames
+
+-- | Find the column type name of a type. Other types use their 'Show' text.
+duckDBTypeToName :: LogicalTypeId -> Text
+duckDBTypeToName dtype =
+  maybe (Text.pack (show dtype)) fst (find ((== dtype) . snd) duckDBTypeNames)
diff --git a/src/Database/DuckDB/Simple/Logging.hs b/src/Database/DuckDB/Simple/Logging.hs
--- a/src/Database/DuckDB/Simple/Logging.hs
+++ b/src/Database/DuckDB/Simple/Logging.hs
@@ -1,95 +1,24 @@
-{-# LANGUAGE BlockArguments #-}
-{-# LANGUAGE NamedFieldPuns #-}
-
-{- |
-Module      : Database.DuckDB.Simple.Logging
-Description : High-level wrappers for DuckDB custom log storage.
--}
+-- |
+-- Module      : Database.DuckDB.Simple.Logging
+-- Description : V2 log sinks with managed callbacks and copied log entries.
 module Database.DuckDB.Simple.Logging (
-    LogEntry (..),
-    registerLogStorage,
+  LogEntry (..),
+  LogLevel (..),
+  LogScope (..),
+  registerLogStorage,
+  registerLogSink,
+  registerInstanceLogSink,
+  logConnectionMessage,
+  logInstanceMessage,
 ) where
 
-import Control.Exception (bracket, mask_)
-import Control.Monad (when)
-import Data.Ratio ((%))
-import Data.Text (Text)
-import qualified Data.Text as Text
-import qualified Data.Text.Foreign as TextForeign
-import Data.Time.Clock (UTCTime)
-import Data.Time.Clock.POSIX (posixSecondsToUTCTime)
-import Database.DuckDB.FFI
-import Database.DuckDB.Simple.Callback (ignoreCallbackExceptions, withCallbackResources)
-import Database.DuckDB.Simple.Internal (Connection, peekUtf8CString, throwRegistrationError, withDatabaseHandle)
-import Foreign.C.String (CString)
-import Foreign.Marshal.Alloc (alloca)
-import Foreign.Ptr (Ptr, nullFunPtr, nullPtr)
-import Foreign.Storable (peek, poke)
-
--- | A single log event delivered through DuckDB's log-storage callback.
-data LogEntry = LogEntry
-    { logEntryTimestamp :: !(Maybe UTCTime)
-    , logEntryLevel :: !Text
-    , logEntryType :: !Text
-    , logEntryMessage :: !Text
-    }
-    deriving (Eq, Show)
-
--- | Register a custom log storage callback on the database behind a connection.
-registerLogStorage :: Connection -> Text -> (LogEntry -> IO ()) -> IO ()
-registerLogStorage conn name callback = do
-    when (Text.null name || Text.any (== '\0') name) $
-        throwRegistrationError "invalid log storage name"
-    bracket c_duckdb_create_log_storage destroyLogStorage \storage -> do
-        when (storage == nullPtr) $ throwRegistrationError "allocate log storage"
-        withCallbackResources
-            (\allocate -> allocate (mkWriteLogEntryCallback (logStorageHandler callback)))
-            (c_duckdb_log_storage_set_extra_data storage)
-            \writeCb -> do
-                TextForeign.withCString name $ c_duckdb_log_storage_set_name storage
-                c_duckdb_log_storage_set_write_log_entry storage writeCb
-                withDatabaseHandle conn \db -> mask_ do
-                    rc <- c_duckdb_register_log_storage db storage
-                    -- DuckDB consumes extra data on duplicate-name failure.
-                    -- Clear the wrapper to prevent a second destruction.
-                    c_duckdb_log_storage_set_extra_data storage nullPtr nullFunPtr
-                    when (rc /= DuckDBSuccess) $ throwRegistrationError "register log storage"
-
-logStorageHandler ::
-    (LogEntry -> IO ()) ->
-    Ptr () ->
-    Ptr DuckDBTimestamp ->
-    CString ->
-    CString ->
-    CString ->
-    IO ()
-logStorageHandler callback _ timestampPtr levelPtr logTypePtr messagePtr =
-    ignoreCallbackExceptions do
-        entry <- do
-            logEntryTimestamp <- readTimestamp timestampPtr
-            logEntryLevel <- readCStringText levelPtr
-            logEntryType <- readCStringText logTypePtr
-            logEntryMessage <- readCStringText messagePtr
-            pure LogEntry{logEntryTimestamp, logEntryLevel, logEntryType, logEntryMessage}
-        callback entry
-
-readTimestamp :: Ptr DuckDBTimestamp -> IO (Maybe UTCTime)
-readTimestamp ptr
-    | ptr == nullPtr = pure Nothing
-    | otherwise = do
-        DuckDBTimestamp micros <- peek ptr
-        pure (Just (posixSecondsToUTCTime (fromRational (toInteger micros % 1000000))))
-
-readCStringText :: CString -> IO Text
-readCStringText ptr
-    | ptr == nullPtr = pure Text.empty
-    | otherwise = peekUtf8CString ptr
-
-destroyLogStorage :: DuckDBLogStorage -> IO ()
-destroyLogStorage storage =
-    alloca \ptr -> poke ptr storage >> c_duckdb_destroy_log_storage ptr
-
-foreign import ccall "wrapper"
-    mkWriteLogEntryCallback ::
-        (Ptr () -> Ptr DuckDBTimestamp -> CString -> CString -> CString -> IO ()) ->
-        IO DuckDBLoggerWriteLogEntryFun
+import Database.DuckDB.Simple.Logging.Internal (
+  LogEntry (..),
+  LogLevel (..),
+  LogScope (..),
+  logConnectionMessage,
+  logInstanceMessage,
+  registerInstanceLogSink,
+  registerLogSink,
+  registerLogStorage,
+ )
diff --git a/src/Database/DuckDB/Simple/Logging/Internal.hs b/src/Database/DuckDB/Simple/Logging/Internal.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/Logging/Internal.hs
@@ -0,0 +1,178 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE StrictData #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.Logging.Internal
+-- Description : Share the log sink registration for connections and extensions.
+--
+-- The cabal file lists this hidden module in @other-modules@.
+-- 'registerLogSinkOn' takes a registration target.
+-- "Database.DuckDB.Simple.Logging" exports the connection and instance forms.
+-- "Database.DuckDB.Simple.Extension" exports the extension form.
+module Database.DuckDB.Simple.Logging.Internal (
+  LogEntry (..),
+  LogLevel (..),
+  LogScope (..),
+  registerLogStorage,
+  registerLogSink,
+  registerInstanceLogSink,
+  registerLogSinkOn,
+  logConnectionMessage,
+  logInstanceMessage,
+) where
+
+import Control.Exception (bracket)
+import Control.Monad (when)
+import Data.Ratio ((%))
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Data.Time.Clock (UTCTime)
+import Data.Time.Clock.POSIX (posixSecondsToUTCTime)
+import Data.Word (Word64)
+import Database.DuckDB.Simple.Callback (
+  RegistrationTarget (..),
+  attachOpaque,
+  install,
+  installAll,
+  requireWorkerCallbackRuntime,
+  runCallback,
+  withCallbackResourcesFinally,
+ )
+import Database.DuckDB.Simple.Internal (Connection, Instance, withConnectionHandle, withDatabaseHandle, withInstanceHandle)
+import Database.DuckDB.Simple.Native
+import Foreign.C.ConstPtr (ConstPtr (..))
+import Foreign.C.Types (CBool)
+import Foreign.Marshal.Alloc (alloca)
+import Foreign.Ptr (Ptr)
+import Foreign.Storable (peek)
+
+-- | A copied log event. Native context identifiers are absent outside their scope.
+data LogEntry = LogEntry
+  { logEntryTimestamp :: Maybe UTCTime
+  , logEntryLevel :: Text
+  , logEntryType :: Text
+  , logEntryMessage :: Text
+  , logEntrySeverity :: LogLevel
+  , logEntryScope :: LogScope
+  , logEntryConnectionId :: Maybe Word64
+  , logEntryTransactionId :: Maybe Word64
+  , logEntryQueryId :: Maybe Word64
+  , logEntryThreadId :: Maybe Word64
+  }
+  deriving (Eq, Show)
+
+-- | Register a log sink without a flush action.
+-- Select the sink through DuckDB's logging configuration to receive entries.
+registerLogStorage :: Connection -> Text -> (LogEntry -> IO ()) -> IO ()
+registerLogStorage conn name write = registerLogSink conn name write (pure ())
+
+-- | Register an instance log sink through a live connection. Log sinks require
+-- the threaded GHC runtime (@-threaded@), including with one query thread.
+-- Callbacks can run concurrently on native threads. They must not log or change
+-- logging settings. Native logging discards callback errors after containment.
+-- The flush action also runs when DuckDB releases the sink. If the registration
+-- fails after the name check, the flush action runs one time.
+registerLogSink :: Connection -> Text -> (LogEntry -> IO ()) -> IO () -> IO ()
+registerLogSink conn name write flush = withDatabaseHandle conn \instance_ ->
+  withInstanceFactory instance_ \factory ->
+    registerSink
+      factory
+      (checked . c_duckdb_v2_instance_register_log_sink instance_)
+      name
+      write
+      flush
+
+-- | Register a log sink on an explicitly managed instance. If the registration
+-- fails after the name check, the flush action runs one time.
+registerInstanceLogSink :: Instance -> Text -> (LogEntry -> IO ()) -> IO () -> IO ()
+registerInstanceLogSink instance_ name write flush = withInstanceHandle instance_ \native ->
+  withInstanceFactory native \factory ->
+    registerSink
+      factory
+      (checked . c_duckdb_v2_instance_register_log_sink native)
+      name
+      write
+      flush
+
+-- | Register a log sink on a connection or a loading extension.
+registerLogSinkOn :: RegistrationTarget -> Text -> (LogEntry -> IO ()) -> IO () -> IO ()
+registerLogSinkOn target name write flush = case target of
+  ConnectionTarget conn -> registerLogSink conn name write flush
+  ExtensionTarget extension context -> withContextFactory context \factory ->
+    registerSink
+      factory
+      (checked . c_duckdb_v2_extension_register_log_sink extension)
+      name
+      write
+      flush
+
+-- | Transfer callback ownership to the native sink and release its builder.
+registerSink
+  :: DuckDBV2FactoryHandle -> (DuckDBV2LogSinkHandle -> IO ()) -> Text -> (LogEntry -> IO ()) -> IO () -> IO ()
+registerSink factory register name write flush = do
+  when (Text.null name || Text.any (== '\0') name) $ throwInvalidArgument "log sink name must be nonempty and must not contain NUL"
+  bracket (output (c_duckdb_v2_log_sink_create factory)) (destroy c_duckdb_v2_log_sink_destroy) \sink ->
+    withCallbackResourcesFinally
+      (requireWorkerCallbackRuntime "log sink")
+      flush
+      ( \allocate ->
+          installAll
+            [ install
+                allocate
+                DuckDBV2LogSinkWriteCallbackFn
+                ( DuckDBV2LogSinkWriteCallbackFn_Aux \info _ timestamp level scope (ConstPtr kind) (ConstPtr message) err -> runCallback err do
+                    category <- peek kind >>= readText
+                    body <- peek message >>= readText
+                    connection <- optionalId (c_duckdb_v2_log_sink_write_info_get_connection_id info)
+                    transaction <- optionalId (c_duckdb_v2_log_sink_write_info_get_transaction_id info)
+                    query <- optionalId (c_duckdb_v2_log_sink_write_info_get_query_id info)
+                    thread <- optionalId (c_duckdb_v2_log_sink_write_info_get_thread_id info)
+                    severity <- logLevelFromNative level
+                    origin <- logScopeFromNative scope
+                    let time = posixSecondsToUTCTime (fromRational (toInteger timestamp % 1000000))
+                    write (LogEntry (Just time) (levelName severity) category body severity origin connection transaction query thread)
+                )
+                (c_duckdb_v2_log_sink_set_write_callback sink)
+            , install
+                allocate
+                DuckDBV2LogSinkFlushCallbackFn
+                (DuckDBV2LogSinkFlushCallbackFn_Aux \_ _ err -> runCallback err flush)
+                (c_duckdb_v2_log_sink_set_flush_callback sink)
+            ]
+      )
+      (attachOpaque (c_duckdb_v2_log_sink_set_user_data sink))
+      \installCallbacks -> do
+        withIdentifier name $ checked . c_duckdb_v2_log_sink_set_name sink
+        installCallbacks
+        register sink
+
+-- | Copy an optional identifier from a borrowed log-entry context.
+optionalId :: (Ptr DuckDBIdx -> Ptr CBool -> Ptr DuckDBV2ErrorInfoHandle -> IO DuckDBV2Error) -> IO (Maybe Word64)
+optionalId getter = alloca \present -> do
+  value <- output (\slot -> getter slot present)
+  exists <- peek present
+  pure (if exists == 0 then Nothing else Just (fromIntegral value))
+
+-- | Retain the textual severity names of the log-storage interface.
+levelName :: LogLevel -> Text
+levelName = \case
+  LogLevelTrace -> "TRACE"
+  LogLevelDebug -> "DEBUG"
+  LogLevelInfo -> "INFO"
+  LogLevelWarning -> "WARNING"
+  LogLevelError -> "ERROR"
+  LogLevelFatal -> "FATAL"
+
+-- | Emit a connection-scoped message through its current logging configuration.
+logConnectionMessage :: Connection -> LogLevel -> Text -> Text -> IO ()
+logConnectionMessage conn level category message = withConnectionHandle conn \native ->
+  withText category \kind -> withText message \body ->
+    checked (c_duckdb_v2_connection_log native (logLevelToNative level) kind body)
+
+-- | Emit a database-scoped message on an explicit instance.
+logInstanceMessage :: Instance -> LogLevel -> Text -> Text -> IO ()
+logInstanceMessage instance_ level category message = withInstanceHandle instance_ \native ->
+  withText category \kind -> withText message \body ->
+    checked (c_duckdb_v2_instance_log native (logLevelToNative level) kind body)
diff --git a/src/Database/DuckDB/Simple/LogicalRep.hs b/src/Database/DuckDB/Simple/LogicalRep.hs
--- a/src/Database/DuckDB/Simple/LogicalRep.hs
+++ b/src/Database/DuckDB/Simple/LogicalRep.hs
@@ -1,252 +1,315 @@
-{-# LANGUAGE BlockArguments #-}
 {-# LANGUAGE LambdaCase #-}
 {-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
 
-{- |
-Module      : Database.DuckDB.Simple.LogicalRep
-Description : Structured logical-type and value representations for DuckDB.
--}
+-- |
+-- Module      : Database.DuckDB.Simple.LogicalRep
+-- Description : Structured logical-type and value representations for DuckDB.
+--
+-- "Database.DuckDB.Simple.V2.LogicalRep" converts these types to and from native
+-- logical types.
 module Database.DuckDB.Simple.LogicalRep (
-    -- * Structured value helpers
-    StructField (..),
-    StructValue (..),
-    UnionMemberType (..),
-    UnionValue (..),
-    LogicalTypeRep (..),
-    structValueTypeRep,
-    unionValueTypeRep,
-    logicalTypeToRep,
-    logicalTypeFromRep,
-    logicalTypeFromRepWith,
-    destroyLogicalType,
+  -- * Structured value helpers
+  StructField (..),
+  StructValue (..),
+  TupleValue (..),
+  UnionMemberType (..),
+  UnionValue (..),
+  LogicalTypeRep (..),
+  LogicalTypeId (..),
+  TypeDeclaration (..),
+  withoutAliases,
+  aliasBase,
+  listElementType,
+  mapEntryTypes,
+  logicalTypeSQL,
+  structValueTypeRep,
+  tupleValueTypeRep,
+  unionValueTypeRep,
 ) where
 
-import Control.Exception (bracket, throwIO)
-import Control.Monad (forM, when)
-import Data.Array (Array, elems, listArray)
-import qualified Data.ByteString as BS
+import Data.Array (Array, elems)
+import Data.Char (isAsciiLower, isAsciiUpper, isDigit)
 import Data.Map.Strict (Map)
+import Data.Set (Set)
+import qualified Data.Set as Set
 import Data.Text (Text)
 import qualified Data.Text as Text
-import qualified Data.Text.Encoding as TextEncoding
 import Data.Word (Word16, Word64, Word8)
-import Database.DuckDB.FFI
-import Foreign.C.String (CString)
-import Foreign.Marshal.Alloc (alloca)
-import Foreign.Marshal.Array (withArray)
-import Foreign.Marshal.Utils (withMany)
-import Foreign.Ptr (castPtr, nullPtr)
-import Foreign.Storable (poke)
+import Database.DuckDB.Simple.Native (LogicalTypeId (..), logicalTypeIdName)
 
--- | A Haskell description of a DuckDB logical type tree.
+-- | A Haskell description of a DuckDB logical type tree. See
+-- Note [Type aliases] for 'LogicalTypeAlias'.
 data LogicalTypeRep
-    = LogicalTypeScalar DuckDBType
-    | LogicalTypeDecimal !Word8 !Word8
-    | LogicalTypeGeometry !(Maybe Text)
-    | LogicalTypeList LogicalTypeRep
-    | LogicalTypeArray LogicalTypeRep !Word64
-    | LogicalTypeMap LogicalTypeRep LogicalTypeRep
-    | LogicalTypeStruct !(Array Int (StructField LogicalTypeRep))
-    | LogicalTypeUnion !(Array Int UnionMemberType)
-    | LogicalTypeEnum !(Array Int Text)
-    deriving (Eq, Show)
+  = LogicalTypeScalar LogicalTypeId
+  | LogicalTypeDecimal !Word8 !Word8
+  | LogicalTypeCollatedVarchar !Text
+  | LogicalTypeGeometry !(Maybe Text)
+  | LogicalTypeList LogicalTypeRep
+  | LogicalTypeArray LogicalTypeRep !Word64
+  | LogicalTypeMap LogicalTypeRep LogicalTypeRep
+  | LogicalTypeStruct !(Array Int (StructField LogicalTypeRep))
+  | LogicalTypeTuple !(Array Int LogicalTypeRep)
+  | LogicalTypeUnion !(Array Int UnionMemberType)
+  | LogicalTypeEnum !(Array Int Text)
+  | LogicalTypeAlias !Text LogicalTypeRep
+  deriving (Eq, Show)
 
+{- Note [Type aliases]
+~~~~~~~~~~~~~~~~~~~~~~
+DuckDB can keep an alias on a type. The alias uses the value representation of
+its base type, and the type text of DuckDB gives the alias. In DuckDB 2.0.0 these
+types have an alias:
+
+- JSON. It is VARCHAR with the alias JSON, also as a child type, for example
+  the element type of JSON[].
+- A type from 'Database.DuckDB.Simple.Registration.registerCustomType'.
+- A type from duckdb_v2_factory_create_type_with_alias.
+
+A column of a type from SQL @CREATE TYPE name AS base@ has the base type and no
+alias. A column of an ENUM type from @CREATE TYPE name AS ENUM (...)@ also has
+no name.
+
+LogicalTypeAlias holds the alias and the base type. logicalTypeToRep in
+"Database.DuckDB.Simple.V2.LogicalRep" makes it at each depth. The V2 API has
+no function that gives only the alias. duckdb_v2_logical_type_get_name gives
+the alias of a type, or the name of the type id for a type with no alias. A
+name that is not the name of the type id (logicalTypeIdName in
+"Database.DuckDB.Simple.Native") is an alias. When the names are equal,
+logicalTypeToRep makes a temporary copy with that alias and compares the two
+native types. DuckDB includes the alias in type equality, so equal types mean
+that the original type has the alias. This also distinguishes INTEGER from
+INTEGER with the alias INTEGER, whose type texts are equal.
+
+logicalTypeToRep borrows a factory for this comparison. The factory can be
+from any instance. The comparison does not parse a type, run SQL, or call user
+code. The temporary type is destroyed before the function returns.
+logicalTypeFromRep writes the alias with
+duckdb_v2_factory_create_type_with_alias.
+
+The base type decides value conversion and vector layout. These operations use
+logicalTypeToBaseRep, which reads no type name. Collection binding also compares
+native type identity to keep aliases during element type inference. A temporal
+promotion reads full type trees to keep aliases on unchanged leaves. See
+Note [Element types of a list] in "Database.DuckDB.Simple.ToField".
+These places keep the alias:
+
+- A 'Database.DuckDB.Simple.Catalog.ColumnDescription'.
+- The type fields of a STRUCT, TUPLE, or UNION value that a reader gives. The
+  reader of a vector takes its tree from logicalTypeToRep, and it decides with
+  aliasBase. A value that the library reads and binds again keeps its type when
+  the native default cast supports its aliases, for example STRUCT(k JSON).
+
+Alias metadata does not imply native cast support. DuckDB 2.0.0 cannot cast a
+TIME value to an alias of TIME through the default cast. The library writes
+TIME alias payloads through public vector storage. See Note [TIME alias values]
+in "Database.DuckDB.Simple.ToField". LogicalTypeRep stores the alias
+name and public type parameters. It does not store other C++ extension metadata.
+
+Use withoutAliases to compare base types.
+-}
+
+-- | Replace each alias with its base type, at each depth. See
+-- Note [Type aliases].
+withoutAliases :: LogicalTypeRep -> LogicalTypeRep
+withoutAliases = \case
+  LogicalTypeAlias _ base -> withoutAliases base
+  LogicalTypeList child -> LogicalTypeList (withoutAliases child)
+  LogicalTypeArray child size -> LogicalTypeArray (withoutAliases child) size
+  LogicalTypeMap key value -> LogicalTypeMap (withoutAliases key) (withoutAliases value)
+  LogicalTypeStruct fields -> LogicalTypeStruct (fmap (\field -> field{structFieldValue = withoutAliases (structFieldValue field)}) fields)
+  LogicalTypeTuple fields -> LogicalTypeTuple (fmap withoutAliases fields)
+  LogicalTypeUnion members -> LogicalTypeUnion (fmap (\member -> member{unionMemberType = withoutAliases (unionMemberType member)}) members)
+  rep -> rep
+
+-- | Remove the aliases at the top of a type. The child types keep their
+-- aliases. See Note [Type aliases].
+aliasBase :: LogicalTypeRep -> LogicalTypeRep
+aliasBase (LogicalTypeAlias _ base) = aliasBase base
+aliasBase rep = rep
+
+-- | The type of an element of a LIST or an ARRAY, from the type of its parent.
+-- The function looks through an alias. Another parent type gives VARIANT: the
+-- type of each stored value decides. See Note [Column types] in
+-- "Database.DuckDB.Simple.FromField".
+listElementType :: LogicalTypeRep -> LogicalTypeRep
+listElementType parent = case aliasBase parent of
+  LogicalTypeList element -> element
+  LogicalTypeArray element _ -> element
+  _ -> LogicalTypeScalar LogicalTypeIdVariant
+
+-- | The key type and the value type of a MAP, from the type of its parent, as
+-- 'listElementType' gives an element type.
+mapEntryTypes :: LogicalTypeRep -> (LogicalTypeRep, LogicalTypeRep)
+mapEntryTypes parent = case aliasBase parent of
+  LogicalTypeMap key value -> (key, value)
+  _ -> (LogicalTypeScalar LogicalTypeIdVariant, LogicalTypeScalar LogicalTypeIdVariant)
+
+{- Note [Type texts]
+~~~~~~~~~~~~~~~~~~~~
+logicalTypeSQL gives the text of a type that duckdb_v2_logical_type_to_text of
+DuckDB 2.0.0 gives, for example DECIMAL(18,3), BIGINT[], INTEGER[3],
+MAP(VARCHAR, BIGINT), ENUM('sad', 'happy'), and GEOMETRY('OGC:CRS84'). An
+alias gives its name, for example JSON. The function is pure, so an error of a
+FromField instance can name the type with no native handle, and the text costs
+nothing until an error renders.
+
+These rules follow LogicalType::ToString of DuckDB 2.0.0:
+
+- A scalar type has the name of its type id (logicalTypeIdName in
+  "Database.DuckDB.Simple.Native"), and SQL NULL is "NULL" in double quotes. A
+  VARCHAR with a collation is VARCHAR: the text has no collation.
+- A label of an ENUM and a CRS are in single quotes, with each single quote
+  doubled.
+- A field name of a STRUCT and a member name of a UNION are in double quotes,
+  with each double quote doubled, when the name needs quotes. A name needs
+  quotes when it has a character that is not an ASCII letter, a digit, or an
+  underscore, when it starts with a digit or an underscore followed by a digit,
+  or when it is a keyword of DuckDB in any case (SQLIdentifier::ToString).
+  The keywords are the 502 names of duckdb_keywords() of DuckDB 2.0.0.
+- An empty STRUCT or TUPLE has only its type name, with no parentheses.
+
+A test case compares the text with duckdb_v2_logical_type_to_text for one type of
+each kind and for a STRUCT with each keyword as a field name.
+-}
+
+-- | The SQL text of a type, as DuckDB gives it, for example DECIMAL(18,3) or
+-- JSON. See Note [Type texts].
+logicalTypeSQL :: LogicalTypeRep -> Text
+logicalTypeSQL = \case
+  LogicalTypeScalar LogicalTypeIdSQLNull -> "\"NULL\""
+  LogicalTypeScalar ident -> logicalTypeIdName ident
+  LogicalTypeDecimal width scale -> "DECIMAL(" <> number width <> "," <> number scale <> ")"
+  LogicalTypeCollatedVarchar _ -> "VARCHAR"
+  LogicalTypeGeometry Nothing -> "GEOMETRY"
+  LogicalTypeGeometry (Just crs) -> "GEOMETRY(" <> quoted '\'' crs <> ")"
+  LogicalTypeList element -> logicalTypeSQL element <> "[]"
+  LogicalTypeArray element size -> logicalTypeSQL element <> "[" <> number size <> "]"
+  LogicalTypeMap key value -> "MAP(" <> logicalTypeSQL key <> ", " <> logicalTypeSQL value <> ")"
+  LogicalTypeStruct fields
+    | null (elems fields) -> "STRUCT"
+    | otherwise -> "STRUCT(" <> commas [identifier name <> " " <> logicalTypeSQL rep | StructField name rep <- elems fields] <> ")"
+  LogicalTypeTuple fields
+    | null (elems fields) -> "TUPLE"
+    | otherwise -> "TUPLE(" <> commas (map logicalTypeSQL (elems fields)) <> ")"
+  LogicalTypeUnion members -> "UNION(" <> commas [identifier name <> " " <> logicalTypeSQL rep | UnionMemberType name rep <- elems members] <> ")"
+  LogicalTypeEnum labels -> "ENUM(" <> commas (map (quoted '\'') (elems labels)) <> ")"
+  LogicalTypeAlias name _ -> name
+  where
+    number :: (Show n) => n -> Text
+    number = Text.pack . show
+    commas = Text.intercalate ", "
+    quoted mark text = Text.singleton mark <> Text.replace (Text.singleton mark) (Text.pack [mark, mark]) text <> Text.singleton mark
+    identifier name
+      | needsQuotes name = quoted '"' name
+      | otherwise = name
+    needsQuotes name =
+      Text.null name
+        || (Text.isPrefixOf "_" name && maybe False (isDigit . fst) (Text.uncons (Text.drop 1 name)))
+        || not (and (zipWith plain [0 :: Int ..] (Text.unpack name)))
+        || Set.member (Text.toLower name) duckDBKeywords
+    plain index char = isAsciiLower char || isAsciiUpper char || char == '_' || (index > 0 && isDigit char)
+
+-- | The keywords of DuckDB 2.0.0, from duckdb_keywords(). A field name that is
+-- a keyword needs quotes. See Note [Type texts].
+duckDBKeywords :: Set Text
+duckDBKeywords =
+  Set.fromList . Text.words $
+    "abort absolute access action add admin after aggregate all also alter always analyse analyze and anti any \
+    \ approx array as asc asof assertion assignment asymmetric at attach attribute authorization backward before \
+    \ begin between bigint binary bit boolean both by cache call called cascade cascaded case cast catalog centuries \
+    \ century chain char character characteristics check checkpoint class close cluster coalesce collate collation \
+    \ column columns comment comments commit committed compression concurrently configuration conflict connect \
+    \ connection constraint constraints content continue conversion copy cost create cross csv cube current cursor \
+    \ cycle data database day days deallocate dec decade decades decimal declare default defaults deferrable \
+    \ deferred definer delete delimiter delimiters depends desc describe destroy detach dictionary disable discard \
+    \ disconnect distance distinct do document domain double drop each else enable encoding encrypted end enum error \
+    \ escape event exact except exclude excluding exclusive execute exists explain export export_state extension \
+    \ extensions external extract false family fetch filter first float following for force foreign forward freeze \
+    \ from full function functions generated glob global grant granted group grouping grouping_id groups handler \
+    \ having header hold hour hours identity if ignore ilike immediate immutable implicit import in include \
+    \ including increment index indexes inherit inherits initially inline inner inout input insensitive insert \
+    \ install instead int integer intersect interval into invoker is isnull isolation join json key label lambda \
+    \ language large last lateral leading leakproof left level like limit listen load local location lock locked \
+    \ logged macro map mapping match matched materialized maxvalue merge method microsecond microseconds millennia \
+    \ millennium millisecond milliseconds minute minutes minvalue mode month months move name names national natural \
+    \ nchar nearest new next no none not nothing notify notnull nowait null nullif nulls numeric object of off \
+    \ offset oids old on only operator option options or order ordinality others out outer over overlaps overlay \
+    \ overriding owned owner parallel parser partial partition partitioned passing password percent persistent pivot \
+    \ pivot_longer pivot_wider placing plans policy position positional pragma preceding precision prepare prepared \
+    \ preserve primary prior privileges procedural procedure program publication qualify quarter quarters quote \
+    \ range read real reassign recheck recursive ref references referencing refresh register reindex relative \
+    \ release rename repeatable replace replica reset resource resources respect restart restrict returning returns \
+    \ revoke right role rollback rollup row rows rule sample savepoint schema schemas scope scroll search second \
+    \ seconds secret secure security select semi sequence sequences serializable server session set setof sets share \
+    \ show similar similarity simple skip smallint snapshot some sorted source sql stable standalone start statement \
+    \ statistics stdin stdout storage stored strict strip struct subscription substring summarize symmetric sysid \
+    \ system table tables tablesample tablespace target temp template temporary text then ties time timestamp to \
+    \ trailing transaction transform treat trigger trim true truncate trusted try_cast tuple type types unbounded \
+    \ uncommitted unencrypted union unique unknown unlisten unlogged unpack unpivot until update use user using \
+    \ vacuum valid validate validator value values varchar variable variadic varying verbose version view views \
+    \ virtual volatile week weeks when where whitespace window with within without work wrapper write xml \
+    \ xmlattributes xmlconcat xmlelement xmlexists xmlforest xmlnamespaces xmlparse xmlpi xmlroot xmlserialize \
+    \ xmltable year years yes zone"
+
+-- | A structured type or a SQL type expression. A 'TypeExpression' with the
+-- name of a type from 'Database.DuckDB.Simple.Registration.registerCustomType'
+-- keeps that name, so a cast to it is a cast to the custom type. A name from
+-- SQL @CREATE TYPE name AS base@ is only another name for the base type, so a
+-- cast to it is a cast to the base type. In a test with DuckDB 2.0.0, a
+-- registered cast from BIGINT to a name for BIGINT did not run. The header of
+-- DuckDB 2.0.0 says that a catalog type name is not kept, but DuckDB 2.0.0
+-- keeps the name of a type from
+-- 'Database.DuckDB.Simple.Registration.registerCustomType'.
+data TypeDeclaration = StructuredType LogicalTypeRep | TypeExpression Text
+  deriving (Eq, Show)
+
 -- | A named field within a STRUCT-like value or type.
 data StructField a = StructField
-    { structFieldName :: !Text
-    , structFieldValue :: !a
-    }
-    deriving (Eq, Show)
+  { structFieldName :: !Text
+  , structFieldValue :: !a
+  }
+  deriving (Eq, Show)
 
 -- | A fully materialized STRUCT value together with its type metadata.
 data StructValue a = StructValue
-    { structValueFields :: !(Array Int (StructField a))
-    , structValueTypes :: !(Array Int (StructField LogicalTypeRep))
-    , structValueIndex :: !(Map Text Int)
-    }
-    deriving (Eq, Show)
+  { structValueFields :: !(Array Int (StructField a))
+  , structValueTypes :: !(Array Int (StructField LogicalTypeRep))
+  , structValueIndex :: !(Map Text Int)
+  }
+  deriving (Eq, Show)
 
+-- | A positional TUPLE value with its field types. Array bounds are independent.
+data TupleValue a = TupleValue
+  { tupleValueFields :: !(Array Int a)
+  , tupleValueTypes :: !(Array Int LogicalTypeRep)
+  }
+  deriving (Eq, Show)
+
 -- | A named member within a UNION type.
 data UnionMemberType = UnionMemberType
-    { unionMemberName :: !Text
-    , unionMemberType :: !LogicalTypeRep
-    }
-    deriving (Eq, Show)
+  { unionMemberName :: !Text
+  , unionMemberType :: !LogicalTypeRep
+  }
+  deriving (Eq, Show)
 
 -- | A fully materialized UNION value together with its member metadata.
 data UnionValue a = UnionValue
-    { unionValueIndex :: !Word16
-    , unionValueLabel :: !Text
-    , unionValuePayload :: !a
-    , unionValueMembers :: !(Array Int UnionMemberType)
-    }
-    deriving (Eq, Show)
+  { unionValueIndex :: !Word16
+  , unionValueLabel :: !Text
+  , unionValuePayload :: !a
+  , unionValueMembers :: !(Array Int UnionMemberType)
+  }
+  deriving (Eq, Show)
 
 -- | Recover the logical STRUCT type corresponding to a @StructValue@.
 structValueTypeRep :: StructValue a -> LogicalTypeRep
 structValueTypeRep StructValue{structValueTypes} = LogicalTypeStruct structValueTypes
 
+-- | Recover the logical TUPLE type of a positional value.
+tupleValueTypeRep :: TupleValue a -> LogicalTypeRep
+tupleValueTypeRep TupleValue{tupleValueTypes} = LogicalTypeTuple tupleValueTypes
+
 -- | Recover the logical UNION type corresponding to a @UnionValue@.
 unionValueTypeRep :: UnionValue a -> LogicalTypeRep
 unionValueTypeRep UnionValue{unionValueMembers} = LogicalTypeUnion unionValueMembers
-
--- | Destroy a logical type handle obtained from DuckDB.
-destroyLogicalType :: DuckDBLogicalType -> IO ()
-destroyLogicalType logical =
-    alloca \ptr -> do
-        poke ptr logical
-        c_duckdb_destroy_logical_type ptr
-
--- | Convert a DuckDB logical type handle into the pure @LogicalTypeRep@ tree.
-logicalTypeToRep :: DuckDBLogicalType -> IO LogicalTypeRep
-logicalTypeToRep logical = do
-    dtype <- c_duckdb_get_type_id logical
-    case dtype of
-        DuckDBTypeGeometry ->
-            bracket (c_duckdb_geometry_type_get_crs logical) (c_duckdb_free . castPtr) \ptr ->
-                LogicalTypeGeometry <$> if ptr == nullPtr then pure Nothing else Just . TextEncoding.decodeUtf8 <$> BS.packCString ptr
-        DuckDBTypeStruct -> do
-            childCountRaw <- c_duckdb_struct_type_child_count logical
-            childCount <- word64ToInt (Text.pack "struct child count") childCountRaw
-            fields <-
-                forM [0 .. childCount - 1] \idx -> do
-                    name <- bracket (c_duckdb_struct_type_child_name logical (fromIntegral idx)) (c_duckdb_free . castPtr) $ \ptr -> do
-                        when (ptr == nullPtr) $
-                            throwIO (userError "duckdb-simple: struct child name is null")
-                        TextEncoding.decodeUtf8 <$> BS.packCString ptr
-                    childRep <-
-                        bracket (c_duckdb_struct_type_child_type logical (fromIntegral idx)) destroyLogicalType logicalTypeToRep
-                    pure StructField{structFieldName = name, structFieldValue = childRep}
-            pure $
-                LogicalTypeStruct
-                    (listArray (0, childCount - 1) fields)
-        DuckDBTypeUnion -> do
-            memberCountRaw <- c_duckdb_union_type_member_count logical
-            memberCount <- word64ToInt (Text.pack "union member count") memberCountRaw
-            members <-
-                forM [0 .. memberCount - 1] \idx -> do
-                    name <- bracket (c_duckdb_union_type_member_name logical (fromIntegral idx)) (c_duckdb_free . castPtr) $ \ptr -> do
-                        when (ptr == nullPtr) $
-                            throwIO (userError "duckdb-simple: union member name is null")
-                        TextEncoding.decodeUtf8 <$> BS.packCString ptr
-                    memberRep <-
-                        bracket (c_duckdb_union_type_member_type logical (fromIntegral idx)) destroyLogicalType logicalTypeToRep
-                    pure UnionMemberType{unionMemberName = name, unionMemberType = memberRep}
-            pure $
-                LogicalTypeUnion
-                    (listArray (0, memberCount - 1) members)
-        DuckDBTypeList -> do
-            childRep <- bracket (c_duckdb_list_type_child_type logical) destroyLogicalType logicalTypeToRep
-            pure (LogicalTypeList childRep)
-        DuckDBTypeArray -> do
-            childRep <- bracket (c_duckdb_array_type_child_type logical) destroyLogicalType logicalTypeToRep
-            size <- c_duckdb_array_type_array_size logical
-            pure (LogicalTypeArray childRep size)
-        DuckDBTypeMap -> do
-            keyRep <- bracket (c_duckdb_map_type_key_type logical) destroyLogicalType logicalTypeToRep
-            valueRep <- bracket (c_duckdb_map_type_value_type logical) destroyLogicalType logicalTypeToRep
-            pure (LogicalTypeMap keyRep valueRep)
-        DuckDBTypeDecimal -> do
-            width <- c_duckdb_decimal_width logical
-            scale <- c_duckdb_decimal_scale logical
-            pure (LogicalTypeDecimal width scale)
-        DuckDBTypeEnum -> do
-            dictSize <- c_duckdb_enum_dictionary_size logical
-            let count = fromIntegral dictSize :: Int
-            entries <-
-                forM [0 .. count - 1] \idx -> do
-                    entry <- bracket (c_duckdb_enum_dictionary_value logical (fromIntegral idx)) (c_duckdb_free . castPtr) $ \ptr -> do
-                        when (ptr == nullPtr) $
-                            throwIO (userError "duckdb-simple: enum dictionary value is null")
-                        TextEncoding.decodeUtf8 <$> BS.packCString ptr
-                    pure entry
-            pure $
-                LogicalTypeEnum
-                    (listArray (0, count - 1) entries)
-        _ ->
-            pure (LogicalTypeScalar dtype)
-
-{- | Materialize a DuckDB logical type handle from a @LogicalTypeRep@ tree.
-The C API cannot create a usable VARIANT type or a GEOMETRY type with a CRS.
-This function raises an error for VARIANT. It creates GEOMETRY without a CRS
-and ignores the CRS of 'LogicalTypeGeometry'. Parameter binding uses the
-types that a connection reads the first time a parameter needs one.
--}
-logicalTypeFromRep :: LogicalTypeRep -> IO DuckDBLogicalType
-logicalTypeFromRep = logicalTypeFromRepWith \case
-    -- TODO: improve this when this becomes available in the C API.
-    -- See https://github.com/Tritlo/duckdb-haskell/issues/26 and
-    -- https://github.com/Tritlo/duckdb-haskell/issues/27.
-    LogicalTypeScalar DuckDBTypeVariant ->
-        throwIO (userError "duckdb-simple: a VARIANT type needs the type cache of a connection; bind the value as a parameter or cast a plain value with ?::VARIANT")
-    _ -> c_duckdb_create_logical_type DuckDBTypeGeometry
-
-{- | Materialize a type tree. The function argument creates the leaves that the
-C API cannot create: VARIANT, and GEOMETRY with a CRS. The caller must
-destroy the result.
--}
-logicalTypeFromRepWith :: (LogicalTypeRep -> IO DuckDBLogicalType) -> LogicalTypeRep -> IO DuckDBLogicalType
-logicalTypeFromRepWith resolve rep = do
-    logical <- create rep
-    when (logical == nullPtr) $
-        throwIO (userError "duckdb-simple: DuckDB logical type construction failed")
-    pure logical
-  where
-    create = \case
-        leaf@(LogicalTypeScalar DuckDBTypeVariant) -> resolve leaf
-        LogicalTypeScalar dtype -> c_duckdb_create_logical_type dtype
-        leaf@(LogicalTypeGeometry (Just _)) -> resolve leaf
-        LogicalTypeGeometry Nothing -> c_duckdb_create_logical_type DuckDBTypeGeometry
-        LogicalTypeDecimal width scale -> do
-            when (width < 1 || width > 38 || scale > width) $
-                throwIO (userError "duckdb-simple: invalid DECIMAL width or scale")
-            c_duckdb_create_decimal_type width scale
-        LogicalTypeList elemRep ->
-            bracket (logicalTypeFromRepWith resolve elemRep) destroyLogicalType c_duckdb_create_list_type
-        LogicalTypeArray elemRep size ->
-            bracket (logicalTypeFromRepWith resolve elemRep) destroyLogicalType $
-                flip c_duckdb_create_array_type size
-        LogicalTypeMap keyRep valueRep ->
-            bracket (logicalTypeFromRepWith resolve keyRep) destroyLogicalType \keyType ->
-                bracket (logicalTypeFromRepWith resolve valueRep) destroyLogicalType $
-                    c_duckdb_create_map_type keyType
-        LogicalTypeStruct fieldArray -> do
-            let fields = elems fieldArray
-            withMany (\field -> bracket (logicalTypeFromRepWith resolve (structFieldValue field)) destroyLogicalType) fields \childTypes ->
-                withMany withTypeName (map structFieldName fields) \names ->
-                    withArray names \nameArray ->
-                        withArray childTypes \typeArray ->
-                            c_duckdb_create_struct_type typeArray nameArray (fromIntegral (length fields))
-        LogicalTypeUnion memberArray -> do
-            let members = elems memberArray
-            withMany (\member -> bracket (logicalTypeFromRepWith resolve (unionMemberType member)) destroyLogicalType) members \memberTypes ->
-                withMany withTypeName (map unionMemberName members) \names ->
-                    withArray names \nameArray ->
-                        withArray memberTypes \typeArray ->
-                            c_duckdb_create_union_type typeArray nameArray (fromIntegral (length members))
-        LogicalTypeEnum dictArray ->
-            withMany withTypeName (elems dictArray) \names ->
-                withArray names \nameArray ->
-                    c_duckdb_create_enum_type nameArray (fromIntegral (length names))
-
--- | Encode native type names as UTF-8 and reject embedded NUL.
-withTypeName :: Text -> (CString -> IO a) -> IO a
-withTypeName name action = do
-    when (Text.any (== '\0') name) $
-        throwIO (userError "duckdb-simple: logical type name contains NUL")
-    BS.useAsCString (TextEncoding.encodeUtf8 name) action
-
-word64ToInt :: Text -> Word64 -> IO Int
-word64ToInt label value =
-    let actual = toInteger value
-        limit = toInteger (maxBound :: Int)
-     in if actual <= limit
-            then pure (fromIntegral value)
-            else
-                throwIO
-                    ( userError
-                        ( "duckdb-simple: "
-                            <> Text.unpack label
-                            <> " exceeds Int range"
-                        )
-                    )
diff --git a/src/Database/DuckDB/Simple/Materialize.hs b/src/Database/DuckDB/Simple/Materialize.hs
--- a/src/Database/DuckDB/Simple/Materialize.hs
+++ b/src/Database/DuckDB/Simple/Materialize.hs
@@ -1,308 +1,749 @@
 {-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE DataKinds #-}
 {-# LANGUAGE LambdaCase #-}
 {-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE TypeApplications #-}
 
+-- |
+-- Module      : Database.DuckDB.Simple.Materialize
+-- Description : Readers that copy native vectors and values to field values.
 module Database.DuckDB.Simple.Materialize (
-    prepareValueReader,
-    prepareVectorReader,
+  VectorReader,
+  FallbackReaders (..),
+  rejectRows,
+  prepareVariantReader,
+  readCallbackVariant,
+  readInstanceVariant,
+  createHelperInstance,
+  ReadFactory (..),
+  callbackReadFactory,
+  readFactoryHandle,
+  prepareGeometryReader,
+  materializeValue,
+  prepareVectorReader,
+  TypeTree,
+  EnumLabels,
+  prepareVectorReaderWith,
 ) where
 
-import Control.Exception (throwIO)
-import Control.Monad (forM, when)
-import Data.Array (Array, elems, listArray)
+import Control.Exception (bracket)
+import Control.Monad (foldM, forM, when)
+import Data.Array (Array, bounds, elems, listArray, rangeSize, (!))
+import Data.IORef (IORef, modifyIORef', newIORef, readIORef, writeIORef)
 import Data.Int (Int16, Int32, Int64)
+import qualified Data.IntMap.Strict as IntMap
 import qualified Data.Map.Strict as Map
 import Data.Text (Text)
 import qualified Data.Text as Text
+import Data.Void (Void)
 import Data.Word (Word16, Word32, Word64, Word8)
-import Database.DuckDB.FFI
 import Database.DuckDB.Simple.Element (
-    chunkDecodeBlob,
-    chunkIsRowValid,
-    decodeElement,
-    duckDBHugeIntToInteger,
-    vectorElementType,
-    withVectorType,
+  chunkIsRowValid,
+  decodeElement,
+  duckDBHugeIntToInteger,
+  vectorElementType,
+  withVectorType,
  )
 import Database.DuckDB.Simple.FromField (
-    DecimalValue (..),
-    FieldValue (..),
-    RawGeometry (..),
+  DecimalValue (..),
+  FieldValue (..),
+  RawGeometry (..),
  )
 import Database.DuckDB.Simple.LogicalRep (
-    LogicalTypeRep (..),
-    StructField (..),
-    StructValue (..),
-    UnionMemberType (..),
-    UnionValue (..),
-    logicalTypeToRep,
+  LogicalTypeRep (..),
+  StructField (..),
+  StructValue (..),
+  TupleValue (..),
+  UnionMemberType (..),
+  UnionValue (..),
+  aliasBase,
+  logicalTypeSQL,
  )
-import Database.DuckDB.Simple.VariantCodec (decodeVariant, prepareVariantDecoder)
+import Database.DuckDB.Simple.Native
+import Database.DuckDB.Simple.V2.LogicalRep (logicalTypeToBaseRep, logicalTypeToRep)
+import qualified Database.DuckDB.Simple.VariantCodec as VariantCodec
+import Foreign.C.ConstPtr (ConstPtr (..))
+import Foreign.Marshal.Alloc (alloca)
 import Foreign.Ptr (Ptr, castPtr, nullPtr)
 import Foreign.Storable (Storable (..), peekElemOff)
+import GHC.Records (getField)
 
--- | Read the type, data, and validity of a vector, and prepare its reader.
-prepareVectorReader :: DuckDBVector -> IO (Int -> IO FieldValue)
-prepareVectorReader vector = do
-    dtype <- vectorElementType vector
-    dataPtr <- c_duckdb_vector_get_data vector
-    validity <- c_duckdb_vector_get_validity vector
-    prepareValueReader dtype vector dataPtr validity
+-- | Prepare a reader for the rows of a vector. The reader must not outlive the vector.
+type VectorReader = DuckDBV2VectorHandle -> IO (Int -> IO FieldValue)
 
+-- | Readers that need state outside the vector. Type metadata needs a factory,
+-- VARIANT needs a helper connection, and GEOMETRY needs a factory for casts.
+-- See Note [Type trees]. For VARIANT, see Note [VARIANT decoding] in
+-- "Database.DuckDB.Simple.VariantCodec".
+data FallbackReaders = FallbackReaders
+  { typeReader :: DuckDBV2LogicalTypeHandle -> IO LogicalTypeRep
+  , variantReader :: VectorReader
+  , geometryReader :: VectorReader
+  }
+
+-- | A reader for a type that the caller cannot read. It reads each row when the
+-- row is read, not when the vector is prepared. A NULL row gives 'FieldNull',
+-- and a row that holds a value raises the error. Thus a value of a nested type
+-- with no value of that type, such as an empty VARIANT list or a NULL STRUCT,
+-- gives its value. The header commits to no view layout for VARIANT and
+-- GEOMETRY, so the reader reads each row with @duckdb_v2_vector_get_value@,
+-- whose row is logical. 'prepareVectorReaderWith' flattens the vector, so the
+-- row that the reader gets is the logical row. See Note [Vector flatten]. The
+-- reader creates and destroys one native value for each row.
+rejectRows :: IO FieldValue -> VectorReader
+rejectRows raise vector = pure \row ->
+  bracket (output (c_duckdb_v2_vector_get_value vector (fromIntegral row))) destroyValue \value -> do
+    isNull <- output (c_duckdb_v2_value_is_null value)
+    if isNull /= 0 then pure FieldNull else raise
+
+-- | Copy VARIANT rows before releasing the borrowed helper connection. The
+-- state belongs to that connection. The decoder reads logical rows. See
+-- Note [Vector flatten] and Note [VARIANT decoding] in
+-- "Database.DuckDB.Simple.VariantCodec".
+prepareVariantReader :: VariantCodec.VariantState -> VectorReader
+prepareVariantReader =
+  VariantCodec.prepareVariantDecoder
+    (materializeValue noVariant . InstanceFactory)
+    ( \factory vector ->
+        prepareVectorReader (FallbackReaders (logicalTypeToRep factory) noVariant (prepareGeometryReader (InstanceFactory factory))) vector
+          >>= ($ 0)
+    )
+  where
+    noVariant = rejectRows (throwInternalError (Text.pack "expected a value without VARIANT"))
+
+{- Note [VARIANT reads inside callbacks]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The VARIANT decoder runs SQL. A callback cannot run it on the executing
+connection. Even a new connection to the host instance can need a lock that
+the caller holds, for example during SET GLOBAL. An extension has no host
+instance handle at all.
+
+The decoder uses an instance with only built-in types, casts and system
+functions. A scalar or aggregate registration opens its instance on demand.
+Each vector uses a separate connection on that instance. Other typed
+callbacks, including extension COPY TO, open a private instance for each
+VARIANT vector. The decoder copies the rows before it closes the connection.
+See Note [Function argument readers] in "Database.DuckDB.Simple.Typed"
+and Note [VARIANT decoding] in "Database.DuckDB.Simple.VariantCodec".
+-}
+
+-- | Decode a callback's VARIANT vector independently of the invoking database.
+readCallbackVariant :: VectorReader
+readCallbackVariant vector =
+  bracket (output c_duckdb_v2_environment_create) (destroy c_duckdb_v2_environment_destroy) \env ->
+    bracket (createHelperInstance env) (destroy c_duckdb_v2_instance_destroy) (`readInstanceVariant` vector)
+
+-- | Copy a VARIANT vector through a temporary connection on the supplied instance.
+readInstanceVariant :: DuckDBV2InstanceHandle -> VectorReader
+readInstanceVariant instance_ vector =
+  bracket (output (c_duckdb_v2_connection_create instance_)) (destroy c_duckdb_v2_connection_destroy) \helper ->
+    withInstanceFactory instance_ \factory ->
+      bracket (VariantCodec.newVariantState helper factory) VariantCodec.destroyVariantState (`prepareVariantReader` vector)
+
+-- | Create an instance for synchronous metadata work, without background workers.
+createHelperInstance :: DuckDBV2EnvironmentHandle -> IO DuckDBV2InstanceHandle
+createHelperInstance env =
+  withTextArray (map Text.pack ["threads", "async_threads"]) \names ->
+    withTextArray (map Text.pack ["1", "0"]) \values ->
+      output (c_duckdb_v2_instance_create_with_options env (ConstPtr names) (ConstPtr values) 2)
+
+-- | The factory of a read, and its kind. The kind decides how
+-- 'prepareGeometryReader' casts GEOMETRY to BLOB. See
+-- Note [User casts and the casts of the library].
+data ReadFactory
+  = -- | The factory of an instance. Its casts are the built-in casts.
+    InstanceFactory DuckDBV2FactoryHandle
+  | -- | The factory of a callback context. Its casts include the casts that a
+    -- user registers.
+    ContextFactory DuckDBV2FactoryHandle
+
+-- | The factory of a read in a callback: the factory of the instance from
+-- 'Database.DuckDB.Simple.Callback.targetCastFactory', or the factory of the
+-- context for an extension target, which has no instance.
+callbackReadFactory :: Maybe DuckDBV2FactoryHandle -> DuckDBV2FactoryHandle -> ReadFactory
+callbackReadFactory casts context = maybe (ContextFactory context) InstanceFactory casts
+
+-- | The handle of a read factory.
+readFactoryHandle :: ReadFactory -> DuckDBV2FactoryHandle
+readFactoryHandle (InstanceFactory factory) = factory
+readFactoryHandle (ContextFactory factory) = factory
+
+-- | Copy one value through an owned vector. The caller retains the factory owner.
+-- The first argument reads VARIANT. 'prepareGeometryReader' reads GEOMETRY with
+-- the factory.
+materializeValue :: VectorReader -> ReadFactory -> DuckDBV2ValueHandle -> IO FieldValue
+materializeValue readVariant factory value =
+  bracket (output (c_duckdb_v2_value_get_logical_type value)) (destroy c_duckdb_v2_logical_type_destroy) \logical ->
+    withOwnedVector (readFactoryHandle factory) logical \vector -> do
+      checked (c_duckdb_v2_vector_set_size vector 1)
+      checked (c_duckdb_v2_vector_set_value vector 0 value)
+      prepareVectorReader (FallbackReaders (logicalTypeToRep (readFactoryHandle factory)) readVariant (prepareGeometryReader factory)) vector
+        >>= ($ 0)
+
+{- Note [Type trees]
+~~~~~~~~~~~~~~~~~~~~
+A reader of a vector uses two kinds of type information.
+
+- A layout parameter gives the layout of the bytes, for example the width of a
+  DECIMAL, the size of an ARRAY, or the size of an ENUM dictionary. A decoder
+  takes each layout parameter from the type of its own vector, because that
+  type gives the layout of the bytes. The header of duckdb_v2_vector_get_view
+  says that the data has the layout that the logical type of the vector
+  implies.
+
+- A description is the field names and field types of a STRUCT or TUPLE, or
+  the members of a UNION. A decoder takes a description from a type tree: the
+  LogicalTypeRep that an action of type TypeTree gives. A decoder runs the
+  action only when it needs a description.
+
+Thus a wrong tree gives an error or a wrong description, but it does not change
+how bytes are read. checkChildCount raises an error when a tree gives another
+child count than the vector has.
+
+These are the sources of a tree.
+
+- prepareVectorReader converts the type of the vector.
+- A caller of prepareVectorReaderWith gives the action. A result converts the
+  tree of a column from the vector of the first chunk that needs it, and keeps
+  the tree for one execution (prepareChunkReaders).
+- A nested decoder gives each child an action that takes the tree of the child
+  from its own tree (elementTree, prepareStructDecoder, prepareTupleDecoder, and
+  prepareUnionDecoder). The action of a child runs the action of the parent
+  only when the child needs its tree.
+- The MAP decoder gives its key reader and its value reader no tree, and the
+  UNION decoder gives its tag reader no tree. Each of these readers converts
+  the type of its own vector when it needs a description.
+
+The readers do not use the result schema. The header of
+duckdb_v2_result_get_schema calls the schema the authoritative source of the
+column types, and says that vectors do not carry their own type. But the header
+of duckdb_v2_vector_get_logical_type says that a vector has the type that was
+set on creation, and the layout follows the type of the vector. So the vector
+type is the source of each type.
+-}
+
+-- | An action that gives the type tree of one vector. A decoder runs it only
+-- when it needs a description. See Note [Type trees].
+type TypeTree = IO LogicalTypeRep
+
+-- | Read the type, data, and validity of a vector, and prepare its reader. A
+-- decoder that needs the type tree converts the type of the vector. See
+-- Note [Type trees].
+prepareVectorReader :: FallbackReaders -> DuckDBV2VectorHandle -> IO (Int -> IO FieldValue)
+prepareVectorReader readers vector = do
+  -- The cache of ENUM labels lives as long as this reader. See Note [ENUM labels].
+  labels <- newIORef IntMap.empty
+  -- See Note [Type aliases] in "Database.DuckDB.Simple.LogicalRep".
+  prepareVectorReaderWith readers (withVectorType vector (typeReader readers)) (Just labels) vector
+
+-- | The labels of an ENUM type that readers read, by index. 'Nothing' means
+-- that the type tree holds the labels. See Note [ENUM labels].
+type EnumLabels = Maybe (IORef (IntMap.IntMap Text))
+
+{- Note [Vector flatten]
+~~~~~~~~~~~~~~~~~~~~~~~~
+vector_flatten changes a vector to the FLAT representation in place. A reader
+flattens each vector before it reads the view. A writer of a callback output
+vector flattens the vector before it writes rows.
+
+Read (prepareVectorReaderWith).
+
+- The header of duckdb_v2_vector_get_view says: "Rejects VECTOR_TYPE_OTHER;
+  call vector_flatten first." The flatten also changes a CONSTANT or DICTIONARY
+  vector to FLAT.
+
+- In DuckDB 2.0.0 the view of a FLAT vector has no selection
+  (duckdb_v2_vector_get_view in src/main/capi/v2/capi_v2_vector.cpp). The header
+  does not say this. Then the physical row is the logical row. The readers of
+  VARIANT and GEOMETRY need this, because they read logical rows (rejectRows,
+  prepareVariantReader, and prepareGeometryReader). The reader still applies
+  the selection of a view that has one.
+
+- The flatten changes the buffers of the vector, so it runs before the view is
+  read.
+
+- In DuckDB 2.0.0 the flatten is recursive: it also flattens the child of a
+  LIST or MAP vector and the fields of a STRUCT vector (VectorListBuffer::Flatten
+  and VectorStructBuffer::Flatten). The header does not say this. The MAP
+  decoder (prepareMapDecoder) depends on this, because it takes the key and
+  value vectors from the entry STRUCT and does not flatten that STRUCT itself.
+
+Write. A writer of a callback output vector sets the size of the vector, and
+then flattens the vector (writeRows and writeResults). A writer of an
+owned vector from withOwnedVector does not flatten (materializeValue, and the
+writers of one-row vectors in "Database.DuckDB.Simple.ToField").
+
+- The writer sets the size before the flatten. In DuckDB 2.0.0,
+  duckdb_v2_vector_flatten flattens the rows of the current size of the vector:
+  it calls Vector::Flatten without a row count
+  (src/main/capi/v2/capi_v2_vector.cpp). duckdb_v2_vector_set_size reserves
+  memory only for a vector that is already FLAT. Thus after this order the
+  vector is FLAT and has the new number of rows. The header gives no order.
+
+- A new vector of a data chunk is FLAT. The header of
+  duckdb_v2_data_chunk_create says: "Allocates one FLAT vector per element of
+  the types array". Thus the writer of an owned vector needs no flatten. In
+  DuckDB 2.0.0 the children of such a vector are FLAT too: the vector cache
+  resets each child of a LIST, ARRAY, or STRUCT vector to FLAT
+  (VectorCacheEntry::ResetFromCache in src/common/types/vector_cache.cpp). The
+  header does not say this for the children. The writer of a UNION value writes
+  the child vectors of a new vector (unionValueDuckValue in
+  "Database.DuckDB.Simple.ToField").
+
+- The set operations check the row against the size. The header of
+  duckdb_v2_vector_set_value and duckdb_v2_vector_set_null says that each call
+  requires a FLAT vector and checks the row against vector_get_size.
+
+- writeResults reads the data pointer and the validity pointer after the
+  flatten. The header of duckdb_v2_vector_get_data_mutable says that the storage
+  shape of the vector must not change while the pointer is in use.
+
+- prepareResultWriter does not change the size and does not flatten. It raises
+  an error for a vector that is not FLAT.
+-}
+
+-- | Read the type, data, and validity of a vector, and prepare its reader. The
+-- action gives the type tree of the vector. A nested decoder gives each child
+-- an action that takes the tree of the child from this tree. The function
+-- flattens the vector first. See Note [Vector flatten] and Note [Type trees].
+prepareVectorReaderWith :: FallbackReaders -> TypeTree -> EnumLabels -> DuckDBV2VectorHandle -> IO (Int -> IO FieldValue)
+prepareVectorReaderWith readers tree labels vector = do
+  -- Flatten before the view is read. See Note [Vector flatten].
+  checked (c_duckdb_v2_vector_flatten vector)
+  dtype <- vectorElementType vector
+  view <- output (c_duckdb_v2_vector_get_view vector)
+  let ConstPtr dataPtr = getField @"data'" view
+      ConstPtr validity = getField @"validity" view
+      ConstPtr selection = getField @"sel" view
+  -- See Note [Type aliases] in "Database.DuckDB.Simple.LogicalRep".
+  readValue <- prepareValueReader readers (aliasBase <$> tree) labels dtype vector dataPtr validity
+  pure \row -> do
+    when (row < 0 || fromIntegral row >= getField @"count" view) $
+      throwInternalError (Text.pack "vector row index out of range")
+    physical <- if selection == nullPtr then pure row else fromIntegral <$> peekElemOff selection row
+    readValue physical
+
+{- Note [ENUM labels]
+~~~~~~~~~~~~~~~~~~~~
+A FieldEnum holds the index and the label of an ENUM value. The label is the
+text of the cast of DuckDB to VARCHAR. The reader does not cast the vector, so
+a user cast cannot change a label. The reader takes the label from one of two
+sources:
+
+- A cache (EnumLabels). The reader reads the label of an index through the
+  dictionary of the vector type (duckdb_v2_logical_type_get_param) at the first
+  row that has the index, and keeps it. Thus a query reads only the labels of
+  the values that it reads.
+- The type tree. A STRUCT, TUPLE, or UNION decoder converts the type of the
+  value, which reads the whole dictionary of each ENUM type in it (see
+  logicalTypeToRep). The reader of a child uses the labels of that tree, and it
+  raises an error when the tree has another dictionary size than the vector.
+
+A result column has one cache, which lives for one execution, as the tree of
+the column (statementStreamColumnLabels in "Database.DuckDB.Simple.Internal").
+The column reader gives the cache to the element reader of a LIST or an ARRAY,
+because one column has at most one ENUM type outside a STRUCT, a TUPLE, a
+UNION, and a MAP. prepareVectorReader makes a new cache for each reader. These
+readers use it: the key and value readers of a MAP, the tag reader of a UNION,
+the readers of typed arguments, function arguments, and COPY TO rows, and
+materializeValue. There the cache lives for one vector.
+
+Each index is checked against the parameter count of the vector type. An index
+out of range raises an error, so the reader cannot give a wrong label.
+-}
+
 -- | Prepare metadata once for a vector. The reader must not outlive its chunk.
-prepareValueReader :: DuckDBType -> DuckDBVector -> Ptr () -> Ptr Word64 -> IO (Int -> IO FieldValue)
-prepareValueReader dtype vector dataPtr validity = case dtype of
-    DuckDBTypeVariant -> prepareVariantDecoder vector
-    DuckDBTypeGeometry -> whenValid FieldGeometry <$> prepareGeometryDecoder vector dataPtr
-    DuckDBTypeStruct -> whenValid FieldStruct <$> prepareStructDecoder vector
-    DuckDBTypeUnion -> whenValid FieldUnion <$> prepareUnionDecoder vector
-    _ -> pure (materializeValue dtype vector dataPtr validity)
+prepareValueReader
+  :: FallbackReaders
+  -> TypeTree
+  -> EnumLabels
+  -> DuckDBV2LogicalTypeId
+  -> DuckDBV2VectorHandle
+  -> Ptr Void
+  -> Ptr Word64
+  -> IO (Int -> IO FieldValue)
+prepareValueReader readers tree labels dtype vector dataPtr validity = case dtype of
+  DuckDBV2LogicalTypeIdVariant -> variantReader readers vector
+  DuckDBV2LogicalTypeIdGeometry -> geometryReader readers vector
+  DuckDBV2LogicalTypeIdArray -> whenValid FieldArray <$> prepareArrayDecoder readers tree labels vector
+  DuckDBV2LogicalTypeIdList -> whenValid FieldList <$> prepareListDecoder readers tree labels vector dataPtr
+  DuckDBV2LogicalTypeIdMap -> whenValid FieldMap <$> prepareMapDecoder readers vector dataPtr
+  DuckDBV2LogicalTypeIdStruct -> whenValid FieldStruct <$> prepareStructDecoder readers tree vector
+  DuckDBV2LogicalTypeIdTuple -> whenValid FieldTuple <$> prepareTupleDecoder readers tree vector
+  DuckDBV2LogicalTypeIdUnion -> whenValid FieldUnion <$> prepareUnionDecoder readers tree vector
+  DuckDBV2LogicalTypeIdDecimal -> do
+    -- See Note [Type aliases] in "Database.DuckDB.Simple.LogicalRep".
+    (width, scale) <-
+      withVectorType vector logicalTypeToBaseRep >>= \case
+        LogicalTypeDecimal width scale -> pure (width, scale)
+        _ -> throwInternalError (Text.pack "invalid DECIMAL type")
+    pure (whenValid (FieldDecimal . DecimalValue width scale) (decimalStorage dataPtr width))
+  DuckDBV2LogicalTypeIdEnum -> do
+    -- See Note [ENUM labels].
+    count <- withVectorType vector (output . c_duckdb_v2_logical_type_get_param_count)
+    label <- case labels of
+      Just cache -> pure (cachedLabel cache)
+      Nothing ->
+        tree >>= \case
+          LogicalTypeEnum entries | toInteger (rangeSize (bounds entries)) == toInteger count -> pure (pure . (entries !) . fromIntegral)
+          _ -> throwInternalError (Text.pack "invalid ENUM type")
+    let readEnum row = do
+          index <- enumStorage dataPtr count row
+          when (toInteger index >= toInteger count) $ throwInternalError (Text.pack "ENUM index out of range")
+          FieldEnum index <$> label index
+    pure (whenValid id readEnum)
+  DuckDBV2LogicalTypeIdSQLNull -> pure \_ -> pure FieldNull
+  _ -> pure (whenValid id (decodeElement dtype dataPtr))
   where
+    -- Read a label through the dictionary of the vector type at the first row
+    -- that needs it. See Note [ENUM labels].
+    cachedLabel cache index =
+      IntMap.lookup (fromIntegral index) <$> readIORef cache >>= \case
+        Just text -> pure text
+        Nothing -> do
+          text <- withVectorType vector \logical -> alloca \nameSlot ->
+            bracket (output (c_duckdb_v2_logical_type_get_param logical (fromIntegral index) nameSlot)) destroyValue \value ->
+              output (c_duckdb_v2_value_get_varchar value) >>= readText
+          modifyIORef' cache (IntMap.insert (fromIntegral index) text)
+          pure text
+    -- See Note [Vector memory layouts] in "Database.DuckDB.Simple.Element".
     whenValid wrap decode row = do
-        valid <- chunkIsRowValid validity (fromIntegral row)
-        if valid then wrap <$> decode row else pure FieldNull
+      valid <- chunkIsRowValid validity (fromIntegral row)
+      if valid then wrap <$> decode row else pure FieldNull
 
-{- | Copy CRS metadata once for a vector. The decoder copies the WKB bytes of
-a valid row. It must not outlive its chunk.
+{- Note [User casts and the casts of the library]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A cast that a user registers is a cast function of each connection of the
+database, also of the helper connection of the VARIANT codec. DuckDB uses a
+registered cast in place of the built-in cast for the same pair of types. The
+header says: "A connection's or callback's factory casts with that client's
+cast functions and settings". It also says that the factory of an instance
+"supports only the built-in casts, with default settings".
+
+The library runs casts of DuckDB for its own work. A user cast does not change
+their result:
+
+- Reads. prepareGeometryReader casts a GEOMETRY vector to BLOB. A result, the
+  value of an option (getConfigValue), and the default value of an option
+  (getConfigDefaultValue) read a GEOMETRY value with the factory of the
+  instance, and so does queryMetrics. Callbacks registered on a connection
+  use the same instance factory.
+  A scalar or aggregate function registered by a loadable extension uses
+  its private instance factory. See Note [Function argument readers] in
+  "Database.DuckDB.Simple.Typed". Both paths cast the whole vector.
+  Other extension callbacks have a context factory, which includes user
+  casts. For those callbacks, withDefaultCastVector writes each row to a
+  BLOB vector with the default cast ("Database.DuckDB.Simple.Native").
+  This prevents a user cast from GEOMETRY to BLOB from calling itself when
+  its callback reads a GEOMETRY argument.
+  TODO: When V2 exposes WKB directly, copy it from the input vector and
+  remove the intermediate BLOB cast.
+- withObjectChildren and withCast cast VARIANT values to the types of their
+  payloads ("Database.DuckDB.Simple.VariantCodec"). The codec also reads a
+  GEOMETRY payload. It uses the factory of the instance of its helper
+  connection (variantCasts).
+- Values. rawGeometryDuckValue casts BLOB to GEOMETRY, the ToDuckValue instance
+  of Geometry casts VARCHAR to GEOMETRY, enumDuckValue casts VARCHAR to ENUM,
+  and variantDuckValue casts its payload to VARIANT
+  ("Database.DuckDB.Simple.ToField"). defaultCast writes each value to a
+  one-row vector of the target type and reads it back. vector_set_value uses
+  "the non-strict default cast". This is the documented cell writer for
+  GEOMETRY and VARIANT, which have no committed view layout. For ENUM, it avoids
+  value_cast, which includes registered casts. A VARCHAR-to-ENUM user cast
+  must not change the label of a FieldEnum. The factory resolves the target
+  type. Only a connection or callback factory can construct a GEOMETRY
+  type with a CRS. See Note [Raw GEOMETRY parameters] in
+  "Database.DuckDB.Simple.ToField". UNION values use a vector to preserve the
+  explicit member tag. See Note [UNION values] in that module.
+- The bind-time CRS query passes a BLOB literal to ST_GeomFromWKB and binds
+  the label as VARCHAR. It needs no user cast. See Note [Bind-time CRS types] in
+  "Database.DuckDB.Simple.V2.LogicalRep".
+
+These casts still use the cast functions of the session, so a user cast for
+the same pair changes their result:
+
+- setConfigValue and setConfigOption. DuckDB casts the value to the type of the
+  option as SQL SET does.
+- The casts of the SQL text. DuckDB runs them with the casts of the session.
+  The library does not choose them.
 -}
-prepareGeometryDecoder :: DuckDBVector -> Ptr () -> IO (Int -> IO RawGeometry)
-prepareGeometryDecoder vector dataPtr = do
-    crs <- withVectorType vector \logical -> do
-        rep <- logicalTypeToRep logical
-        case rep of
-            LogicalTypeGeometry value -> pure value
-            _ -> throwIO (userError "duckdb-simple: invalid GEOMETRY type")
-    pure \row -> (`RawGeometry` crs) <$> chunkDecodeBlob dataPtr (fromIntegral row)
 
-materializeValue :: DuckDBType -> DuckDBVector -> Ptr () -> Ptr Word64 -> Int -> IO FieldValue
-materializeValue dtype vector dataPtr validity rowIdx = do
-    valid <- chunkIsRowValid validity (fromIntegral rowIdx)
-    if not valid
-        then pure FieldNull
-        else case dtype of
-            DuckDBTypeGeometry -> FieldGeometry <$> (prepareGeometryDecoder vector dataPtr >>= ($ rowIdx))
-            DuckDBTypeVariant -> decodeVariant vector rowIdx
-            DuckDBTypeDecimal ->
-                withVectorType vector \logical -> do
-                    width <- c_duckdb_decimal_width logical
-                    scale <- c_duckdb_decimal_scale logical
-                    internalTy <- c_duckdb_decimal_internal_type logical
-                    rawValue <-
-                        case internalTy of
-                            DuckDBTypeSmallInt ->
-                                toInteger <$> peekElemOff (castPtr dataPtr :: Ptr Int16) rowIdx
-                            DuckDBTypeInteger ->
-                                toInteger <$> peekElemOff (castPtr dataPtr :: Ptr Int32) rowIdx
-                            DuckDBTypeBigInt ->
-                                toInteger <$> peekElemOff (castPtr dataPtr :: Ptr Int64) rowIdx
-                            DuckDBTypeHugeInt ->
-                                duckDBHugeIntToInteger <$> peekElemOff (castPtr dataPtr :: Ptr DuckDBHugeInt) rowIdx
-                            _ ->
-                                error "duckdb-simple: unsupported decimal internal storage type"
-                    pure (FieldDecimal (DecimalValue width scale rawValue))
-            DuckDBTypeArray -> FieldArray <$> decodeArrayElements vector rowIdx
-            DuckDBTypeList -> FieldList <$> decodeListElements vector dataPtr rowIdx
-            DuckDBTypeMap -> FieldMap <$> decodeMapPairs vector dataPtr rowIdx
-            DuckDBTypeStruct -> FieldStruct <$> (prepareStructDecoder vector >>= ($ rowIdx))
-            DuckDBTypeUnion -> FieldUnion <$> (prepareUnionDecoder vector >>= ($ rowIdx))
-            DuckDBTypeEnum ->
-                withVectorType vector \logical -> do
-                    enumInternal <- c_duckdb_enum_internal_type logical
-                    case enumInternal of
-                        DuckDBTypeUTinyInt ->
-                            FieldEnum . fromIntegral <$> peekElemOff (castPtr dataPtr :: Ptr Word8) rowIdx
-                        DuckDBTypeUSmallInt ->
-                            FieldEnum . fromIntegral <$> peekElemOff (castPtr dataPtr :: Ptr Word16) rowIdx
-                        DuckDBTypeUInteger ->
-                            FieldEnum <$> peekElemOff (castPtr dataPtr :: Ptr Word32) rowIdx
-                        _ ->
-                            error "duckdb-simple: unsupported enum internal storage type"
-            DuckDBTypeSQLNull -> pure FieldNull
-            _ -> decodeElement dtype dataPtr rowIdx
+-- | Copy the WKB bytes and CRS of every GEOMETRY row in a vector. GEOMETRY has
+-- no committed vector layout, so a cast to BLOB reads the rows. The reader takes
+-- logical rows. See Note [Vector flatten]. With the factory of an instance, one
+-- native cast casts the vector. With the factory of a context, the default cast
+-- of 'withDefaultCastVector' casts each row. See
+-- Note [User casts and the casts of the library].
+prepareGeometryReader :: ReadFactory -> DuckDBV2VectorHandle -> IO (Int -> IO FieldValue)
+prepareGeometryReader readFactory vector = do
+  -- See Note [Type aliases] in "Database.DuckDB.Simple.LogicalRep".
+  crs <-
+    withVectorType vector logicalTypeToBaseRep >>= \case
+      LogicalTypeGeometry value -> pure value
+      _ -> throwInternalError (Text.pack "invalid GEOMETRY type")
+  size <- output (c_duckdb_v2_vector_get_size vector)
+  let count = fromIntegral size
+      factory = readFactoryHandle readFactory
+      readBlobs target = do
+        let notBlob = rejectRows (throwInternalError (Text.pack "expected a BLOB vector"))
+        readBlob <- prepareVectorReader (FallbackReaders (logicalTypeToRep factory) notBlob notBlob) target
+        forM [0 .. count - 1] readBlob
+  blobs <-
+    bracket
+      (output (c_duckdb_v2_factory_create_type_from_id factory DuckDBV2LogicalTypeIdBlob (ConstPtr nullPtr) (ConstPtr nullPtr) 0))
+      destroyLogicalType
+      \blob -> case readFactory of
+        InstanceFactory _ -> withOwnedVector factory blob \target -> do
+          checked (c_duckdb_v2_vector_cast factory vector target DuckDBV2CastModeNormal nullPtr nullPtr)
+          readBlobs target
+        ContextFactory _ ->
+          withDefaultCastVector
+            factory
+            blob
+            size
+            (\row write -> bracket (output (c_duckdb_v2_vector_get_value vector row)) destroyValue write)
+            readBlobs
+  let rows = listArray (0, count - 1) blobs :: Array Int FieldValue
+  pure \row -> case rows ! row of
+    FieldBlob bytes -> pure (FieldGeometry (RawGeometry bytes crs))
+    FieldNull -> pure FieldNull
+    _ -> throwInternalError (Text.pack "GEOMETRY cast did not produce a BLOB")
 
-decodeArrayElements :: DuckDBVector -> Int -> IO (Array Int FieldValue)
-decodeArrayElements vector rowIdx = do
-    arraySize <-
-        withVectorType vector \logical -> do
-            sizeRaw <- c_duckdb_array_type_array_size logical
-            let sizeWord = fromIntegral sizeRaw :: Word64
-            ensureWithinIntRange (Text.pack "array size") sizeWord
-    childVec <- c_duckdb_array_vector_get_child vector
-    when (childVec == nullPtr) $
-        throwIO (userError "duckdb-simple: array child vector is null")
-    readChild <- prepareVectorReader childVec
+-- | Read a DECIMAL. DuckDB stores it in the smallest integer type for its width.
+-- See Note [Vector memory layouts] in "Database.DuckDB.Simple.Element".
+decimalStorage :: Ptr Void -> Word8 -> Int -> IO Integer
+decimalStorage dataPtr width rowIdx
+  | width <= 4 = toInteger <$> peekElemOff (castPtr dataPtr :: Ptr Int16) rowIdx
+  | width <= 9 = toInteger <$> peekElemOff (castPtr dataPtr :: Ptr Int32) rowIdx
+  | width <= 18 = toInteger <$> peekElemOff (castPtr dataPtr :: Ptr Int64) rowIdx
+  | otherwise = duckDBHugeIntToInteger <$> peekElemOff (castPtr dataPtr :: Ptr DuckDBV2HugeintT) rowIdx
+
+-- | Read an ENUM index. DuckDB stores it in the smallest unsigned type for the dictionary size.
+-- See Note [Vector memory layouts] in "Database.DuckDB.Simple.Element".
+enumStorage :: Ptr Void -> DuckDBIdx -> Int -> IO Word32
+enumStorage dataPtr count rowIdx
+  | count <= 255 = fromIntegral <$> peekElemOff (castPtr dataPtr :: Ptr Word8) rowIdx
+  | count <= 65535 = fromIntegral <$> peekElemOff (castPtr dataPtr :: Ptr Word16) rowIdx
+  | otherwise = peekElemOff (castPtr dataPtr :: Ptr Word32) rowIdx
+
+-- | Read the ARRAY size and prepare the element reader once for a vector. The
+-- size gives the layout of the elements, so it comes from the type of this
+-- vector. Parameter 1 of an ARRAY type is the size, as 'logicalTypeToRep' reads
+-- it. The decoder does not convert the element type. The element reader takes
+-- its tree from the tree of the ARRAY. See Note [Type trees].
+-- See Note [Constant stack at safe calls] in "Database.DuckDB.Simple.Native".
+prepareArrayDecoder :: FallbackReaders -> TypeTree -> EnumLabels -> DuckDBV2VectorHandle -> IO (Int -> IO (Array Int FieldValue))
+prepareArrayDecoder readers tree labels vector = do
+  size <- withVectorType vector \logical -> alloca \name ->
+    bracket (output (c_duckdb_v2_logical_type_get_param logical 1 name)) destroyValue (output . c_duckdb_v2_value_get_bigint)
+  arraySize <- ensureWithinIntRange (Text.pack "array size") (fromIntegral size)
+  readChild <- vectorChild vector 0 >>= prepareVectorReaderWith readers (elementTree tree) labels
+  pure \rowIdx -> do
     let baseIdx = rowIdx * arraySize
-    values <-
-        forM [0 .. arraySize - 1] \delta ->
-            readChild (baseIdx + delta)
-    pure $
-        listArray (0, arraySize - 1) values
+    values <- reverse <$> foldM (\values delta -> (: values) <$> readChild (baseIdx + delta)) [] [0 .. arraySize - 1]
+    pure (listArray (0, arraySize - 1) values)
 
-decodeListElements :: DuckDBVector -> Ptr () -> Int -> IO [FieldValue]
-decodeListElements vector dataPtr rowIdx = do
-    entry <- peekElemOff (castPtr dataPtr :: Ptr DuckDBListEntry) rowIdx
+-- | Prepare the element reader once for a LIST vector. The element reader
+-- takes its tree from the tree of the LIST. See Note [Type trees].
+-- See Note [Constant stack at safe calls] in "Database.DuckDB.Simple.Native".
+prepareListDecoder :: FallbackReaders -> TypeTree -> EnumLabels -> DuckDBV2VectorHandle -> Ptr Void -> IO (Int -> IO [FieldValue])
+prepareListDecoder readers tree labels vector dataPtr = do
+  readChild <- vectorChild vector 0 >>= prepareVectorReaderWith readers (elementTree tree) labels
+  pure \rowIdx -> do
+    entry <- peekElemOff (castPtr dataPtr :: Ptr DuckDBV2ListEntry) rowIdx
     (baseIdx, len) <- listEntryBounds (Text.pack "list") entry
-    childVec <- c_duckdb_list_vector_get_child vector
-    when (childVec == nullPtr) $
-        throwIO (userError "duckdb-simple: list child vector is null")
-    readChild <- prepareVectorReader childVec
-    forM [0 .. len - 1] \delta ->
-        readChild (baseIdx + delta)
+    reverse <$> foldM (\values delta -> (: values) <$> readChild (baseIdx + delta)) [] [0 .. len - 1]
 
-decodeMapPairs :: DuckDBVector -> Ptr () -> Int -> IO [(FieldValue, FieldValue)]
-decodeMapPairs vector dataPtr rowIdx = do
-    entry <- peekElemOff (castPtr dataPtr :: Ptr DuckDBListEntry) rowIdx
+-- | Prepare the key reader and the value reader once for a MAP vector. The
+-- decoder gives them no type tree. Each converts the type of its own vector when
+-- it needs a description. A tree of the MAP holds the key type and the value
+-- type together. A value reader that took its tree from it would thus also
+-- convert the key type, for example the dictionary of a large ENUM. The
+-- decoder does not flatten the entry STRUCT. See Note [Vector flatten] and
+-- Note [Type trees].
+-- See Note [Constant stack at safe calls] in "Database.DuckDB.Simple.Native".
+prepareMapDecoder :: FallbackReaders -> DuckDBV2VectorHandle -> Ptr Void -> IO (Int -> IO [(FieldValue, FieldValue)])
+prepareMapDecoder readers vector dataPtr = do
+  entries <- vectorChild vector 0
+  readKey <- vectorChild entries 0 >>= prepareVectorReader readers
+  readValue <- vectorChild entries 1 >>= prepareVectorReader readers
+  pure \rowIdx -> do
+    entry <- peekElemOff (castPtr dataPtr :: Ptr DuckDBV2ListEntry) rowIdx
     (baseIdx, len) <- listEntryBounds (Text.pack "map") entry
-    structVec <- c_duckdb_list_vector_get_child vector
-    when (structVec == nullPtr) $
-        throwIO (userError "duckdb-simple: map struct vector is null")
-    keyVec <- c_duckdb_struct_vector_get_child structVec 0
-    valueVec <- c_duckdb_struct_vector_get_child structVec 1
-    when (keyVec == nullPtr || valueVec == nullPtr) $
-        throwIO (userError "duckdb-simple: map child vectors are null")
-    readKey <- prepareVectorReader keyVec
-    readValue <- prepareVectorReader valueVec
-    forM [0 .. len - 1] \delta -> do
-        let childIdx = baseIdx + delta
-        keyValue <- readKey childIdx
-        valueValue <- readValue childIdx
-        pure (keyValue, valueValue)
+    reverse
+      <$> foldM
+        ( \pairs delta -> do
+            let childIdx = baseIdx + delta
+            keyValue <- readKey childIdx
+            valueValue <- readValue childIdx
+            pure ((keyValue, valueValue) : pairs)
+        )
+        []
+        [0 .. len - 1]
 
-{- | Read the STRUCT type and prepare a reader for each child once for a vector.
-The decoder reads a valid row. It must not outlive its chunk.
--}
-prepareStructDecoder :: DuckDBVector -> IO (Int -> IO (StructValue FieldValue))
-prepareStructDecoder vector =
-    withVectorType vector \logical -> do
-        structTypeRep <- logicalTypeToRep logical
-        structFields <-
-            case structTypeRep of
-                LogicalTypeStruct typeArray -> pure typeArray
-                other ->
-                    throwIO
-                        ( userError
-                            ( "duckdb-simple: expected STRUCT logical type, but saw "
-                                <> show other
-                            )
-                        )
-        let typeList = elems structFields
-            count = length typeList
-            indexMap =
-                Map.fromList (zip (map structFieldName typeList) [0 ..])
-        childReaders <-
-            forM (zip [0 .. count - 1] typeList) \(childIdx, StructField{structFieldName}) -> do
-                childVec <- c_duckdb_struct_vector_get_child vector (fromIntegral childIdx)
-                when (childVec == nullPtr) $
-                    throwIO (userError "duckdb-simple: struct child vector is null")
-                readChild <- prepareVectorReader childVec
-                pure (structFieldName, readChild)
-        pure \rowIdx -> do
-            valueFields <-
-                forM childReaders \(name, readChild) -> do
-                    value <- readChild rowIdx
-                    pure StructField{structFieldName = name, structFieldValue = value}
-            let fieldArray =
-                    listArray (0, count - 1) valueFields
-            pure
-                StructValue
-                    { structValueFields = fieldArray
-                    , structValueTypes = structFields
-                    , structValueIndex = indexMap
-                    }
+-- | Read the STRUCT type and prepare a reader for each child once for a vector.
+-- The decoder reads a valid row. It must not outlive its chunk. See
+-- Note [Type trees].
+prepareStructDecoder :: FallbackReaders -> TypeTree -> DuckDBV2VectorHandle -> IO (Int -> IO (StructValue FieldValue))
+prepareStructDecoder readers tree vector = do
+  structFields <-
+    tree >>= \case
+      LogicalTypeStruct typeArray -> pure typeArray
+      other ->
+        throwInternalError (Text.pack "expected STRUCT logical type, but saw " <> logicalTypeSQL other)
+  let typeList = elems structFields
+      count = length typeList
+      indexMap =
+        Map.fromList (zip (map structFieldName typeList) [0 ..])
+  checkChildCount "STRUCT" vector count
+  childReaders <-
+    forM (zip [0 ..] typeList) \(childIdx, StructField{structFieldName, structFieldValue}) -> do
+      readChild <- vectorChild vector childIdx >>= prepareVectorReaderWith readers (pure structFieldValue) Nothing
+      pure (structFieldName, readChild)
+  pure \rowIdx -> do
+    valueFields <-
+      forM childReaders \(name, readChild) -> do
+        value <- readChild rowIdx
+        pure StructField{structFieldName = name, structFieldValue = value}
+    let fieldArray =
+          listArray (0, count - 1) valueFields
+    pure
+      StructValue
+        { structValueFields = fieldArray
+        , structValueTypes = structFields
+        , structValueIndex = indexMap
+        }
 
-{- | Read the UNION type and prepare the tag reader and a reader for each member
-once for a vector. The decoder reads a valid row. It must not outlive its chunk.
--}
-prepareUnionDecoder :: DuckDBVector -> IO (Int -> IO (UnionValue FieldValue))
-prepareUnionDecoder vector =
-    withVectorType vector \logical -> do
-        unionTypeRep <- logicalTypeToRep logical
-        membersArray <-
-            case unionTypeRep of
-                LogicalTypeUnion members -> pure members
-                other ->
-                    throwIO
-                        ( userError
-                            ( "duckdb-simple: expected UNION logical type, but saw "
-                                <> show other
-                            )
-                        )
-        let membersList = elems membersArray
-            memberCount = length membersList
-        tagVec <- c_duckdb_struct_vector_get_child vector 0
-        when (tagVec == nullPtr) $
-            throwIO (userError "duckdb-simple: union tag vector is null")
-        readTag <- prepareVectorReader tagVec
-        memberReaders <-
-            forM [1 .. memberCount] \childIdx -> do
-                memberVec <- c_duckdb_struct_vector_get_child vector (fromIntegral childIdx)
-                when (memberVec == nullPtr) $
-                    throwIO (userError "duckdb-simple: union member vector is null")
-                prepareVectorReader memberVec
-        pure \rowIdx -> do
-            memberIdx <- readTag rowIdx >>= unionTagIndex
-            when (memberIdx < 0 || memberIdx >= memberCount) $
-                throwIO (userError "duckdb-simple: union tag out of range")
-            payload <- (memberReaders !! memberIdx) rowIdx
-            pure
-                UnionValue
-                    { unionValueIndex = fromIntegral memberIdx
-                    , unionValueLabel = unionMemberName (membersList !! memberIdx)
-                    , unionValuePayload = payload
-                    , unionValueMembers = membersArray
-                    }
+-- | Read positional field metadata and prepare readers that borrow the tuple.
+-- See Note [Type trees].
+prepareTupleDecoder :: FallbackReaders -> TypeTree -> DuckDBV2VectorHandle -> IO (Int -> IO (TupleValue FieldValue))
+prepareTupleDecoder readers tree vector = do
+  types <-
+    tree >>= \case
+      LogicalTypeTuple fields -> pure fields
+      _ -> throwInternalError (Text.pack "invalid TUPLE type")
+  let typeList = elems types
+      count = length typeList
+  checkChildCount "TUPLE" vector count
+  fieldReaders <- forM (zip [0 ..] typeList) \(index, fieldType) ->
+    vectorChild vector index >>= prepareVectorReaderWith readers (pure fieldType) Nothing
+  pure \row -> do
+    fields <- mapM ($ row) fieldReaders
+    pure (TupleValue (listArray (0, count - 1) fields) types)
 
+-- | Read the UNION type and prepare the tag reader once for a vector. Prepare
+-- the reader of a member at the first row that selects the member, so that a
+-- member that no row selects makes no native call. The decoder reads a valid
+-- row. It must not outlive its chunk. See Note [Type trees].
+prepareUnionDecoder :: FallbackReaders -> TypeTree -> DuckDBV2VectorHandle -> IO (Int -> IO (UnionValue FieldValue))
+prepareUnionDecoder readers tree vector = do
+  membersArray <-
+    tree >>= \case
+      LogicalTypeUnion members -> pure members
+      other ->
+        throwInternalError (Text.pack "expected UNION logical type, but saw " <> logicalTypeSQL other)
+  let memberCount = rangeSize (bounds membersArray)
+  -- Child 0 of a UNION vector is the tag, and member j is child j + 1. The tag
+  -- reader needs no type tree.
+  checkChildCount "UNION" vector (memberCount + 1)
+  readTag <- vectorChild vector 0 >>= prepareVectorReader readers
+  readersByTag <- fmap (listArray (0, memberCount - 1)) $
+    forM (zip [1 ..] (elems membersArray)) \(childIdx, UnionMemberType{unionMemberName, unionMemberType}) -> do
+      memberVec <- vectorChild vector childIdx
+      prepared <- newIORef Nothing
+      pure \row -> do
+        cached <- readIORef prepared
+        readMember <- case cached of
+          Just reader -> pure reader
+          Nothing -> do
+            reader <- prepareVectorReaderWith readers (pure unionMemberType) Nothing memberVec
+            writeIORef prepared (Just reader)
+            pure reader
+        payload <- readMember row
+        pure (unionMemberName, payload)
+  pure \rowIdx -> do
+    memberIdx <- readTag rowIdx >>= unionTagIndex
+    when (memberIdx < 0 || memberIdx >= memberCount) $
+      throwInternalError (Text.pack "union tag out of range")
+    (name, payload) <- (readersByTag ! memberIdx) rowIdx
+    pure
+      UnionValue
+        { unionValueIndex = fromIntegral memberIdx
+        , unionValueLabel = name
+        , unionValuePayload = payload
+        , unionValueMembers = membersArray
+        }
+
 -- | Convert a decoded UNION tag to a member index.
 unionTagIndex :: FieldValue -> IO Int
 unionTagIndex = \case
-    FieldWord8 tagWord -> pure (fromIntegral tagWord :: Int)
-    FieldWord16 tagWord -> pure (fromIntegral tagWord :: Int)
-    FieldWord32 tagWord ->
-        if tagWord <= fromIntegral (maxBound :: Word16)
-            then pure (fromIntegral tagWord)
-            else throwIO (userError "duckdb-simple: union tag exceeds Word16 range")
-    FieldWord64 tagWord ->
-        if tagWord <= fromIntegral (maxBound :: Word16)
-            then pure (fromIntegral tagWord)
-            else throwIO (userError "duckdb-simple: union tag exceeds Word16 range")
-    FieldInt8 tagInt
-        | tagInt >= 0 -> pure (fromIntegral tagInt)
-        | otherwise -> throwIO (userError "duckdb-simple: union tag negative")
-    FieldInt16 tagInt
-        | tagInt >= 0 -> pure (fromIntegral tagInt)
-        | otherwise -> throwIO (userError "duckdb-simple: union tag negative")
-    FieldInt32 tagInt
-        | tagInt >= 0 && tagInt <= fromIntegral (maxBound :: Word16) -> pure (fromIntegral tagInt)
-        | tagInt < 0 -> throwIO (userError "duckdb-simple: union tag negative")
-        | otherwise -> throwIO (userError "duckdb-simple: union tag exceeds Word16 range")
-    FieldInt64 tagInt
-        | tagInt >= 0 && tagInt <= fromIntegral (maxBound :: Word16) -> pure (fromIntegral tagInt)
-        | tagInt < 0 -> throwIO (userError "duckdb-simple: union tag negative")
-        | otherwise -> throwIO (userError "duckdb-simple: union tag exceeds Word16 range")
-    FieldNull ->
-        throwIO (userError "duckdb-simple: encountered NULL union tag")
-    other ->
-        throwIO
-            ( userError
-                ( "duckdb-simple: unexpected union tag value "
-                    <> show other
-                )
-            )
+  FieldWord8 tagWord -> pure (fromIntegral tagWord :: Int)
+  FieldWord16 tagWord -> pure (fromIntegral tagWord :: Int)
+  FieldWord32 tagWord ->
+    if tagWord <= fromIntegral (maxBound :: Word16)
+      then pure (fromIntegral tagWord)
+      else throwInternalError (Text.pack "union tag exceeds Word16 range")
+  FieldWord64 tagWord ->
+    if tagWord <= fromIntegral (maxBound :: Word16)
+      then pure (fromIntegral tagWord)
+      else throwInternalError (Text.pack "union tag exceeds Word16 range")
+  FieldInt8 tagInt
+    | tagInt >= 0 -> pure (fromIntegral tagInt)
+    | otherwise -> throwInternalError (Text.pack "union tag negative")
+  FieldInt16 tagInt
+    | tagInt >= 0 -> pure (fromIntegral tagInt)
+    | otherwise -> throwInternalError (Text.pack "union tag negative")
+  FieldInt32 tagInt
+    | tagInt >= 0 && tagInt <= fromIntegral (maxBound :: Word16) -> pure (fromIntegral tagInt)
+    | tagInt < 0 -> throwInternalError (Text.pack "union tag negative")
+    | otherwise -> throwInternalError (Text.pack "union tag exceeds Word16 range")
+  FieldInt64 tagInt
+    | tagInt >= 0 && tagInt <= fromIntegral (maxBound :: Word16) -> pure (fromIntegral tagInt)
+    | tagInt < 0 -> throwInternalError (Text.pack "union tag negative")
+    | otherwise -> throwInternalError (Text.pack "union tag exceeds Word16 range")
+  FieldNull ->
+    throwInternalError (Text.pack "encountered NULL union tag")
+  other ->
+    throwInternalError (Text.pack ("unexpected union tag value " <> show other))
 
-listEntryBounds :: Text -> DuckDBListEntry -> IO (Int, Int)
-listEntryBounds context DuckDBListEntry{duckDBListEntryOffset, duckDBListEntryLength} = do
-    base <- ensureWithinIntRange (context <> Text.pack " offset") duckDBListEntryOffset
-    len <- ensureWithinIntRange (context <> Text.pack " length") duckDBListEntryLength
-    let maxInt = toInteger (maxBound :: Int)
-        upperBound = toInteger base + toInteger len - 1
-    when (len > 0 && upperBound > maxInt) $
-        throwIO (userError ("duckdb-simple: " <> Text.unpack context <> " bounds exceed Int range"))
-    pure (base, len)
+listEntryBounds :: Text -> DuckDBV2ListEntry -> IO (Int, Int)
+listEntryBounds context (DuckDBV2ListEntry offset lenRaw) = do
+  base <- ensureWithinIntRange (context <> Text.pack " offset") (fromIntegral offset)
+  len <- ensureWithinIntRange (context <> Text.pack " length") (fromIntegral lenRaw)
+  let maxInt = toInteger (maxBound :: Int)
+      upperBound = toInteger base + toInteger len - 1
+  when (len > 0 && upperBound > maxInt) $
+    throwInternalError (context <> Text.pack " bounds exceed Int range")
+  pure (base, len)
 
 ensureWithinIntRange :: Text -> Word64 -> IO Int
 ensureWithinIntRange context value =
-    let actual = toInteger value
-        limit = toInteger (maxBound :: Int)
-     in if actual <= limit
-            then pure (fromInteger actual)
-            else throwIO (userError ("duckdb-simple: " <> Text.unpack context <> " exceeds Int range"))
+  let actual = toInteger value
+      limit = toInteger (maxBound :: Int)
+  in  if actual <= limit
+        then pure (fromInteger actual)
+        else throwInternalError (context <> Text.pack " exceeds Int range")
+
+-- | Take the element tree from the tree of a LIST or ARRAY. Read the parent
+-- tree only when the element reader needs its tree. See
+-- Note [Type trees].
+elementTree :: TypeTree -> TypeTree
+elementTree tree =
+  tree >>= \case
+    LogicalTypeList element -> pure element
+    LogicalTypeArray element _ -> pure element
+    _ -> throwInternalError (Text.pack "invalid LIST or ARRAY type")
+
+-- | Raise an error when the type tree of a STRUCT, TUPLE, or UNION vector gives
+-- another child count than the vector has. The tree can come from the type of a
+-- parent vector, and the decoder must not drop a child. See Note [Type trees].
+checkChildCount :: String -> DuckDBV2VectorHandle -> Int -> IO ()
+checkChildCount kind vector expected = do
+  actual <- output (c_duckdb_v2_vector_get_child_count vector)
+  when (toInteger actual /= toInteger expected) $
+    throwInternalError
+      (Text.pack ("invalid " <> kind <> " type: the type has " <> show expected <> " children, but the vector has " <> show actual))
+
+-- | Borrow a nested vector from its parent chunk.
+vectorChild :: DuckDBV2VectorHandle -> DuckDBIdx -> IO DuckDBV2VectorHandle
+vectorChild vector index = output (c_duckdb_v2_vector_get_child vector index)
diff --git a/src/Database/DuckDB/Simple/Native.hs b/src/Database/DuckDB/Simple/Native.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/Native.hs
@@ -0,0 +1,982 @@
+{-# LANGUAGE DerivingStrategies #-}
+{-# LANGUAGE FlexibleContexts #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.Native
+-- Description : Shared V2 error handling and UTF-8 views.
+module Database.DuckDB.Simple.Native (
+  module Database.DuckDB.FFI.V2,
+  Query (..),
+  SQLError (..),
+  ErrorType (..),
+  errorTypeCodes,
+  errorTypeFromNative,
+  SettingScope (..),
+  settingScopeToNative,
+  settingScopeFromNative,
+  LogLevel (..),
+  logLevelToNative,
+  logLevelFromNative,
+  LogScope (..),
+  logScopeFromNative,
+  TokenType (..),
+  tokenTypeFromNative,
+  MacroFunctionType (..),
+  macroFunctionTypeToNative,
+  LogicalTypeId (..),
+  logicalTypeIdToNative,
+  logicalTypeIdFromNative,
+  logicalTypeIdName,
+  arraySizeReason,
+  maxArraySize,
+  FileFlag (..),
+  fileFlagToNative,
+  checked,
+  checkCode,
+  output,
+  destroy,
+  destroyValue,
+  destroyLogicalType,
+  acquireItems,
+  releaseItems,
+  withCreatedValues,
+  withOwnedVector,
+  withDefaultCastVector,
+  nullHandle,
+  indices,
+  withText,
+  withTextArray,
+  readText,
+  valueText,
+  withBytes,
+  readBytes,
+  withIdentifier,
+  withIdentifierArray,
+  readIdentifier,
+  foldIdentifier,
+  quoteIdentifier,
+  throwInvalidArgument,
+  throwConversionError,
+  throwInternalError,
+  exceptionText,
+  withConnectionFactory,
+  factoryOutput,
+  withSQLStatement,
+  withContextFactory,
+  withInstanceFactory,
+  ValueFactory,
+  NativeValue,
+) where
+
+import Control.Applicative ((<|>))
+import Control.Exception (Exception (..), SomeException (..), bracket, evaluate, finally, mask_, onException, throwIO, try)
+import Control.Monad (foldM, forM_, mfilter, unless, when, (<$!>))
+import qualified Data.ByteString as BS
+import Data.Char (isAsciiUpper, toLower)
+import Data.Coerce (Coercible, coerce)
+import Data.Maybe (fromMaybe)
+import Data.String (IsString (..))
+import Data.Text (Text)
+import qualified Data.Text as Text
+import qualified Data.Text.Encoding as Text
+import Data.Text.Encoding.Error (lenientDecode)
+import qualified Data.Text.Foreign as TextForeign
+import Database.DuckDB.FFI.V2
+import Foreign.C.ConstPtr (ConstPtr (..))
+import Foreign.C.Types (CUInt)
+import Foreign.Marshal.Alloc (alloca, allocaBytes)
+import Foreign.Marshal.Array (withArray)
+import Foreign.Marshal.Utils (fillBytes, with, withMany)
+import Foreign.Ptr (Ptr, castPtr, nullPtr)
+import Foreign.Storable (Storable, peek, poke, sizeOf)
+
+-- | The largest size of a DuckDB ARRAY: @ArrayType::MAX_ARRAY_SIZE@ in
+-- @src/include/duckdb/common/types.hpp@ of DuckDB 2.0.0. See
+-- Note [Sized ARRAY bounds].
+maxArraySize :: Int
+maxArraySize = 100000
+
+-- | Give the reason why a size has no DuckDB ARRAY type, or 'Nothing' for a
+-- valid size. See Note [Sized ARRAY bounds].
+arraySizeReason :: Integer -> Maybe Text
+arraySizeReason size
+  | size < 1 = Just "a DuckDB ARRAY has at least one element"
+  | size > toInteger maxArraySize = Just ("a DuckDB ARRAY has at most " <> Text.pack (show maxArraySize) <> " elements")
+  | otherwise = Nothing
+
+{- Note [Sized ARRAY bounds]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A DuckDB ARRAY has 1 to maxArraySize elements. Its value API does not check
+this limit, so both logical type construction and value binding must check
+the size. Generic declarations check each ARRAY, also below an alias or a
+container. A non-NULL SizedArray read also checks the size before it counts
+or converts the elements.
+
+SizedArray has a type-level Nat, but LogicalTypeArray stores a Word64. The
+generic logical type saturates a Nat above maxBound Word64 to that bound.
+This is an invalid-size sentinel. It cannot wrap into a valid size, and the
+declaration and native construction checks reject it. No pure conversion
+throws an exception.
+-}
+
+-- | SQL text encoded as UTF-8 when it is sent to DuckDB.
+newtype Query = Query {fromQuery :: Text}
+  deriving stock (Eq, Ord, Show)
+
+instance Semigroup Query where
+  Query a <> Query b = Query (a <> b)
+
+instance IsString Query where
+  fromString = Query . Text.pack
+
+-- | A native V2 error or an error reported by duckdb-simple.
+data SQLError = SQLError
+  { sqlErrorMessage :: Text
+  , sqlErrorType :: Maybe ErrorType
+  , sqlErrorQuery :: Maybe Query
+  , sqlErrorBody :: Maybe Text
+  -- ^ The text of a native error without the prefix of its type. For example,
+  -- the message @Conversion Error: Could not convert ...@ has the body
+  -- @Could not convert ...@. An error of duckdb-simple has no body. A callback
+  -- gives the type and the body of an error back to DuckDB, except for the
+  -- types that the section /Errors/ of the README lists.
+  }
+  deriving stock (Eq, Show)
+
+instance Exception SQLError
+
+-- | The category of a native DuckDB error. An error that duckdb-simple reports
+-- itself has an error type where one category fits the failure. An input check
+-- for a value that its SQL type cannot hold raises 'ErrorTypeConversion', as
+-- DuckDB does for the same value in SQL (see 'throwConversionError'). Each
+-- other input check raises 'ErrorInputInvalid', also for a value of the wrong
+-- shape or type (see 'throwInvalidArgument'). For a nanosecond target, DuckDB
+-- can raise the error itself (see Note [Nanosecond parameters] in
+-- "Database.DuckDB.Simple.ToField"). A callback that waits too long for a
+-- connection lock gets 'ErrorResourceInUse'.
+-- These errors of duckdb-simple have no error type: the use of a closed
+-- environment, instance, connection, or statement, a loaded DuckDB
+-- library of another version, a callback state read with the wrong type, and a
+-- result value that does not convert to its Haskell type.
+--
+-- A failed check of the state of the library, or of a vector, a type, or a
+-- value that DuckDB gave, raises an t'SQLError' of the type
+-- 'ErrorRuntimeInternal'. Such an error is a defect of the library or of
+-- DuckDB, not an error of the input. Report it. Inside a callback, the
+-- statement that runs the callback fails with 'ErrorInputInvalid', because a
+-- callback does not pass 'ErrorRuntimeInternal' (a cast gives
+-- 'ErrorTypeMismatch'). See Note [Internal errors in callbacks].
+data ErrorType
+  = ErrorApi
+  | ErrorIOFileNotFound
+  | ErrorIOReadFailure
+  | ErrorIOEof
+  | ErrorIOGeneral
+  | ErrorIONetwork
+  | ErrorIOHTTP
+  | ErrorInputInvalid
+  | ErrorInputParameterInvalid
+  | ErrorInputOutOfRange
+  | ErrorInputObjectSize
+  | ErrorInputMetadataDeferred
+  | ErrorResourceInUse
+  | ErrorResourceOutOfMemory
+  | ErrorResourceConnection
+  | ErrorResourceDependency
+  | ErrorResourceMissingExtension
+  | ErrorResourceAutoload
+  | ErrorTypeConversion
+  | ErrorTypeUnknown
+  | ErrorTypeInvalid
+  | ErrorTypeMismatch
+  | ErrorTypeDecimal
+  | ErrorTypeDivideByZero
+  | ErrorQueryParser
+  | ErrorQuerySyntax
+  | ErrorQueryBinder
+  | ErrorQueryPlanner
+  | ErrorQueryOptimizer
+  | ErrorQueryExpression
+  | ErrorQueryExecutor
+  | ErrorQueryScheduler
+  | ErrorQueryNotImplemented
+  | ErrorQueryParameterNotResolved
+  | ErrorQueryParameterNotAllowed
+  | ErrorDatabaseCatalog
+  | ErrorDatabaseTransaction
+  | ErrorDatabaseConstraint
+  | ErrorDatabaseIndex
+  | ErrorDatabaseSequence
+  | ErrorDatabaseStatistics
+  | ErrorDatabaseSerialization
+  | ErrorConfigurationSettings
+  | ErrorConfigurationInvalid
+  | ErrorConfigurationPermission
+  | ErrorRuntimeInternal
+  | ErrorRuntimeFatal
+  | ErrorRuntimeInterrupt
+  | ErrorRuntimeNullPointer
+  deriving (Eq, Ord, Show, Read, Enum, Bounded)
+
+-- | Each error type and its native error code.
+errorTypeCodes :: [(ErrorType, DuckDBV2Error)]
+errorTypeCodes =
+  [ (ErrorApi, DuckDBV2ErrorApi)
+  , (ErrorIOFileNotFound, DuckDBV2ErrorIOFileNotFound)
+  , (ErrorIOReadFailure, DuckDBV2ErrorIOReadFailure)
+  , (ErrorIOEof, DuckDBV2ErrorIOEof)
+  , (ErrorIOGeneral, DuckDBV2ErrorIOGeneral)
+  , (ErrorIONetwork, DuckDBV2ErrorIONetwork)
+  , (ErrorIOHTTP, DuckDBV2ErrorIOHTTP)
+  , (ErrorInputInvalid, DuckDBV2ErrorInputInvalid)
+  , (ErrorInputParameterInvalid, DuckDBV2ErrorInputParameterInvalid)
+  , (ErrorInputOutOfRange, DuckDBV2ErrorInputOutOfRange)
+  , (ErrorInputObjectSize, DuckDBV2ErrorInputObjectSize)
+  , (ErrorInputMetadataDeferred, DuckDBV2ErrorInputMetadataDeferred)
+  , (ErrorResourceInUse, DuckDBV2ErrorResourceInUse)
+  , (ErrorResourceOutOfMemory, DuckDBV2ErrorResourceOutOfMemory)
+  , (ErrorResourceConnection, DuckDBV2ErrorResourceConnection)
+  , (ErrorResourceDependency, DuckDBV2ErrorResourceDependency)
+  , (ErrorResourceMissingExtension, DuckDBV2ErrorResourceMissingExtension)
+  , (ErrorResourceAutoload, DuckDBV2ErrorResourceAutoload)
+  , (ErrorTypeConversion, DuckDBV2ErrorTypeConversion)
+  , (ErrorTypeUnknown, DuckDBV2ErrorTypeUnknown)
+  , (ErrorTypeInvalid, DuckDBV2ErrorTypeInvalid)
+  , (ErrorTypeMismatch, DuckDBV2ErrorTypeMismatch)
+  , (ErrorTypeDecimal, DuckDBV2ErrorTypeDecimal)
+  , (ErrorTypeDivideByZero, DuckDBV2ErrorTypeDivideByZero)
+  , (ErrorQueryParser, DuckDBV2ErrorQueryParser)
+  , (ErrorQuerySyntax, DuckDBV2ErrorQuerySyntax)
+  , (ErrorQueryBinder, DuckDBV2ErrorQueryBinder)
+  , (ErrorQueryPlanner, DuckDBV2ErrorQueryPlanner)
+  , (ErrorQueryOptimizer, DuckDBV2ErrorQueryOptimizer)
+  , (ErrorQueryExpression, DuckDBV2ErrorQueryExpression)
+  , (ErrorQueryExecutor, DuckDBV2ErrorQueryExecutor)
+  , (ErrorQueryScheduler, DuckDBV2ErrorQueryScheduler)
+  , (ErrorQueryNotImplemented, DuckDBV2ErrorQueryNotImplemented)
+  , (ErrorQueryParameterNotResolved, DuckDBV2ErrorQueryParameterNotResolved)
+  , (ErrorQueryParameterNotAllowed, DuckDBV2ErrorQueryParameterNotAllowed)
+  , (ErrorDatabaseCatalog, DuckDBV2ErrorDatabaseCatalog)
+  , (ErrorDatabaseTransaction, DuckDBV2ErrorDatabaseTransaction)
+  , (ErrorDatabaseConstraint, DuckDBV2ErrorDatabaseConstraint)
+  , (ErrorDatabaseIndex, DuckDBV2ErrorDatabaseIndex)
+  , (ErrorDatabaseSequence, DuckDBV2ErrorDatabaseSequence)
+  , (ErrorDatabaseStatistics, DuckDBV2ErrorDatabaseStatistics)
+  , (ErrorDatabaseSerialization, DuckDBV2ErrorDatabaseSerialization)
+  , (ErrorConfigurationSettings, DuckDBV2ErrorConfigurationSettings)
+  , (ErrorConfigurationInvalid, DuckDBV2ErrorConfigurationInvalid)
+  , (ErrorConfigurationPermission, DuckDBV2ErrorConfigurationPermission)
+  , (ErrorRuntimeInternal, DuckDBV2ErrorRuntimeInternal)
+  , (ErrorRuntimeFatal, DuckDBV2ErrorRuntimeFatal)
+  , (ErrorRuntimeInterrupt, DuckDBV2ErrorRuntimeInterrupt)
+  , (ErrorRuntimeNullPointer, DuckDBV2ErrorRuntimeNullPointer)
+  ]
+
+-- | Find the error type of a native error code. The success code and an unknown
+-- code give 'Nothing'.
+errorTypeFromNative :: DuckDBV2Error -> Maybe ErrorType
+errorTypeFromNative code = lookup code [(native, errorType) | (errorType, native) <- errorTypeCodes]
+
+-- | A null pointer represented by an opaque native handle.
+nullHandle :: (Coercible (Ptr ()) a) => a
+nullHandle = coerce (nullPtr @())
+
+-- | Check a status from an operation without an error-info output.
+checkCode :: DuckDBV2Error -> IO ()
+checkCode code =
+  unless (code == DuckDBV2ErrorNone) $
+    throwIO (SQLError (Text.pack (show code)) (errorTypeFromNative code) Nothing Nothing)
+
+-- | Copy a native diagnostic and release its error-info handle. The message is
+-- the text of the diagnostic, and the body is its text without the prefix (see
+-- 'sqlErrorBody'). Decode the error text with replacement characters, so that
+-- a native text that is not valid UTF-8 cannot raise when the error is shown.
+checked :: (Ptr DuckDBV2ErrorInfoHandle -> IO DuckDBV2Error) -> IO ()
+checked action = mask_ $ alloca $ \slot -> do
+  poke slot nullHandle
+  -- A successful call leaves the slot null. Destroy only a handle in the slot.
+  let release = do
+        info <- peek slot
+        unless (info == nullHandle) (c_duckdb_v2_error_info_destroy slot >>= checkCode)
+  flip finally release $ do
+    code <- action slot
+    unless (code == DuckDBV2ErrorNone) $ do
+      info <- peek slot
+      let readInfo getText
+            | info == nullHandle = pure Nothing
+            | otherwise = alloca $ \view -> do
+                rc <- getText info view
+                if rc == DuckDBV2ErrorNone
+                  then Just . Text.decodeUtf8With lenientDecode <$> (peek view >>= readBytes)
+                  else pure Nothing
+      message <- fromMaybe (Text.pack (show code)) <$> readInfo c_duckdb_v2_error_info_get_text
+      body <- readInfo c_duckdb_v2_error_info_get_raw_text
+      throwIO (SQLError message (errorTypeFromNative code) Nothing (mfilter (not . Text.null) body))
+
+-- | Read one checked native output. Initialize its storage before the call.
+output :: forall a. (Storable a) => (Ptr a -> Ptr DuckDBV2ErrorInfoHandle -> IO DuckDBV2Error) -> IO a
+output action = alloca $ \slot -> do
+  fillBytes slot 0 (sizeOf (undefined :: a))
+  checked (action slot)
+  peek slot
+
+-- | Destroy an owned handle held in a temporary native slot.
+destroy :: (Storable a) => (Ptr a -> IO DuckDBV2Error) -> a -> IO ()
+destroy release value = with value (\slot -> release slot >>= checkCode)
+
+-- | Release an owned native value.
+destroyValue :: DuckDBV2ValueHandle -> IO ()
+destroyValue = destroy c_duckdb_v2_value_destroy
+
+-- | Release an owned native logical type.
+destroyLogicalType :: DuckDBV2LogicalTypeHandle -> IO ()
+destroyLogicalType = destroy c_duckdb_v2_logical_type_destroy
+
+{- Note [Constant stack at safe calls]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Each c_duckdb_v2 binding is a safe foreign call. At a safe call, the GHC
+runtime (threadPaused) reads the frames of the current stack chunk. A loop that
+keeps a frame for each element or row adds those retained frames to this work.
+
+Thus a loop whose steps make native calls keeps a constant stack. The rule
+applies to a loop over the rows of a chunk, over the chunks of a result, and
+over a list of native items. It applies also when only some steps make a native
+call, as in the row loop of withStreamRows in
+"Database.DuckDB.Simple.Result".
+
+The code uses these forms:
+
+- forM_ for a loop that gives no result (writeRows in
+  "Database.DuckDB.Simple.Typed.Table").
+
+- foldM with an accumulator. A fold can keep one value, as the first error in
+  releaseItems. The LIST, ARRAY, and MAP readers in
+  "Database.DuckDB.Simple.Materialize" prepend each element and then reverse
+  the list. They read elements in order, so the first failing read stays first.
+
+- A tail-recursive loop with an accumulator. acquireItems puts each item in
+  front of the list, and then reverses the list. Its exception handler covers
+  one step, including the evaluation of the next list constructor.
+
+- A loop that reads the elements from the last to the first, and puts each
+  element in front of the list. The list then needs no reverse (the row loop of
+  withStreamRows).
+
+These loops keep a frame for each element, and they stay as they are, because
+the list is short in practice or the operation is rare:
+
+- The row loop of materializeChunkRows in
+  "Database.DuckDB.Simple.Copy.Internal". Only a BIGNUM element, the first
+  row of a UNION member, and a rejectRows reader make a native call for each
+  row there.
+
+- The row loop of executeScalarFunction in
+  "Database.DuckDB.Simple.Function.Internal", for the same readers.
+
+- cleanupAll, for a connection with many open statements, in
+  "Database.DuckDB.Simple.Internal".
+
+- The option loop in "Database.DuckDB.Simple.Config".
+-}
+
+-- | Run the acquire actions in list order under 'mask_', and give the items in
+-- list order. If evaluation of the input list or an acquire action fails,
+-- release the items that the earlier actions gave, from the last to the first,
+-- and raise that error. The loop keeps a constant stack. See
+-- Note [Constant stack at safe calls].
+acquireItems :: (a -> IO ()) -> [IO a] -> IO [a]
+acquireItems release = mask_ . go []
+  where
+    go owned remaining = do
+      next <- flip onException (releaseItems release owned) $ do
+        actions <- evaluate remaining
+        case actions of
+          [] -> pure Nothing
+          acquire : rest -> do
+            item <- acquire
+            pure (Just (item, rest))
+      case next of
+        Nothing -> pure (reverse owned)
+        Just (item, rest) -> go (item : owned) rest
+
+-- | Release each item in list order, also when a release raises an error.
+-- Raise the first error after the last release. The fold keeps a constant stack.
+-- See Note [Constant stack at safe calls].
+releaseItems :: (a -> IO ()) -> [a] -> IO ()
+releaseItems release items = foldM step (Nothing :: Maybe SomeException) items >>= mapM_ throwIO
+  where
+    step failure item = either (\err -> failure <|> Just err) (const failure) <$!> try (release item)
+
+-- | Create the values in list order, and give them to the action. Destroy the
+-- values in reverse order of creation after the action or after a failure. One
+-- 'bracket' covers the whole list.
+withCreatedValues :: [IO DuckDBV2ValueHandle] -> ([DuckDBV2ValueHandle] -> IO a) -> IO a
+withCreatedValues creates = bracket (acquireItems destroyValue creates) (releaseItems destroyValue . reverse)
+
+-- | Run an action with a new vector of the given type. The V2 API creates a
+-- vector only as a column of a data chunk, so this function creates a chunk
+-- with one column. The function destroys the chunk after the action, so the
+-- vector must not be used after the action returns.
+withOwnedVector :: DuckDBV2FactoryHandle -> DuckDBV2LogicalTypeHandle -> (DuckDBV2VectorHandle -> IO a) -> IO a
+withOwnedVector factory logicalType action =
+  with logicalType $ \types ->
+    bracket (output (c_duckdb_v2_data_chunk_create factory (ConstPtr types) 1)) (destroy c_duckdb_v2_data_chunk_destroy) $ \chunk ->
+      output (c_duckdb_v2_data_chunk_get_vector chunk 0) >>= action
+
+-- | Cast values with the default cast of DuckDB. The function makes a new
+-- vector of the type with the given number of rows (withOwnedVector). For each
+-- row, the writer gives a borrowed value to its second argument, and
+-- duckdb_v2_vector_set_value writes the value to the row. The header says that
+-- this call casts "through the non-strict default cast". Then the action reads
+-- the vector. See Note [User casts and the casts of the library] in
+-- <src/Database.DuckDB.Simple.Materialize.html Database.DuckDB.Simple.Materialize>.
+withDefaultCastVector
+  :: DuckDBV2FactoryHandle
+  -> DuckDBV2LogicalTypeHandle
+  -> DuckDBIdx
+  -> (DuckDBIdx -> (DuckDBV2ValueHandle -> IO ()) -> IO ())
+  -> (DuckDBV2VectorHandle -> IO a)
+  -> IO a
+withDefaultCastVector factory logicalType count writeRow action =
+  withOwnedVector factory logicalType $ \vector -> do
+    checked (c_duckdb_v2_vector_set_size vector count)
+    forM_ (indices count) $ \row -> writeRow row (checked . c_duckdb_v2_vector_set_value vector row)
+    action vector
+
+-- | List the indices below a native count without unsigned underflow.
+indices :: DuckDBIdx -> [DuckDBIdx]
+indices count = if count == 0 then [] else [0 .. count - 1]
+
+-- | Lend UTF-8 text to DuckDB for the duration of the action.
+withText :: Text -> (ConstPtr DuckDBV2Str -> IO a) -> IO a
+withText value = withBytes (Text.encodeUtf8 value)
+
+-- | Lend an array of UTF-8 views to DuckDB for the duration of the action.
+withTextArray :: [Text] -> (Ptr DuckDBV2Str -> IO a) -> IO a
+withTextArray values action =
+  withMany withText values $ \views -> mapM (\(ConstPtr view) -> peek view) views >>= (`withArray` action)
+
+-- | Copy the bytes of a UTF-8 view whose memory DuckDB owns. The result stays
+-- valid after DuckDB frees that memory.
+readText :: DuckDBV2Str -> IO Text
+readText view = Text.decodeUtf8 <$> readBytes view
+
+-- | Copy the native text of a value.
+valueText :: DuckDBV2ValueHandle -> IO Text
+valueText value = do
+  count <- output (c_duckdb_v2_value_to_string value nullPtr 0)
+  when (toInteger count >= toInteger (maxBound :: Int)) $ throwInternalError "value text exceeds Int range"
+  allocaBytes (fromIntegral count + 1) $ \buffer -> do
+    _ <- output (c_duckdb_v2_value_to_string value buffer (count + 1))
+    Text.decodeUtf8 <$> BS.packCStringLen (buffer, fromIntegral count)
+
+-- | Lend bytes to DuckDB through a length-delimited view for the duration of the action.
+withBytes :: BS.ByteString -> (ConstPtr DuckDBV2Str -> IO a) -> IO a
+withBytes value action = BS.useAsCStringLen value $ \(ptr, count) ->
+  with (DuckDBV2Str (ConstPtr ptr) (fromIntegral count)) (action . ConstPtr)
+
+-- | Copy the bytes of a view whose memory DuckDB owns, including interior NUL
+-- bytes. The result stays valid after DuckDB frees that memory.
+readBytes :: DuckDBV2Str -> IO BS.ByteString
+readBytes (DuckDBV2Str (ConstPtr ptr) count)
+  | count == 0 = pure BS.empty
+  | otherwise = BS.packCStringLen (ptr, fromIntegral count)
+
+-- | Lend a UTF-8 identifier to DuckDB for the duration of the action.
+withIdentifier :: Text -> (ConstPtr DuckDBV2IdentifierT -> IO a) -> IO a
+withIdentifier value action = withText value (action . coerce)
+
+-- | Lend an array of UTF-8 identifiers to DuckDB for the duration of the action.
+withIdentifierArray :: [Text] -> (Ptr DuckDBV2IdentifierT -> IO a) -> IO a
+withIdentifierArray values action = withTextArray values (action . castPtr)
+
+-- | Copy the bytes of an identifier whose memory DuckDB owns. The result stays
+-- valid after DuckDB frees that memory.
+readIdentifier :: DuckDBV2IdentifierT -> IO Text
+readIdentifier = readText . coerce
+
+-- | Fold ASCII letters to lower case, as DuckDB does for identifiers.
+foldIdentifier :: Text -> Text
+foldIdentifier = Text.map (\char -> if isAsciiUpper char then toLower char else char)
+
+{- Note [SQL text of the library]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The library runs some SQL statements of its own. It builds each statement from
+constant text, and it gives each value of a user to DuckDB as a parameter.
+Thus a value of a user cannot change the statement. These are the statements:
+
+- withTransaction in "Database.DuckDB.Simple": BEGIN TRANSACTION, COMMIT, and
+  ROLLBACK. The statements are constant.
+
+- catalogTypeName in "Database.DuckDB.Simple.Catalog": a SELECT from
+  duckdb_databases(). The database name is a parameter.
+
+- lookupCatalogEntry in "Database.DuckDB.Simple.Catalog": a SELECT from a
+  duckdb_*() table function. The module selects the table function and the
+  column from constants. The catalog name, the schema name, and the entry name
+  are parameters.
+
+- queryGeometryType in "Database.DuckDB.Simple.V2.LogicalRep": a constant
+  SELECT with a fixed WKB literal and one parameter for the CRS name.
+
+- metadataStatement in "Database.DuckDB.Simple.VariantCodec": a constant
+  SELECT. The list of VARIANT values is a parameter.
+
+- extractionStatement in "Database.DuckDB.Simple.VariantCodec": a SELECT with
+  one placeholder for each object key. The library makes the placeholders from
+  the number of keys. The list of VARIANT values and each key are parameters.
+
+- deleteFunction in "Database.DuckDB.Simple.Function": DROP FUNCTION IF EXISTS.
+  This statement is the exception. DROP FUNCTION takes no parameter for the
+  name of the function, so the name goes into the text. The library parses the
+  name with duckdb_v2_qname_parse, the rules of DuckDB for a qualified name,
+  and quoteIdentifier quotes each part of the result.
+
+quoteIdentifier puts an identifier in double quotes, and it doubles each double
+quote in the identifier. Thus DuckDB reads the identifier as one name, also
+when it contains a quote, a dot, or a semicolon. Use quoteIdentifier for each
+identifier that the library puts into SQL text, and add each new statement to
+this list.
+-}
+
+-- | Put an SQL identifier in double quotes, and double each double quote in
+-- it. See Note [SQL text of the library].
+quoteIdentifier :: Text -> Text
+quoteIdentifier identifier = "\"" <> Text.replace "\"" "\"\"" identifier <> "\""
+
+-- | Raise the error of an input check: an argument of a library function, or a
+-- parameter value, that the library rejects. The error is an t'SQLError' of the
+-- type 'ErrorInputInvalid' with no query. The checks of arguments use this
+-- function, and so do the checks of a parameter value of the wrong shape or
+-- type, for example a UNION tag that is not a member, a leaf of another type
+-- than its declaration, a STRUCT field that does not match its type, a DECIMAL
+-- width outside 1 to 38, or an empty Array, also where DuckDB gives another
+-- error type for the same input. A value that its SQL type cannot hold uses
+-- 'throwConversionError'. An error that is not about an input, for example a
+-- state error or a native failure, does not use this function.
+throwInvalidArgument :: Text -> IO a
+throwInvalidArgument message = throwIO (SQLError ("duckdb-simple: " <> message) (Just ErrorInputInvalid) Nothing Nothing)
+
+-- | Raise the error of an input check for a value that its SQL type cannot
+-- hold. The error is an t'SQLError' of the type 'ErrorTypeConversion' with no
+-- query, as the "Conversion Error" of DuckDB for the same value in SQL, for
+-- example for @300::TINYINT@, @'25:00:00'::TIME@, or @\'x\'::ENUM(\'a\', \'b\')@.
+-- These checks use this function: an integer outside its parameter type or
+-- its declared type, a HUGEINT or UHUGEINT value outside its type, a DECIMAL
+-- value that its width cannot hold, a date or a timestamp outside the range of
+-- DuckDB, a nanosecond timestamp outside its storage, a TIMETZ offset outside
+-- -57599 to 57599 seconds, a time of day that is not a TIME value, and an ENUM
+-- label that is not in the dictionary of its type.
+throwConversionError :: Text -> IO a
+throwConversionError message = throwIO (SQLError ("duckdb-simple: " <> message) (Just ErrorTypeConversion) Nothing Nothing)
+
+-- | Raise the error of a check of the state of the library, or of a vector, a
+-- type, or a value that DuckDB gave: an t'SQLError' of the type
+-- 'ErrorRuntimeInternal' with no query. Such an error means a defect of the
+-- library or of DuckDB, not a defect of an input. See
+-- Note [Internal errors in callbacks].
+throwInternalError :: Text -> IO a
+throwInternalError message = throwIO (SQLError ("duckdb-simple: " <> message) (Just ErrorRuntimeInternal) Nothing Nothing)
+
+-- | The 'displayException' text of the exception in a t'SomeException'. In
+-- base 4.20 (GHC 9.10), the 'displayException' of t'SomeException' adds a
+-- newline and the context of the exception, also when the context is empty.
+-- The text of an error must be the same with each GHC version, so the
+-- library shows the inner exception.
+exceptionText :: SomeException -> String
+exceptionText (SomeException failure) = displayException failure
+
+{- Note [Internal errors in callbacks]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+throwInternalError can raise its SQLError inside a DuckDB callback, for
+example in a decoder check of an argument vector or in a state check of an
+aggregate. runCallback in "Database.DuckDB.Simple.Callback" writes the code
+of the type of an SQLError into the error slot of a callback, but it holds
+back ErrorRuntimeInternal and ErrorRuntimeFatal and writes the code
+DuckDBV2ErrorApi and the message for them. See
+Note [Errors that leave a callback] in "Database.DuckDB.Simple.Callback". The
+type ErrorRuntimeInternal, and ErrorRuntimeFatal, must never go into the error
+slot of a callback, because DuckDB 2.0.0 then invalidates the database, and
+each later statement raises "FATAL Error: ... database has been invalidated".
+This holds for a callback at execution time, for example a scalar function, a
+table function, a cast, or COPY FROM; at bind time, for example in a
+replacement scan or a query pragma, the database stays usable. The rule
+applies at bind time too.
+-}
+
+-- | Borrow a factory while its connection remains alive. Do not destroy it.
+withConnectionFactory :: DuckDBV2ConnectionHandle -> (DuckDBV2FactoryHandle -> IO a) -> IO a
+withConnectionFactory connection action = output (c_duckdb_v2_connection_get_factory connection) >>= action
+
+-- | Read one checked output from a call that borrows the connection's factory.
+factoryOutput
+  :: (Storable a) => DuckDBV2ConnectionHandle -> (DuckDBV2FactoryHandle -> Ptr a -> Ptr DuckDBV2ErrorInfoHandle -> IO DuckDBV2Error) -> IO a
+factoryOutput connection create = withConnectionFactory connection (output . create)
+
+-- | Parse trusted SQL and borrow its first statement.
+withSQLStatement :: DuckDBV2ConnectionHandle -> Text -> (DuckDBV2SqlStatementHandle -> IO a) -> IO a
+withSQLStatement connection sql action =
+  TextForeign.withCString sql $ \source ->
+    bracket (output (c_duckdb_v2_parse_sql connection (ConstPtr source))) (destroy c_duckdb_v2_statement_iterator_destroy) $ \iterator ->
+      bracket (output (c_duckdb_v2_statement_iterator_next iterator)) (destroy c_duckdb_v2_sql_statement_destroy) action
+
+-- | Borrow a factory during its native callback. Do not retain or destroy it.
+withContextFactory :: DuckDBV2ContextHandle -> (DuckDBV2FactoryHandle -> IO a) -> IO a
+withContextFactory context action = output (c_duckdb_v2_context_get_factory context) >>= action
+
+-- | Borrow an instance factory for built-in types, casts, and allocations.
+withInstanceFactory :: DuckDBV2InstanceHandle -> (DuckDBV2FactoryHandle -> IO a) -> IO a
+withInstanceFactory instance_ action = output (c_duckdb_v2_instance_get_factory instance_) >>= action
+
+-- | The native factory that makes values and types. A connection, a callback
+-- context, and an instance each lend one. The name has no C API version: a later
+-- version changes only this synonym.
+type ValueFactory = DuckDBV2FactoryHandle
+
+-- | An owned native value. Destroy it after use. The name has no C API
+-- version: a later version changes only this synonym.
+type NativeValue = DuckDBV2ValueHandle
+
+-- | The scope of a configuration value. The default scope selects the scope that the option declares.
+data SettingScope
+  = SettingScopeDefault
+  | SettingScopeGlobal
+  | SettingScopeSession
+  deriving (Eq, Ord, Show, Read, Enum, Bounded)
+
+-- | Convert a setting scope to its native value.
+settingScopeToNative :: SettingScope -> DuckDBV2SettingScope
+settingScopeToNative = \case
+  SettingScopeDefault -> DuckDBV2SettingScopeDefault
+  SettingScopeGlobal -> DuckDBV2SettingScopeGlobal
+  SettingScopeSession -> DuckDBV2SettingScopeSession
+
+-- | Convert a native setting scope. An unknown value raises t'SQLError'.
+settingScopeFromNative :: DuckDBV2SettingScope -> IO SettingScope
+settingScopeFromNative = \case
+  DuckDBV2SettingScopeDefault -> pure SettingScopeDefault
+  DuckDBV2SettingScopeGlobal -> pure SettingScopeGlobal
+  DuckDBV2SettingScopeSession -> pure SettingScopeSession
+  DuckDBV2SettingScope value -> throwUnknownNative "setting scope" value
+
+-- | The severity of a log entry.
+data LogLevel
+  = LogLevelTrace
+  | LogLevelDebug
+  | LogLevelInfo
+  | LogLevelWarning
+  | LogLevelError
+  | LogLevelFatal
+  deriving (Eq, Ord, Show, Read, Enum, Bounded)
+
+-- | Convert a log level to its native value.
+logLevelToNative :: LogLevel -> DuckDBV2LogLevel
+logLevelToNative = \case
+  LogLevelTrace -> DuckDBV2LogLevelTrace
+  LogLevelDebug -> DuckDBV2LogLevelDebug
+  LogLevelInfo -> DuckDBV2LogLevelInfo
+  LogLevelWarning -> DuckDBV2LogLevelWarning
+  LogLevelError -> DuckDBV2LogLevelError
+  LogLevelFatal -> DuckDBV2LogLevelFatal
+
+-- | Convert a native log level. An unknown value raises t'SQLError'.
+logLevelFromNative :: DuckDBV2LogLevel -> IO LogLevel
+logLevelFromNative = \case
+  DuckDBV2LogLevelTrace -> pure LogLevelTrace
+  DuckDBV2LogLevelDebug -> pure LogLevelDebug
+  DuckDBV2LogLevelInfo -> pure LogLevelInfo
+  DuckDBV2LogLevelWarning -> pure LogLevelWarning
+  DuckDBV2LogLevelError -> pure LogLevelError
+  DuckDBV2LogLevelFatal -> pure LogLevelFatal
+  DuckDBV2LogLevel value -> throwUnknownNative "log level" value
+
+-- | The context of a log entry: the database, a connection, or a thread.
+data LogScope
+  = LogScopeDatabase
+  | LogScopeConnection
+  | LogScopeThread
+  deriving (Eq, Ord, Show, Read, Enum, Bounded)
+
+-- | Convert a native log scope. An unknown value raises t'SQLError'.
+logScopeFromNative :: DuckDBV2LogScope -> IO LogScope
+logScopeFromNative = \case
+  DuckDBV2LogScopeDatabase -> pure LogScopeDatabase
+  DuckDBV2LogScopeConnection -> pure LogScopeConnection
+  DuckDBV2LogScopeThread -> pure LogScopeThread
+  DuckDBV2LogScope value -> throwUnknownNative "log scope" value
+
+-- | The kind of a SQL token.
+data TokenType
+  = TokenTypeInvalid
+  | TokenTypeKeyword
+  | TokenTypeIdentifier
+  | TokenTypeStringLiteral
+  | TokenTypeNumberLiteral
+  | TokenTypeOperator
+  | TokenTypeComment
+  | TokenTypeTerminator
+  | TokenTypeEndOfInput
+  deriving (Eq, Ord, Show, Read, Enum, Bounded)
+
+-- | Convert a native token type. An unknown value raises t'SQLError'.
+tokenTypeFromNative :: DuckDBV2TokenType -> IO TokenType
+tokenTypeFromNative = \case
+  DuckDBV2TokenTypeInvalid -> pure TokenTypeInvalid
+  DuckDBV2TokenTypeKeyword -> pure TokenTypeKeyword
+  DuckDBV2TokenTypeIdentifier -> pure TokenTypeIdentifier
+  DuckDBV2TokenTypeStringLiteral -> pure TokenTypeStringLiteral
+  DuckDBV2TokenTypeNumberLiteral -> pure TokenTypeNumberLiteral
+  DuckDBV2TokenTypeOperator -> pure TokenTypeOperator
+  DuckDBV2TokenTypeComment -> pure TokenTypeComment
+  DuckDBV2TokenTypeTerminator -> pure TokenTypeTerminator
+  DuckDBV2TokenTypeEndOfInput -> pure TokenTypeEndOfInput
+  DuckDBV2TokenType value -> throwUnknownNative "token type" value
+
+-- | The kind of a macro: a scalar expression or a table SELECT.
+data MacroFunctionType
+  = MacroFunctionTypeScalar
+  | MacroFunctionTypeTable
+  deriving (Eq, Ord, Show, Read, Enum, Bounded)
+
+-- | Convert a macro kind to its native value.
+macroFunctionTypeToNative :: MacroFunctionType -> DuckDBV2MacroFunctionType
+macroFunctionTypeToNative = \case
+  MacroFunctionTypeScalar -> DuckDBV2MacroFunctionTypeScalar
+  MacroFunctionTypeTable -> DuckDBV2MacroFunctionTypeTable
+
+-- | The id of a logical type. The id gives the kind of the type, for example
+-- BIGINT or STRUCT. It does not give the parameters of the type.
+data LogicalTypeId
+  = LogicalTypeIdInvalid
+  | LogicalTypeIdSQLNull
+  | LogicalTypeIdUnknown
+  | LogicalTypeIdAny
+  | LogicalTypeIdType
+  | LogicalTypeIdBoolean
+  | LogicalTypeIdTinyInt
+  | LogicalTypeIdSmallInt
+  | LogicalTypeIdInteger
+  | LogicalTypeIdBigInt
+  | LogicalTypeIdDate
+  | LogicalTypeIdTime
+  | LogicalTypeIdTimestampSec
+  | LogicalTypeIdTimestampMs
+  | LogicalTypeIdTimestamp
+  | LogicalTypeIdTimestampNs
+  | LogicalTypeIdDecimal
+  | LogicalTypeIdFloat
+  | LogicalTypeIdDouble
+  | LogicalTypeIdVarchar
+  | LogicalTypeIdBlob
+  | LogicalTypeIdInterval
+  | LogicalTypeIdUTinyInt
+  | LogicalTypeIdUSmallInt
+  | LogicalTypeIdUInteger
+  | LogicalTypeIdUBigInt
+  | LogicalTypeIdTimestampTz
+  | LogicalTypeIdTimestampTzNs
+  | LogicalTypeIdTimeTz
+  | LogicalTypeIdTimeNs
+  | LogicalTypeIdBit
+  | LogicalTypeIdBigNum
+  | LogicalTypeIdUHugeInt
+  | LogicalTypeIdHugeInt
+  | LogicalTypeIdUUID
+  | LogicalTypeIdGeometry
+  | LogicalTypeIdStruct
+  | LogicalTypeIdList
+  | LogicalTypeIdMap
+  | LogicalTypeIdEnum
+  | LogicalTypeIdUnion
+  | LogicalTypeIdArray
+  | LogicalTypeIdVariant
+  | LogicalTypeIdTuple
+  deriving (Eq, Ord, Show, Read, Enum, Bounded)
+
+-- | Convert a logical type id to its native value.
+logicalTypeIdToNative :: LogicalTypeId -> DuckDBV2LogicalTypeId
+logicalTypeIdToNative = \case
+  LogicalTypeIdInvalid -> DuckDBV2LogicalTypeIdInvalid
+  LogicalTypeIdSQLNull -> DuckDBV2LogicalTypeIdSQLNull
+  LogicalTypeIdUnknown -> DuckDBV2LogicalTypeIdUnknown
+  LogicalTypeIdAny -> DuckDBV2LogicalTypeIdAny
+  LogicalTypeIdType -> DuckDBV2LogicalTypeIdType
+  LogicalTypeIdBoolean -> DuckDBV2LogicalTypeIdBoolean
+  LogicalTypeIdTinyInt -> DuckDBV2LogicalTypeIdTinyInt
+  LogicalTypeIdSmallInt -> DuckDBV2LogicalTypeIdSmallInt
+  LogicalTypeIdInteger -> DuckDBV2LogicalTypeIdInteger
+  LogicalTypeIdBigInt -> DuckDBV2LogicalTypeIdBigInt
+  LogicalTypeIdDate -> DuckDBV2LogicalTypeIdDate
+  LogicalTypeIdTime -> DuckDBV2LogicalTypeIdTime
+  LogicalTypeIdTimestampSec -> DuckDBV2LogicalTypeIdTimestampSec
+  LogicalTypeIdTimestampMs -> DuckDBV2LogicalTypeIdTimestampMs
+  LogicalTypeIdTimestamp -> DuckDBV2LogicalTypeIdTimestamp
+  LogicalTypeIdTimestampNs -> DuckDBV2LogicalTypeIdTimestampNs
+  LogicalTypeIdDecimal -> DuckDBV2LogicalTypeIdDecimal
+  LogicalTypeIdFloat -> DuckDBV2LogicalTypeIdFloat
+  LogicalTypeIdDouble -> DuckDBV2LogicalTypeIdDouble
+  LogicalTypeIdVarchar -> DuckDBV2LogicalTypeIdVarchar
+  LogicalTypeIdBlob -> DuckDBV2LogicalTypeIdBlob
+  LogicalTypeIdInterval -> DuckDBV2LogicalTypeIdInterval
+  LogicalTypeIdUTinyInt -> DuckDBV2LogicalTypeIdUTinyInt
+  LogicalTypeIdUSmallInt -> DuckDBV2LogicalTypeIdUSmallInt
+  LogicalTypeIdUInteger -> DuckDBV2LogicalTypeIdUInteger
+  LogicalTypeIdUBigInt -> DuckDBV2LogicalTypeIdUBigInt
+  LogicalTypeIdTimestampTz -> DuckDBV2LogicalTypeIdTimestampTz
+  LogicalTypeIdTimestampTzNs -> DuckDBV2LogicalTypeIdTimestampTzNs
+  LogicalTypeIdTimeTz -> DuckDBV2LogicalTypeIdTimeTz
+  LogicalTypeIdTimeNs -> DuckDBV2LogicalTypeIdTimeNs
+  LogicalTypeIdBit -> DuckDBV2LogicalTypeIdBit
+  LogicalTypeIdBigNum -> DuckDBV2LogicalTypeIdBigNum
+  LogicalTypeIdUHugeInt -> DuckDBV2LogicalTypeIdUHugeInt
+  LogicalTypeIdHugeInt -> DuckDBV2LogicalTypeIdHugeInt
+  LogicalTypeIdUUID -> DuckDBV2LogicalTypeIdUUID
+  LogicalTypeIdGeometry -> DuckDBV2LogicalTypeIdGeometry
+  LogicalTypeIdStruct -> DuckDBV2LogicalTypeIdStruct
+  LogicalTypeIdList -> DuckDBV2LogicalTypeIdList
+  LogicalTypeIdMap -> DuckDBV2LogicalTypeIdMap
+  LogicalTypeIdEnum -> DuckDBV2LogicalTypeIdEnum
+  LogicalTypeIdUnion -> DuckDBV2LogicalTypeIdUnion
+  LogicalTypeIdArray -> DuckDBV2LogicalTypeIdArray
+  LogicalTypeIdVariant -> DuckDBV2LogicalTypeIdVariant
+  LogicalTypeIdTuple -> DuckDBV2LogicalTypeIdTuple
+
+-- | Convert a native logical type id. An unknown value raises t'SQLError'.
+logicalTypeIdFromNative :: DuckDBV2LogicalTypeId -> IO LogicalTypeId
+logicalTypeIdFromNative = \case
+  DuckDBV2LogicalTypeIdInvalid -> pure LogicalTypeIdInvalid
+  DuckDBV2LogicalTypeIdSQLNull -> pure LogicalTypeIdSQLNull
+  DuckDBV2LogicalTypeIdUnknown -> pure LogicalTypeIdUnknown
+  DuckDBV2LogicalTypeIdAny -> pure LogicalTypeIdAny
+  DuckDBV2LogicalTypeIdType -> pure LogicalTypeIdType
+  DuckDBV2LogicalTypeIdBoolean -> pure LogicalTypeIdBoolean
+  DuckDBV2LogicalTypeIdTinyInt -> pure LogicalTypeIdTinyInt
+  DuckDBV2LogicalTypeIdSmallInt -> pure LogicalTypeIdSmallInt
+  DuckDBV2LogicalTypeIdInteger -> pure LogicalTypeIdInteger
+  DuckDBV2LogicalTypeIdBigInt -> pure LogicalTypeIdBigInt
+  DuckDBV2LogicalTypeIdDate -> pure LogicalTypeIdDate
+  DuckDBV2LogicalTypeIdTime -> pure LogicalTypeIdTime
+  DuckDBV2LogicalTypeIdTimestampSec -> pure LogicalTypeIdTimestampSec
+  DuckDBV2LogicalTypeIdTimestampMs -> pure LogicalTypeIdTimestampMs
+  DuckDBV2LogicalTypeIdTimestamp -> pure LogicalTypeIdTimestamp
+  DuckDBV2LogicalTypeIdTimestampNs -> pure LogicalTypeIdTimestampNs
+  DuckDBV2LogicalTypeIdDecimal -> pure LogicalTypeIdDecimal
+  DuckDBV2LogicalTypeIdFloat -> pure LogicalTypeIdFloat
+  DuckDBV2LogicalTypeIdDouble -> pure LogicalTypeIdDouble
+  DuckDBV2LogicalTypeIdVarchar -> pure LogicalTypeIdVarchar
+  DuckDBV2LogicalTypeIdBlob -> pure LogicalTypeIdBlob
+  DuckDBV2LogicalTypeIdInterval -> pure LogicalTypeIdInterval
+  DuckDBV2LogicalTypeIdUTinyInt -> pure LogicalTypeIdUTinyInt
+  DuckDBV2LogicalTypeIdUSmallInt -> pure LogicalTypeIdUSmallInt
+  DuckDBV2LogicalTypeIdUInteger -> pure LogicalTypeIdUInteger
+  DuckDBV2LogicalTypeIdUBigInt -> pure LogicalTypeIdUBigInt
+  DuckDBV2LogicalTypeIdTimestampTz -> pure LogicalTypeIdTimestampTz
+  DuckDBV2LogicalTypeIdTimestampTzNs -> pure LogicalTypeIdTimestampTzNs
+  DuckDBV2LogicalTypeIdTimeTz -> pure LogicalTypeIdTimeTz
+  DuckDBV2LogicalTypeIdTimeNs -> pure LogicalTypeIdTimeNs
+  DuckDBV2LogicalTypeIdBit -> pure LogicalTypeIdBit
+  DuckDBV2LogicalTypeIdBigNum -> pure LogicalTypeIdBigNum
+  DuckDBV2LogicalTypeIdUHugeInt -> pure LogicalTypeIdUHugeInt
+  DuckDBV2LogicalTypeIdHugeInt -> pure LogicalTypeIdHugeInt
+  DuckDBV2LogicalTypeIdUUID -> pure LogicalTypeIdUUID
+  DuckDBV2LogicalTypeIdGeometry -> pure LogicalTypeIdGeometry
+  DuckDBV2LogicalTypeIdStruct -> pure LogicalTypeIdStruct
+  DuckDBV2LogicalTypeIdList -> pure LogicalTypeIdList
+  DuckDBV2LogicalTypeIdMap -> pure LogicalTypeIdMap
+  DuckDBV2LogicalTypeIdEnum -> pure LogicalTypeIdEnum
+  DuckDBV2LogicalTypeIdUnion -> pure LogicalTypeIdUnion
+  DuckDBV2LogicalTypeIdArray -> pure LogicalTypeIdArray
+  DuckDBV2LogicalTypeIdVariant -> pure LogicalTypeIdVariant
+  DuckDBV2LogicalTypeIdTuple -> pure LogicalTypeIdTuple
+  DuckDBV2LogicalTypeId value -> throwUnknownNative "logical type id" value
+
+-- | The name of a type id in DuckDB 2.0.0. duckdb_v2_logical_type_get_name
+-- gives this name for a type with no alias. See Note [Type aliases] in
+-- "Database.DuckDB.Simple.LogicalRep".
+logicalTypeIdName :: LogicalTypeId -> Text
+logicalTypeIdName = \case
+  LogicalTypeIdInvalid -> "INVALID"
+  LogicalTypeIdSQLNull -> "NULL"
+  LogicalTypeIdUnknown -> "UNKNOWN"
+  LogicalTypeIdAny -> "ANY"
+  LogicalTypeIdType -> "TYPE"
+  LogicalTypeIdBoolean -> "BOOLEAN"
+  LogicalTypeIdTinyInt -> "TINYINT"
+  LogicalTypeIdSmallInt -> "SMALLINT"
+  LogicalTypeIdInteger -> "INTEGER"
+  LogicalTypeIdBigInt -> "BIGINT"
+  LogicalTypeIdDate -> "DATE"
+  LogicalTypeIdTime -> "TIME"
+  LogicalTypeIdTimestampSec -> "TIMESTAMP_S"
+  LogicalTypeIdTimestampMs -> "TIMESTAMP_MS"
+  LogicalTypeIdTimestamp -> "TIMESTAMP"
+  LogicalTypeIdTimestampNs -> "TIMESTAMP_NS"
+  LogicalTypeIdDecimal -> "DECIMAL"
+  LogicalTypeIdFloat -> "FLOAT"
+  LogicalTypeIdDouble -> "DOUBLE"
+  LogicalTypeIdVarchar -> "VARCHAR"
+  LogicalTypeIdBlob -> "BLOB"
+  LogicalTypeIdInterval -> "INTERVAL"
+  LogicalTypeIdUTinyInt -> "UTINYINT"
+  LogicalTypeIdUSmallInt -> "USMALLINT"
+  LogicalTypeIdUInteger -> "UINTEGER"
+  LogicalTypeIdUBigInt -> "UBIGINT"
+  LogicalTypeIdTimestampTz -> "TIMESTAMP WITH TIME ZONE"
+  LogicalTypeIdTimestampTzNs -> "TIMESTAMPTZ_NS"
+  LogicalTypeIdTimeTz -> "TIME WITH TIME ZONE"
+  LogicalTypeIdTimeNs -> "TIME_NS"
+  LogicalTypeIdBit -> "BIT"
+  LogicalTypeIdBigNum -> "BIGNUM"
+  LogicalTypeIdUHugeInt -> "UHUGEINT"
+  LogicalTypeIdHugeInt -> "HUGEINT"
+  LogicalTypeIdUUID -> "UUID"
+  LogicalTypeIdGeometry -> "GEOMETRY"
+  LogicalTypeIdStruct -> "STRUCT"
+  LogicalTypeIdList -> "LIST"
+  LogicalTypeIdMap -> "MAP"
+  LogicalTypeIdEnum -> "ENUM"
+  LogicalTypeIdUnion -> "UNION"
+  LogicalTypeIdArray -> "ARRAY"
+  LogicalTypeIdVariant -> "VARIANT"
+  LogicalTypeIdTuple -> "TUPLE"
+
+-- | A behaviour of a file open. The flags are not a bitmask. Each flag in the
+-- list adds one behaviour.
+data FileFlag
+  = -- | Open the file for reading.
+    FileFlagRead
+  | -- | Open the file for writing.
+    FileFlagWrite
+  | -- | Create the file if it does not exist. Keep the contents of an existing file.
+    FileFlagCreate
+  | -- | Create the file if it does not exist. Truncate an existing file to empty.
+    FileFlagCreateNew
+  | -- | Open the file in append mode.
+    FileFlagAppend
+  | -- | Fail if the file exists. Use it only together with 'FileFlagCreate'.
+    FileFlagExclusiveCreate
+  | -- | Read and write at explicit offsets from more than one thread at the same time.
+    FileFlagParallelAccess
+  | -- | Read the file through the external file cache of DuckDB. Use it only for reading.
+    FileFlagExternalFileCache
+  deriving (Eq, Ord, Show, Read, Enum, Bounded)
+
+-- | Convert a file flag to its native value.
+fileFlagToNative :: FileFlag -> DuckDBV2FileFlag
+fileFlagToNative = \case
+  FileFlagRead -> DuckDBV2FileFlagRead
+  FileFlagWrite -> DuckDBV2FileFlagWrite
+  FileFlagCreate -> DuckDBV2FileFlagCreate
+  FileFlagCreateNew -> DuckDBV2FileFlagCreateNew
+  FileFlagAppend -> DuckDBV2FileFlagAppend
+  FileFlagExclusiveCreate -> DuckDBV2FileFlagExclusiveCreate
+  FileFlagParallelAccess -> DuckDBV2FileFlagParallelAccess
+  FileFlagExternalFileCache -> DuckDBV2FileFlagExternalFileCache
+
+-- | Raise t'SQLError' for a native enum value that has no Haskell constructor.
+throwUnknownNative :: Text -> CUInt -> IO a
+throwUnknownNative kind value = throwInternalError ("unknown native " <> kind <> " " <> Text.pack (show value))
diff --git a/src/Database/DuckDB/Simple/Ok.hs b/src/Database/DuckDB/Simple/Ok.hs
--- a/src/Database/DuckDB/Simple/Ok.hs
+++ b/src/Database/DuckDB/Simple/Ok.hs
@@ -1,18 +1,17 @@
 {-# LANGUAGE DeriveFunctor #-}
 {-# LANGUAGE DerivingStrategies #-}
 
-{- |
-Module      : Database.DuckDB.Simple.Ok
-Description : Lightweight error accumulation for row parsing.
-
-The @Ok@ type mirrors the helper used by @sqlite-simple@: it behaves like an
-@Either [SomeException]@ with sensible @Alternative@ semantics that accumulate
-failure reasons instead of discarding them. This underpins the row parser
-machinery in @Database.DuckDB.Simple.FromRow@.
--}
+-- |
+-- Module      : Database.DuckDB.Simple.Ok
+-- Description : Accumulate errors from row parsing.
+--
+-- The @Ok@ type mirrors the helper used by @sqlite-simple@. It behaves like
+-- @Either [SomeException]@. Its @Alternative@ instance keeps the errors when
+-- both alternatives fail. @Database.DuckDB.Simple.Conversion.runConversion@
+-- returns it after conversion effects and diagnostics have completed.
 module Database.DuckDB.Simple.Ok (
-    Ok (..),
-    ManyErrors (..),
+  Ok (..),
+  ManyErrors (..),
 ) where
 
 import Control.Applicative (Alternative (..))
@@ -20,45 +19,45 @@
 import Control.Monad (MonadPlus (..))
 import qualified Control.Monad.Fail as Fail
 
--- | Simple success-or-errors container with error accumulation.
+-- | A value or a list of errors.
 data Ok a
-    = Errors [SomeException]
-    | Ok !a
-    deriving stock (Show)
-    deriving stock (Functor)
+  = Errors [SomeException]
+  | Ok !a
+  deriving stock (Show)
+  deriving stock (Functor)
 
 -- | Two failures are considered equal regardless of their payload.
 instance (Eq a) => Eq (Ok a) where
-    Errors _ == Errors _ = True
-    Ok a == Ok b = a == b
-    _ == _ = False
+  Errors _ == Errors _ = True
+  Ok a == Ok b = a == b
+  _ == _ = False
 
 instance Applicative Ok where
-    pure = Ok
-    Ok f <*> Ok a = Ok (f a)
-    Errors es <*> Ok _ = Errors es
-    Ok _ <*> Errors es = Errors es
-    Errors es1 <*> Errors es2 = Errors (es1 <> es2)
+  pure = Ok
+  Ok f <*> Ok a = Ok (f a)
+  Errors es <*> Ok _ = Errors es
+  Ok _ <*> Errors es = Errors es
+  Errors es1 <*> Errors es2 = Errors (es1 <> es2)
 
 instance Alternative Ok where
-    empty = Errors []
-    Ok x <|> _ = Ok x
-    Errors _ <|> Ok y = Ok y
-    Errors xs <|> Errors ys = Errors (xs <> ys)
+  empty = Errors []
+  Ok x <|> _ = Ok x
+  Errors _ <|> Ok y = Ok y
+  Errors xs <|> Errors ys = Errors (xs <> ys)
 
 instance Monad Ok where
-    Ok a >>= f = f a
-    Errors es >>= _ = Errors es
+  Ok a >>= f = f a
+  Errors es >>= _ = Errors es
 
 instance MonadPlus Ok where
-    mzero = empty
-    mplus = (<|>)
+  mzero = empty
+  mplus = (<|>)
 
 instance Fail.MonadFail Ok where
-    fail msg = Errors [toException (userError msg)]
+  fail msg = Errors [toException (userError msg)]
 
--- | Bundle multiple underlying exceptions into a single throwable value.
+-- | Store multiple exceptions in one exception.
 newtype ManyErrors = ManyErrors [SomeException]
-    deriving stock (Show)
+  deriving stock (Show)
 
 instance Exception ManyErrors
diff --git a/src/Database/DuckDB/Simple/Pragma.hs b/src/Database/DuckDB/Simple/Pragma.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/Pragma.hs
@@ -0,0 +1,13 @@
+-- |
+-- Module      : Database.DuckDB.Simple.Pragma
+-- Description : Register PRAGMA functions with typed Haskell callbacks.
+--
+-- A callback gets the arguments of the call as one row, decoded with
+-- t'Database.DuckDB.Simple.FromRow.FromRow'.
+-- "Database.DuckDB.Simple.V2.Pragma" has the callbacks that get native handles.
+module Database.DuckDB.Simple.Pragma (
+  PragmaCallback (..),
+  registerPragmaFunction,
+) where
+
+import Database.DuckDB.Simple.Pragma.Internal (PragmaCallback (..), registerPragmaFunction)
diff --git a/src/Database/DuckDB/Simple/Pragma/Internal.hs b/src/Database/DuckDB/Simple/Pragma/Internal.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/Pragma/Internal.hs
@@ -0,0 +1,103 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.Pragma.Internal
+-- Description : Share the typed PRAGMA registration for connections and extensions.
+--
+-- The cabal file lists this hidden module in @other-modules@.
+-- 'registerPragmaFunctionOn' takes a registration target.
+-- "Database.DuckDB.Simple.Pragma" exports the connection form.
+-- "Database.DuckDB.Simple.Extension" exports the extension form.
+module Database.DuckDB.Simple.Pragma.Internal (
+  PragmaCallback (..),
+  registerPragmaFunction,
+  registerPragmaFunctionOn,
+) where
+
+import Control.Exception (throwIO)
+import Control.Monad (forM, when)
+import Data.Maybe (fromMaybe)
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Database.DuckDB.Simple.Callback (targetCastFactory)
+import Database.DuckDB.Simple.Conversion (runConversion)
+import Database.DuckDB.Simple.FromRow (FromRow (..), parseRow, rowErrorsToSqlError)
+import Database.DuckDB.Simple.Internal (Connection)
+import Database.DuckDB.Simple.Materialize (callbackReadFactory)
+import Database.DuckDB.Simple.Native
+import Database.DuckDB.Simple.Ok (Ok (..))
+import Database.DuckDB.Simple.TypeScope (TypeScope, withTypeScope)
+import Database.DuckDB.Simple.Typed (readBoundField)
+import qualified Database.DuckDB.Simple.V2.Pragma as V2
+import Database.DuckDB.Simple.V2.Registration (
+  FunctionParameter,
+  RegistrationTarget (..),
+ )
+import Foreign.Marshal.Array (advancePtr, allocaArray, peekArray)
+
+-- | The callback of a pragma. The argument @args@ is the row of the
+-- arguments of the call. A query callback gives SQL. DuckDB runs that SQL in
+-- place of the PRAGMA statement. An execution callback does an action and gives
+-- no rows. An exception becomes an SQL error.
+data PragmaCallback args
+  = QueryPragma (args -> IO Text)
+  | ExecPragma (args -> IO ())
+
+-- | Register a pragma on a connection. The pragma has no return type.
+--
+-- The row has one field for each argument, in this order: the positional-only
+-- parameters, the standard parameters, the arguments of the positional variadic
+-- parameter, the named-only parameters, and the arguments of the named variadic
+-- parameter. Parameters of one kind keep the order of the declaration. The
+-- arguments of a variadic parameter keep the order of the call. Thus, for
+-- parameters from 'Database.DuckDB.Simple.Registration.parameter', the row has
+-- one field for each parameter, in the order of the declaration.
+--
+-- A call gives a standard parameter by position or by name, for example
+-- @PRAGMA p(1, label = \'x\')@. The field is at the position of the parameter in
+-- both cases. When the call omits a parameter, the field has the default value of
+-- the parameter. A NULL argument needs a 'Maybe' field. When the row does not
+-- decode, the call fails with an SQL error that names the pragma.
+--
+-- > registerPragmaFunction conn "repeat_answer" [parameter "times" (TypeExpression "BIGINT")] $
+-- >     QueryPragma \(Only (times :: Int64)) -> pure ("SELECT 42 FROM range(" <> Text.pack (show times) <> ")")
+registerPragmaFunction :: (FromRow args) => Connection -> Text -> [FunctionParameter] -> PragmaCallback args -> IO ()
+registerPragmaFunction = registerPragmaFunctionOn . ConnectionTarget
+
+-- | Register a pragma on a connection or a loading extension.
+-- 'registerPragmaFunction' gives the rules for the argument row.
+registerPragmaFunctionOn :: (FromRow args) => RegistrationTarget -> Text -> [FunctionParameter] -> PragmaCallback args -> IO ()
+registerPragmaFunctionOn target name parameters callback = do
+  -- Check the name before the read of the state of the target, as each
+  -- registration does. 'V2.registerPragmaFunctionOn' checks it again.
+  when (Text.null name || Text.any (== '\0') name) $
+    throwInvalidArgument "pragma function name must be nonempty and must not contain NUL"
+  casts <- targetCastFactory target
+  V2.registerPragmaFunctionOn target name parameters case callback of
+    QueryPragma action -> V2.QueryPragma \info context -> withTypeScope \scope -> pragmaArguments scope casts name info context >>= action
+    ExecPragma action -> V2.ExecPragma \info context -> withTypeScope \scope -> pragmaArguments scope casts name info context >>= action
+
+-- | Copy the arguments of a pragma call and decode them as one row. The first
+-- argument is the name of the pragma for the error message.
+pragmaArguments
+  :: (FromRow args) => TypeScope -> Maybe DuckDBV2FactoryHandle -> Text -> DuckDBV2FunctionBindInfoHandle -> DuckDBV2ContextHandle -> IO args
+pragmaArguments scope casts name info context = withContextFactory context \contextFactory -> do
+  let factory = callbackReadFactory casts contextFactory
+  count <- allocaArray 4 \counts -> do
+    checked (c_duckdb_v2_function_bind_get_arg_count info counts (advancePtr counts 1) (advancePtr counts 2) (advancePtr counts 3))
+    sum <$> peekArray 4 counts
+  fields <- forM (indices count) \index -> do
+    argument <- output (c_duckdb_v2_function_bind_get_arg_name info index) >>= readIdentifier
+    readBoundField scope factory info argument index
+  converted <- runConversion (parseRow fromRow fields)
+  case converted of
+    Ok args -> pure args
+    Errors failures -> do
+      let message = sqlErrorMessage (rowErrorsToSqlError (Query name) failures)
+      throwIO
+        ( userError
+            ( Text.unpack
+                ("duckdb-simple: cannot decode the arguments of pragma " <> name <> ": " <> fromMaybe message (Text.stripPrefix "duckdb-simple: " message))
+            )
+        )
diff --git a/src/Database/DuckDB/Simple/QueryMetrics.hs b/src/Database/DuckDB/Simple/QueryMetrics.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/QueryMetrics.hs
@@ -0,0 +1,68 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.QueryMetrics
+-- Description : Copied query profiles.
+--
+-- Returned values do not retain native snapshot handles.
+module Database.DuckDB.Simple.QueryMetrics (
+  QueryMetrics (..),
+  enableProfiling,
+  queryMetrics,
+) where
+
+import Control.Exception (bracket)
+import Control.Monad (forM, when)
+import Data.Text (Text)
+import Database.DuckDB.Simple.FromField (FieldValue)
+import Database.DuckDB.Simple.Internal (Connection, connectionInstance, instanceCastFactory, withConnectionHandle)
+import Database.DuckDB.Simple.Materialize (ReadFactory (..), materializeValue, rejectRows)
+import Database.DuckDB.Simple.Native
+
+-- | One query or operator node. Metric order is unspecified. Any metric or
+-- operator can be absent. Native V2 reports numeric metrics only.
+-- Values and child nodes use Haskell-owned storage.
+data QueryMetrics = QueryMetrics
+  { metricsNodeName :: Text
+  , metricsValues :: [(Text, FieldValue)]
+  , metricsChildren :: [QueryMetrics]
+  }
+  deriving (Eq, Show)
+
+-- | Enable or disable profiling for later queries on this connection.
+-- Enabling sets the native @enable_profiling@ option to @no_output@. DuckDB then
+-- collects the metrics and does not print a profile. The option has the
+-- session scope, so another connection to the same database keeps its own
+-- setting.
+enableProfiling :: Connection -> Bool -> IO ()
+enableProfiling connection enabled = withConnectionHandle connection \native -> do
+  when enabled do
+    config <- output (c_duckdb_v2_connection_get_config native)
+    withIdentifier "enable_profiling" \name -> withText "no_output" \value ->
+      checked (c_duckdb_v2_config_set_option_text config name value DuckDBV2SettingScopeDefault)
+  checked (c_duckdb_v2_connection_enable_profiling native (if enabled then 1 else 0))
+
+-- | Copy the profile of the last completed query. Drain or close any active
+-- result first. The returned snapshot does not change when later queries run.
+-- Without profiling, the root has no metrics and no children. The function
+-- releases all native snapshot and value handles before it returns.
+queryMetrics :: Connection -> IO QueryMetrics
+queryMetrics connection = withConnectionHandle connection \native ->
+  bracket (output (c_duckdb_v2_connection_get_query_metrics native)) (destroy c_duckdb_v2_query_metrics_destroy) \snapshot -> do
+    casts <- instanceCastFactory (connectionInstance connection)
+    root <- output (c_duckdb_v2_query_metrics_get_root snapshot)
+    copyNode (materializeValue unexpectedVariant (InstanceFactory casts)) root
+  where
+    unexpectedVariant = rejectRows (throwInternalError "query metrics must be numeric")
+    copyNode readValue node = do
+      name <- output (c_duckdb_v2_query_metrics_node_get_name node) >>= readText
+      metricCount <- output (c_duckdb_v2_query_metrics_node_get_metric_count node)
+      metrics <- forM (indices metricCount) \index -> do
+        key <- output (c_duckdb_v2_query_metrics_node_get_metric_name node index) >>= readText
+        value <- bracket (output (c_duckdb_v2_query_metrics_node_get_metric_value node index)) (destroy c_duckdb_v2_value_destroy) readValue
+        pure (key, value)
+      childCount <- output (c_duckdb_v2_query_metrics_node_get_child_count node)
+      children <- forM (indices childCount) \index ->
+        output (c_duckdb_v2_query_metrics_node_get_child node index) >>= copyNode readValue
+      pure (QueryMetrics name metrics children)
diff --git a/src/Database/DuckDB/Simple/Registration.hs b/src/Database/DuckDB/Simple/Registration.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/Registration.hs
@@ -0,0 +1,84 @@
+-- |
+-- Module      : Database.DuckDB.Simple.Registration
+-- Description : Typed registration of custom types, replacement scans, and shared declarations.
+--
+-- This module has the declarations that typed registrations share. It also
+-- registers custom types and replacement scans on a connection or an instance.
+-- Its signatures have no native handle. A t'FunctionParameter' from 'parameter' is
+-- a required parameter. The V2 module has the field for the other parameter
+-- kinds. "Database.DuckDB.Simple.V2.Registration" has the registrations with
+-- native callbacks.
+module Database.DuckDB.Simple.Registration (
+  TypeDeclaration (..),
+  DefaultValue,
+  defaultValue,
+  -- See Note [Abstract parameter selectors].
+  FunctionParameter,
+  parameterName,
+  parameterType,
+  parameterDefault,
+  parameter,
+  registerCustomType,
+  Replacement (..),
+  registerReplacementScan,
+  registerInstanceReplacementScan,
+) where
+
+import Data.Text (Text)
+import Database.DuckDB.Simple.Internal (Connection, Instance)
+import Database.DuckDB.Simple.Typed (Replacement (..), replacementScanCallback)
+import Database.DuckDB.Simple.V2.Registration (
+  DefaultValue,
+  FunctionParameter (..),
+  RegistrationTarget (ConnectionTarget),
+  TypeDeclaration (..),
+  defaultValue,
+  parameter,
+  registerCustomType,
+ )
+import qualified Database.DuckDB.Simple.V2.Registration as V2
+
+{- Note [Abstract parameter selectors]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Haddock 2.33.0 omits selector declarations from bundled exports when the
+constructor is hidden. Export the selectors separately so the index has
+matching destinations. GHC retains the parent type of each selector.
+Bundled imports and record updates still work.
+-}
+
+-- | Register a replacement scan on a connection. DuckDB calls the function
+-- while it plans a query on this connection that reads a table that the catalog
+-- does not have. Other connections of the instance do not use the scan.
+--
+-- The function gets the parts of the table name as the query writes them. A name
+-- without a schema has one part. A qualified name has its catalog and schema
+-- before the table name, for example @[\"memory\", \"main\", \"t\"]@. DuckDB
+-- gives the parts also when the catalog or the schema does not exist. Each part
+-- keeps the case of the query text. DuckDB removes the quotes of a quoted part. A
+-- dot in a quoted part stays in that part. A file path in single quotes, for
+-- example @\'data.csv\'@, is one part without the quotes.
+--
+-- 'Nothing' declines the name. DuckDB then asks the next scan. When no scan
+-- replaces the name, the query fails with the usual error for an unknown table.
+-- An exception in the function fails the query with an SQL error that contains
+-- the message of the exception.
+--
+-- DuckDB asks the scans of the connection first, in the order of registration.
+-- Then it asks the scans of the instance, which include the built-in scans for
+-- file paths. The first scan that replaces the name wins. Thus a connection scan
+-- can replace a file path. A scan stays registered until the connection closes.
+-- No function removes a scan.
+registerReplacementScan :: Connection -> ([Text] -> IO (Maybe Replacement)) -> IO ()
+registerReplacementScan connection = V2.registerReplacementScanOn (ConnectionTarget connection) . replacementScanCallback
+
+-- | Register a replacement scan on an instance. Each connection of the
+-- instance uses the scan until the instance closes. No function removes a scan.
+-- DuckDB asks the scans of a connection before the scans of its instance. It asks
+-- the scans of the instance in the order of registration.
+-- 'registerReplacementScan' gives the rules for the function.
+--
+-- Register the scan before a connection runs a query. Registration while another
+-- connection plans a query is not thread safe. The function can run on several
+-- connections at the same time.
+registerInstanceReplacementScan :: Instance -> ([Text] -> IO (Maybe Replacement)) -> IO ()
+registerInstanceReplacementScan instance' = V2.registerInstanceReplacementScan instance' . replacementScanCallback
diff --git a/src/Database/DuckDB/Simple/Result.hs b/src/Database/DuckDB/Simple/Result.hs
--- a/src/Database/DuckDB/Simple/Result.hs
+++ b/src/Database/DuckDB/Simple/Result.hs
@@ -3,225 +3,288 @@
 {-# LANGUAGE NamedFieldPuns #-}
 {-# LANGUAGE TupleSections #-}
 
--- | Shared result decoding and cursor ownership for both execution modes.
+-- |
+-- Module      : Database.DuckDB.Simple.Result
+-- Description : Shared result decoding and cursor ownership for both execution modes.
 module Database.DuckDB.Simple.Result (
-    collectRows,
-    foldStatementWith,
-    nextRowWith,
-    resetStatementStream,
-    cleanupStatementStreamRef,
+  withRows,
+  withParsedRows,
+  foldStatementWith,
+  nextRowWith,
+  resetStatementStream,
 ) where
 
-import Control.Exception (bracket, evaluate, finally, mask, mask_, onException, throwIO)
-import Control.Monad (forM, when, zipWithM)
-import Data.IORef (IORef, atomicModifyIORef', readIORef, writeIORef)
+import Control.Exception (bracket, finally, mask, mask_, onException, throwIO)
+import Control.Monad (foldM, forM, when, zipWithM)
+import Data.IORef (IORef, atomicModifyIORef', newIORef, readIORef, writeIORef)
+import qualified Data.IntMap.Strict as IntMap
 import qualified Data.Text as Text
-import Database.DuckDB.FFI
+import Database.DuckDB.Simple.Conversion (runConversion)
+import Database.DuckDB.Simple.Element (withVectorType)
 import Database.DuckDB.Simple.FromField (Field (..), FieldValue)
 import Database.DuckDB.Simple.FromRow (RowParser, parseRow, rowErrorsToSqlError)
 import Database.DuckDB.Simple.Internal
-import Database.DuckDB.Simple.Materialize (prepareVectorReader)
+import Database.DuckDB.Simple.Materialize (
+  FallbackReaders (..),
+  ReadFactory (..),
+  prepareGeometryReader,
+  prepareVectorReaderWith,
+ )
 import Database.DuckDB.Simple.Ok (Ok (..))
-import Foreign.Marshal.Alloc (free, malloc)
-import Foreign.Marshal.Utils (fillBytes)
-import Foreign.Ptr (Ptr, nullPtr)
-import Foreign.Storable (sizeOf)
+import Database.DuckDB.Simple.TypeScope (TypeScope, closeTypeScope, newTypeScope, scopedTypeRep)
+import Database.DuckDB.Simple.V2.LogicalRep (logicalTypeToRep)
+import Foreign.Marshal.Alloc (alloca)
+import Foreign.Storable (peek)
 
--- | Fold rows from one statement and release its result on every exit path.
+-- | Fold rows from a statement owned by the enclosing @withStatement@.
 foldStatementWith :: ResultMode -> RowParser row -> Statement -> a -> (a -> row -> IO a) -> IO a
-foldStatementWith mode parser stmt initial step =
-    let loop acc = do
-            nextVal <- nextRowWith mode parser stmt
-            case nextVal of
-                Nothing -> pure acc
-                Just row -> do
-                    acc' <- step acc row
-                    acc' `seq` loop acc'
-     in loop initial `finally` resetStatementStream stmt
+foldStatementWith mode parser stmt initial step = loop initial
+  where
+    loop acc =
+      nextRowWith mode parser stmt >>= \case
+        Nothing -> pure acc
+        Just row -> do
+          acc' <- step acc row
+          acc' `seq` loop acc'
 
 -- | Read one row. The first fetch selects execution until the cursor resets.
+-- See Note [Statement cursor] in "Database.DuckDB.Simple.Internal".
 nextRowWith :: ResultMode -> RowParser r -> Statement -> IO (Maybe r)
 nextRowWith mode parser stmt@Statement{statementStream} =
-    withStatementHandle stmt \_ -> mask \restore -> do
-        state <- readIORef statementStream
-        case state of
-            StatementStreamExhausted -> pure Nothing
-            StatementStreamIdle -> do
-                newStream <- startStatementStream mode stmt
-                case newStream of
-                    Nothing -> writeIORef statementStream StatementStreamExhausted >> pure Nothing
-                    Just stream -> do
-                        writeIORef statementStream (StatementStreamActive stream)
-                        restore (consumeStream statementStream parser stmt stream)
-                            `onException` exhaustStatementStream statementStream
-            StatementStreamActive stream ->
-                restore (consumeStream statementStream parser stmt stream)
-                    `onException` exhaustStatementStream statementStream
+  withStatementHandle stmt \_ -> mask \restore -> do
+    let consume stream =
+          restore (consumeStream statementStream parser stmt stream)
+            `onException` exhaustStatementStream statementStream (statementStreamTypes stream)
+    state <- readIORef statementStream
+    case state of
+      StatementStreamExhausted -> pure Nothing
+      StatementStreamIdle -> do
+        newStream <- startStatementStream mode stmt
+        case newStream of
+          Nothing -> writeIORef statementStream StatementStreamExhausted >> pure Nothing
+          Just stream -> do
+            writeIORef statementStream (StatementStreamActive stream)
+            consume stream
+      StatementStreamActive stream -> consume stream
 
--- | Release an active cursor and allow the statement to execute again.
+-- | Release an active cursor and allow the statement to execute again. Then
+-- clear the schema cache of the statement. See Note [Statement schemas] in
+-- "Database.DuckDB.Simple.Internal".
 resetStatementStream :: Statement -> IO ()
-resetStatementStream Statement{statementStream} =
-    cleanupStatementStreamRef statementStream
+resetStatementStream stmt@Statement{statementStream} =
+  cleanupStatementStreamRef statementStream `finally` clearStatementSchemas stmt
 
 consumeStream :: IORef StatementStreamState -> RowParser r -> Statement -> StatementStream -> IO (Maybe r)
 consumeStream streamRef parser stmt stream = mask \restore -> do
-    loaded <- case statementStreamChunk stream of
-        Nothing -> fetchChunk (statementConnection stmt) (statementQuery stmt) stream
-        Just _ -> pure stream
-    writeIORef streamRef (StatementStreamActive loaded)
-    case statementStreamChunk loaded of
-        Nothing -> exhaustStatementStream streamRef >> pure Nothing
-        Just chunk -> do
-            fields <- restore $ buildMaterializedRow (statementStreamColumns loaded) (statementStreamChunkReaders chunk) (statementStreamChunkIndex chunk)
-            parsed <- restore (evaluate (parseRow parser fields))
-            case parsed of
-                Errors rowErr -> throwIO $ rowErrorsToSqlError (statementQuery stmt) rowErr
-                Ok value -> do
-                    let nextIndex = statementStreamChunkIndex chunk + 1
-                    if nextIndex < statementStreamChunkSize chunk
-                        then writeIORef streamRef (StatementStreamActive loaded{statementStreamChunk = Just chunk{statementStreamChunkIndex = nextIndex}})
-                        else do
-                            writeIORef streamRef (StatementStreamActive loaded{statementStreamChunk = Nothing})
-                            finalizeChunk chunk
-                    pure (Just value)
+  loaded <- case statementStreamChunk stream of
+    Nothing -> restore (fetchChunk streamRef (statementConnection stmt) (statementQuery stmt) stream)
+    Just _ -> pure stream
+  writeIORef streamRef (StatementStreamActive loaded)
+  case statementStreamChunk loaded of
+    Nothing -> exhaustStatementStream streamRef (statementStreamTypes loaded) >> pure Nothing
+    Just chunk -> do
+      fields <-
+        restore $ buildMaterializedRow (statementStreamColumns loaded) (statementStreamChunkReaders chunk) (statementStreamChunkIndex chunk)
+      let nextIndex = statementStreamChunkIndex chunk + 1
+      if nextIndex < statementStreamChunkSize chunk
+        then writeIORef streamRef (StatementStreamActive loaded{statementStreamChunk = Just chunk{statementStreamChunkIndex = nextIndex}})
+        else do
+          writeIORef streamRef (StatementStreamActive loaded{statementStreamChunk = Nothing})
+          finalizeChunk chunk
+      restore (runConversion (parseRow parser fields)) >>= \case
+        Errors rowErr -> throwIO $ rowErrorsToSqlError (statementQuery stmt) rowErr
+        Ok value -> pure (Just value)
 
--- | Release the cursor and retain its exhausted state until an explicit reset.
-exhaustStatementStream :: IORef StatementStreamState -> IO ()
-exhaustStatementStream ref = mask_ do
-    state <- atomicModifyIORef' ref (StatementStreamExhausted,)
-    finalizeStreamState state
+-- | Release the cursor only if it still belongs to this execution.
+-- See Note [Statement cursor] in "Database.DuckDB.Simple.Internal".
+exhaustStatementStream :: IORef StatementStreamState -> TypeScope -> IO ()
+exhaustStatementStream ref types = mask_ do
+  owned <- atomicModifyIORef' ref \case
+    StatementStreamActive stream | statementStreamTypes stream == types -> (StatementStreamExhausted, Just stream)
+    state -> (state, Nothing)
+  mapM_ finalizeStream owned
 
 startStatementStream :: ResultMode -> Statement -> IO (Maybe StatementStream)
-startStatementStream mode stmt =
-    withStatementHandle stmt \handle -> do
-        resultPtr <- malloc
-        fillBytes resultPtr 0 (sizeOf (undefined :: DuckDBResult))
-        let release = c_duckdb_destroy_result resultPtr `finally` free resultPtr
-        flip onException release do
-            rc <- runInterruptibleQuery (statementConnection stmt) (executePreparedResult mode handle resultPtr)
-            when (rc /= DuckDBSuccess) do
-                (errMsg, errType) <- fetchResultError resultPtr
-                throwIO $ mkExecuteError (statementQuery stmt) errMsg errType
-            resultType <- c_duckdb_result_return_type resultPtr
-            if resultType /= DuckDBResultTypeQueryResult
-                then release >> pure Nothing
-                else do
-                    columns <- collectResultColumns resultPtr
-                    pure (Just (StatementStream resultPtr columns Nothing mode))
+startStatementStream mode stmt = withQueryError (statementQuery stmt) . withResultWindow (statementConnection stmt) (mapM_ finalizeStream) $ mask_ do
+  -- A materialized result closes here. A stream stays open after the lock is released.
+  -- See Note [Result window] in "Database.DuckDB.Simple.Internal".
+  result <- executePreparedResult stmt
+  startResultStream mode (statementConnection stmt) result
 
-fetchChunk :: Connection -> Query -> StatementStream -> IO StatementStream
-fetchChunk conn queryText stream@StatementStream{statementStreamResult} = do
-    chunk <- fetchResultChunk (statementStreamMode stream) conn statementStreamResult
-    if chunk == nullPtr
+-- | Take ownership of a cursor and retain its chunks in the selected mode.
+-- A changed-row result gives its row with the count, as a query result gives its rows.
+startResultStream :: ResultMode -> Connection -> DuckDBV2ResultHandle -> IO (Maybe StatementStream)
+startResultStream mode conn result = mask_ do
+  (owned, cursor, types) <-
+    ((,,) <$> newIORef [] <*> newIORef result <*> newTypeScope)
+      `onException` destroy c_duckdb_v2_result_destroy result
+  -- Take each handle out before its release, so that a second call releases no handle again.
+  let destroyResult = atomicModifyIORef' cursor (nullHandle,) >>= destroy c_duckdb_v2_result_destroy
+      release = closeTypeScope types `finally` ((atomicModifyIORef' owned ([],) >>= releaseItems destroyDataChunk) `finally` destroyResult)
+      fetch = fetchResultChunk conn result
+      gather = do
+        chunk <- fetch
+        when (chunk /= nullHandle) do
+          atomicModifyIORef' owned (\chunks -> (chunk : chunks, ()))
+          gather
+  flip onException release do
+    -- Expanded statements expose metadata after the first native fetch.
+    first <- fetch
+    when (first /= nullHandle) $
+      atomicModifyIORef' owned (\chunks -> (first : chunks, ()))
+    resultType <- output (c_duckdb_v2_result_get_result_type result)
+    if resultType /= DuckDBV2ResultTypeQueryResult && resultType /= DuckDBV2ResultTypeChangedRows
+      then do
+        _ <- runInterruptibleQuery conn (output (c_duckdb_v2_result_drain result))
+        release
+        pure Nothing
+      else do
+        columns <- collectResultColumns types (withConnectionHandle conn \_ -> instanceCastFactory (connectionInstance conn)) result
+        case mode of
+          MaterializedResult -> do
+            gather
+            chunks <- reverse <$> readIORef owned
+            destroyResult
+            pure (Just (StatementStream nullHandle types columns chunks Nothing))
+          StreamingResult -> do
+            chunks <- reverse <$> readIORef owned
+            pure (Just (StatementStream result types columns chunks Nothing))
+
+fetchChunk :: IORef StatementStreamState -> Connection -> Query -> StatementStream -> IO StatementStream
+fetchChunk ref conn queryText stream = withQueryError queryText $ mask \restore -> do
+  (chunk, remaining) <- case statementStreamPendingChunks stream of
+    next : rest -> pure (next, rest)
+    [] | statementStreamResult stream == nullHandle -> pure (nullHandle, [])
+    -- The fetch of an explicit stream holds the connection lock. This call is
+    -- not in the result window, so this thread does not hold the lock here.
+    -- See Note [Connection lock] in "Database.DuckDB.Simple.Internal".
+    [] -> (,[]) <$> withConnectionLock conn (fetchResultChunk conn (statementStreamResult stream))
+  let nextStream = stream{statementStreamPendingChunks = remaining}
+  if chunk == nullHandle
+    then pure nextStream
+    else do
+      -- Transfer ownership before native metadata or reader setup can fail.
+      -- See Note [Statement cursor] in "Database.DuckDB.Simple.Internal".
+      let owned = nextStream{statementStreamChunk = Just (StatementStreamChunk chunk 0 0 [])}
+      writeIORef ref (StatementStreamActive owned)
+      rowCount <- fromIntegral <$> output (c_duckdb_v2_data_chunk_get_size chunk)
+      if rowCount <= 0
         then do
-            throwResultError queryText statementStreamResult
-            pure stream
+          writeIORef ref (StatementStreamActive nextStream)
+          destroyDataChunk chunk
+          restore (fetchChunk ref conn queryText nextStream)
         else do
-            rawSize <- c_duckdb_data_chunk_get_size chunk
-            let rowCount = fromIntegral rawSize :: Int
-            if rowCount <= 0
-                then do
-                    destroyDataChunk chunk
-                    fetchChunk conn queryText stream
-                else do
-                    readers <-
-                        prepareChunkReaders chunk (statementStreamColumns stream)
-                            `onException` destroyDataChunk chunk
-                    let chunkState =
-                            StatementStreamChunk
-                                { statementStreamChunkPtr = chunk
-                                , statementStreamChunkSize = rowCount
-                                , statementStreamChunkIndex = 0
-                                , statementStreamChunkReaders = readers
-                                }
-                    pure stream{statementStreamChunk = Just chunkState}
-
--- | Prepare one reader for each column. The readers must not outlive the chunk.
-prepareChunkReaders :: DuckDBDataChunk -> [StatementStreamColumn] -> IO [Int -> IO FieldValue]
-prepareChunkReaders chunk columns =
-    forM columns \StatementStreamColumn{statementStreamColumnIndex} ->
-        c_duckdb_data_chunk_get_vector chunk (fromIntegral statementStreamColumnIndex) >>= prepareVectorReader
-
--- | Clear cursor ownership before releasing native resources.
-cleanupStatementStreamRef :: IORef StatementStreamState -> IO ()
-cleanupStatementStreamRef ref = mask_ do
-    state <- atomicModifyIORef' ref (StatementStreamIdle,)
-    finalizeStreamState state
-
-finalizeStreamState :: StatementStreamState -> IO ()
-finalizeStreamState = \case
-    StatementStreamIdle -> pure ()
-    StatementStreamExhausted -> pure ()
-    StatementStreamActive stream -> finalizeStream stream
+          readers <- restore (prepareChunkReaders conn chunk (statementStreamColumns stream))
+          pure nextStream{statementStreamChunk = Just (StatementStreamChunk chunk rowCount 0 readers)}
 
-finalizeStream :: StatementStream -> IO ()
-finalizeStream StatementStream{statementStreamResult, statementStreamChunk} = do
-    maybe (pure ()) finalizeChunk statementStreamChunk
-    c_duckdb_destroy_result statementStreamResult
-    free statementStreamResult
+-- | Prepare readers that borrow the vectors in an owned chunk. A reader takes
+-- each layout parameter from its vector type and each description from the
+-- column's type tree. The reader builds the tree on its first use, from the
+-- current vector type. The tree lives for one execution. The readers do not
+-- use the result schema. See Note [Type trees] in
+-- "Database.DuckDB.Simple.Materialize".
+prepareChunkReaders :: Connection -> DuckDBV2DataChunkHandle -> [StatementStreamColumn] -> IO [Int -> IO FieldValue]
+prepareChunkReaders conn chunk columns = do
+  casts <- instanceCastFactory (connectionInstance conn)
+  -- See Note [VARIANT decoding] in "Database.DuckDB.Simple.VariantCodec" and
+  -- Note [User casts and the casts of the library] in
+  -- "Database.DuckDB.Simple.Materialize".
+  let readType = logicalTypeToRep casts
+      readers = FallbackReaders readType (readConnectionVariant conn) (prepareGeometryReader (InstanceFactory casts))
+  forM columns \StatementStreamColumn{statementStreamColumnIndex, statementStreamColumnTree, statementStreamColumnLabels} -> do
+    vector <- output (c_duckdb_v2_data_chunk_get_vector chunk (fromIntegral statementStreamColumnIndex))
+    let tree =
+          readIORef statementStreamColumnTree >>= \case
+            Just rep -> pure rep
+            Nothing -> do
+              -- See Note [Type aliases] in "Database.DuckDB.Simple.LogicalRep".
+              rep <- withVectorType vector readType
+              writeIORef statementStreamColumnTree (Just rep)
+              pure rep
+    prepareVectorReaderWith readers tree (Just statementStreamColumnLabels) vector
 
-finalizeChunk :: StatementStreamChunk -> IO ()
-finalizeChunk StatementStreamChunk{statementStreamChunkPtr} =
-    destroyDataChunk statementStreamChunkPtr
+-- | Materialize all rows, then run the decoder while column metadata is live.
+withRows :: Statement -> ([[Field]] -> IO a) -> IO a
+withRows stmt = withStreamRows (statementConnection stmt) (statementQuery stmt) (startStatementStream MaterializedResult stmt)
 
--- | Copy all rows from a materialized native result.
-collectRows :: Query -> Ptr DuckDBResult -> IO [[Field]]
-collectRows queryText resPtr = do
-    columns <- collectResultColumns resPtr
-    collectChunks columns []
+-- | Execute a parsed statement directly and materialize its owned native chunks.
+-- See Note [Result window] in "Database.DuckDB.Simple.Internal".
+withParsedRows :: Connection -> Query -> DuckDBV2SqlStatementHandle -> ([[Field]] -> IO a) -> IO a
+withParsedRows conn query parsed = withStreamRows conn query acquire
   where
-    collectChunks columns acc = do
-        fetched <- bracket (c_duckdb_fetch_chunk resPtr) destroyDataChunk \chunk ->
-            if chunk == nullPtr
-                then throwResultError queryText resPtr >> pure Nothing
-                else Just <$> decodeChunk columns chunk
-        case fetched of
-            Nothing -> pure (concat (reverse acc))
-            Just rows -> do
-                let acc' = maybe acc (: acc) rows
-                collectChunks columns acc'
+    acquire = withResultWindow conn (mapM_ finalizeStream) $ mask_ do
+      result <- executeParsedResult conn query parsed
+      startResultStream MaterializedResult conn result
 
-    decodeChunk columns chunk = do
-        rawSize <- c_duckdb_data_chunk_get_size chunk
-        let rowCount = fromIntegral rawSize :: Int
-        if rowCount <= 0
-            then pure Nothing
-            else
-                if null columns
-                    then pure (Just (replicate rowCount []))
-                    else do
-                        readers <- prepareChunkReaders chunk columns
-                        rows <- mapM (buildMaterializedRow columns readers) [0 .. rowCount - 1]
-                        pure (Just rows)
+-- | Copy rows from owned chunks, then run the decoder before metadata closes.
+-- Destroy each chunk after its values are copied.
+withStreamRows :: Connection -> Query -> IO (Maybe StatementStream) -> ([[Field]] -> IO a) -> IO a
+withStreamRows conn query acquire decode = withQueryError query $
+  bracket (acquire >>= traverse adopt) (mapM_ release) \case
+    Nothing -> decode []
+    Just (owned, pending) -> do
+      -- Both loops keep a constant stack. See
+      -- Note [Constant stack at safe calls] in "Database.DuckDB.Simple.Native".
+      --
+      -- The chunk loop must keep a constant stack, because the code for
+      -- each chunk makes native calls.
+      --
+      -- The reference holds the chunks that the fold has not reached, in
+      -- the order of the fold. Each step takes its chunk out of the
+      -- reference and destroys that chunk after its rows. The bracket of
+      -- the step thus owns the chunk while its rows are decoded, and the
+      -- release of this function destroys only the chunks in the reference.
+      let readChunk done expected = bracket (takeChunk pending expected) destroyDataChunk \chunk -> do
+            rowCount <- fromIntegral <$> output (c_duckdb_v2_data_chunk_get_size chunk)
+            readers <- prepareChunkReaders conn chunk (statementStreamColumns owned)
+            -- The row loop reads the rows from the last to the first, and
+            -- puts each row in front of the list. The list then needs no
+            -- reverse. The constant stack of this loop is necessary for a
+            -- reader that makes a native call for each row: a BIGNUM
+            -- column, and the first use of a UNION member.
+            let readFrom row decoded
+                  | row < 0 = pure decoded
+                  | otherwise = buildMaterializedRow (statementStreamColumns owned) readers row >>= \fields -> readFrom (row - 1) (fields : decoded)
+            (: done) <$> readFrom (rowCount - 1) []
+      -- The fold prepends each decoded chunk. Reverse that list after the fold.
+      rows <- foldM readChunk [] (statementStreamPendingChunks owned)
+      decode (concat (reverse rows))
+  where
+    adopt stream =
+      ((,) stream <$> newIORef (statementStreamPendingChunks stream))
+        `onException` finalizeStream stream
+    release (stream, pending) = do
+      remaining <- atomicModifyIORef' pending ([],)
+      finalizeStream stream{statementStreamPendingChunks = remaining}
+    -- Take the first chunk out of the reference. It must be the chunk of the
+    -- fold step. Otherwise leave the reference as it is, so that the release
+    -- destroys each chunk in it.
+    takeChunk pending expected =
+      atomicModifyIORef' pending (\case chunk : rest | chunk == expected -> (rest, Just chunk); chunks -> (chunks, Nothing))
+        >>= maybe (throwInternalError (Text.pack "internal error: the owned chunks do not match the chunk fold")) pure
 
-collectResultColumns :: Ptr DuckDBResult -> IO [StatementStreamColumn]
-collectResultColumns resPtr = do
-    rawCount <- c_duckdb_column_count resPtr
-    let cc = fromIntegral rawCount :: Int
-    forM [0 .. cc - 1] \columnIndex -> do
-        namePtr <- c_duckdb_column_name resPtr (fromIntegral columnIndex)
-        name <-
-            if namePtr == nullPtr
-                then pure (Text.pack ("column" <> show columnIndex))
-                else peekUtf8CString namePtr
-        dtype <- c_duckdb_column_type resPtr (fromIntegral columnIndex)
-        pure
-            StatementStreamColumn
-                { statementStreamColumnIndex = columnIndex
-                , statementStreamColumnName = name
-                , statementStreamColumnType = dtype
-                }
+collectResultColumns :: TypeScope -> IO DuckDBV2FactoryHandle -> DuckDBV2ResultHandle -> IO [StatementStreamColumn]
+collectResultColumns types acquireFactory result =
+  bracket (output (c_duckdb_v2_result_get_schema result)) (destroy c_duckdb_v2_schema_destroy) \schema -> do
+    count <- fromIntegral <$> output (c_duckdb_v2_schema_get_count schema)
+    forM [0 .. count - 1] \idx -> alloca \name -> do
+      borrowed <- output (c_duckdb_v2_schema_get_field schema (fromIntegral idx) name)
+      columnName <- peek name >>= readIdentifier
+      -- The result scope owns the copied type. The schema closes after this loop.
+      columnType <- scopedTypeRep types acquireFactory (output (c_duckdb_v2_logical_type_copy borrowed))
+      StatementStreamColumn idx columnName columnType <$> newIORef Nothing <*> newIORef IntMap.empty
 
 buildMaterializedRow :: [StatementStreamColumn] -> [Int -> IO FieldValue] -> Int -> IO [Field]
 buildMaterializedRow columns readers rowIdx =
-    zipWithM (buildMaterializedField rowIdx) columns readers
+  zipWithM (buildMaterializedField rowIdx) columns readers
 
 buildMaterializedField :: Int -> StatementStreamColumn -> (Int -> IO FieldValue) -> IO Field
 buildMaterializedField rowIdx column readValue = do
-    value <- readValue rowIdx
-    pure
-        Field
-            { fieldName = statementStreamColumnName column
-            , fieldIndex = statementStreamColumnIndex column
-            , fieldValue = value
-            }
+  value <- readValue rowIdx
+  pure
+    Field
+      { fieldName = statementStreamColumnName column
+      , fieldIndex = statementStreamColumnIndex column
+      , fieldValue = value
+      , fieldType = statementStreamColumnType column
+      }
diff --git a/src/Database/DuckDB/Simple/Streaming.hs b/src/Database/DuckDB/Simple/Streaming.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/Streaming.hs
@@ -0,0 +1,91 @@
+{-# LANGUAGE BlockArguments #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.Streaming
+-- Description : Optional streaming through the native V2 execution API.
+--
+-- Import this module qualified to request native streaming. Operators such as
+-- sorting can buffer data. Streaming reduces result storage when the query
+-- supports it. It does not bound query memory. The default
+-- "Database.DuckDB.Simple" API materializes native results.
+--
+-- Rows and Arrow batches use the same decoders and cleanup as the default API.
+-- Cancellation also interrupts native chunk fetching. Prompt interruption requires
+-- @-threaded@ and waits for native code and Haskell callbacks to return. A
+-- program that registers a callback needs @-threaded@ in each case: see
+-- "Database.DuckDB.Simple.Function".
+--
+-- Serialize connection use for the entire cursor or fold. Another query on the
+-- same connection fails while its stream is active. Call
+-- 'Database.DuckDB.Simple.closeStatement' or
+-- 'Database.DuckDB.Simple.clearStatementBindings' on an abandoned statement to
+-- release its result.
+module Database.DuckDB.Simple.Streaming (
+  fold,
+  fold_,
+  foldNamed,
+  nextRow,
+  nextRowWith,
+  foldArrow,
+  foldArrow_,
+) where
+
+import Database.DuckDB.FFI.V2 (ArrowArray, ArrowSchema)
+import Database.DuckDB.Simple (bind, bindNamed, withStatement)
+import qualified Database.DuckDB.Simple.Arrow.Internal as Arrow
+import Database.DuckDB.Simple.FromRow (FromRow (..), RowParser)
+import Database.DuckDB.Simple.Internal (Connection, Query, ResultMode (StreamingResult), Statement)
+import qualified Database.DuckDB.Simple.Result as Result
+import Database.DuckDB.Simple.ToField (NamedParam)
+import Database.DuckDB.Simple.ToRow (ToRow (..))
+import Foreign.Ptr (Ptr)
+
+-- | Fold a parameterized query, requesting native streaming.
+fold :: (FromRow row, ToRow params) => Connection -> Query -> params -> a -> (a -> row -> IO a) -> IO a
+fold conn sql params initial step =
+  withStatement conn sql \stmt -> do
+    bind stmt (toRow params)
+    Result.foldStatementWith StreamingResult fromRow stmt initial step
+
+-- | Fold a query without parameters, requesting native streaming.
+fold_ :: (FromRow row) => Connection -> Query -> a -> (a -> row -> IO a) -> IO a
+fold_ conn sql initial step =
+  withStatement conn sql \stmt ->
+    Result.foldStatementWith StreamingResult fromRow stmt initial step
+
+-- | Fold a query with named parameters, requesting native streaming.
+foldNamed :: (FromRow row) => Connection -> Query -> [NamedParam] -> a -> (a -> row -> IO a) -> IO a
+foldNamed conn sql params initial step =
+  withStatement conn sql \stmt -> do
+    bindNamed stmt params
+    Result.foldStatementWith StreamingResult fromRow stmt initial step
+
+-- | Fetch the next row, requesting native streaming on the first fetch.
+nextRow :: (FromRow r) => Statement -> IO (Maybe r)
+nextRow = nextRowWith fromRow
+
+-- | Fetch a row with a custom parser, requesting streaming on the first fetch.
+--   The active result retains its execution mode until
+--   'Database.DuckDB.Simple.bind', 'Database.DuckDB.Simple.bindNamed',
+--   'Database.DuckDB.Simple.clearStatementBindings', or
+--   'Database.DuckDB.Simple.executeStatement' releases it. Switching between this
+--   module and 'Database.DuckDB.Simple.nextRow' does not restart or change an
+--   active result.
+--   After EOF, this function returns 'Nothing' until one of those functions runs.
+nextRowWith :: RowParser r -> Statement -> IO (Maybe r)
+nextRowWith = Result.nextRowWith StreamingResult
+
+-- | Fold Arrow batches, requesting native streaming.
+--   Each batch has a separate schema and array. The callback may read, release,
+--   or move them under the Arrow C Data Interface. The pointers themselves are
+--   valid during the callback only. See "Database.DuckDB.Simple.Arrow" for the
+--   ownership rules.
+--   Query execution and Arrow export use the native V2 API.
+--   The fold releases contents that the consumer has not
+--   released or moved. The consumer owns any moved contents.
+foldArrow :: (ToRow params) => Connection -> Query -> params -> a -> (a -> Ptr ArrowSchema -> Ptr ArrowArray -> IO a) -> IO a
+foldArrow = Arrow.foldArrowWith StreamingResult
+
+-- | Fold Arrow batches from a query without parameters.
+foldArrow_ :: Connection -> Query -> a -> (a -> Ptr ArrowSchema -> Ptr ArrowArray -> IO a) -> IO a
+foldArrow_ conn sql = foldArrow conn sql ()
diff --git a/src/Database/DuckDB/Simple/Time.hs b/src/Database/DuckDB/Simple/Time.hs
--- a/src/Database/DuckDB/Simple/Time.hs
+++ b/src/Database/DuckDB/Simple/Time.hs
@@ -1,21 +1,24 @@
 {-# LANGUAGE DeriveFunctor #-}
+{-# LANGUAGE StrictData #-}
 
--- | Dates and timestamps that can represent DuckDB's infinities.
+-- |
+-- Module      : Database.DuckDB.Simple.Time
+-- Description : Dates and timestamps that can represent DuckDB's infinities.
 module Database.DuckDB.Simple.Time (
-    Unbounded (..),
-    Date,
-    LocalTimestamp,
-    UTCTimestamp,
+  Unbounded (..),
+  Date,
+  LocalTimestamp,
+  UTCTimestamp,
 ) where
 
 import Data.Time (Day, LocalTime, UTCTime)
 
 -- | A finite value or either infinity, as in @postgresql-simple@.
 data Unbounded a
-    = NegInfinity
-    | Finite !a
-    | PosInfinity
-    deriving (Eq, Ord, Show, Read, Functor)
+  = NegInfinity
+  | Finite a
+  | PosInfinity
+  deriving (Eq, Ord, Show, Read, Functor)
 
 -- | A DuckDB DATE, including infinity.
 type Date = Unbounded Day
diff --git a/src/Database/DuckDB/Simple/ToField.hs b/src/Database/DuckDB/Simple/ToField.hs
--- a/src/Database/DuckDB/Simple/ToField.hs
+++ b/src/Database/DuckDB/Simple/ToField.hs
@@ -2,1009 +2,2308 @@
 {-# LANGUAGE DefaultSignatures #-}
 {-# LANGUAGE FlexibleInstances #-}
 {-# LANGUAGE GADTs #-}
-{-# LANGUAGE NamedFieldPuns #-}
-{-# LANGUAGE OverloadedStrings #-}
-{-# LANGUAGE ScopedTypeVariables #-}
-
-{- |
-Module      : Database.DuckDB.Simple.ToField
-Description : Convert Haskell parameters into DuckDB bindable values.
-
-The @ToField@ class mirrors the interface provided by @sqlite-simple@ while
-delegating to the DuckDB C API under the hood.
--}
-module Database.DuckDB.Simple.ToField (
-    FieldBinding,
-    ToDuckValue (..),
-    ToField (..),
-    DuckDBColumnType (..),
-    NamedParam (..),
-    duckdbColumnType,
-    bindFieldBinding,
-    renderFieldBinding,
-) where
-
-import Control.Exception (bracket, throwIO)
-import Control.Monad (filterM, forM_, when)
-import Data.Array (Array, elems)
-import Data.Bits (complement, shiftL, shiftR, (.&.), (.|.))
-import qualified Data.ByteString as BS
-import Data.Fixed (Pico)
-import qualified Data.Geometry as G
-import qualified Data.Geometry.WKT as WKT
-import Data.Int (Int16, Int32, Int64, Int8)
-import qualified Data.List as List
-import Data.Proxy (Proxy (..))
-import Data.Text (Text)
-import qualified Data.Text as Text
-import qualified Data.Text.Encoding as TextEncoding
-import Data.Time.Calendar (Day, diffDays, fromGregorian)
-import Data.Time.Clock (UTCTime (..), diffTimeToPicoseconds)
-import Data.Time.LocalTime (LocalTime (..), TimeOfDay (..), TimeZone (..), timeOfDayToTime, timeZoneMinutes, utc, utcToLocalTime)
-import qualified Data.UUID as UUID
-import Data.Word (Word16, Word32, Word64, Word8)
-import Database.DuckDB.FFI
-import Database.DuckDB.Simple.FromField (BigNum (..), BitString (..), DecimalValue (..), FieldValue (..), IntervalValue (..), TimeWithZone (..), toBigNumBytes)
-import Database.DuckDB.Simple.Internal (
-    SQLError (..),
-    Statement (..),
-    destroyValue,
-    duckDBTypeFromName,
-    fetchPrepareError,
-    withStatementHandle,
-    withTypeCache,
- )
-import Database.DuckDB.Simple.LogicalRep (
-    LogicalTypeRep (..),
-    StructField (..),
-    StructValue (..),
-    UnionMemberType (..),
-    UnionValue (..),
-    destroyLogicalType,
-    logicalTypeFromRep,
-    logicalTypeFromRepWith,
-    logicalTypeToRep,
-    structValueTypeRep,
-    unionValueTypeRep,
- )
-import Database.DuckDB.Simple.Time (Date, LocalTimestamp, UTCTimestamp, Unbounded (..))
-import Database.DuckDB.Simple.TypeCache (TypeCache, cachedLogicalType)
-import Database.DuckDB.Simple.Types (Null (..))
-import Database.DuckDB.Simple.Variant (Variant (..))
-import Foreign.C.Types (CDouble (..), CFloat (..))
-import Foreign.Marshal (fromBool)
-import Foreign.Marshal.Alloc (alloca)
-import Foreign.Marshal.Array (withArray)
-import Foreign.Marshal.Utils (withMany)
-import Foreign.Ptr (Ptr, castPtr, nullPtr)
-import Foreign.Storable (poke)
-import Numeric.Natural (Natural)
-
--- | Represents a named parameter binding using the @:=@ operator.
-data NamedParam where
-    (:=) :: (ToField a) => Text -> a -> NamedParam
-
-infixr 3 :=
-
--- | Encapsulates the action required to bind a single positional parameter, together with a textual description used in diagnostics.
-data FieldBinding = FieldBinding
-    { fieldBindingValue :: !(TypeCache -> IO DuckDBValue)
-    , fieldBindingDisplay :: !String
-    }
-
--- | Low-level class for values that can be marshalled directly into `DuckDBValue`s.
-class (DuckDBColumnType a) => ToDuckValue a where
-    -- | Convert a Haskell value into an owned DuckDB boxed value.
-    toDuckValue :: a -> IO DuckDBValue
-
-valueBinding :: String -> IO DuckDBValue -> FieldBinding
-valueBinding display = cacheValueBinding display . const
-
--- | Construct a value with the type cache of the statement's connection.
-cacheValueBinding :: String -> (TypeCache -> IO DuckDBValue) -> FieldBinding
-cacheValueBinding display makeValue =
-    FieldBinding
-        { fieldBindingValue = makeValue
-        , fieldBindingDisplay = display
-        }
-
--- | Build types with the cached types for VARIANT and GEOMETRY with a CRS.
-cachedTypeFromRep :: TypeCache -> LogicalTypeRep -> IO DuckDBLogicalType
-cachedTypeFromRep = logicalTypeFromRepWith . cachedLogicalType
-
--- | Types that map to a concrete DuckDB column type when used with @ToField@.
-class DuckDBColumnType a where
-    duckdbColumnTypeFor :: Proxy a -> Text
-
--- | Report the DuckDB column type that best matches a given @ToField@ instance.
-duckdbColumnType :: forall a. (DuckDBColumnType a) => Proxy a -> Text
-duckdbColumnType = duckdbColumnTypeFor
-
--- | Apply a @FieldBinding@ to the given statement/index.
-bindFieldBinding :: Statement -> DuckDBIdx -> FieldBinding -> IO ()
-bindFieldBinding stmt idx FieldBinding{fieldBindingValue} =
-    withTypeCache (statementConnection stmt) \cache ->
-        bindDuckValue stmt idx (fieldBindingValue cache)
-
--- | Render a bound parameter for error reporting.
-renderFieldBinding :: FieldBinding -> String
-renderFieldBinding FieldBinding{fieldBindingDisplay} = fieldBindingDisplay
-
--- | Types that can be used as positional parameters.
-class ToField a where
-    toField :: a -> FieldBinding
-    default toField :: (Show a, ToDuckValue a) => a -> FieldBinding
-    toField value = valueBinding (show value) (toDuckValue value)
-
-instance ToField Null where
-    toField Null = nullBinding "NULL"
-
-instance ToField Bool
-instance ToField Int
-instance ToField Int8
-instance ToField Int16
-instance ToField Int32
-instance ToField Int64
-instance ToField Integer
-instance ToField Natural
-instance ToField UUID.UUID
-instance ToField Word
-instance ToField Word8
-instance ToField Word16
-instance ToField Word32
-instance ToField Word64
-instance ToField Double
-instance ToField Float
-instance ToField Text
-instance ToField String
-instance ToField BitString
-instance ToField Day
-instance ToField TimeOfDay
-instance ToField LocalTime
-
--- | Bind the shape as @GEOMETRY@ with no CRS.
-instance ToField G.Geometry
-
--- | Bind the payload as a VARIANT with the type cache of the connection.
-instance ToField Variant where
-    toField value =
-        cacheValueBinding (show value) \cache ->
-            variantDuckValue (cachedTypeFromRep cache) (variantPayload value)
-
-instance ToField UTCTime
-instance ToField (Unbounded Day)
-instance ToField (Unbounded LocalTime)
-instance ToField (Unbounded UTCTime)
-
-instance ToField BigNum where
-    toField big@(BigNum n) = valueBinding (show n) (bigNumDuckValue big)
-
-instance ToField (StructValue FieldValue) where
-    toField structVal =
-        cacheValueBinding "<struct>" \cache ->
-            structValueDuckValue (cachedTypeFromRep cache) structVal
-
-instance ToField (UnionValue FieldValue) where
-    toField unionVal =
-        let label = Text.unpack (unionValueLabel unionVal)
-         in cacheValueBinding ("<union " <> label <> ">") \cache ->
-                unionValueDuckValue (cachedTypeFromRep cache) unionVal
-
-instance DuckDBColumnType BitString where
-    duckdbColumnTypeFor _ = "BIT"
-
-instance ToField BS.ByteString where
-    toField bs =
-        valueBinding
-            ("<blob length=" <> show (BS.length bs) <> ">")
-            (toDuckValue bs)
-
-instance (DuckDBColumnType a, ToField a) => ToField (Array Int a) where
-    toField arr =
-        cacheValueBinding
-            ("<array length=" <> show (length (elems arr)) <> ">")
-            \cache -> arrayDuckValue (cachedTypeFromRep cache) (\value -> fieldBindingValue (toField value) cache) arr
-
-instance (ToField a) => ToField (Maybe a) where
-    toField Nothing = nullBinding "Nothing"
-    toField (Just value) =
-        let binding = toField value
-         in binding
-                { fieldBindingDisplay = "Just " <> renderFieldBinding binding
-                }
-
-instance DuckDBColumnType G.Geometry where
-    duckdbColumnTypeFor _ = "GEOMETRY"
-
-instance DuckDBColumnType Variant where
-    duckdbColumnTypeFor _ = "VARIANT"
-
-instance DuckDBColumnType Null where
-    duckdbColumnTypeFor _ = "NULL"
-
-instance DuckDBColumnType Bool where
-    duckdbColumnTypeFor _ = "BOOLEAN"
-
-instance DuckDBColumnType Int where
-    duckdbColumnTypeFor _ = "BIGINT"
-
-instance DuckDBColumnType Int8 where
-    duckdbColumnTypeFor _ = "TINYINT"
-
-instance DuckDBColumnType Int16 where
-    duckdbColumnTypeFor _ = "SMALLINT"
-
-instance DuckDBColumnType Int32 where
-    duckdbColumnTypeFor _ = "INTEGER"
-
-instance DuckDBColumnType Int64 where
-    duckdbColumnTypeFor _ = "BIGINT"
-
-instance DuckDBColumnType BigNum where
-    duckdbColumnTypeFor _ = "BIGNUM"
-
-instance DuckDBColumnType UUID.UUID where
-    duckdbColumnTypeFor _ = "UUID"
-
-instance DuckDBColumnType Integer where
-    duckdbColumnTypeFor _ = "BIGNUM"
-
-instance DuckDBColumnType Natural where
-    duckdbColumnTypeFor _ = "BIGNUM"
-
-instance DuckDBColumnType Word where
-    duckdbColumnTypeFor _ = "UBIGINT"
-
-instance DuckDBColumnType Word8 where
-    duckdbColumnTypeFor _ = "UTINYINT"
-
-instance DuckDBColumnType Word16 where
-    duckdbColumnTypeFor _ = "USMALLINT"
-
-instance DuckDBColumnType Word32 where
-    duckdbColumnTypeFor _ = "UINTEGER"
-
-instance DuckDBColumnType Word64 where
-    duckdbColumnTypeFor _ = "UBIGINT"
-
-instance DuckDBColumnType Double where
-    duckdbColumnTypeFor _ = "DOUBLE"
-
-instance DuckDBColumnType Float where
-    duckdbColumnTypeFor _ = "FLOAT"
-
-instance DuckDBColumnType Text where
-    duckdbColumnTypeFor _ = "TEXT"
-
-instance DuckDBColumnType String where
-    duckdbColumnTypeFor _ = "TEXT"
-
-instance DuckDBColumnType BS.ByteString where
-    duckdbColumnTypeFor _ = "BLOB"
-
-instance DuckDBColumnType Day where
-    duckdbColumnTypeFor _ = "DATE"
-
-instance DuckDBColumnType TimeOfDay where
-    duckdbColumnTypeFor _ = "TIME"
-
-instance DuckDBColumnType LocalTime where
-    duckdbColumnTypeFor _ = "TIMESTAMP"
-
-instance DuckDBColumnType UTCTime where
-    duckdbColumnTypeFor _ = "TIMESTAMPTZ"
-
-instance DuckDBColumnType (Unbounded Day) where
-    duckdbColumnTypeFor _ = "DATE"
-
-instance DuckDBColumnType (Unbounded LocalTime) where
-    duckdbColumnTypeFor _ = "TIMESTAMP"
-
-instance DuckDBColumnType (Unbounded UTCTime) where
-    duckdbColumnTypeFor _ = "TIMESTAMPTZ"
-
-instance DuckDBColumnType (StructValue FieldValue) where
-    duckdbColumnTypeFor _ = "STRUCT"
-
-instance DuckDBColumnType (UnionValue FieldValue) where
-    duckdbColumnTypeFor _ = "UNION"
-
-instance (DuckDBColumnType a) => DuckDBColumnType (Maybe a) where
-    duckdbColumnTypeFor _ = duckdbColumnTypeFor (Proxy :: Proxy a)
-
-instance (DuckDBColumnType a) => DuckDBColumnType (Array Int a) where
-    duckdbColumnTypeFor _ = duckdbColumnTypeFor (Proxy :: Proxy a) <> Text.pack "[]"
-
-nullBinding :: String -> FieldBinding
-nullBinding repr = valueBinding repr nullDuckValue
-
-nullDuckValue :: IO DuckDBValue
-nullDuckValue = c_duckdb_create_null_value
-
-boolDuckValue :: Bool -> IO DuckDBValue
-boolDuckValue value = c_duckdb_create_bool (if value then 1 else 0)
-
-int8DuckValue :: Int8 -> IO DuckDBValue
-int8DuckValue = c_duckdb_create_int8
-
-int16DuckValue :: Int16 -> IO DuckDBValue
-int16DuckValue = c_duckdb_create_int16
-
-int32DuckValue :: Int32 -> IO DuckDBValue
-int32DuckValue = c_duckdb_create_int32
-
-int64DuckValue :: Int64 -> IO DuckDBValue
-int64DuckValue = c_duckdb_create_int64
-
-uint64DuckValue :: Word64 -> IO DuckDBValue
-uint64DuckValue = c_duckdb_create_uint64
-
-uint32DuckValue :: Word32 -> IO DuckDBValue
-uint32DuckValue = c_duckdb_create_uint32
-
-uint16DuckValue :: Word16 -> IO DuckDBValue
-uint16DuckValue = c_duckdb_create_uint16
-
-uint8DuckValue :: Word8 -> IO DuckDBValue
-uint8DuckValue = c_duckdb_create_uint8
-
-doubleDuckValue :: Double -> IO DuckDBValue
-doubleDuckValue = c_duckdb_create_double . CDouble
-
-floatDuckValue :: Float -> IO DuckDBValue
-floatDuckValue = c_duckdb_create_float . CFloat
-
-textDuckValue :: Text -> IO DuckDBValue
-textDuckValue txt =
-    BS.useAsCStringLen (TextEncoding.encodeUtf8 txt) \(ptr, len) ->
-        c_duckdb_create_varchar_length ptr (fromIntegral len)
-
-stringDuckValue :: String -> IO DuckDBValue
-stringDuckValue = textDuckValue . Text.pack
-
-blobDuckValue :: BS.ByteString -> IO DuckDBValue
-blobDuckValue bs =
-    BS.useAsCStringLen bs \(ptr, len) ->
-        c_duckdb_create_blob (castPtr ptr :: Ptr Word8) (fromIntegral len)
-
-uuidDuckValue :: UUID.UUID -> IO DuckDBValue
-uuidDuckValue uuid =
-    alloca $ \ptr -> do
-        let (upper, lower) = UUID.toWords64 uuid
-        poke
-            ptr
-            DuckDBUHugeInt
-                { duckDBUHugeIntLower = lower
-                , duckDBUHugeIntUpper = upper
-                }
-        c_duckdb_create_uuid ptr
-
-bitDuckValue :: BitString -> IO DuckDBValue
-bitDuckValue (BitString padding bits) = do
-    when (BS.null bits || padding > 7) $
-        throwIO (userError "duckdb-simple: BIT requires nonempty data and padding from 0 to 7")
-    let nativePadding = complement ((1 `shiftL` (8 - fromIntegral padding)) - 1) :: Word8
-        payload = BS.cons padding (BS.cons (BS.head bits .|. nativePadding) (BS.tail bits))
-    BS.useAsCStringLen payload \(rawPtr, len) ->
-        alloca \ptr -> do
-            poke ptr DuckDBBit{duckDBBitData = castPtr rawPtr, duckDBBitSize = fromIntegral len}
-            c_duckdb_create_bit ptr
-
-bigNumDuckValue :: BigNum -> IO DuckDBValue
-bigNumDuckValue (BigNum big) =
-    let neg = fromBool (big < 0)
-        payload =
-            BS.pack $
-                if big < 0
-                    then map complement (drop 3 $ toBigNumBytes big)
-                    else drop 3 $ toBigNumBytes big
-        withPayload action =
-            if BS.null payload
-                then alloca \ptr -> do
-                    poke
-                        ptr
-                        DuckDBBignum
-                            { duckDBBignumData = nullPtr
-                            , duckDBBignumSize = 0
-                            , duckDBBignumIsNegative = neg
-                            }
-                    action ptr
-                else BS.useAsCStringLen payload \(rawPtr, len) ->
-                    alloca \ptr -> do
-                        poke
-                            ptr
-                            DuckDBBignum
-                                { duckDBBignumData = castPtr rawPtr
-                                , duckDBBignumSize = fromIntegral len
-                                , duckDBBignumIsNegative = neg
-                                }
-                        action ptr
-     in withPayload c_duckdb_create_bignum
-
-dayDuckValue :: Day -> IO DuckDBValue
-dayDuckValue day = do
-    duckDate <- encodeDay day
-    c_duckdb_create_date duckDate
-
-timeOfDayDuckValue :: TimeOfDay -> IO DuckDBValue
-timeOfDayDuckValue tod = do
-    duckTime <- encodeTimeOfDay tod
-    c_duckdb_create_time duckTime
-
-localTimeDuckValue :: LocalTime -> IO DuckDBValue
-localTimeDuckValue ts = do
-    duckTimestamp <- encodeLocalTime ts
-    c_duckdb_create_timestamp duckTimestamp
-
-utcTimeDuckValue :: UTCTime -> IO DuckDBValue
-utcTimeDuckValue utcTime =
-    encodeLocalTime (utcToLocalTime utc utcTime) >>= c_duckdb_create_timestamp_tz
-
--- | Bind a date, including either infinity sentinel.
-dateDuckValue :: Date -> IO DuckDBValue
-dateDuckValue value =
-    encodeUnbounded (fmap unDuckDBDate . encodeDay) value >>= c_duckdb_create_date . DuckDBDate
-
--- | Bind a timestamp without a time zone, including infinity.
-localTimestampDuckValue :: LocalTimestamp -> IO DuckDBValue
-localTimestampDuckValue value =
-    encodeUnbounded (encodeTimestampUnits 1000000) value >>= c_duckdb_create_timestamp . DuckDBTimestamp
-
--- | Bind a timestamp with a time zone, including infinity.
-utcTimestampDuckValue :: UTCTimestamp -> IO DuckDBValue
-utcTimestampDuckValue value =
-    encodeUnbounded (encodeTimestampUnits 1000000 . utcToLocalTime utc) value >>= c_duckdb_create_timestamp_tz . DuckDBTimestamp
-
-{- | Build an array value with a function for each element. A scalar element
-type comes from the column type name of the element, so an empty array keeps
-it. Other element types, such as STRUCT, UNION, and ARRAY, come from the
-first element that is not NULL. All present elements must have the same type.
--}
-arrayDuckValue ::
-    forall a.
-    (DuckDBColumnType a) =>
-    (LogicalTypeRep -> IO DuckDBLogicalType) ->
-    (a -> IO DuckDBValue) ->
-    Array Int a ->
-    IO DuckDBValue
-arrayDuckValue typeFromRep elementValue arr =
-    withCreatedValues (map elementValue (elems arr)) \values ->
-        withElementType values \elementType ->
-            withDuckValues values \ptr ->
-                checkedValue (c_duckdb_create_array_value elementType ptr (fromIntegral (length values)))
-  where
-    typeName = duckdbColumnType (Proxy :: Proxy a)
-    withElementType values action =
-        case duckDBTypeFromName typeName of
-            Just dtype -> bracket (typeFromRep (LogicalTypeScalar dtype)) destroyLogicalType action
-            Nothing -> do
-                present <- filterM (fmap (== 0) . c_duckdb_is_null_value) values
-                case present of
-                    -- The value owns this type.
-                    value : rest -> do
-                        logical <- c_duckdb_get_value_type value
-                        expected <- logicalTypeToRep logical
-                        forM_ rest \element -> do
-                            actual <- c_duckdb_get_value_type element >>= logicalTypeToRep
-                            when (actual /= expected) $
-                                throwIO (userError "duckdb-simple: array elements have different logical types")
-                        action logical
-                    [] ->
-                        throwIO
-                            SQLError
-                                { sqlErrorMessage = "duckdb-simple: an empty or all-NULL array of " <> typeName <> " elements has no element type"
-                                , sqlErrorType = Nothing
-                                , sqlErrorQuery = Nothing
-                                }
-
-structValueDuckValue :: (LogicalTypeRep -> IO DuckDBLogicalType) -> StructValue FieldValue -> IO DuckDBValue
-structValueDuckValue typeFromRep StructValue{structValueFields, structValueTypes, structValueIndex = _} = do
-    let valueFields = elems structValueFields
-        typeFields = elems structValueTypes
-        typeNames = map structFieldName typeFields
-        valueNames = map structFieldName valueFields
-    when (length valueFields /= length typeFields) $
-        throwIO (userError "duckdb-simple: struct value/type arity mismatch")
-    when (typeNames /= valueNames) $
-        throwIO (userError "duckdb-simple: struct value/type field names mismatch")
-    let actions =
-            zipWith
-                ( \StructField{structFieldValue = typeRep} StructField{structFieldValue = fieldVal} ->
-                    fieldValueWithTypeDuckValue typeFromRep typeRep fieldVal
-                )
-                typeFields
-                valueFields
-    bracket (typeFromRep (LogicalTypeStruct structValueTypes)) destroyLogicalType \structLogical ->
-        withCreatedValues actions \childValues ->
-            withDuckValues childValues $ \ptr ->
-                checkedValue (c_duckdb_create_struct_value structLogical ptr)
-
-unionValueDuckValue :: (LogicalTypeRep -> IO DuckDBLogicalType) -> UnionValue FieldValue -> IO DuckDBValue
-unionValueDuckValue typeFromRep UnionValue{unionValueIndex, unionValueLabel, unionValuePayload, unionValueMembers} = do
-    let membersList = elems unionValueMembers
-        idx = fromIntegral unionValueIndex :: Int
-        memberCount = length membersList
-    when (idx < 0 || idx >= memberCount) $
-        throwIO (userError "duckdb-simple: union value tag out of range")
-    let UnionMemberType{unionMemberName, unionMemberType = memberType} = membersList !! idx
-    when (unionValueLabel /= unionMemberName) $
-        throwIO (userError "duckdb-simple: union tag and member name mismatch")
-    bracket (typeFromRep (LogicalTypeUnion unionValueMembers)) destroyLogicalType \unionLogical ->
-        bracket (checkedValue (fieldValueWithTypeDuckValue typeFromRep memberType unionValuePayload)) destroyValue \payloadValue ->
-            checkedValue (c_duckdb_create_union_value unionLogical (fromIntegral unionValueIndex) payloadValue)
-
-fieldValueWithTypeDuckValue :: (LogicalTypeRep -> IO DuckDBLogicalType) -> LogicalTypeRep -> FieldValue -> IO DuckDBValue
-fieldValueWithTypeDuckValue typeFromRep typeRep FieldNull =
-    bracket (typeFromRep typeRep) destroyLogicalType \logical ->
-        withCreatedValues [nullDuckValue] \values ->
-            withDuckValues values \ptr ->
-                bracket (checkedValue (c_duckdb_create_list_value logical ptr 1)) destroyValue \list ->
-                    checkedValue (c_duckdb_get_list_child list 0)
-fieldValueWithTypeDuckValue typeFromRep rep value =
-    case rep of
-        LogicalTypeScalar DuckDBTypeVariant -> variantDuckValue typeFromRep value
-        LogicalTypeScalar dtype -> scalarFieldValueDuckValue dtype value
-        LogicalTypeGeometry _ ->
-            case value of
-                FieldGeometry{} -> unsupportedRawGeometryBinding
-                other -> typeMismatch "GEOMETRY" other
-        LogicalTypeDecimal width scale ->
-            case value of
-                FieldDecimal decVal@DecimalValue{decimalWidth, decimalScale}
-                    | decimalWidth == width && decimalScale == scale -> decimalDuckValue decVal
-                    | otherwise -> throwIO (userError "duckdb-simple: decimal value metadata mismatch")
-                other -> typeMismatch "DECIMAL" other
-        LogicalTypeList elemRep ->
-            case value of
-                FieldList elemsList ->
-                    bracket (typeFromRep elemRep) destroyLogicalType \childLogical ->
-                        withCreatedValues (map (fieldValueWithTypeDuckValue typeFromRep elemRep) elemsList) \values ->
-                            withDuckValues values \ptr ->
-                                checkedValue (c_duckdb_create_list_value childLogical ptr (fromIntegral (length values)))
-                other -> typeMismatch "LIST" other
-        LogicalTypeArray elemRep size ->
-            case value of
-                FieldArray arr -> do
-                    let elemsList = elems arr
-                        actualCount = length elemsList
-                    when (fromIntegral actualCount /= size) $
-                        throwIO (userError "duckdb-simple: array length mismatch")
-                    bracket (typeFromRep elemRep) destroyLogicalType \childLogical ->
-                        withCreatedValues (map (fieldValueWithTypeDuckValue typeFromRep elemRep) elemsList) \values ->
-                            withDuckValues values \ptr ->
-                                checkedValue (c_duckdb_create_array_value childLogical ptr (fromIntegral actualCount))
-                other -> typeMismatch "ARRAY" other
-        LogicalTypeMap keyRep valueRep ->
-            case value of
-                FieldMap pairs ->
-                    bracket (typeFromRep (LogicalTypeMap keyRep valueRep)) destroyLogicalType \mapLogical ->
-                        withCreatedValues (map (fieldValueWithTypeDuckValue typeFromRep keyRep . fst) pairs) \keyValues ->
-                            withCreatedValues (map (fieldValueWithTypeDuckValue typeFromRep valueRep . snd) pairs) \valValues ->
-                                withDuckValues keyValues \keyPtr ->
-                                    withDuckValues valValues \valPtr ->
-                                        checkedValue (c_duckdb_create_map_value mapLogical keyPtr valPtr (fromIntegral (length pairs)))
-                other -> typeMismatch "MAP" other
-        LogicalTypeStruct structRep ->
-            case value of
-                FieldStruct structVal
-                    | structValueTypeRep structVal == LogicalTypeStruct structRep -> structValueDuckValue typeFromRep structVal
-                    | otherwise -> throwIO (userError "duckdb-simple: struct value type mismatch")
-                other -> typeMismatch "STRUCT" other
-        LogicalTypeUnion unionRep ->
-            case value of
-                FieldUnion unionVal
-                    | unionValueTypeRep unionVal == LogicalTypeUnion unionRep -> unionValueDuckValue typeFromRep unionVal
-                    | otherwise -> throwIO (userError "duckdb-simple: union value type mismatch")
-                other -> typeMismatch "UNION" other
-        LogicalTypeEnum dict ->
-            case value of
-                FieldEnum enumIdx -> enumDuckValue dict enumIdx
-                other -> typeMismatch "ENUM" other
-
-scalarFieldValueDuckValue :: DuckDBType -> FieldValue -> IO DuckDBValue
-scalarFieldValueDuckValue dtype value =
-    case (dtype, value) of
-        (DuckDBTypeBoolean, FieldBool b) -> boolDuckValue b
-        (DuckDBTypeTinyInt, FieldInt8 i) -> int8DuckValue i
-        (DuckDBTypeSmallInt, FieldInt16 i) -> int16DuckValue i
-        (DuckDBTypeInteger, FieldInt32 i) -> int32DuckValue i
-        (DuckDBTypeBigInt, FieldInt64 i) -> int64DuckValue i
-        (DuckDBTypeUTinyInt, FieldWord8 w) -> uint8DuckValue w
-        (DuckDBTypeUSmallInt, FieldWord16 w) -> uint16DuckValue w
-        (DuckDBTypeUInteger, FieldWord32 w) -> uint32DuckValue w
-        (DuckDBTypeUBigInt, FieldWord64 w) -> uint64DuckValue w
-        (DuckDBTypeFloat, FieldFloat f) -> floatDuckValue f
-        (DuckDBTypeDouble, FieldDouble d) -> doubleDuckValue d
-        (DuckDBTypeVarchar, FieldText t) -> textDuckValue t
-        (DuckDBTypeBlob, FieldBlob b) -> blobDuckValue b
-        (DuckDBTypeGeometry, FieldGeometry{}) -> unsupportedRawGeometryBinding
-        (DuckDBTypeUUID, FieldUUID u) -> uuidDuckValue u
-        (DuckDBTypeBit, FieldBit bits) -> bitDuckValue bits
-        (DuckDBTypeDate, FieldDate d) -> dateDuckValue d
-        (DuckDBTypeTime, FieldTime t) -> timeOfDayDuckValue t
-        (DuckDBTypeTimeNs, FieldTime t) ->
-            timeOfDayUnits 1000000000 t >>= c_duckdb_create_time_ns . DuckDBTimeNs . fromInteger
-        (DuckDBTypeTimeTz, FieldTimeTZ tz) -> timeWithZoneDuckValue tz
-        (DuckDBTypeTimestamp, FieldTimestamp ts) -> localTimestampDuckValue ts
-        (DuckDBTypeTimestampS, FieldTimestamp ts) ->
-            encodeUnbounded (encodeTimestampUnits 1) ts >>= c_duckdb_create_timestamp_s . DuckDBTimestampS
-        (DuckDBTypeTimestampMs, FieldTimestamp ts) ->
-            encodeUnbounded (encodeTimestampUnits 1000) ts >>= c_duckdb_create_timestamp_ms . DuckDBTimestampMs
-        (DuckDBTypeTimestampNs, FieldTimestamp ts) ->
-            encodeUnbounded (encodeTimestampUnits 1000000000) ts >>= c_duckdb_create_timestamp_ns . DuckDBTimestampNs
-        (DuckDBTypeTimestampTz, FieldTimestampTZ ts) -> utcTimestampDuckValue ts
-        (DuckDBTypeInterval, FieldInterval iv) -> intervalDuckValue iv
-        (DuckDBTypeHugeInt, FieldHugeInt i) -> hugeIntDuckValue i
-        (DuckDBTypeUHugeInt, FieldUHugeInt i) -> uhugeIntDuckValue i
-        (DuckDBTypeBigNum, FieldBigNum big) -> bigNumDuckValue big
-        (DuckDBTypeSQLNull, _) -> nullDuckValue
-        _ ->
-            case value of
-                FieldNull -> nullDuckValue
-                other ->
-                    throwIO
-                        ( userError
-                            ( "duckdb-simple: unsupported scalar conversion for "
-                                <> show dtype
-                                <> " from "
-                                <> show other
-                            )
-                        )
-
-enumDuckValue :: Array Int Text -> Word32 -> IO DuckDBValue
-enumDuckValue dict idx = do
-    when (toInteger idx >= toInteger (length (elems dict))) $
-        throwIO (userError "duckdb-simple: ENUM index out of range")
-    bracket (logicalTypeFromRep (LogicalTypeEnum dict)) destroyLogicalType \enumLogical ->
-        checkedValue (c_duckdb_create_enum_value enumLogical (fromIntegral idx))
-
-hugeIntDuckValue :: Integer -> IO DuckDBValue
-hugeIntDuckValue value =
-    integerToHugeInt value >>= \huge ->
-        alloca \ptr -> do
-            poke ptr huge
-            c_duckdb_create_hugeint ptr
-
-uhugeIntDuckValue :: Integer -> IO DuckDBValue
-uhugeIntDuckValue value =
-    integerToUHugeInt value >>= \uhu ->
-        alloca \ptr -> do
-            poke ptr uhu
-            c_duckdb_create_uhugeint ptr
-
-decimalDuckValue :: DecimalValue -> IO DuckDBValue
-decimalDuckValue DecimalValue{decimalWidth, decimalScale, decimalInteger} = do
-    when (decimalWidth < 1 || decimalWidth > 38 || decimalScale > decimalWidth) $
-        throwIO (userError "duckdb-simple: invalid DECIMAL width or scale")
-    when (abs decimalInteger >= 10 ^ decimalWidth) $
-        throwIO (userError "duckdb-simple: DECIMAL value exceeds declared precision")
-    huge <- integerToHugeInt decimalInteger
-    alloca \ptr -> do
-        poke
-            ptr
-            DuckDBDecimal
-                { duckDBDecimalWidth = decimalWidth
-                , duckDBDecimalScale = decimalScale
-                , duckDBDecimalValue = huge
-                }
-        c_duckdb_create_decimal ptr
-
-intervalDuckValue :: IntervalValue -> IO DuckDBValue
-intervalDuckValue IntervalValue{intervalMonths, intervalDays, intervalMicros} =
-    alloca \ptr -> do
-        poke ptr (DuckDBInterval intervalMonths intervalDays intervalMicros)
-        c_duckdb_create_interval ptr
-
-timeWithZoneDuckValue :: TimeWithZone -> IO DuckDBValue
-timeWithZoneDuckValue TimeWithZone{timeWithZoneTime, timeWithZoneZone} = do
-    totalMicros <- timeOfDayUnits 1000000 timeWithZoneTime
-    let offsetSeconds = toInteger (timeZoneMinutes timeWithZoneZone) * 60
-    when (abs offsetSeconds > 57599) $
-        throwIO (userError "duckdb-simple: TIME WITH TIME ZONE offset out of range")
-    tzValue <- c_duckdb_create_time_tz (fromIntegral totalMicros) (fromIntegral offsetSeconds)
-    c_duckdb_create_time_tz_value tzValue
-
-integerToHugeInt :: Integer -> IO DuckDBHugeInt
-integerToHugeInt value = do
-    let minVal = negate (1 `shiftL` 127)
-        maxVal = (1 `shiftL` 127) - 1
-    when (value < minVal || value > maxVal) $
-        throwIO (userError "duckdb-simple: HUGEINT value out of range")
-    let lowerMask = (1 `shiftL` 64) - 1
-        lower = fromIntegral (value .&. lowerMask)
-        upper = fromIntegral (value `shiftR` 64)
-    pure DuckDBHugeInt{duckDBHugeIntLower = lower, duckDBHugeIntUpper = upper}
-
-integerToUHugeInt :: Integer -> IO DuckDBUHugeInt
-integerToUHugeInt value = do
-    let minVal = 0
-        maxVal = (1 `shiftL` 128) - 1
-    when (value < minVal || value > maxVal) $
-        throwIO (userError "duckdb-simple: UHUGEINT value out of range")
-    let lowerMask = (1 `shiftL` 64) - 1
-        lower = fromIntegral (value .&. lowerMask)
-        upper = fromIntegral (value `shiftR` 64)
-    pure DuckDBUHugeInt{duckDBUHugeIntLower = lower, duckDBUHugeIntUpper = upper}
-
--- | Release every child handle when construction fails or completes.
-withCreatedValues :: [IO DuckDBValue] -> ([DuckDBValue] -> IO a) -> IO a
-withCreatedValues = withMany (\action -> bracket (checkedValue action) destroyValue)
-
--- | Reject failed native constructors before a handle is used.
-checkedValue :: IO DuckDBValue -> IO DuckDBValue
-checkedValue action = do
-    value <- action
-    when (value == nullPtr) $
-        throwIO (userError "duckdb-simple: DuckDB value construction failed")
-    pure value
-
-withDuckValues :: [DuckDBValue] -> (Ptr DuckDBValue -> IO a) -> IO a
-withDuckValues xs action = withArray xs action
-
-typeMismatch :: String -> FieldValue -> IO a
-typeMismatch expected actual =
-    throwIO
-        ( userError
-            ( "duckdb-simple: cannot encode "
-                <> show actual
-                <> " as "
-                <> expected
-            )
-        )
-
--- | Reject raw values that the C API cannot bind without format conversion.
-unsupportedRawGeometryBinding :: IO a
-unsupportedRawGeometryBinding =
-    throwIO (userError "duckdb-simple: raw GEOMETRY binding requires explicit ST_GeomFromWKB and ST_SetCRS parameters")
-
-{- | Construct an owned VARIANT value. A scalar keeps its native type. Lists,
-arrays, and STRUCT fields contain VARIANT values. The C API casts the payload
-through a one-element VARIANT list.
--}
-variantDuckValue :: (LogicalTypeRep -> IO DuckDBLogicalType) -> FieldValue -> IO DuckDBValue
-variantDuckValue typeFromRep value = do
-    (rep, payload) <- variantPayloadType value
-    bracket (typeFromRep (LogicalTypeScalar DuckDBTypeVariant)) destroyLogicalType \variantType ->
-        withCreatedValues [fieldValueWithTypeDuckValue typeFromRep rep payload] \values ->
-            withDuckValues values \ptr ->
-                bracket (checkedValue (c_duckdb_create_list_value variantType ptr 1)) destroyValue \list ->
-                    checkedValue (c_duckdb_get_list_child list 0)
-
-{- | Choose the native type of a VARIANT payload. Containers get VARIANT
-elements and fields. Time values with sub-microsecond digits use nanosecond
-types. Wide timestamps use milliseconds or seconds when these preserve the
-value and fit the native range.
--}
-variantPayloadType :: FieldValue -> IO (LogicalTypeRep, FieldValue)
-variantPayloadType value = case value of
-    FieldNull -> pure (variant, value)
-    FieldBool{} -> scalar DuckDBTypeBoolean
-    FieldInt8{} -> scalar DuckDBTypeTinyInt
-    FieldInt16{} -> scalar DuckDBTypeSmallInt
-    FieldInt32{} -> scalar DuckDBTypeInteger
-    FieldInt64{} -> scalar DuckDBTypeBigInt
-    FieldWord8{} -> scalar DuckDBTypeUTinyInt
-    FieldWord16{} -> scalar DuckDBTypeUSmallInt
-    FieldWord32{} -> scalar DuckDBTypeUInteger
-    FieldWord64{} -> scalar DuckDBTypeUBigInt
-    FieldHugeInt{} -> scalar DuckDBTypeHugeInt
-    FieldUHugeInt{} -> scalar DuckDBTypeUHugeInt
-    FieldFloat{} -> scalar DuckDBTypeFloat
-    FieldDouble{} -> scalar DuckDBTypeDouble
-    FieldDecimal DecimalValue{decimalWidth, decimalScale} -> pure (LogicalTypeDecimal decimalWidth decimalScale, value)
-    FieldText{} -> scalar DuckDBTypeVarchar
-    FieldBlob{} -> scalar DuckDBTypeBlob
-    FieldUUID{} -> scalar DuckDBTypeUUID
-    FieldDate{} -> scalar DuckDBTypeDate
-    FieldTime time
-        | hasNanos time -> scalar DuckDBTypeTimeNs
-        | otherwise -> scalar DuckDBTypeTime
-    FieldTimestamp (Finite LocalTime{localDay, localTimeOfDay})
-        | hasNanos localTimeOfDay -> scalar DuckDBTypeTimestampNs
-        | inFiniteRange (minBound :: Int64) maxBound micros -> scalar DuckDBTypeTimestamp
-        | micros `rem` 1000 == 0 && inFiniteRange (minBound :: Int64) maxBound (micros `div` 1000) -> scalar DuckDBTypeTimestampMs
-        | micros `rem` 1000000 == 0 && inFiniteRange (minBound :: Int64) maxBound (micros `div` 1000000) -> scalar DuckDBTypeTimestampS
-      where
-        micros = diffDays localDay (fromGregorian 1970 1 1) * 86400 * 1000000 + diffTimeToPicoseconds (timeOfDayToTime localTimeOfDay) `div` 1000000
-    FieldTimestamp{} -> scalar DuckDBTypeTimestamp
-    FieldTimestampTZ{} -> scalar DuckDBTypeTimestampTz
-    FieldTimeTZ{} -> scalar DuckDBTypeTimeTz
-    FieldInterval{} -> scalar DuckDBTypeInterval
-    FieldBigNum{} -> scalar DuckDBTypeBigNum
-    FieldBit{} -> scalar DuckDBTypeBit
-    FieldList{} -> pure (LogicalTypeList variant, value)
-    FieldArray items -> pure (LogicalTypeList variant, FieldList (elems items))
-    FieldStruct structValue@StructValue{structValueTypes} -> do
-        let names = map structFieldName (elems structValueTypes)
-        when (any Text.null names || length names /= length (List.nub names)) $
-            throwIO (userError "duckdb-simple: VARIANT objects need unique, nonempty keys")
-        let types = fmap (\field -> field{structFieldValue = variant}) structValueTypes
-        pure (LogicalTypeStruct types, FieldStruct structValue{structValueTypes = types})
-    FieldUnion unionValue -> pure (unionValueTypeRep unionValue, value)
-    FieldGeometry{} -> unsupportedRawGeometryBinding
-    FieldMap{} -> throwIO (userError "duckdb-simple: VARIANT payloads cannot contain MAP values")
-    FieldEnum{} -> throwIO (userError "duckdb-simple: VARIANT payloads cannot contain ENUM values")
-  where
-    variant = LogicalTypeScalar DuckDBTypeVariant
-    scalar dtype = pure (LogicalTypeScalar dtype, value)
-    hasNanos time = snd (properFraction (todSec time * 1000000) :: (Integer, Pico)) /= 0
-
-instance ToDuckValue G.Geometry where
-    toDuckValue geometry = do
-        wkt <- either (throwIO . userError) pure (WKT.encodeWKT geometry)
-        bracket (logicalTypeFromRep (LogicalTypeGeometry Nothing)) destroyLogicalType \logical ->
-            withCreatedValues [textDuckValue wkt] \values ->
-                withDuckValues values \ptr ->
-                    bracket (checkedValue (c_duckdb_create_list_value logical ptr 1)) destroyValue \list ->
-                        checkedValue (c_duckdb_get_list_child list 0)
-
-instance ToDuckValue Null where
-    toDuckValue _ = nullDuckValue
-
-instance ToDuckValue Bool where
-    toDuckValue = boolDuckValue
-
-instance ToDuckValue Int where
-    toDuckValue = int64DuckValue . fromIntegral
-
-instance ToDuckValue Int8 where
-    toDuckValue = int8DuckValue
-
-instance ToDuckValue Int16 where
-    toDuckValue = int16DuckValue
-
-instance ToDuckValue Int32 where
-    toDuckValue = int32DuckValue
-
-instance ToDuckValue Int64 where
-    toDuckValue = int64DuckValue
-
-instance ToDuckValue BigNum where
-    toDuckValue = bigNumDuckValue
-
-instance ToDuckValue UUID.UUID where
-    toDuckValue = uuidDuckValue
-
-instance ToDuckValue Integer where
-    toDuckValue = bigNumDuckValue . BigNum
-
-instance ToDuckValue Natural where
-    toDuckValue = bigNumDuckValue . BigNum . toInteger
-
-instance ToDuckValue Word where
-    toDuckValue = uint64DuckValue . fromIntegral
-
-instance ToDuckValue Word16 where
-    toDuckValue = uint16DuckValue
-
-instance ToDuckValue Word32 where
-    toDuckValue = uint32DuckValue
-
-instance ToDuckValue Word64 where
-    toDuckValue = uint64DuckValue
-
-instance ToDuckValue Word8 where
-    toDuckValue = uint8DuckValue
-
-instance ToDuckValue Double where
-    toDuckValue = doubleDuckValue
-
-instance ToDuckValue Float where
-    toDuckValue = floatDuckValue
-
-instance ToDuckValue Text where
-    toDuckValue = textDuckValue
-
-instance ToDuckValue String where
-    toDuckValue = stringDuckValue
-
-instance ToDuckValue BS.ByteString where
-    toDuckValue = blobDuckValue
-
-instance ToDuckValue BitString where
-    toDuckValue = bitDuckValue
-
-instance ToDuckValue Day where
-    toDuckValue = dayDuckValue
-
-instance ToDuckValue TimeOfDay where
-    toDuckValue = timeOfDayDuckValue
-
-instance ToDuckValue LocalTime where
-    toDuckValue = localTimeDuckValue
-
-instance ToDuckValue UTCTime where
-    toDuckValue = utcTimeDuckValue
-
-instance ToDuckValue (Unbounded Day) where
-    toDuckValue = dateDuckValue
-
-instance ToDuckValue (Unbounded LocalTime) where
-    toDuckValue = localTimestampDuckValue
-
-instance ToDuckValue (Unbounded UTCTime) where
-    toDuckValue = utcTimestampDuckValue
-
-instance ToDuckValue (StructValue FieldValue) where
-    toDuckValue = structValueDuckValue logicalTypeFromRep
-
-instance ToDuckValue (UnionValue FieldValue) where
-    toDuckValue = unionValueDuckValue logicalTypeFromRep
-
-{- | Build an array without a connection. The elements need 'ToDuckValue', so
-this instance does not accept t'Variant' elements. 'toField' binds those.
--}
-instance (DuckDBColumnType a, ToDuckValue a) => ToDuckValue (Array Int a) where
-    toDuckValue = arrayDuckValue logicalTypeFromRep toDuckValue
-
-instance (ToDuckValue a) => ToDuckValue (Maybe a) where
-    toDuckValue Nothing = nullDuckValue
-    toDuckValue (Just value) = toDuckValue value
-
--- | Preserve infinity sentinels and validate finite values before narrowing.
-encodeUnbounded :: (Integral b, Bounded b) => (a -> IO b) -> Unbounded a -> IO b
-encodeUnbounded _ NegInfinity = pure (negate maxBound)
-encodeUnbounded _ PosInfinity = pure maxBound
-encodeUnbounded encode (Finite value) = encode value
-
--- | Encode finite dates as days from the Unix epoch.
-encodeDay :: Day -> IO DuckDBDate
-encodeDay day = do
-    let days = diffDays day (fromGregorian 1970 1 1)
-    checkFiniteRange "DATE" (minBound :: Int32) maxBound days
-    pure (DuckDBDate (fromInteger days))
-
--- | Encode a time of day at DuckDB microsecond precision.
-encodeTimeOfDay :: TimeOfDay -> IO DuckDBTime
-encodeTimeOfDay tod = DuckDBTime . fromInteger <$> timeOfDayUnits 1000000 tod
-
--- | Encode finite timestamps without native calendar conversions.
-encodeLocalTime :: LocalTime -> IO DuckDBTimestamp
-encodeLocalTime ts = DuckDBTimestamp <$> encodeTimestampUnits 1000000 ts
-
--- | Encode finite timestamps in the requested number of units per second.
-encodeTimestampUnits :: Integer -> LocalTime -> IO Int64
-encodeTimestampUnits units LocalTime{localDay, localTimeOfDay} = do
-    time <- timeOfDayUnits units localTimeOfDay
-    let total = diffDays localDay (fromGregorian 1970 1 1) * 86400 * units + time
-    checkFiniteRange "TIMESTAMP" (minBound :: Int64) maxBound total
-    pure (fromInteger total)
-
--- | Check storage limits and the two DuckDB infinity sentinels.
-checkFiniteRange :: (Integral a) => String -> a -> a -> Integer -> IO ()
-checkFiniteRange label lower upper value =
-    when (not (inFiniteRange lower upper value)) $
-        throwIO (userError ("duckdb-simple: " <> label <> " value out of finite range"))
-
--- | Check storage limits without accepting the two infinity sentinels.
-inFiniteRange :: (Integral a) => a -> a -> Integer -> Bool
-inFiniteRange lower upper value =
-    value >= toInteger lower && value < toInteger upper && value /= negate (toInteger upper)
-
--- | Validate time components and convert to the requested units per second.
-timeOfDayUnits :: Integer -> TimeOfDay -> IO Integer
-timeOfDayUnits units tod@(TimeOfDay hours minutes seconds) = do
-    when (hours < 0 || hours > 24 || minutes < 0 || minutes > 59 || seconds < 0 || seconds >= 61 || (hours == 24 && (minutes /= 0 || seconds /= 0))) $
-        throwIO (userError "duckdb-simple: invalid time of day")
-    let value = diffTimeToPicoseconds (timeOfDayToTime tod) `div` (1000000000000 `div` units)
-    when (value > 86400 * units) $
-        throwIO (userError "duckdb-simple: time of day out of range")
-    pure value
-
-bindDuckValue :: Statement -> DuckDBIdx -> IO DuckDBValue -> IO ()
-bindDuckValue stmt idx makeValue =
-    withStatementHandle stmt \handle ->
-        bracket (checkedValue makeValue) destroyValue \value -> do
-            rc <- c_duckdb_bind_value handle idx value
-            when (rc /= DuckDBSuccess) $ do
-                err <- fetchPrepareError (Text.pack "duckdb-simple: parameter binding failed") handle
-                throwBindError stmt err
-
-throwBindError :: Statement -> Text -> IO a
-throwBindError Statement{statementQuery} msg =
-    throwIO
-        SQLError
-            { sqlErrorMessage = msg
-            , sqlErrorType = Nothing
-            , sqlErrorQuery = Just statementQuery
-            }
+{-# LANGUAGE MagicHash #-}
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.ToField
+-- Description : Convert Haskell parameters into DuckDB bindable values.
+--
+-- The @ToField@ class mirrors the interface provided by @sqlite-simple@ while
+-- delegating to the DuckDB C API under the hood.
+--
+-- A 'ToDuckValue' instance of a new type needs no call of the C API. A newtype
+-- instance uses the instance of the wrapped type, for example
+-- @toDuckValue factory (Age years) = toDuckValue factory years@, and the
+-- newtype also needs a 'DuckDBColumnType' instance. A record or a sum type gets
+-- both instances through 'Database.DuckDB.Simple.Generic.ViaDuckDB':
+--
+-- > data User = User {userId :: Int64, userName :: Text}
+-- >   deriving stock (Generic)
+-- >   deriving (DuckDBColumnType, ToDuckValue) via (ViaDuckDB User)
+module Database.DuckDB.Simple.ToField (
+  FieldBinding,
+  ToDuckValue (..),
+  ValueFactory,
+  NativeValue,
+  ToField (..),
+  DuckDBColumnType (..),
+  NamedParam (..),
+  duckdbColumnType,
+  bindFieldBinding,
+  renderFieldBinding,
+) where
+
+import Control.Exception (bracket, mask_, onException)
+import Control.Monad (foldM, forM_, unless, when)
+import Data.Array (Array, bounds, elems, listArray)
+import Data.Bits (complement, shiftL, shiftR, xor, (.|.))
+import qualified Data.ByteString as BS
+import Data.Fixed (Pico)
+import qualified Data.Geometry as G
+import qualified Data.Geometry.WKT as WKT
+import Data.Int (Int16, Int32, Int64, Int8)
+import qualified Data.Map.Strict as Map
+import Data.Proxy (Proxy (..))
+import qualified Data.Set as Set
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Data.Time.Calendar (Day, diffDays, fromGregorian)
+import Data.Time.Clock (UTCTime (..), diffTimeToPicoseconds)
+import Data.Time.LocalTime (LocalTime (..), TimeOfDay (..), timeOfDayToTime, utc, utcToLocalTime)
+import qualified Data.UUID as UUID
+import Data.Word (Word16, Word32, Word64, Word8)
+import Database.DuckDB.Simple.Element (containsType, timeTzMaxOffsetSeconds, timeTzOffsetBits, valueTypeName)
+import Database.DuckDB.Simple.FromField (
+  BigNum (..),
+  BitString (..),
+  DecimalValue (..),
+  FieldValue (..),
+  IntervalValue (..),
+  SizedArray,
+  TimeWithZone (..),
+  sizedArrayToArray,
+ )
+import Database.DuckDB.Simple.Geometry (RawGeometry (..))
+import Database.DuckDB.Simple.Internal (
+  Statement (..),
+  connectionInstance,
+  duckDBTypeFromName,
+  duckDBTypeToName,
+  preparedParameterType,
+  storeBoundValue,
+  withConnectionHandle,
+  withInstanceHandle,
+ )
+import Database.DuckDB.Simple.LogicalRep (
+  LogicalTypeRep (..),
+  StructField (..),
+  StructValue (..),
+  TupleValue (..),
+  TypeDeclaration (..),
+  UnionMemberType (..),
+  UnionValue (..),
+  logicalTypeSQL,
+  structValueTypeRep,
+  tupleValueTypeRep,
+  unionValueTypeRep,
+  withoutAliases,
+ )
+import Database.DuckDB.Simple.Native
+import Database.DuckDB.Simple.Time (Date, LocalTimestamp, UTCTimestamp, Unbounded (..))
+import Database.DuckDB.Simple.Types (Null (..))
+import Database.DuckDB.Simple.V2.LogicalRep (
+  bindingLogicalType,
+  logicalTypeFromRep,
+  logicalTypeToBaseRep,
+  logicalTypeToRep,
+  valuesHaveType,
+ )
+import Database.DuckDB.Simple.Variant (Variant (..))
+import Foreign.C.ConstPtr (ConstPtr (..))
+import Foreign.C.Types (CDouble (..), CFloat (..))
+import Foreign.Marshal (fromBool)
+import Foreign.Marshal.Alloc (alloca, allocaBytes)
+import Foreign.Marshal.Array (withArray)
+import Foreign.Marshal.Utils (with)
+import Foreign.Ptr (Ptr, castPtr, nullPtr)
+import Foreign.Storable (peek, poke)
+import GHC.Exts (Ptr (..))
+import GHC.Num.Integer (integerLog2, integerToAddr)
+import GHC.TypeLits (KnownNat, natVal)
+import Numeric.Natural (Natural)
+
+-- | Represents a named parameter binding using the @:=@ operator.
+data NamedParam where
+  (:=) :: (ToField a) => Text -> a -> NamedParam
+
+infixr 3 :=
+
+-- | Encapsulates the action required to bind a single positional parameter, together with a textual description used in diagnostics.
+data FieldBinding = FieldBinding
+  { fieldBindingValue :: !(ValueBuilder -> IO (Maybe LogicalTypeRep) -> IO DuckDBV2ValueHandle)
+  , fieldBindingDisplay :: !String
+  }
+
+-- | A factory and a type constructor of the same scope. The builder of a
+-- statement resolves CRS types when it binds a parameter. See
+-- Note [Bind-time CRS types] in "Database.DuckDB.Simple.V2.LogicalRep".
+data ValueBuilder = ValueBuilder
+  { builderFactory :: !DuckDBV2FactoryHandle
+  , builderType :: !(LogicalTypeRep -> IO DuckDBV2LogicalTypeHandle)
+  }
+
+-- | A builder that constructs each type directly through the factory.
+plainBuilder :: DuckDBV2FactoryHandle -> ValueBuilder
+plainBuilder factory = ValueBuilder factory (logicalTypeFromRep factory)
+
+-- | Low-level class for values that convert directly to a 'NativeValue'.
+class (DuckDBColumnType a) => ToDuckValue a where
+  -- | Construct an owned value through a borrowed native factory. Keep the
+  --     owner of the factory (a connection, a callback context, or an instance)
+  --     alive until you destroy the value. This is a rule of the library. The
+  --     header says that a factory is valid for as long as its owner is. The
+  --     header gives no rule for a value after the owner of its factory ends.
+  --     A value with a GEOMETRY type that has a CRS needs the factory of a
+  --     connection or of a callback context, because the factory of an
+  --     instance cannot make that type. Use 'ToField' to resolve a custom CRS
+  --     label when binding a parameter.
+  toDuckValue :: ValueFactory -> a -> IO NativeValue
+
+valueBinding :: String -> (DuckDBV2FactoryHandle -> IO DuckDBV2ValueHandle) -> FieldBinding
+valueBinding display make = builderValueBinding display (make . builderFactory)
+
+-- | Construct a value with the builder of the statement's connection.
+builderValueBinding :: String -> (ValueBuilder -> IO DuckDBV2ValueHandle) -> FieldBinding
+builderValueBinding display makeValue =
+  targetValueBinding display (\builder _ -> makeValue builder)
+
+-- | Construct a value with the prepared parameter type, when it is available.
+targetValueBinding :: String -> (ValueBuilder -> IO (Maybe LogicalTypeRep) -> IO DuckDBV2ValueHandle) -> FieldBinding
+targetValueBinding display makeValue =
+  FieldBinding
+    { fieldBindingValue = makeValue
+    , fieldBindingDisplay = display
+    }
+
+{- Note [Nanosecond parameters]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A TimeOfDay, a LocalTime, and a UTCTime hold picoseconds. A TIME, a TIMESTAMP,
+and a TIMESTAMPTZ hold microseconds. TIME_NS, TIMESTAMP_NS, and TIMESTAMPTZ_NS
+hold nanoseconds. timeValueBinding binds these Haskell values, and their
+Unbounded forms, with this rule:
+
+- A value with no digits below a microsecond binds as a microsecond value. The
+  binding does not read the parameter type.
+- A value with digits below a microsecond makes the binding read the parameter
+  type. A nanosecond parameter (TIME_NS, TIMESTAMP_NS, or TIMESTAMPTZ_NS for
+  the three types) gets a nanosecond value. A VARIANT parameter also gets a
+  nanosecond value, when the value fits the range of the nanosecond type
+  (fitsNanoseconds). A VARIANT holds TIME_NS, TIMESTAMP_NS, and TIMESTAMPTZ_NS
+  values. A value outside that range, for example in the year 3000, gets the
+  microsecond value, as for a parameter with no known type. The payload of a
+  Variant follows the same rule (variantPayloadType). Each other parameter,
+  and a parameter with no known type, gets the microsecond value. The binding
+  discards the digits below one microsecond, as the SQL literal does.
+- The binding discards the digits below one nanosecond in each case.
+
+A value in a SizedArray, a list, a Map, a STRUCT, a TUPLE, or a UNION parameter
+follows the type of its leaf in the target: timestampTypeForTarget gives a
+nanosecond type to a TIME, TIMESTAMP, or TIMESTAMPTZ leaf of a nanosecond
+target leaf. These parameters read the parameter type for each value. A
+VARIANT leaf does not give a nanosecond type: bindElement gives an element of
+a VARIANT list or map no target, and timestampTypeForTarget has no VARIANT
+case. A list, a SizedArray, or a Map for a VARIANT parameter has no element
+type in the target (collectionChildType and mapPartTypes give Nothing), so its
+time elements also get the microsecond value. One LIST has one element type
+for all its elements. For a Haskell list, a SizedArray, or a Map of TimeOfDay,
+LocalTime, or UTCTime values, withElementType declares the microsecond type of
+the element, for example TIMESTAMP for a LocalTime, so a nanosecond element
+would be cast to that type, and the cast rounds. A FieldList or a FieldMap
+takes the type that its elements give, as the SQL list literal does
+(withValueType). TIME and TIME_NS elements, and
+TIMESTAMPTZ and TIMESTAMPTZ_NS elements, have no common type, and DuckDB raises
+an error. TIMESTAMP and TIMESTAMP_NS elements give TIMESTAMP_NS[], but an
+element outside the range of TIMESTAMP_NS stays a TIMESTAMP (fitsNanoseconds),
+and DuckDB cannot cast that element to TIMESTAMP_NS. Thus a time element gets
+the microsecond value in each of these collections, because a nanosecond value
+would round or raise an error in some of them.
+
+- Why the binding reads the parameter type only for such digits. A read of the
+  parameter type runs the binder of DuckDB. See Note [Statement schemas] in
+  "Database.DuckDB.Simple.Internal". A microsecond value gives the same result
+  for each parameter type, so the read has no use for it.
+
+- Why a microsecond parameter gets the microsecond value. In DuckDB 2.0.0, the
+  SQL literal '03:04:05.123456999'::TIME gives 03:04:05.123456, but a cast from
+  TIME_NS to TIME rounds and gives 03:04:05.123457. The same holds for
+  TIMESTAMP. A nanosecond value would thus change what a microsecond column
+  stores.
+
+- An explicit cast of the parameter to a nanosecond type, as in
+  ?::TIMESTAMP_NS, makes it a nanosecond parameter. DuckDB then rounds when it
+  casts the value to a microsecond type, for example for a TIMESTAMP column or
+  in ?::TIMESTAMP_NS + INTERVAL 1 DAY. A plain parameter for a microsecond
+  type cuts the digits.
+
+- A LocalTime for a TIMESTAMP_NS parameter, or for the TIMESTAMP_NS elements
+  of a SizedArray, a list, or a Map, is in one of three zones:
+  * In the range of TIMESTAMP_NS (about the years 1677 to 2262): no error.
+  * Outside the range, when DuckDB also cannot cast the microsecond value to
+    TIMESTAMP_NS (outsideNanosecondRange): the value binds as a microsecond
+    value. For a parameter, DuckDB raises its SQLError "Could not convert
+    Timestamp to higher precision", of the type ErrorTypeConversion, when it
+    casts the value. For an element, the native constructor of the LIST, the
+    ARRAY, or the MAP casts each element when the value binds, and it would
+    raise the ErrorInputInvalid "Failed to cast value". Before that cast,
+    checkNanosecondElements raises the SQLError of the library "duckdb-simple:
+    TIMESTAMP value out of finite range", of the type ErrorTypeConversion, for
+    each element that the cast cannot hold. Thus the element gets the type of
+    a parameter, and no element gets an error that the cast does not raise.
+  * From 2262-04-11 23:47:16.854775807 to 23:47:16.854775999: DuckDB can cast
+    the microsecond value, but the cast cuts the digits with no error. Thus
+    the encoder raises the SQLError of the library "duckdb-simple: TIMESTAMP
+    value out of finite range", of the type ErrorTypeConversion. The low end of
+    the range has no such zone, because the microsecond value is cut toward
+    the earlier time.
+  A UTCTime for a TIMESTAMPTZ_NS parameter, or for the TIMESTAMPTZ_NS elements
+  of a SizedArray, a list, or a Map, is in the same three zones, on its instant in
+  UTC. Each leaf of a STRUCT, TUPLE, or UNION outside the range gets the error
+  of the encoder, because in TRY_CAST DuckDB keeps the other leaves of a
+  microsecond value with their digits cut.
+-}
+
+-- | Test whether a time of day has digits below one microsecond. See
+-- Note [Nanosecond parameters].
+hasSubMicroseconds :: TimeOfDay -> Bool
+hasSubMicroseconds time = snd (properFraction (todSec time * 1000000) :: (Integer, Pico)) /= 0
+
+-- | Bind a TIME, TIMESTAMP, or TIMESTAMPTZ value. The source is the microsecond
+-- type of the value, and the last argument makes the microsecond value. See
+-- Note [Nanosecond parameters].
+timeValueBinding :: String -> LogicalTypeRep -> FieldValue -> (ValueBuilder -> IO DuckDBV2ValueHandle) -> FieldBinding
+timeValueBinding display source value makeDefault
+  | subMicroseconds value = temporalValueBinding display source value makeDefault
+  | otherwise = builderValueBinding display makeDefault
+  where
+    subMicroseconds (FieldTime time) = hasSubMicroseconds time
+    subMicroseconds (FieldTimestamp (Finite LocalTime{localTimeOfDay})) = hasSubMicroseconds localTimeOfDay
+    subMicroseconds (FieldTimestampTZ (Finite instant)) = hasSubMicroseconds (localTimeOfDay (utcToLocalTime utc instant))
+    subMicroseconds _ = False
+
+-- | Bind a value with the nanosecond types of the prepared parameter. See
+-- Note [Nanosecond parameters].
+temporalValueBinding :: String -> LogicalTypeRep -> FieldValue -> (ValueBuilder -> IO DuckDBV2ValueHandle) -> FieldBinding
+temporalValueBinding display source value makeDefault =
+  targetValueBinding display \builder readTarget -> do
+    target <- readTarget
+    let precise = case (target, source) of
+          -- A time value with digits below a microsecond for a VARIANT
+          -- parameter. See Note [Nanosecond parameters].
+          (Just (LogicalTypeScalar LogicalTypeIdVariant), LogicalTypeScalar _)
+            | fitsNanoseconds value -> nanosecondType source
+          _ -> timestampTypeForTarget target source
+    if precise == source || outsideNanosecondRange precise value
+      then makeDefault builder
+      else fieldValueWithTypeDuckValue builder precise (valueWithTypeMetadata precise value)
+
+-- | Give the nanosecond type of a TIME, TIMESTAMP, or TIMESTAMPTZ type.
+nanosecondType :: LogicalTypeRep -> LogicalTypeRep
+nanosecondType (LogicalTypeScalar LogicalTypeIdTime) = LogicalTypeScalar LogicalTypeIdTimeNs
+nanosecondType (LogicalTypeScalar LogicalTypeIdTimestamp) = LogicalTypeScalar LogicalTypeIdTimestampNs
+nanosecondType (LogicalTypeScalar LogicalTypeIdTimestampTz) = LogicalTypeScalar LogicalTypeIdTimestampTzNs
+nanosecondType rep = rep
+
+-- | Test whether the nanosecond value of a time value fits the range of its
+-- nanosecond type, with the range test of the encoder. Each time of day fits.
+fitsNanoseconds :: FieldValue -> Bool
+fitsNanoseconds (FieldTimestamp (Finite time)) = inFiniteRange (minBound :: Int64) maxBound (timestampUnits 1000000000 time)
+fitsNanoseconds (FieldTimestampTZ (Finite instant)) = fitsNanoseconds (FieldTimestamp (Finite (utcToLocalTime utc instant)))
+fitsNanoseconds _ = True
+
+-- | Bind an element of a LIST, an ARRAY, or a MAP for its element type in the
+-- target. A VARIANT element type gives no target, so the element binds as for
+-- a parameter with no known type. See Note [Nanosecond parameters].
+bindElement :: (ToField a) => ValueBuilder -> Maybe LogicalTypeRep -> a -> IO DuckDBV2ValueHandle
+bindElement builder target value = fieldBindingValue (toField value) builder (pure elementTarget)
+  where
+    elementTarget = case target of
+      Just (LogicalTypeScalar LogicalTypeIdVariant) -> Nothing
+      _ -> target
+
+-- | Test whether a t'LocalTime' for a TIMESTAMP_NS parameter, or a t'UTCTime'
+-- for a TIMESTAMPTZ_NS parameter on its instant in UTC, is outside the range of
+-- the nanosecond type, and DuckDB also cannot cast its microsecond value to that
+-- type. See Note [Nanosecond parameters].
+outsideNanosecondRange :: LogicalTypeRep -> FieldValue -> Bool
+outsideNanosecondRange (LogicalTypeScalar LogicalTypeIdTimestampNs) (FieldTimestamp (Finite time)) =
+  not (fits (timestampUnits 1000000000 time)) && not (fits (1000 * timestampUnits 1000000 time))
+  where
+    fits = inFiniteRange (minBound :: Int64) maxBound
+outsideNanosecondRange (LogicalTypeScalar LogicalTypeIdTimestampTzNs) (FieldTimestampTZ (Finite instant)) =
+  outsideNanosecondRange (LogicalTypeScalar LogicalTypeIdTimestampNs) (FieldTimestamp (Finite (utcToLocalTime utc instant)))
+outsideNanosecondRange _ _ = False
+
+-- | Read the element type of a prepared LIST or ARRAY parameter.
+collectionChildType :: Maybe LogicalTypeRep -> Maybe LogicalTypeRep
+collectionChildType (Just (LogicalTypeList child)) = Just child
+collectionChildType (Just (LogicalTypeArray child _)) = Just child
+collectionChildType _ = Nothing
+
+-- | Read the key type and the value type of a prepared MAP parameter.
+mapPartTypes :: Maybe LogicalTypeRep -> (Maybe LogicalTypeRep, Maybe LogicalTypeRep)
+mapPartTypes (Just (LogicalTypeMap key value)) = (Just key, Just value)
+mapPartTypes _ = (Nothing, Nothing)
+
+-- | Give a nanosecond type to each TIME, TIMESTAMP, and TIMESTAMPTZ leaf of the
+-- source whose target leaf has that nanosecond type. See
+-- Note [Nanosecond parameters].
+timestampTypeForTarget :: Maybe LogicalTypeRep -> LogicalTypeRep -> LogicalTypeRep
+timestampTypeForTarget target source = case (target, source) of
+  -- Keep an alias only when its base type stays unchanged.
+  (_, LogicalTypeAlias _ base) ->
+    let promoted = timestampTypeForTarget target base
+    in  if promoted == base then source else promoted
+  (Just (LogicalTypeScalar LogicalTypeIdTimestampTzNs), LogicalTypeScalar LogicalTypeIdTimestampTz) ->
+    LogicalTypeScalar LogicalTypeIdTimestampTzNs
+  (Just (LogicalTypeScalar LogicalTypeIdTimestampNs), LogicalTypeScalar LogicalTypeIdTimestamp) ->
+    LogicalTypeScalar LogicalTypeIdTimestampNs
+  (Just (LogicalTypeScalar LogicalTypeIdTimeNs), LogicalTypeScalar LogicalTypeIdTime) ->
+    LogicalTypeScalar LogicalTypeIdTimeNs
+  (_, LogicalTypeList child) ->
+    maybe source (\expected -> LogicalTypeList (timestampTypeForTarget (Just expected) child)) (collectionChildType target)
+  (_, LogicalTypeArray child size) ->
+    maybe source (\expected -> LogicalTypeArray (timestampTypeForTarget (Just expected) child) size) (collectionChildType target)
+  (Just (LogicalTypeMap targetKey targetValue), LogicalTypeMap key value) ->
+    LogicalTypeMap (timestampTypeForTarget (Just targetKey) key) (timestampTypeForTarget (Just targetValue) value)
+  (Just (LogicalTypeStruct targetFields), LogicalTypeStruct fields) ->
+    let sourceFields = elems fields
+        targets = [(identifier name, rep) | StructField name rep <- elems targetFields]
+        matching = [lookup (identifier (structFieldName field)) targets | field <- sourceFields]
+        updated = zipWith (\field expected -> field{structFieldValue = timestampTypeForTarget expected (structFieldValue field)}) sourceFields matching
+    in  LogicalTypeStruct (listArray (bounds fields) updated)
+  (Just (LogicalTypeTuple targetFields), LogicalTypeStruct fields) ->
+    let matching = map Just (elems targetFields) <> repeat Nothing
+        updated = zipWith (\field expected -> field{structFieldValue = timestampTypeForTarget expected (structFieldValue field)}) (elems fields) matching
+    in  LogicalTypeStruct (listArray (bounds fields) updated)
+  (Just (LogicalTypeTuple targetFields), LogicalTypeTuple fields) ->
+    positionalTuple (elems targetFields) fields
+  (Just (LogicalTypeStruct targetFields), LogicalTypeTuple fields) ->
+    positionalTuple (map structFieldValue (elems targetFields)) fields
+  (Just (LogicalTypeUnion targetMembers), LogicalTypeUnion members) ->
+    let targets = [(identifier name, rep) | UnionMemberType name rep <- elems targetMembers]
+    in  LogicalTypeUnion
+          ( fmap
+              (\member -> member{unionMemberType = timestampTypeForTarget (lookup (identifier (unionMemberName member)) targets) (unionMemberType member)})
+              members
+          )
+  _ -> source
+  where
+    -- DuckDB compares identifiers without ASCII case.
+    identifier = foldIdentifier
+    positionalTuple targets fields = LogicalTypeTuple (listArray (bounds fields) (zipWith timestampTypeForTarget (map Just targets <> repeat Nothing) (elems fields)))
+
+-- | Copy adapted type metadata into nested values without changing their payloads.
+valueWithTypeMetadata :: LogicalTypeRep -> FieldValue -> FieldValue
+valueWithTypeMetadata logical value = case (logical, value) of
+  (LogicalTypeList child, FieldList values) -> FieldList (map (valueWithTypeMetadata child) values)
+  (LogicalTypeArray child _, FieldArray values) -> FieldArray (fmap (valueWithTypeMetadata child) values)
+  (LogicalTypeMap keyType valueType, FieldMap pairs) ->
+    FieldMap [(valueWithTypeMetadata keyType key, valueWithTypeMetadata valueType item) | (key, item) <- pairs]
+  (LogicalTypeStruct types, FieldStruct struct) ->
+    let sourceFields = elems (structValueFields struct)
+        fields = [(structFieldName field, structFieldValue field) | field <- elems types]
+        matching = [lookup (structFieldName field) fields | field <- sourceFields]
+        update field expected = case expected of
+          Nothing -> field
+          Just rep -> field{structFieldValue = valueWithTypeMetadata rep (structFieldValue field)}
+    in  FieldStruct
+          struct{structValueTypes = types, structValueFields = listArray (bounds (structValueFields struct)) (zipWith update sourceFields matching)}
+  (LogicalTypeTuple types, FieldTuple tuple) ->
+    let update item expected = maybe item (`valueWithTypeMetadata` item) expected
+        fields = zipWith update (elems (tupleValueFields tuple)) (map Just (elems types) <> repeat Nothing)
+    in  FieldTuple tuple{tupleValueTypes = types, tupleValueFields = listArray (bounds (tupleValueFields tuple)) fields}
+  (LogicalTypeUnion members, FieldUnion union) ->
+    let payload = case drop (fromIntegral (unionValueIndex union)) (elems members) of
+          member : _ -> valueWithTypeMetadata (unionMemberType member) (unionValuePayload union)
+          [] -> unionValuePayload union
+    in  FieldUnion union{unionValueMembers = members, unionValuePayload = payload}
+  _ -> value
+
+{- Note [Type declarations]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+duckdbTypeDeclaration gives the SQL type that a typed registration declares for
+a Haskell type: an argument or the result of a scalar function, a parameter
+or a column of a typed table function, and an argument or the result of a
+typed aggregate function. Right gives the declaration. Left gives the reason
+why the type has no declaration.
+
+- The default is the text of duckdbColumnTypeFor. DuckDB parses the text when
+  the registration declares the type. Thus a newtype with its own
+  DuckDBColumnType instance gives its own type text, for example
+  DECIMAL(18,3).
+- Integer and Natural give HUGEINT and UHUGEINT, but their text is BIGNUM.
+  See Note [Integer parameters].
+- ViaDuckDB gives the structured type of the record or the sum type
+  (genericLogicalType in "Database.DuckDB.Simple.Generic"). A SizedArray
+  field, or a field of a newtype whose DuckValue instance gives the size,
+  declares an ARRAY.
+- Maybe a has the declaration of a.
+- A list gives a LIST (listDeclaration): the text T[] for the element text T,
+  or a structured LIST for a structured element type.
+- A SizedArray gives the ARRAY of its size (arrayDeclaration, see
+  Note [Sized arrays]). A newtype with the type text of one size, for example
+  BIGINT[3], also declares that ARRAY. DuckDB then rejects an ARRAY of another
+  size when it binds the call (a Binder Error). It casts a LIST of the same length to the ARRAY with no error,
+  because the cast from LIST to ARRAY is implicit in DuckDB. A LIST of
+  another length raises the conversion error of DuckDB when the statement
+  runs.
+- A Map gives a MAP (mapDeclaration). Two texts give the text MAP(K, V). In
+  the other cases, a structured MAP needs a scalar type name as the text of a
+  part (duckDBTypeFromName). With another text, a structured part that is a
+  scalar type, or a LIST or a MAP of scalar types, gives its text, and the
+  declaration is the text MAP(K, V), for example MAP(INTEGER[], HUGEINT[]).
+  Each other case gives Left.
+- StructValue, TupleValue, and UnionValue give Left. They have no static
+  field types. Their text is the bare name STRUCT, TUPLE, or UNION. The bare
+  text STRUCT is a valid type, a STRUCT with no fields. That type is also the
+  type of a record with no fields. Thus a check of the declared type cannot
+  find these three types.
+
+A registration raises the Left text as an SQLError before it registers the
+SQL object. For a parameter with no known type, a LIST or a MAP value with no
+element that is not NULL takes its element type from a structured declaration
+(withElementType). See Note [Element types of a list]. The ToDuckValue
+instances of a list, a SizedArray, and a Map give the structured declaration of
+the element as its target (declaredTarget).
+-}
+
+-- | Types that map to a concrete DuckDB column type when used with @ToField@.
+-- A newtype with its own instance gives its own type text. A 'SizedArray' gives the
+-- text of its ARRAY type, for example @BIGINT[3]@ for @SizedArray 3 Int64@.
+-- See Note [Type declarations].
+class DuckDBColumnType a where
+  -- | The DuckDB type text of @a@.
+  duckdbColumnTypeFor :: Proxy a -> Text
+
+  -- | The SQL type that a typed registration declares for @a@, or the reason
+  -- why @a@ has no declaration. The default is the text of
+  -- 'duckdbColumnTypeFor'. A list declares a LIST, and a 'SizedArray' an
+  -- ARRAY. See Note [Type declarations].
+  duckdbTypeDeclaration :: Proxy a -> Either Text TypeDeclaration
+  duckdbTypeDeclaration proxy = Right (TypeExpression (duckdbColumnTypeFor proxy))
+
+-- | The structured declaration of a type, as the target type of an element.
+-- 'Nothing' for a type text or a type with no declaration. See
+-- Note [Type declarations].
+declaredTarget :: (DuckDBColumnType a) => Proxy a -> Maybe LogicalTypeRep
+declaredTarget proxy = case duckdbTypeDeclaration proxy of
+  Right (StructuredType rep) -> Just rep
+  _ -> Nothing
+
+-- | Declare a LIST with the declaration of its element type. See
+-- Note [Type declarations].
+listDeclaration :: TypeDeclaration -> TypeDeclaration
+listDeclaration (TypeExpression element) = TypeExpression (element <> "[]")
+listDeclaration (StructuredType element) = StructuredType (LogicalTypeList element)
+
+-- | Declare a MAP with the declarations of its key type and its value type.
+-- See Note [Type declarations].
+mapDeclaration :: TypeDeclaration -> TypeDeclaration -> Either Text TypeDeclaration
+mapDeclaration key value = case (key, value) of
+  (TypeExpression keyName, TypeExpression valueName) -> Right (TypeExpression (mapText keyName valueName))
+  _ -> case LogicalTypeMap <$> structured key <*> structured value of
+    Right rep -> Right (StructuredType rep)
+    Left reason -> maybe (Left reason) (Right . TypeExpression) (mapText <$> typeText key <*> typeText value)
+  where
+    mapText keyName valueName = "MAP(" <> keyName <> ", " <> valueName <> ")"
+    -- A scalar type, and a LIST or a MAP of such types, has a type text, for
+    -- example HUGEINT[] for a list of Integer values.
+    typeText (TypeExpression text) = Just text
+    typeText (StructuredType rep) = repText rep
+    repText (LogicalTypeScalar dtype) = Just (duckDBTypeToName dtype)
+    repText (LogicalTypeList element) = (<> "[]") <$> repText element
+    repText (LogicalTypeMap keyRep valueRep) = mapText <$> repText keyRep <*> repText valueRep
+    repText _ = Nothing
+    structured (StructuredType rep) = Right rep
+    structured (TypeExpression text) = case duckDBTypeFromName text of
+      Just dtype -> Right (LogicalTypeScalar dtype)
+      Nothing ->
+        Left
+          ( "a MAP with the type text "
+              <> text
+              <> " and a structured type has no declaration. Use a newtype of the Map with its own DuckDBColumnType instance."
+          )
+
+-- | The reason why a type with no static field types has no declaration. See
+-- Note [Type declarations].
+noStaticFieldTypes :: Text -> Text
+noStaticFieldTypes name =
+  name <> " has no static field types. Use a record with ViaDuckDB, or a newtype with its own DuckDBColumnType instance."
+
+-- | Report the DuckDB column type that best matches a given @ToField@ instance.
+duckdbColumnType :: forall a. (DuckDBColumnType a) => Proxy a -> Text
+duckdbColumnType = duckdbColumnTypeFor
+
+-- | Apply a @FieldBinding@ to the given statement/index. The builder takes its
+-- factory from the statement's connection. See Note [Bind-time CRS types]
+-- in "Database.DuckDB.Simple.V2.LogicalRep".
+bindFieldBinding :: Statement -> DuckDBIdx -> FieldBinding -> IO ()
+bindFieldBinding stmt idx FieldBinding{fieldBindingValue} =
+  withConnectionHandle (statementConnection stmt) \connection -> withConnectionFactory connection \factory ->
+    let makeType rep = withInstanceHandle (connectionInstance (statementConnection stmt)) \inst -> bindingLogicalType factory inst rep
+    in  bindDuckValue stmt idx (fieldBindingValue (ValueBuilder factory makeType) (preparedParameterType stmt idx))
+
+-- | Render a bound parameter for error reporting.
+renderFieldBinding :: FieldBinding -> String
+renderFieldBinding FieldBinding{fieldBindingDisplay} = fieldBindingDisplay
+
+-- | Types that can be used as positional parameters.
+class ToField a where
+  toField :: a -> FieldBinding
+  default toField :: (Show a, ToDuckValue a) => a -> FieldBinding
+  toField value = valueBinding (show value) (\factory -> toDuckValue factory value)
+
+instance ToField Null where
+  toField Null = nullBinding "NULL"
+
+instance ToField Bool
+
+instance ToField Int
+
+instance ToField Int8
+
+instance ToField Int16
+
+instance ToField Int32
+
+instance ToField Int64
+
+-- | A value from -2^127 to 2^127 - 1 binds as a HUGEINT. A value outside this
+-- range binds as a UHUGEINT for a UHUGEINT parameter that can hold it, and as a
+-- BIGNUM for a parameter that has no known type or is not an integer or DECIMAL
+-- type. For another integer or DECIMAL parameter, such a value raises
+-- t'SQLError'. Bind a t'BigNum' to bind a BIGNUM value in each case. See
+-- Note [Integer parameters].
+instance ToField Integer where
+  toField = integerBinding
+
+-- | A value from 0 to 2^127 - 1 binds as a HUGEINT. A larger value binds as a
+-- UHUGEINT for a UHUGEINT parameter that can hold it, and as a BIGNUM for a
+-- parameter that has no known type or is not an integer or DECIMAL type. For
+-- another integer or DECIMAL parameter, such a value raises t'SQLError'. Bind a
+-- t'BigNum' to bind a BIGNUM value in each case. See Note [Integer parameters].
+instance ToField Natural where
+  toField = integerBinding . toInteger
+
+{- Note [Integer parameters]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+integerBinding binds an Integer or a Natural parameter with this rule:
+
+- A value from -2^127 to 2^127 - 1 binds as a HUGEINT. The binding does not
+  read the parameter type.
+- A value outside this range makes the binding read the parameter type. A
+  UHUGEINT parameter that can hold the value gets a UHUGEINT value. Another
+  integer parameter (TINYINT to UHUGEINT) or a DECIMAL parameter gets an
+  SQLError with the type ErrorTypeConversion. Each other parameter, and a
+  parameter with no known type, gets a BIGNUM value.
+
+- Why a HUGEINT. In DuckDB 2.0.0, the casts from BIGNUM to the integer types
+  have defects (Bignum::BignumToInt in
+  src/include/duckdb/common/types/bignum.hpp):
+  - A cast to HUGEINT or UHUGEINT fails for each value except 0 and -1.
+  - A cast of a negative value to an unsigned type gives a wrapped value and
+    no error. For example, -5 for a UBIGINT gives 18446744073709551611.
+  - A cast reduces a value of 2^128 or more modulo 2^128 before it checks the
+    range. For example, 2^128 + 5 for a BIGINT gives 5.
+  DuckDB 2.0.0 has no cast from BIGNUM to DECIMAL. DuckDB checks the range of
+  each cast from HUGEINT and UHUGEINT. For TINYINT to UBIGINT, DOUBLE,
+  VARCHAR, BIGNUM, JSON, and VARIANT, the cast from HUGEINT gives the same
+  result as the cast from BIGNUM where the cast from BIGNUM has no defect.
+
+- Why the binding reads the parameter type only outside the HUGEINT range. A
+  read of the parameter type runs the binder of DuckDB. See
+  Note [Statement schemas] in "Database.DuckDB.Simple.Internal". A value in the
+  HUGEINT range does not have this cost.
+
+- What stays BIGNUM:
+  - A value outside the HUGEINT range for a parameter with no known type, as
+    in SELECT ?, binds as a BIGNUM. A cast that DuckDB adds later can still
+    have the defects above.
+  - A BigNum always binds as a BIGNUM.
+
+  Collection values infer their common type as described below and in
+  Note [Element types of a list].
+
+- toDuckValue. ToDuckValue Integer and ToDuckValue Natural use the same range
+  rule (hugeIntInRange): a value from -2^127 to 2^127 - 1 gives a HUGEINT
+  value. A Natural from 2^127 to 2^128 - 1 gives a UHUGEINT value. Each other
+  value raises an SQLError of the type ErrorTypeConversion (outsideRange).
+  toDuckValue has no target type. A BIGNUM value would thus reach a HUGEINT
+  column, and DuckDB 2.0.0 casts the BIGNUM 2^128 to the HUGEINT 0 with no
+  error. The callers of toDuckValue are setConfigValue, defaultValue, the
+  typed rows of table functions and COPY FROM, and the writer of a scalar
+  function result. Use BigNum for a larger value.
+  The default toField of the ToField class also calls toDuckValue. Thus a
+  newtype over Integer with the default toField raises this error for each
+  parameter value outside the HUGEINT range. An Integer parameter uses the
+  rule of integerBinding above, for example a BIGNUM value for a parameter
+  with no known type. Derive ToField with newtype deriving to keep that rule.
+
+- Typed registrations. The DuckDBColumnType text of Integer and Natural stays
+  BIGNUM, the type that holds each value: the element rule of a list
+  parameter and the error texts use it. The declaration is HUGEINT for
+  Integer and UHUGEINT for Natural, as for a field of a generic record (the
+  DuckValue instances in "Database.DuckDB.Simple.Generic"). Thus a column, an
+  argument, and a result of a typed registration have the type of the field.
+  The ToDuckValue instances of a list, a SizedArray, and a Map give the
+  declaration of the element as its target, so a list of Integer values in a
+  typed row has HUGEINT elements. See Note [Type declarations].
+
+- Arrays, lists, and maps. DuckDB casts each element of an ARRAY or a LIST
+  value, and each key and value of a MAP value, to the declared type when it
+  builds the value. The DuckDBColumnType of Integer, Natural, and BigNum is
+  BIGNUM. For a target with an integer or DECIMAL element type, key type, or
+  value type, withElementType declares that type in place of BIGNUM. Each
+  Integer element is a HUGEINT or a UHUGEINT value, so DuckDB checks the range
+  of the cast of each element. For example, [5, -6] for a UBIGINT[2] column
+  raises an error. A SizedArray or a list of BigNum values also takes the element
+  type of the target, but each element is a BIGNUM value. DuckDB casts each
+  element with the casts from BIGNUM, so the result for BigNum elements does
+  not improve. For each other target, and for a parameter with no known type,
+  a list takes the type that its elements give (withValueType), as each scalar
+  Integer and as a SQL list literal of the HUGEINT and BIGNUM values: [1, 2^64]
+  gives HUGEINT[], and [5, 2^130] gives BIGNUM[]. An Integer has no fixed SQL
+  type, so a list with no element, or with only NULL elements, takes the
+  element type of a known target, and otherwise the type NULL, as [] and
+  [NULL] in SQL. The test is on the column type name BIGNUM, so the rule also
+  holds for BigNum elements and for each type whose column type name is
+  BIGNUM, for example a newtype that derives its instances through Integer. A
+  BigNum element is a BIGNUM value in each case.
+
+Issue 41 of duckdb-haskell tracks the defects.
+-}
+
+-- | Bind an integer as a HUGEINT, a UHUGEINT, or a BIGNUM value. See
+-- Note [Integer parameters].
+integerBinding :: Integer -> FieldBinding
+integerBinding value = case hugeIntInRange value of
+  Just make -> valueBinding (show value) make
+  Nothing -> targetValueBinding (show value) \ValueBuilder{builderFactory = factory} readTarget -> do
+    target <- readTarget
+    case target of
+      Just (LogicalTypeScalar LogicalTypeIdUHugeInt) | value >= 0 && value < 1 `shiftL` 128 -> uhugeIntDuckValue factory value
+      Just (LogicalTypeScalar dtype) | dtype `elem` integerTypes -> outOfRange (duckDBTypeToName dtype)
+      Just (LogicalTypeDecimal width scale) -> outOfRange ("DECIMAL(" <> Text.pack (show width) <> "," <> Text.pack (show scale) <> ")")
+      _ -> bigNumDuckValue factory (BigNum value)
+  where
+    outOfRange typeName = throwConversionError ("the value " <> Text.pack (show value) <> " is out of range for a parameter of the type " <> typeName)
+
+-- | Construct a HUGEINT value for an integer from -2^127 to 2^127 - 1. Give
+-- Nothing for each other integer. See Note [Integer parameters].
+hugeIntInRange :: Integer -> Maybe (DuckDBV2FactoryHandle -> IO DuckDBV2ValueHandle)
+hugeIntInRange value
+  | value >= negate (1 `shiftL` 127) && value < 1 `shiftL` 127 = Just (`hugeIntDuckValue` value)
+  | otherwise = Nothing
+
+-- | The integer types, from TINYINT to UHUGEINT. See Note [Integer parameters].
+integerTypes :: [LogicalTypeId]
+integerTypes =
+  [ LogicalTypeIdTinyInt
+  , LogicalTypeIdSmallInt
+  , LogicalTypeIdInteger
+  , LogicalTypeIdBigInt
+  , LogicalTypeIdHugeInt
+  , LogicalTypeIdUTinyInt
+  , LogicalTypeIdUSmallInt
+  , LogicalTypeIdUInteger
+  , LogicalTypeIdUBigInt
+  , LogicalTypeIdUHugeInt
+  ]
+
+instance ToField UUID.UUID
+
+instance ToField Word
+
+instance ToField Word8
+
+instance ToField Word16
+
+instance ToField Word32
+
+instance ToField Word64
+
+instance ToField Double
+
+instance ToField Float
+
+instance ToField Text
+
+instance ToField String
+
+instance ToField BitString
+
+-- | Bind a day as a DATE. A day outside the range of DuckDB, from -5877641-06-25
+-- (5877642-06-25 BC) to 5881580-07-10 in the notation of "Data.Time", raises an
+-- t'SQLError' of the type 'ErrorTypeConversion'. See Note [Time ranges].
+instance ToField Day
+
+-- | Bind a time of day as a TIME, or as a TIME_NS. See
+-- Note [Nanosecond parameters]. A time of exactly 60 seconds (a leap second)
+-- binds as the next second, as @make_time@ of DuckDB gives it: 23:59:60 binds as
+-- 24:00:00. A later time, for example 23:59:60.5, raises an t'SQLError'. The
+-- section \"Errors\" of the README gives its type. See Note [Time ranges].
+instance ToField TimeOfDay where
+  toField value =
+    timeValueBinding (show value) (LogicalTypeScalar LogicalTypeIdTime) (FieldTime value) \builder -> timeOfDayDuckValue (builderFactory builder) value
+
+-- | Bind a local time as a TIMESTAMP, or as a TIMESTAMP_NS. See
+-- Note [Nanosecond parameters]. A time outside the range of DuckDB, from
+-- -290308-12-22 00:00:00 (290309-12-22 BC) to 294247-01-10 04:00:54.775806 in
+-- the notation of "Data.Time", raises an t'SQLError' of the type
+-- 'ErrorTypeConversion'. For a TIMESTAMP_NS target, a time outside the range
+-- of TIMESTAMP_NS can get another error, also a time outside the range of
+-- DuckDB in a STRUCT, a TUPLE, or a UNION. See Note [Nanosecond parameters]. A
+-- time of exactly 60 seconds (a leap second) binds as the next second. A later
+-- time, for example 23:59:60.5, raises an t'SQLError'. The section
+-- \"Errors\" of the README gives its type. See Note [Time ranges].
+instance ToField LocalTime where
+  toField value =
+    timeValueBinding (show value) (LogicalTypeScalar LogicalTypeIdTimestamp) (FieldTimestamp (Finite value)) \builder -> localTimeDuckValue (builderFactory builder) value
+
+-- | Bind the months, days, and microseconds as an INTERVAL. DuckDB keeps the
+-- three fields.
+instance ToField IntervalValue
+
+-- | Bind the time and its offset in seconds as a TIMETZ. An offset outside
+-- -57599 to 57599 seconds raises an t'SQLError' of the type
+-- 'ErrorTypeConversion'. A time with digits below one
+-- microsecond loses these digits, as in SQL text. A time of exactly 60 seconds
+-- (a leap second) binds as the next second. A later time, for example
+-- 23:59:60.5, raises an t'SQLError'. The section \"Errors\" of the README gives
+-- its type. See Note [Time ranges].
+instance ToField TimeWithZone
+
+-- | Bind the value as a DECIMAL with its own width and scale. DuckDB casts it
+-- to the type of the parameter. A width outside 1 to 38, or a scale larger than
+-- the width, raises an t'SQLError' of the type 'ErrorInputInvalid'. An integer
+-- that the width cannot hold raises an t'SQLError' of the type
+-- 'ErrorTypeConversion'.
+instance ToField DecimalValue where
+  toField value = valueBinding (show value) (`decimalDuckValue` value)
+
+-- | Bind the shape as @GEOMETRY@ with no CRS.
+instance ToField G.Geometry
+
+-- | Bind the WKB bytes as a GEOMETRY value with the CRS of the raw geometry.
+-- DuckDB then casts the value to the type of the parameter. See
+-- Note [Raw GEOMETRY parameters].
+instance ToField RawGeometry where
+  toField raw@RawGeometry{rawGeometryWKB, rawGeometryCRS} =
+    builderValueBinding
+      ("<geometry length=" <> show (BS.length rawGeometryWKB) <> ">")
+      \builder -> rawGeometryDuckValue builder rawGeometryCRS raw
+
+-- | Bind the payload as a VARIANT.
+instance ToField Variant where
+  toField value =
+    builderValueBinding (show value) \builder -> variantDuckValue builder (variantPayload value)
+
+-- | Bind an instant as a TIMESTAMPTZ, or as a TIMESTAMPTZ_NS. An instant
+-- outside the range of the t'LocalTime' instance, in UTC, raises an
+-- t'SQLError' of the type 'ErrorTypeConversion'. For a TIMESTAMPTZ_NS target,
+-- an instant outside the range of TIMESTAMPTZ_NS can get another error, also
+-- an instant outside the range of DuckDB in a STRUCT, a TUPLE, or a UNION, as
+-- for a t'LocalTime'. See Note [Nanosecond parameters]. A leap second of
+-- exactly 60 seconds binds as the next second. A later time in a leap second,
+-- for example 60.5 seconds, raises an t'SQLError'. The section \"Errors\" of
+-- the README gives its type. See Note [Time ranges].
+instance ToField UTCTime where
+  toField value =
+    timeValueBinding
+      (show value)
+      (LogicalTypeScalar LogicalTypeIdTimestampTz)
+      (FieldTimestampTZ (Finite value))
+      (\builder -> utcTimeDuckValue (builderFactory builder) value)
+
+-- | Bind a day or an infinity as a DATE. A finite day has the range of the
+-- 'Day' instance.
+instance ToField (Unbounded Day)
+
+-- | Bind a local time or an infinity as a TIMESTAMP, or a local time as a
+-- TIMESTAMP_NS. See Note [Nanosecond parameters]. A finite time has the range
+-- of the t'LocalTime' instance.
+instance ToField (Unbounded LocalTime) where
+  toField value =
+    timeValueBinding (show value) (LogicalTypeScalar LogicalTypeIdTimestamp) (FieldTimestamp value) \builder -> localTimestampDuckValue (builderFactory builder) value
+
+-- | Bind an instant or an infinity as a TIMESTAMPTZ, or an instant as a
+-- TIMESTAMPTZ_NS. See Note [Nanosecond parameters]. A finite instant has the
+-- range of the t'UTCTime' instance.
+instance ToField (Unbounded UTCTime) where
+  toField value =
+    timeValueBinding
+      (show value)
+      (LogicalTypeScalar LogicalTypeIdTimestampTz)
+      (FieldTimestampTZ value)
+      (\builder -> utcTimestampDuckValue (builderFactory builder) value)
+
+instance ToField BigNum where
+  toField big@(BigNum n) = valueBinding (show n) (\factory -> bigNumDuckValue factory big)
+
+instance ToField (StructValue FieldValue) where
+  toField structVal =
+    temporalValueBinding "<struct>" (structValueTypeRep structVal) (FieldStruct structVal) (`structValueDuckValue` structVal)
+
+instance ToField (TupleValue FieldValue) where
+  toField tuple =
+    temporalValueBinding "<tuple>" (tupleValueTypeRep tuple) (FieldTuple tuple) (`tupleValueDuckValue` tuple)
+
+instance ToField (UnionValue FieldValue) where
+  toField unionVal =
+    let label = Text.unpack (unionValueLabel unionVal)
+    in  temporalValueBinding ("<union " <> label <> ">") (unionValueTypeRep unionVal) (FieldUnion unionVal) (`unionValueDuckValue` unionVal)
+
+instance DuckDBColumnType BitString where
+  duckdbColumnTypeFor _ = "BIT"
+
+instance ToField BS.ByteString where
+  toField bs =
+    valueBinding
+      ("<blob length=" <> show (BS.length bs) <> ">")
+      (\factory -> toDuckValue factory bs)
+
+-- | Bind a 'SizedArray' as an ARRAY of size @n@. Each element takes the
+-- element type of the parameter as its target. See Note [Sized arrays].
+instance (DuckDBColumnType a, ToField a) => ToField (SizedArray n a) where
+  toField values =
+    targetValueBinding
+      ("<array length=" <> show (length values) <> ">")
+      \builder readTarget -> do
+        target <- readTarget
+        let childTarget = collectionChildType target
+        arrayDuckValue builder childTarget (bindElement builder childTarget) (elems (sizedArrayToArray values))
+
+-- | Bind a list as a LIST value with the element rules of a 'SizedArray'. An empty
+-- list binds as an empty LIST of the element type. When the element type has
+-- no type name, an empty list takes the element type of the parameter, or the
+-- type NULL for a parameter with no known type, as the SQL literal [] does.
+-- See Note [Element types of a list]. 'String' keeps its own instance. A list
+-- as a row is a row of parameters, so bind a list parameter as @Only [..]@.
+instance {-# OVERLAPPABLE #-} (DuckDBColumnType a, ToField a) => ToField [a] where
+  toField values =
+    targetValueBinding
+      ("<list length=" <> show (length values) <> ">")
+      \builder readTarget -> do
+        target <- readTarget
+        let childTarget = collectionChildType target
+        listDuckValue builder childTarget (bindElement builder childTarget) values
+
+-- | Bind a map as a MAP value. The pairs go in ascending key order. The keys
+-- and the values have the element rules of a list, so an empty map binds as an
+-- empty MAP of the key type and the value type, or with the type NULL for a key
+-- or value type with no type name and no type from the parameter. DuckDB
+-- compares two MAP values pair by pair in their order.
+instance (DuckDBColumnType k, DuckDBColumnType v, ToField k, ToField v) => ToField (Map.Map k v) where
+  toField pairs =
+    targetValueBinding
+      ("<map size=" <> show (Map.size pairs) <> ">")
+      \builder readTarget -> do
+        (keyTarget, valueTarget) <- mapPartTypes <$> readTarget
+        mapDuckValue
+          (withElementType (Proxy @k) builder keyTarget)
+          (withElementType (Proxy @v) builder valueTarget)
+          builder
+          (bindElement builder keyTarget)
+          (bindElement builder valueTarget)
+          (Map.toAscList pairs)
+
+-- | Bind a dynamic value, for example one that a query read as a t'FieldValue'.
+-- Each scalar constructor binds with the instance of its payload type, so it
+-- has the DuckDB type of the constructor. 'FieldHugeInt' and 'FieldUHugeInt'
+-- bind as HUGEINT and UHUGEINT. 'FieldNull' binds as NULL. 'FieldStruct',
+-- 'FieldTuple', and 'FieldUnion' bind with their own types. 'FieldGeometry'
+-- binds as a GEOMETRY with its CRS.
+--
+-- 'FieldList', 'FieldArray', and 'FieldMap' read the parameter type, and take
+-- the element type that their elements give. See
+-- Note [Element types of a list].
+--
+-- Some values lose their type:
+--
+-- * A 'FieldTimestamp' binds as a TIMESTAMP, or as a TIMESTAMP_NS when it has
+--   digits below a microsecond and the parameter has the type TIMESTAMP_NS or
+--   VARIANT, whatever the unit of the column it came from. The same holds for
+--   'FieldTime' and 'FieldTimestampTZ'. In a 'FieldList' or a 'FieldMap' for a
+--   VARIANT parameter, such a value gets the microsecond value. See
+--   Note [Nanosecond parameters].
+-- * A 'FieldText' binds as a VARCHAR with no collation, also when it came from
+--   a JSON value.
+-- * A value that came from a VARIANT binds as its payload.
+-- * A 'FieldEnum' binds its label as a VARCHAR. DuckDB casts the text to the
+--   ENUM type of a column.
+--
+-- A 'FieldList', a 'FieldArray', or a 'FieldMap' that is empty or has only
+-- 'FieldNull' elements takes the element type of the parameter, or the type
+-- NULL for a parameter with no known type, as a SQL list literal does.
+--
+-- An empty 'FieldArray' raises an t'SQLError' of the type 'ErrorInputInvalid',
+-- because a DuckDB ARRAY has at least one element. Inside a 'FieldStruct', a
+-- 'FieldTuple', or a 'FieldUnion', a 'FieldEnum' binds its label to the
+-- declared ENUM type.
+--
+-- t'FieldValue' has no 'DuckDBColumnType' and no 'ToDuckValue' instance,
+-- because no one DuckDB type holds each of its values.
+instance ToField FieldValue where
+  toField value = case value of
+    FieldNull -> nullBinding "NULL"
+    FieldInt8 v -> toField v
+    FieldInt16 v -> toField v
+    FieldInt32 v -> toField v
+    FieldInt64 v -> toField v
+    FieldWord8 v -> toField v
+    FieldWord16 v -> toField v
+    FieldWord32 v -> toField v
+    FieldWord64 v -> toField v
+    FieldUUID v -> toField v
+    FieldFloat v -> toField v
+    FieldDouble v -> toField v
+    FieldText v -> toField v
+    FieldBool v -> toField v
+    FieldBlob v -> toField v
+    FieldGeometry v -> toField v
+    FieldDate v -> toField v
+    FieldTime v -> toField v
+    FieldTimestamp v -> toField v
+    FieldInterval v -> toField v
+    FieldHugeInt v -> valueBinding (show v) (`hugeIntDuckValue` v)
+    FieldUHugeInt v -> valueBinding (show v) (`uhugeIntDuckValue` v)
+    FieldDecimal v -> toField v
+    FieldTimestampTZ v -> toField v
+    FieldTimeTZ v -> toField v
+    FieldBit v -> toField v
+    FieldBigNum v -> toField v
+    FieldEnum _ label -> toField label
+    FieldArray items
+      | Just failure <- arraySizeError (length items) -> valueBinding (show value) (const failure)
+      | otherwise -> fieldValueSequence "FieldArray" c_duckdb_v2_value_create_array (elems items)
+    FieldList items -> fieldValueSequence "FieldList" c_duckdb_v2_value_create_list items
+    FieldMap pairs -> fieldValueMap pairs
+    FieldStruct v -> toField v
+    FieldTuple v -> toField v
+    FieldUnion v -> toField v
+
+-- | Bind the elements of a 'FieldList' or a 'FieldArray' with the element type
+-- that they give. See Note [Element types of a list].
+fieldValueSequence
+  :: Text
+  -> ( DuckDBV2FactoryHandle
+       -> DuckDBV2LogicalTypeHandle
+       -> ConstPtr DuckDBV2ValueHandle
+       -> DuckDBIdx
+       -> Ptr DuckDBV2ValueHandle
+       -> Ptr DuckDBV2ErrorInfoHandle
+       -> IO DuckDBV2Error
+     )
+  -> [FieldValue]
+  -> FieldBinding
+fieldValueSequence name create items =
+  targetValueBinding ("<" <> Text.unpack name <> " length=" <> show (length items) <> ">") \builder readTarget -> do
+    childTarget <- collectionChildType <$> readTarget
+    sequenceDuckValue (withValueType builder childTarget) create builder (bindElement builder childTarget) items
+
+-- | Bind the pairs of a 'FieldMap' in their order, with the key type and the
+-- value type that they give. See Note [Element types of a list].
+fieldValueMap :: [(FieldValue, FieldValue)] -> FieldBinding
+fieldValueMap pairs =
+  targetValueBinding ("<FieldMap size=" <> show (length pairs) <> ">") \builder readTarget -> do
+    (keyTarget, valueTarget) <- mapPartTypes <$> readTarget
+    mapDuckValue
+      (withValueType builder keyTarget)
+      (withValueType builder valueTarget)
+      builder
+      (bindElement builder keyTarget)
+      (bindElement builder valueTarget)
+      pairs
+
+instance (ToField a) => ToField (Maybe a) where
+  toField Nothing = nullBinding "Nothing"
+  toField (Just value) =
+    let binding = toField value
+    in  binding
+          { fieldBindingDisplay = "Just " <> renderFieldBinding binding
+          }
+
+instance DuckDBColumnType G.Geometry where
+  duckdbColumnTypeFor _ = "GEOMETRY"
+
+instance DuckDBColumnType Variant where
+  duckdbColumnTypeFor _ = "VARIANT"
+
+instance DuckDBColumnType Null where
+  duckdbColumnTypeFor _ = "NULL"
+
+instance DuckDBColumnType Bool where
+  duckdbColumnTypeFor _ = "BOOLEAN"
+
+instance DuckDBColumnType Int where
+  duckdbColumnTypeFor _ = "BIGINT"
+
+instance DuckDBColumnType Int8 where
+  duckdbColumnTypeFor _ = "TINYINT"
+
+instance DuckDBColumnType Int16 where
+  duckdbColumnTypeFor _ = "SMALLINT"
+
+instance DuckDBColumnType Int32 where
+  duckdbColumnTypeFor _ = "INTEGER"
+
+instance DuckDBColumnType Int64 where
+  duckdbColumnTypeFor _ = "BIGINT"
+
+instance DuckDBColumnType BigNum where
+  duckdbColumnTypeFor _ = "BIGNUM"
+
+instance DuckDBColumnType UUID.UUID where
+  duckdbColumnTypeFor _ = "UUID"
+
+-- | The text is BIGNUM, the type that holds each value. A typed registration
+-- declares HUGEINT. See Note [Integer parameters].
+instance DuckDBColumnType Integer where
+  duckdbColumnTypeFor _ = "BIGNUM"
+  duckdbTypeDeclaration _ = Right (StructuredType (LogicalTypeScalar LogicalTypeIdHugeInt))
+
+-- | The text is BIGNUM, the type that holds each value. A typed registration
+-- declares UHUGEINT. See Note [Integer parameters].
+instance DuckDBColumnType Natural where
+  duckdbColumnTypeFor _ = "BIGNUM"
+  duckdbTypeDeclaration _ = Right (StructuredType (LogicalTypeScalar LogicalTypeIdUHugeInt))
+
+instance DuckDBColumnType Word where
+  duckdbColumnTypeFor _ = "UBIGINT"
+
+instance DuckDBColumnType Word8 where
+  duckdbColumnTypeFor _ = "UTINYINT"
+
+instance DuckDBColumnType Word16 where
+  duckdbColumnTypeFor _ = "USMALLINT"
+
+instance DuckDBColumnType Word32 where
+  duckdbColumnTypeFor _ = "UINTEGER"
+
+instance DuckDBColumnType Word64 where
+  duckdbColumnTypeFor _ = "UBIGINT"
+
+instance DuckDBColumnType Double where
+  duckdbColumnTypeFor _ = "DOUBLE"
+
+instance DuckDBColumnType Float where
+  duckdbColumnTypeFor _ = "FLOAT"
+
+instance DuckDBColumnType Text where
+  duckdbColumnTypeFor _ = "VARCHAR"
+
+instance DuckDBColumnType String where
+  duckdbColumnTypeFor _ = "VARCHAR"
+
+instance DuckDBColumnType BS.ByteString where
+  duckdbColumnTypeFor _ = "BLOB"
+
+instance DuckDBColumnType Day where
+  duckdbColumnTypeFor _ = "DATE"
+
+instance DuckDBColumnType TimeOfDay where
+  duckdbColumnTypeFor _ = "TIME"
+
+instance DuckDBColumnType LocalTime where
+  duckdbColumnTypeFor _ = "TIMESTAMP"
+
+instance DuckDBColumnType IntervalValue where
+  duckdbColumnTypeFor _ = "INTERVAL"
+
+instance DuckDBColumnType TimeWithZone where
+  duckdbColumnTypeFor _ = "TIMETZ"
+
+instance DuckDBColumnType UTCTime where
+  duckdbColumnTypeFor _ = "TIMESTAMPTZ"
+
+instance DuckDBColumnType (Unbounded Day) where
+  duckdbColumnTypeFor _ = "DATE"
+
+instance DuckDBColumnType (Unbounded LocalTime) where
+  duckdbColumnTypeFor _ = "TIMESTAMP"
+
+instance DuckDBColumnType (Unbounded UTCTime) where
+  duckdbColumnTypeFor _ = "TIMESTAMPTZ"
+
+-- | No declaration. See Note [Type declarations].
+instance DuckDBColumnType (StructValue FieldValue) where
+  duckdbColumnTypeFor _ = "STRUCT"
+  duckdbTypeDeclaration _ = Left (noStaticFieldTypes "StructValue")
+
+-- | No declaration. See Note [Type declarations].
+instance DuckDBColumnType (TupleValue FieldValue) where
+  duckdbColumnTypeFor _ = "TUPLE"
+  duckdbTypeDeclaration _ = Left (noStaticFieldTypes "TupleValue")
+
+-- | No declaration. See Note [Type declarations].
+instance DuckDBColumnType (UnionValue FieldValue) where
+  duckdbColumnTypeFor _ = "UNION"
+  duckdbTypeDeclaration _ = Left (noStaticFieldTypes "UnionValue")
+
+instance (DuckDBColumnType a) => DuckDBColumnType (Maybe a) where
+  duckdbColumnTypeFor _ = duckdbColumnTypeFor (Proxy @a)
+  duckdbTypeDeclaration _ = duckdbTypeDeclaration (Proxy @a)
+
+-- | The type text is @T[n]@, and the declaration is the ARRAY type of size @n@.
+-- See Note [Sized arrays].
+instance (KnownNat n, DuckDBColumnType a) => DuckDBColumnType (SizedArray n a) where
+  duckdbColumnTypeFor _ = duckdbColumnTypeFor (Proxy @a) <> Text.pack ("[" <> show (natVal (Proxy @n)) <> "]")
+  duckdbTypeDeclaration _ = case arraySizeReason size of
+    Just reason -> Left ("a SizedArray of size " <> Text.pack (show size) <> " has no ARRAY type, because " <> reason)
+    Nothing -> arrayDeclaration size <$> duckdbTypeDeclaration (Proxy @a)
+    where
+      size = natVal (Proxy @n)
+
+{- Note [Sized arrays]
+~~~~~~~~~~~~~~~~~~~~~~
+A DuckDB ARRAY type has a size, for example BIGINT[3]. SizedArray n a is the
+Haskell type of T[n]: its type text is T[n], and a typed registration declares
+the ARRAY type of size n. A SizedArray holds an Array Int a with the bounds
+(0, n - 1). sizedArray takes an Array with any bounds and stores its elements
+with these bounds, so the derived Eq and Ord compare the elements only. It is
+the one Haskell type of an ARRAY. For an ARRAY
+of a size that varies, a list reads an ARRAY of each size, and DuckDB casts a
+bound list to an ARRAY column of the same length. A FieldArray is an ARRAY
+value that a program builds at run time.
+
+- Binds. A SizedArray binds as an ARRAY of size n. Each element takes the
+  element type of the parameter as its target, and the element type of the
+  value follows Note [Element types of a list].
+- Reads. A SizedArray reads an ARRAY and a LIST, as a list does, and the
+  value must have n elements. The cast of DuckDB from a LIST or an ARRAY to
+  T[n] gives the same value, or an error for another length, so this is a
+  read by the rule of Note [Reads of another SQL type] in
+  "Database.DuckDB.Simple.FromField". The check uses the length of the
+  decoded value and not the column type, so it is the same for a LIST column,
+  an ARRAY column of another size, and a VARIANT. A value of another length
+  raises Incompatible, which names the column type and the SizedArray type.
+- Sizes. A DuckDB ARRAY has 1 to 100000 elements (maxArraySize). DuckDB
+  rejects the SQL type T[0] and a larger type, for example with "ARRAY type
+  size must be at most 100000". The value API of DuckDB 2.0.0 does not check
+  the largest size, so a parameter of a larger ARRAY would bind a value that
+  the SQL of DuckDB cannot write. Thus the library checks both sizes, as an
+  input check: the declaration of a SizedArray of another size gives Left,
+  and the bind of a SizedArray or a FieldArray of another size raises an
+  SQLError of the type ErrorInputInvalid (arraySizeError).
+- Fields. A SizedArray field of a generic record declares the ARRAY of size
+  n through its DuckValue instance, and reads as a SizedArray does.
+-}
+
+-- | Declare an ARRAY of a size with the declaration of its element type. See
+-- Note [Sized arrays].
+arrayDeclaration :: Integer -> TypeDeclaration -> TypeDeclaration
+arrayDeclaration size (TypeExpression element) = TypeExpression (element <> Text.pack ("[" <> show size <> "]"))
+arrayDeclaration size (StructuredType element) = StructuredType (LogicalTypeArray element (fromInteger size))
+
+-- | See Note [Type declarations].
+instance (DuckDBColumnType k, DuckDBColumnType v) => DuckDBColumnType (Map.Map k v) where
+  duckdbColumnTypeFor _ = Text.pack "MAP(" <> duckdbColumnTypeFor (Proxy @k) <> Text.pack ", " <> duckdbColumnTypeFor (Proxy @v) <> Text.pack ")"
+  duckdbTypeDeclaration _ = do
+    key <- duckdbTypeDeclaration (Proxy @k)
+    value <- duckdbTypeDeclaration (Proxy @v)
+    mapDeclaration key value
+
+-- | 'String' keeps its own instance. See Note [Type declarations].
+instance {-# OVERLAPPABLE #-} (DuckDBColumnType a) => DuckDBColumnType [a] where
+  duckdbColumnTypeFor _ = duckdbColumnTypeFor (Proxy @a) <> Text.pack "[]"
+  duckdbTypeDeclaration _ = listDeclaration <$> duckdbTypeDeclaration (Proxy @a)
+
+nullBinding :: String -> FieldBinding
+nullBinding repr = valueBinding repr nullDuckValue
+
+nullDuckValue :: DuckDBV2FactoryHandle -> IO DuckDBV2ValueHandle
+nullDuckValue factory =
+  bracket
+    (logicalTypeFromRep factory (LogicalTypeScalar LogicalTypeIdSQLNull))
+    destroyLogicalType
+    (\logical -> output (c_duckdb_v2_value_create_null factory logical))
+
+boolDuckValue :: DuckDBV2FactoryHandle -> Bool -> IO DuckDBV2ValueHandle
+boolDuckValue factory value = output (c_duckdb_v2_value_create_bool factory (if value then 1 else 0))
+
+int8DuckValue :: DuckDBV2FactoryHandle -> Int8 -> IO DuckDBV2ValueHandle
+int8DuckValue factory value = output (c_duckdb_v2_value_create_tinyint factory value)
+
+int16DuckValue :: DuckDBV2FactoryHandle -> Int16 -> IO DuckDBV2ValueHandle
+int16DuckValue factory value = output (c_duckdb_v2_value_create_smallint factory value)
+
+int32DuckValue :: DuckDBV2FactoryHandle -> Int32 -> IO DuckDBV2ValueHandle
+int32DuckValue factory value = output (c_duckdb_v2_value_create_int factory value)
+
+int64DuckValue :: DuckDBV2FactoryHandle -> Int64 -> IO DuckDBV2ValueHandle
+int64DuckValue factory value = output (c_duckdb_v2_value_create_bigint factory value)
+
+uint64DuckValue :: DuckDBV2FactoryHandle -> Word64 -> IO DuckDBV2ValueHandle
+uint64DuckValue factory value = output (c_duckdb_v2_value_create_ubigint factory value)
+
+uint32DuckValue :: DuckDBV2FactoryHandle -> Word32 -> IO DuckDBV2ValueHandle
+uint32DuckValue factory value = output (c_duckdb_v2_value_create_uint factory value)
+
+uint16DuckValue :: DuckDBV2FactoryHandle -> Word16 -> IO DuckDBV2ValueHandle
+uint16DuckValue factory value = output (c_duckdb_v2_value_create_usmallint factory value)
+
+uint8DuckValue :: DuckDBV2FactoryHandle -> Word8 -> IO DuckDBV2ValueHandle
+uint8DuckValue factory value = output (c_duckdb_v2_value_create_utinyint factory value)
+
+doubleDuckValue :: DuckDBV2FactoryHandle -> Double -> IO DuckDBV2ValueHandle
+doubleDuckValue factory value = output (c_duckdb_v2_value_create_double factory (CDouble value))
+
+floatDuckValue :: DuckDBV2FactoryHandle -> Float -> IO DuckDBV2ValueHandle
+floatDuckValue factory value = output (c_duckdb_v2_value_create_float factory (CFloat value))
+
+textDuckValue :: DuckDBV2FactoryHandle -> Text -> IO DuckDBV2ValueHandle
+textDuckValue factory value = withText value (\text -> output (c_duckdb_v2_value_create_varchar factory text))
+
+stringDuckValue :: DuckDBV2FactoryHandle -> String -> IO DuckDBV2ValueHandle
+stringDuckValue factory = textDuckValue factory . Text.pack
+
+blobDuckValue :: DuckDBV2FactoryHandle -> BS.ByteString -> IO DuckDBV2ValueHandle
+blobDuckValue factory value = withBytes value (\bytes -> output (c_duckdb_v2_value_create_blob factory bytes))
+
+uuidDuckValue :: DuckDBV2FactoryHandle -> UUID.UUID -> IO DuckDBV2ValueHandle
+uuidDuckValue factory uuid =
+  let (upper, lower) = UUID.toWords64 uuid
+      value = DuckDBV2HugeintT lower (fromIntegral (upper `xor` 0x8000000000000000))
+  in  with value (\ptr -> output (c_duckdb_v2_value_create_uuid factory (ConstPtr ptr)))
+
+bitDuckValue :: DuckDBV2FactoryHandle -> BitString -> IO DuckDBV2ValueHandle
+bitDuckValue factory (BitString padding bits) = do
+  when (BS.null bits || padding > 7) $
+    throwInvalidArgument "BIT requires nonempty data and padding from 0 to 7"
+  let nativePadding = complement ((1 `shiftL` (8 - fromIntegral padding)) - 1) :: Word8
+      payload = BS.cons padding (BS.cons (BS.head bits .|. nativePadding) (BS.tail bits))
+  withBytes payload (\bytes -> output (c_duckdb_v2_value_create_bit factory bytes))
+
+bigNumDuckValue :: DuckDBV2FactoryHandle -> BigNum -> IO DuckDBV2ValueHandle
+bigNumDuckValue factory (BigNum value) =
+  withBigEndianMagnitude (abs value) \raw len -> alloca \lengthSlot -> do
+    let encode ptr capacity = checked (c_duckdb_v2_bignum_encode (ConstPtr (castPtr raw)) (fromIntegral len) (fromBool (value < 0)) ptr capacity lengthSlot)
+    encode nullPtr 0
+    size <- peek lengthSlot
+    allocaBytes (fromIntegral size) \storage -> do
+      encode storage size
+      payload <- BS.packCStringLen (castPtr storage, fromIntegral size)
+      withBytes payload (\encoded -> output (c_duckdb_v2_value_create_bignum factory encoded))
+
+-- | Write the unsigned big-endian magnitude of a non-negative number into a
+-- buffer in linear time, and give the buffer and its length to the action. The
+-- magnitude has no leading zero byte. Zero is one zero byte.
+withBigEndianMagnitude :: Integer -> (Ptr Word8 -> Int -> IO a) -> IO a
+withBigEndianMagnitude 0 action = with 0 \buffer -> action buffer 1
+withBigEndianMagnitude magnitude action = allocaBytes size \buffer@(Ptr addr) -> integerToAddr magnitude addr 1# >> action buffer size
+  where
+    size = fromIntegral (integerLog2 magnitude `quot` 8) + 1
+
+dayDuckValue :: DuckDBV2FactoryHandle -> Day -> IO DuckDBV2ValueHandle
+dayDuckValue factory value = encodeDay value >>= (\encoded -> output (c_duckdb_v2_value_create_date factory encoded))
+
+timeOfDayDuckValue :: DuckDBV2FactoryHandle -> TimeOfDay -> IO DuckDBV2ValueHandle
+timeOfDayDuckValue factory value = encodeTimeOfDay value >>= (\encoded -> output (c_duckdb_v2_value_create_time factory encoded))
+
+localTimeDuckValue :: DuckDBV2FactoryHandle -> LocalTime -> IO DuckDBV2ValueHandle
+localTimeDuckValue factory value = encodeLocalTime value >>= (\encoded -> output (c_duckdb_v2_value_create_timestamp factory encoded))
+
+utcTimeDuckValue :: DuckDBV2FactoryHandle -> UTCTime -> IO DuckDBV2ValueHandle
+utcTimeDuckValue factory = utcTimestampDuckValue factory . Finite
+
+dateDuckValue :: DuckDBV2FactoryHandle -> Date -> IO DuckDBV2ValueHandle
+dateDuckValue factory value = encodeUnbounded encodeDay value >>= (\encoded -> output (c_duckdb_v2_value_create_date factory encoded))
+
+localTimestampDuckValue :: DuckDBV2FactoryHandle -> LocalTimestamp -> IO DuckDBV2ValueHandle
+localTimestampDuckValue factory value = encodeUnbounded (encodeTimestampUnits 1000000) value >>= (\encoded -> output (c_duckdb_v2_value_create_timestamp factory encoded))
+
+utcTimestampDuckValue :: DuckDBV2FactoryHandle -> UTCTimestamp -> IO DuckDBV2ValueHandle
+utcTimestampDuckValue factory value =
+  encodeUnbounded (encodeTimestampUnits 1000000 . utcToLocalTime utc) value
+    >>= (\encoded -> output (c_duckdb_v2_value_create_timestamp_tz factory encoded))
+
+-- | Construct an ARRAY value. An array with no element or with more elements
+-- than DuckDB permits raises t'SQLError'. See 'withElementType' for the element
+-- type.
+arrayDuckValue
+  :: forall a
+   . (DuckDBColumnType a)
+  => ValueBuilder
+  -> Maybe LogicalTypeRep
+  -> (a -> IO DuckDBV2ValueHandle)
+  -> [a]
+  -> IO DuckDBV2ValueHandle
+arrayDuckValue builder target elementValue values = do
+  sequence_ (arraySizeError (length values))
+  sequenceDuckValue (withElementType (Proxy @a) builder target) c_duckdb_v2_value_create_array builder elementValue values
+
+-- | Give the input error of an ARRAY parameter of a size that DuckDB does not
+-- have: no element, or more elements than DuckDB permits. A 'SizedArray' and a
+-- 'FieldArray' raise this error. See Note [Sized arrays].
+arraySizeError :: Int -> Maybe (IO a)
+arraySizeError count = case arraySizeReason (toInteger count) of
+  Nothing -> Nothing
+  Just reason ->
+    Just
+      ( throwInvalidArgument case count of
+          0 -> "an empty ARRAY parameter is not possible, because " <> reason <> "; bind an empty list for an empty LIST"
+          _ -> "an ARRAY parameter of " <> Text.pack (show count) <> " elements is not possible, because " <> reason <> "; bind a list for a LIST"
+      )
+
+-- | Construct a LIST value. An empty list is an empty LIST of the element type.
+-- See 'withElementType' for the element type.
+listDuckValue
+  :: forall a
+   . (DuckDBColumnType a)
+  => ValueBuilder
+  -> Maybe LogicalTypeRep
+  -> (a -> IO DuckDBV2ValueHandle)
+  -> [a]
+  -> IO DuckDBV2ValueHandle
+listDuckValue builder target = sequenceDuckValue (withElementType (Proxy @a) builder target) c_duckdb_v2_value_create_list builder
+
+-- | Construct a LIST or an ARRAY value with the native constructor. The first
+-- argument gives the element type of the values to its action:
+-- 'withElementType' for a Haskell element type, or 'withValueType'.
+sequenceDuckValue
+  :: ([DuckDBV2ValueHandle] -> (DuckDBV2LogicalTypeHandle -> IO DuckDBV2ValueHandle) -> IO DuckDBV2ValueHandle)
+  -> ( DuckDBV2FactoryHandle
+       -> DuckDBV2LogicalTypeHandle
+       -> ConstPtr DuckDBV2ValueHandle
+       -> DuckDBIdx
+       -> Ptr DuckDBV2ValueHandle
+       -> Ptr DuckDBV2ErrorInfoHandle
+       -> IO DuckDBV2Error
+     )
+  -> ValueBuilder
+  -> (a -> IO DuckDBV2ValueHandle)
+  -> [a]
+  -> IO DuckDBV2ValueHandle
+sequenceDuckValue withType create ValueBuilder{builderFactory = factory} elementValue elements =
+  withCreatedValues (map elementValue elements) \values ->
+    withType values \elementType ->
+      withArray values \ptr ->
+        output (create factory elementType (ConstPtr ptr) (fromIntegral (length values)))
+
+-- | Construct a MAP value from pairs in their order. The first two arguments
+-- give the key type and the value type, as for 'sequenceDuckValue'.
+mapDuckValue
+  :: ([DuckDBV2ValueHandle] -> (DuckDBV2LogicalTypeHandle -> IO DuckDBV2ValueHandle) -> IO DuckDBV2ValueHandle)
+  -> ([DuckDBV2ValueHandle] -> (DuckDBV2LogicalTypeHandle -> IO DuckDBV2ValueHandle) -> IO DuckDBV2ValueHandle)
+  -> ValueBuilder
+  -> (k -> IO DuckDBV2ValueHandle)
+  -> (v -> IO DuckDBV2ValueHandle)
+  -> [(k, v)]
+  -> IO DuckDBV2ValueHandle
+mapDuckValue withKeyType withMapValueType ValueBuilder{builderFactory = factory} keyValue valueValue pairs =
+  withCreatedValues (map (keyValue . fst) pairs) \keys ->
+    withCreatedValues (map (valueValue . snd) pairs) \values ->
+      withKeyType keys \keyType ->
+        withMapValueType values \valueType ->
+          withArray keys \keyPtr -> withArray values \valuePtr ->
+            output (c_duckdb_v2_value_create_map factory keyType valueType (ConstPtr keyPtr) (ConstPtr valuePtr) (fromIntegral (length pairs)))
+
+{- Note [Element types of a list]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+withElementType and withValueType give the element type of a LIST or an ARRAY
+value, and the key type or the value type of a MAP value, to the native
+constructor:
+
+- A scalar element type comes from the column type name of the element. Some
+  elements take the element type of the target in place of that type: an
+  Integer, a Natural, or a BigNum element for an integer or DECIMAL target (see
+  Note [Integer parameters]), and a TimeOfDay, a LocalTime, or a UTCTime
+  element for a nanosecond target (see Note [Nanosecond parameters]). For each
+  other target, a list of Integer, Natural, or BigNum elements that is not
+  empty takes the type that its elements give, as the elements below do.
+- An element type with no recognized scalar type name uses withValueType to
+  infer its type from values. Examples are a STRUCT, a TUPLE, a UNION, a generic
+  record, a list, an array, and a FieldValue. A complete structured declaration
+  supplies the type only when no value contributes a type, as described below.
+  A typed NULL contributes its type, including aliases and collations.
+  Only a NULL of the unaliased SQLNULL type has no type to contribute. The
+  filter compares each NULL type with one temporary unaliased SQLNULL type.
+  Native equality distinguishes aliases, including the alias "NULL". When
+  each remaining element has the type of the first one, that type is the
+  element type. The check uses native equality to keep aliases and ENUM dictionaries.
+  valuesHaveType checks the metadata that equality omits. In DuckDB 2.0.0,
+  VARCHAR equality ignores collations. STRUCT and UNION names compare without
+  ASCII case. GEOMETRY CRS definitions can compare equal through a shared
+  identifier. The metadata check keeps exact names, collations, and definitions.
+  It reads the first comparison key once, then checks each remaining value.
+  It visits child types but reads no ENUM labels.
+- When the types are different, but timestampTypeForTarget gives each of them
+  the same nanosecond type for the target, that type is the element type. For
+  example, a FieldTime with digits below a microsecond binds as a TIME_NS for a
+  TIME_NS[] parameter, and one with no such digits binds as a TIME. DuckDB has
+  no common type for TIME and TIME_NS, or for TIMESTAMPTZ and TIMESTAMPTZ_NS.
+  This check reads complete type trees only after the equality check fails
+  and the target contains a nanosecond temporal type. The promoted trees must
+  agree, including aliases on unchanged leaves. At least one type must change.
+  The promotion loop releases each native type before its next iteration.
+- When these types are different, the library names no element type. The
+  native constructor then gives the type of a SQL list literal of the elements
+  (duckdb_v2.h: "The child type is the common type of the elements, resolved by
+  the same rule a SQL list literal follows, and every element is cast to it; a
+  set with no common type surfaces the cast error."). For example, a STRUCT(a
+  INTEGER) and a STRUCT(b INTEGER) give STRUCT(a INTEGER, b INTEGER), with NULL
+  for a field that an element does not have. A BIGINT field and a DOUBLE field
+  give a DOUBLE field, which rounds a large BIGINT, as in SQL.
+- Elements with no common type raise the SQLError of DuckDB. For a STRUCT(a
+  INTEGER) and a STRUCT(a VARCHAR), it is "Cannot combine types" of the type
+  ErrorQueryNotImplemented. The SQL list literal raises a Binder Error for the
+  same elements, but array_value raises the same error as the constructor.
+- The target does not change the type of these elements. In SQL, DuckDB also
+  gives the list literal its type before it casts the list to the type of a
+  column.
+- A list with no element or only untyped NULL elements of this kind takes the
+  element type of the target, when the parameter has a known type. DuckDB casts
+  the list literal [] or [NULL, NULL] to the type of a column in the same way.
+- For a parameter with no known type, the element type of a list with no
+  element or only untyped NULL elements is the structured declaration of the
+  element type, when it has one, for example a record through ViaDuckDB (see
+  Note [Type declarations]). The two rules below apply to each other element
+  type.
+- For a parameter with no known type, a list with only untyped NULL elements
+  names no element type. The native constructor then gives the type of the SQL
+  list literal: "NULL"[] for a LIST, "NULL"[2] for an ARRAY of two NULL elements,
+  and MAP(VARCHAR, "NULL") for a MAP of VARCHAR keys and NULL values.
+- For a parameter with no known type, an empty list or map of this kind gets
+  the element type NULL. The SQL literals [] and MAP {} have the types
+  "NULL"[] and MAP("NULL", "NULL"). The native constructor gives no type to an
+  empty set (it raises "cannot resolve the element type of an empty set"), so
+  the library names the type NULL itself. A SizedArray or a FieldArray with no
+  element raises an error before this point, because a DuckDB ARRAY has at
+  least one element.
+-}
+
+-- | Give the element type of the values of a LIST, an ARRAY, or one part of a
+-- MAP to the action. The target is the element type of the parameter. See
+-- Note [Element types of a list].
+withElementType
+  :: forall a b
+   . (DuckDBColumnType a)
+  => Proxy a
+  -> ValueBuilder
+  -> Maybe LogicalTypeRep
+  -> [DuckDBV2ValueHandle]
+  -> (DuckDBV2LogicalTypeHandle -> IO b)
+  -> IO b
+withElementType proxy builder@ValueBuilder{builderType = makeType} target values action = case duckDBTypeFromName typeName of
+  -- See Note [Integer parameters].
+  Just LogicalTypeIdBigNum | not integerTarget -> withValueType builder target values action
+  Just dtype -> do
+    checkNanosecondElements (declaredType dtype) values
+    bracket (makeType (declaredType dtype)) destroyLogicalType action
+  Nothing -> withValueType builder elementTarget values action
+  where
+    typeName = duckdbColumnType proxy
+    -- With no target, the structured declaration of a record is the element
+    -- type of a list with no element that is not NULL. See
+    -- Note [Element types of a list].
+    elementTarget = maybe (declaredTarget proxy) Just target
+    -- See Note [Integer parameters].
+    integerTarget = case target of
+      Just (LogicalTypeScalar dtype) -> dtype `elem` integerTypes
+      Just LogicalTypeDecimal{} -> True
+      _ -> False
+    declaredType LogicalTypeIdBigNum | integerTarget, Just rep <- target = rep
+    declaredType dtype = timestampTypeForTarget target (LogicalTypeScalar dtype)
+
+-- | Raise the range error of the library for each TIMESTAMP or TIMESTAMPTZ
+-- element that a TIMESTAMP_NS or TIMESTAMPTZ_NS element type cannot hold, before
+-- the native constructor casts the element. An infinity value and a NULL value
+-- pass, as in the cast. See Note [Nanosecond parameters].
+checkNanosecondElements :: LogicalTypeRep -> [DuckDBV2ValueHandle] -> IO ()
+checkNanosecondElements declared values = case declared of
+  LogicalTypeScalar LogicalTypeIdTimestampNs -> forM_ values (check LogicalTypeIdTimestamp c_duckdb_v2_value_get_timestamp)
+  LogicalTypeScalar LogicalTypeIdTimestampTzNs -> forM_ values (check LogicalTypeIdTimestampTz c_duckdb_v2_value_get_timestamp_tz)
+  _ -> pure ()
+  where
+    check source get value = do
+      isNull <- output (c_duckdb_v2_value_is_null value)
+      -- See Note [Type aliases] in "Database.DuckDB.Simple.LogicalRep".
+      rep <- bracket (output (c_duckdb_v2_value_get_logical_type value)) destroyLogicalType logicalTypeToBaseRep
+      when (isNull == 0 && rep == LogicalTypeScalar source) do
+        micros <- output (get value)
+        unless (micros == maxBound || micros == negate maxBound) $
+          checkFiniteRange "TIMESTAMP" (minBound :: Int64) maxBound (1000 * toInteger micros)
+
+-- | Give the element type that the values give to the action. The target is
+-- the element type of the parameter. See Note [Element types of a list].
+withValueType :: ValueBuilder -> Maybe LogicalTypeRep -> [DuckDBV2ValueHandle] -> (DuckDBV2LogicalTypeHandle -> IO b) -> IO b
+withValueType ValueBuilder{builderFactory = factory, builderType = makeType} target values action = do
+  -- Keep each value except an untyped NULL, in list order. The fold keeps a
+  -- constant stack. See Note [Constant stack at safe calls] in
+  -- "Database.DuckDB.Simple.Native".
+  let keep plainNull kept value =
+        output (c_duckdb_v2_value_is_null value) >>= \flag ->
+          if flag == 0
+            then pure (value : kept)
+            else do
+              untyped <-
+                bracket (output (c_duckdb_v2_value_get_logical_type value)) destroyLogicalType \logical ->
+                  (/= 0) <$> output (c_duckdb_v2_logical_type_is_equal logical plainNull)
+              pure (if untyped then kept else value : kept)
+  present <-
+    bracket (makeType (LogicalTypeScalar LogicalTypeIdSQLNull)) destroyLogicalType \plainNull ->
+      reverse <$> foldM (keep plainNull) [] values
+  case present of
+    [value] -> bracket (output (c_duckdb_v2_value_get_logical_type value)) destroyLogicalType action
+    value : rest -> bracket (output (c_duckdb_v2_value_get_logical_type value)) destroyLogicalType \logical -> do
+      same <- valuesHaveType logical rest
+      let nanoseconds (LogicalTypeScalar dtype) = dtype `elem` [LogicalTypeIdTimeNs, LogicalTypeIdTimestampNs, LogicalTypeIdTimestampTzNs]
+          nanoseconds _ = False
+      if same
+        then action logical
+        else
+          if not (maybe False (containsType nanoseconds) target)
+            then action nullHandle
+            else do
+              original <- logicalTypeToRep factory logical
+              let promoted = timestampTypeForTarget target original
+                  agree changed [] = pure (if changed then Just promoted else Nothing)
+                  agree changed (element : remaining) = do
+                    -- Release this type before the next iteration.
+                    actual <- bracket (output (c_duckdb_v2_value_get_logical_type element)) destroyLogicalType (logicalTypeToRep factory)
+                    let updated = timestampTypeForTarget target actual
+                    if updated /= promoted
+                      then pure Nothing
+                      else do
+                        let changed' = changed || updated /= actual
+                        changed' `seq` agree changed' remaining
+              common <- agree (promoted /= original) rest
+              case common of
+                Just rep -> bracket (makeType rep) destroyLogicalType action
+                Nothing -> action nullHandle
+    -- See Note [Element types of a list].
+    [] -> case target of
+      Just rep -> bracket (makeType rep) destroyLogicalType action
+      Nothing
+        | not (null values) -> action nullHandle
+        | otherwise -> bracket (makeType (LogicalTypeScalar LogicalTypeIdSQLNull)) destroyLogicalType action
+
+-- | Construct named fields. The native call copies the field values.
+structValueDuckValue
+  :: ValueBuilder -> StructValue FieldValue -> IO DuckDBV2ValueHandle
+structValueDuckValue builder@ValueBuilder{builderFactory = factory} StructValue{structValueFields, structValueTypes} = do
+  let fields = elems structValueFields
+      types = elems structValueTypes
+      names = map structFieldName fields
+  when (names /= map structFieldName types) $
+    throwInvalidArgument "struct value/type fields mismatch"
+  withCreatedValues
+    (zipWith (\field logical -> fieldValueWithTypeDuckValue builder (structFieldValue logical) (structFieldValue field)) fields types)
+    \values ->
+      withIdentifiers names \namePtr -> withArray values \valuePtr ->
+        declaredCompositeValue builder (LogicalTypeStruct structValueTypes) $
+          output (c_duckdb_v2_value_create_struct factory (ConstPtr namePtr) (ConstPtr valuePtr) (fromIntegral (length values)))
+
+-- | Construct positional fields without inferring a TUPLE from field names.
+tupleValueDuckValue
+  :: ValueBuilder -> TupleValue FieldValue -> IO DuckDBV2ValueHandle
+tupleValueDuckValue builder@ValueBuilder{builderFactory = factory} TupleValue{tupleValueFields, tupleValueTypes} = do
+  let fields = elems tupleValueFields
+      types = elems tupleValueTypes
+  when (length fields /= length types) $
+    throwInvalidArgument "tuple value/type fields mismatch"
+  withCreatedValues (zipWith (fieldValueWithTypeDuckValue builder) types fields) \values ->
+    withArray values \valuePtr ->
+      declaredCompositeValue builder (LogicalTypeTuple tupleValueTypes) $
+        output (c_duckdb_v2_value_create_tuple factory (ConstPtr valuePtr) (fromIntegral (length values)))
+
+-- | Preserve declared field types through an owned vector. Scalar VARCHAR
+-- values do not retain collations. Most alias values use their base type,
+-- but their enclosing composite type keeps both. See
+-- Note [Type aliases] in "Database.DuckDB.Simple.LogicalRep".
+declaredCompositeValue
+  :: ValueBuilder
+  -> LogicalTypeRep
+  -> IO DuckDBV2ValueHandle
+  -> IO DuckDBV2ValueHandle
+declaredCompositeValue _ rep create | not (needsDeclaredType rep) = create
+declaredCompositeValue ValueBuilder{builderFactory = factory, builderType = makeType} rep create = bracket create destroyValue \value ->
+  bracket (makeType rep) destroyLogicalType (defaultCast factory value)
+
+-- | Test whether a type tree contains a VARCHAR collation or an alias.
+needsDeclaredType :: LogicalTypeRep -> Bool
+needsDeclaredType = containsType declared
+  where
+    declared (LogicalTypeCollatedVarchar _) = True
+    declared LogicalTypeAlias{} = True
+    declared _ = False
+
+{- Note [UNION values]
+~~~~~~~~~~~~~~~~~~~~~
+V2 has no constructor for a UNION value. unionValueDuckValue writes the tag
+and active member into a one-row UNION vector, sets the inactive members to
+NULL, and reads the row as a value. The header specifies child 0 as the tag
+and children 1 to N as the members. vector_set_value uses the non-strict
+default cast, so a user cast cannot change the payload. See Note [User casts
+and the casts of the library] in "Database.DuckDB.Simple.Materialize".
+
+The header recommends casting a member value to the UNION type, but that cast
+selects the member by type. It is ambiguous for two BIGINT members or a nested
+UNION with a member name of the outer UNION. An intermediate UNION with only
+the active member still fails for the nested UNION and for a STRUCT that
+DuckDB interprets as the STRUCT form of a UNION. Casting a STRUCT with a
+UTINYINT tag and one field per member is another alternative, but the header
+does not document that cast.
+
+The vector construction uses the documented layout and writes. It requires
+FLAT child vectors. DuckDB 2.0.0 supplies them in a new vector, but the header
+does not guarantee this for the children. A change can make the writes fail
+or give a wrong value. See Note [Vector flatten] in
+"Database.DuckDB.Simple.Materialize". Regression cases check the selected
+member at the 255-member limit and a NULL payload in ValueRegressionTests.hs
+("a UNION value binds the member of its tag up to the member limit of DuckDB"
+and "UNION NULL payload retains its member type"). Spec.hs also checks
+"round-trips struct and union parameters".
+-}
+
+-- | Build one UNION row through its tag and member vectors. See
+-- Note [UNION values].
+unionValueDuckValue
+  :: ValueBuilder -> UnionValue FieldValue -> IO DuckDBV2ValueHandle
+unionValueDuckValue builder@ValueBuilder{builderFactory = factory, builderType = makeType} UnionValue{unionValueIndex, unionValueLabel, unionValuePayload, unionValueMembers} = do
+  let members = elems unionValueMembers
+      index = fromIntegral unionValueIndex
+  when (index >= length members) $ throwInvalidArgument "union value tag out of range"
+  let UnionMemberType name rep = members !! index
+  when (name /= unionValueLabel) $ throwInvalidArgument "union tag and member name mismatch"
+  bracket (makeType (LogicalTypeUnion unionValueMembers)) destroyLogicalType \logical ->
+    withOwnedVector factory logical \vector -> do
+      checked (c_duckdb_v2_vector_set_size vector 1)
+      tag <- output (c_duckdb_v2_vector_get_child vector 0)
+      checked (c_duckdb_v2_vector_set_size tag 1)
+      bracket (uint8DuckValue factory (fromIntegral index)) destroyValue \value ->
+        checked (c_duckdb_v2_vector_set_value tag 0 value)
+      forM_ [0 .. length members - 1] \memberIndex -> do
+        member <- output (c_duckdb_v2_vector_get_child vector (fromIntegral memberIndex + 1))
+        checked (c_duckdb_v2_vector_set_size member 1)
+        if memberIndex == index
+          then bracket (fieldValueWithTypeDuckValue builder rep unionValuePayload) destroyValue \value ->
+            checked (c_duckdb_v2_vector_set_value member 0 value)
+          else checked (c_duckdb_v2_vector_set_null member 0)
+      output (c_duckdb_v2_vector_get_value vector 0)
+
+{- Note [TIME alias values]
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+DuckDB 2.0.0 rejects the default cast from TIME to a TIME alias. The public
+API specifies that an alias keeps its base representation. TIME vector data
+uses int64 microseconds since midnight, as encodeTimeOfDay does. Thus a checked
+TIME payload can be written through vector_get_data_mutable without a cast.
+vector_get_value preserves the declared alias. The owned vector has one FLAT
+row, and its validity is set explicitly. NULL uses value_create_null instead.
+-}
+
+-- | Construct a value with explicit logical metadata, including typed NULL.
+fieldValueWithTypeDuckValue
+  :: ValueBuilder -> LogicalTypeRep -> FieldValue -> IO DuckDBV2ValueHandle
+fieldValueWithTypeDuckValue ValueBuilder{builderFactory = factory, builderType = makeType} rep FieldNull = bracket (makeType rep) destroyLogicalType \logical ->
+  output (c_duckdb_v2_value_create_null factory logical)
+fieldValueWithTypeDuckValue builder@ValueBuilder{builderFactory = factory, builderType = makeType} rep value = case (rep, value) of
+  (LogicalTypeAlias _ base, FieldTime time)
+    | withoutAliases base == LogicalTypeScalar LogicalTypeIdTime -> do
+        -- See Note [TIME alias values].
+        micros <- encodeTimeOfDay time
+        bracket (makeType rep) destroyLogicalType \logical -> withOwnedVector factory logical \vector -> do
+          checked (c_duckdb_v2_vector_flatten vector)
+          checked (c_duckdb_v2_vector_set_size vector 1)
+          raw <- output (c_duckdb_v2_vector_get_data_mutable vector)
+          poke (castPtr raw) micros
+          validity <- output (c_duckdb_v2_vector_flat_get_validity_mutable vector)
+          peek validity >>= poke validity . (.|. 1)
+          output (c_duckdb_v2_vector_get_value vector 0)
+  -- A value of the base type. DuckDB casts it to the alias type. See
+  -- Note [Type aliases] in "Database.DuckDB.Simple.LogicalRep".
+  (LogicalTypeAlias _ base, _) -> fieldValueWithTypeDuckValue builder base value
+  (LogicalTypeScalar LogicalTypeIdVariant, _) -> variantDuckValue builder value
+  (LogicalTypeScalar dtype, _) -> scalarFieldValueDuckValue factory dtype value
+  (LogicalTypeCollatedVarchar _, FieldText text) -> textDuckValue factory text
+  (LogicalTypeGeometry crs, FieldGeometry raw) -> rawGeometryDuckValue builder crs raw
+  (LogicalTypeDecimal width scale, FieldDecimal decimal@DecimalValue{decimalWidth, decimalScale})
+    | width == decimalWidth && scale == decimalScale -> decimalDuckValue factory decimal
+  (LogicalTypeList child, FieldList values) -> sequenceValue c_duckdb_v2_value_create_list child values
+  (LogicalTypeArray child size, FieldArray array)
+    | fromIntegral (length (elems array)) == size -> do
+        sequence_ (arraySizeError (length (elems array)))
+        sequenceValue c_duckdb_v2_value_create_array child (elems array)
+  (LogicalTypeMap keyRep valueRep, FieldMap pairs) ->
+    bracket (makeType keyRep) destroyLogicalType \keyType ->
+      bracket (makeType valueRep) destroyLogicalType \valueType ->
+        withCreatedValues (map (fieldValueWithTypeDuckValue builder keyRep . fst) pairs) \keys ->
+          withCreatedValues (map (fieldValueWithTypeDuckValue builder valueRep . snd) pairs) \values ->
+            withArray keys \keyPtr -> withArray values \valuePtr ->
+              output (c_duckdb_v2_value_create_map factory keyType valueType (ConstPtr keyPtr) (ConstPtr valuePtr) (fromIntegral (length pairs)))
+  (LogicalTypeStruct _, FieldStruct struct)
+    | sameBase (structValueTypeRep struct) -> structValueDuckValue builder struct
+  (LogicalTypeTuple _, FieldTuple tuple)
+    | sameBase (tupleValueTypeRep tuple) -> tupleValueDuckValue builder tuple
+  (LogicalTypeUnion _, FieldUnion union)
+    | sameBase (unionValueTypeRep union) -> unionValueDuckValue builder union
+  (LogicalTypeEnum entries, FieldEnum _ label) -> enumDuckValue factory entries label
+  _ -> typeMismatch rep value
+  where
+    -- See Note [Type aliases] in "Database.DuckDB.Simple.LogicalRep".
+    sameBase other = withoutAliases rep == withoutAliases other
+    sequenceValue create child values = bracket (makeType child) destroyLogicalType \logical ->
+      withCreatedValues (map (fieldValueWithTypeDuckValue builder child) values) \native -> withArray native \ptr ->
+        output (create factory logical (ConstPtr ptr) (fromIntegral (length native)))
+
+scalarFieldValueDuckValue :: DuckDBV2FactoryHandle -> LogicalTypeId -> FieldValue -> IO DuckDBV2ValueHandle
+scalarFieldValueDuckValue factory dtype value = case (dtype, value) of
+  (LogicalTypeIdBoolean, FieldBool b) -> boolDuckValue factory b
+  (LogicalTypeIdTinyInt, FieldInt8 i) -> int8DuckValue factory i
+  (LogicalTypeIdSmallInt, FieldInt16 i) -> int16DuckValue factory i
+  (LogicalTypeIdInteger, FieldInt32 i) -> int32DuckValue factory i
+  (LogicalTypeIdBigInt, FieldInt64 i) -> int64DuckValue factory i
+  (LogicalTypeIdUTinyInt, FieldWord8 w) -> uint8DuckValue factory w
+  (LogicalTypeIdUSmallInt, FieldWord16 w) -> uint16DuckValue factory w
+  (LogicalTypeIdUInteger, FieldWord32 w) -> uint32DuckValue factory w
+  (LogicalTypeIdUBigInt, FieldWord64 w) -> uint64DuckValue factory w
+  (LogicalTypeIdFloat, FieldFloat f) -> floatDuckValue factory f
+  (LogicalTypeIdDouble, FieldDouble d) -> doubleDuckValue factory d
+  (LogicalTypeIdVarchar, FieldText t) -> textDuckValue factory t
+  (LogicalTypeIdBlob, FieldBlob b) -> blobDuckValue factory b
+  -- The type id has no CRS. See Note [Raw GEOMETRY parameters].
+  (LogicalTypeIdGeometry, FieldGeometry raw) -> rawGeometryDuckValue (plainBuilder factory) Nothing raw
+  (LogicalTypeIdUUID, FieldUUID u) -> uuidDuckValue factory u
+  (LogicalTypeIdBit, FieldBit bits) -> bitDuckValue factory bits
+  (LogicalTypeIdDate, FieldDate d) -> dateDuckValue factory d
+  (LogicalTypeIdTime, FieldTime t) -> timeOfDayDuckValue factory t
+  (LogicalTypeIdTimeNs, FieldTime t) ->
+    timeOfDayUnits 1000000000 t >>= (\encoded -> output (c_duckdb_v2_value_create_time_ns factory encoded)) . fromInteger
+  (LogicalTypeIdTimeTz, FieldTimeTZ tz) -> timeWithZoneDuckValue factory tz
+  (LogicalTypeIdTimestamp, FieldTimestamp ts) -> localTimestampDuckValue factory ts
+  (LogicalTypeIdTimestampSec, FieldTimestamp ts) ->
+    encodeUnbounded (encodeTimestampUnits 1) ts >>= (\encoded -> output (c_duckdb_v2_value_create_timestamp_sec factory encoded))
+  (LogicalTypeIdTimestampMs, FieldTimestamp ts) ->
+    encodeUnbounded (encodeTimestampUnits 1000) ts >>= (\encoded -> output (c_duckdb_v2_value_create_timestamp_ms factory encoded))
+  (LogicalTypeIdTimestampNs, FieldTimestamp ts) ->
+    encodeUnbounded (encodeTimestampUnits 1000000000) ts >>= (\encoded -> output (c_duckdb_v2_value_create_timestamp_ns factory encoded))
+  (LogicalTypeIdTimestampTz, FieldTimestampTZ ts) -> utcTimestampDuckValue factory ts
+  (LogicalTypeIdTimestampTzNs, FieldTimestampTZ ts) -> utcTimestampNsDuckValue factory ts
+  (LogicalTypeIdInterval, FieldInterval iv) -> intervalDuckValue factory iv
+  (LogicalTypeIdHugeInt, FieldHugeInt i) -> hugeIntDuckValue factory i
+  (LogicalTypeIdUHugeInt, FieldUHugeInt i) -> uhugeIntDuckValue factory i
+  (LogicalTypeIdBigNum, FieldBigNum big) -> bigNumDuckValue factory big
+  _ ->
+    throwInvalidArgument
+      ("unsupported scalar conversion for " <> logicalTypeSQL (LogicalTypeScalar dtype) <> " from a value of type " <> valueTypeName value)
+
+-- | Construct an ENUM value by the default cast of the label to the ENUM type.
+-- The label of a 'FieldEnum' gives the value, not its index: an index of
+-- another dictionary would give another label with no error. A label that is
+-- not in the dictionary raises an t'SQLError' of the type 'ErrorTypeConversion',
+-- as the cast of DuckDB from VARCHAR does. See
+-- Note [User casts and the casts of the library] in
+-- "Database.DuckDB.Simple.Materialize".
+enumDuckValue :: DuckDBV2FactoryHandle -> Array Int Text -> Text -> IO DuckDBV2ValueHandle
+enumDuckValue factory entries label = do
+  unless (label `elem` elems entries) $
+    throwConversionError ("the ENUM label '" <> label <> "' is not in the dictionary of the type")
+  bracket (logicalTypeFromRep factory (LogicalTypeEnum entries)) destroyLogicalType \logical ->
+    bracket (textDuckValue factory label) destroyValue \value ->
+      defaultCast factory value logical
+
+-- | Cast a value to a type with the default cast of DuckDB
+-- ('withDefaultCastVector' with one row). The caller destroys the result. See
+-- Note [User casts and the casts of the library] in
+-- "Database.DuckDB.Simple.Materialize".
+defaultCast :: DuckDBV2FactoryHandle -> DuckDBV2ValueHandle -> DuckDBV2LogicalTypeHandle -> IO DuckDBV2ValueHandle
+defaultCast factory value logical =
+  withDefaultCastVector factory logical 1 (\_ write -> write value) \vector -> output (c_duckdb_v2_vector_get_value vector 0)
+
+hugeIntDuckValue :: DuckDBV2FactoryHandle -> Integer -> IO DuckDBV2ValueHandle
+hugeIntDuckValue factory value = integerToHugeInt value >>= \huge -> with huge (\ptr -> output (c_duckdb_v2_value_create_hugeint factory (ConstPtr ptr)))
+
+uhugeIntDuckValue :: DuckDBV2FactoryHandle -> Integer -> IO DuckDBV2ValueHandle
+uhugeIntDuckValue factory value = integerToUHugeInt value >>= \huge -> with huge (\ptr -> output (c_duckdb_v2_value_create_uhugeint factory (ConstPtr ptr)))
+
+decimalDuckValue :: DuckDBV2FactoryHandle -> DecimalValue -> IO DuckDBV2ValueHandle
+decimalDuckValue factory DecimalValue{decimalWidth, decimalScale, decimalInteger} = do
+  when (decimalWidth < 1 || decimalWidth > 38 || decimalScale > decimalWidth) $
+    throwInvalidArgument "invalid DECIMAL width or scale"
+  when (abs decimalInteger >= 10 ^ decimalWidth) $ throwConversionError "DECIMAL value exceeds declared precision"
+  huge <- integerToHugeInt decimalInteger
+  with huge (\ptr -> output (c_duckdb_v2_value_create_decimal factory (ConstPtr ptr) decimalWidth decimalScale))
+
+intervalDuckValue :: DuckDBV2FactoryHandle -> IntervalValue -> IO DuckDBV2ValueHandle
+intervalDuckValue factory IntervalValue{intervalMonths, intervalDays, intervalMicros} =
+  with
+    (DuckDBV2IntervalT intervalMonths intervalDays intervalMicros)
+    (\ptr -> output (c_duckdb_v2_value_create_interval factory (ConstPtr ptr)))
+
+timeWithZoneDuckValue :: DuckDBV2FactoryHandle -> TimeWithZone -> IO DuckDBV2ValueHandle
+timeWithZoneDuckValue factory TimeWithZone{timeWithZoneTime, timeWithZoneOffsetSeconds} = do
+  micros <- timeOfDayUnits 1000000 timeWithZoneTime
+  let offset = toInteger timeWithZoneOffsetSeconds
+  when (abs offset > toInteger timeTzMaxOffsetSeconds) $
+    throwConversionError
+      ("the TIMETZ offset " <> Text.pack (show offset) <> " seconds is out of range; DuckDB stores an offset from -57599 to 57599 seconds")
+  output
+    ( c_duckdb_v2_value_create_time_tz
+        factory
+        ((fromIntegral micros `shiftL` timeTzOffsetBits) .|. fromIntegral (toInteger timeTzMaxOffsetSeconds - offset))
+    )
+
+integerToHugeInt :: Integer -> IO DuckDBV2HugeintT
+integerToHugeInt value = do
+  when (value < negate (1 `shiftL` 127) || value >= 1 `shiftL` 127) $ throwConversionError "HUGEINT value out of range"
+  pure (DuckDBV2HugeintT (fromIntegral value) (fromIntegral (value `shiftR` 64)))
+
+integerToUHugeInt :: Integer -> IO DuckDBV2UhugeintT
+integerToUHugeInt value = do
+  when (value < 0 || value >= 1 `shiftL` 128) $ throwConversionError "UHUGEINT value out of range"
+  pure (DuckDBV2UhugeintT (fromIntegral value) (fromIntegral (value `shiftR` 64)))
+
+-- | Borrow generated identifier views and reject embedded NUL bytes.
+withIdentifiers :: [Text] -> (Ptr DuckDBV2IdentifierT -> IO a) -> IO a
+withIdentifiers names action = do
+  when (any (Text.any (== '\0')) names) $
+    throwInvalidArgument "logical type name contains NUL"
+  withIdentifierArray names action
+
+-- | Raise the error of a value that does not fit its declared type. The text
+-- names the type as DuckDB does. See Note [Type texts] in
+-- "Database.DuckDB.Simple.LogicalRep".
+typeMismatch :: LogicalTypeRep -> FieldValue -> IO a
+typeMismatch expected actual = throwInvalidArgument ("cannot encode a value of type " <> valueTypeName actual <> " as " <> logicalTypeSQL expected)
+
+-- | Construct a GEOMETRY value of the declared CRS from a raw geometry. See
+-- Note [Raw GEOMETRY parameters], and Note [User casts and the casts of the library] in
+-- "Database.DuckDB.Simple.Materialize".
+rawGeometryDuckValue :: ValueBuilder -> Maybe Text -> RawGeometry -> IO DuckDBV2ValueHandle
+rawGeometryDuckValue ValueBuilder{builderFactory = factory, builderType = makeType} crs RawGeometry{rawGeometryWKB, rawGeometryCRS} = do
+  when (rawGeometryCRS /= crs) $
+    throwInvalidArgument ("a GEOMETRY value with " <> describeCRS rawGeometryCRS <> " cannot bind as a GEOMETRY with " <> describeCRS crs)
+  bracket (makeType (LogicalTypeGeometry crs)) destroyLogicalType \logical ->
+    bracket (blobDuckValue factory rawGeometryWKB) destroyValue \blob ->
+      defaultCast factory blob logical
+  where
+    describeCRS = maybe "no CRS" (("the CRS " <>) . quotedCRS)
+
+-- | Put a CRS between single quotes for an error message.
+quotedCRS :: Text -> Text
+quotedCRS crs = "'" <> crs <> "'"
+
+{- Note [Raw GEOMETRY parameters]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+RawGeometry holds WKB bytes and an optional CRS. GEOMETRY results use this
+representation, including FieldGeometry values inside composite values.
+rawGeometryDuckValue casts a BLOB of the bytes to the declared GEOMETRY type.
+It uses the default cast, so a user cast cannot change the value. See
+Note [User casts and the casts of the library] in
+"Database.DuckDB.Simple.Materialize".
+
+A top-level RawGeometry parameter declares its own CRS. DuckDB then applies
+the casts of SQL text to the parameter's target type:
+
+- A value without a CRS takes the CRS of a target that has one.
+- A target without a CRS removes the CRS without an error.
+- A target with another CRS raises "Binder Error: Cannot cast GEOMETRY with
+  CRS ... to GEOMETRY with different CRS ...". A comparison with = has the
+  same rule.
+
+In a STRUCT, TUPLE, or UNION, the CRS of each raw geometry must equal its
+declared CRS, including when both have no CRS. A mismatch raises SQLError
+with ErrorInputInvalid. The BLOB cast assigns the declared CRS without
+checking the original label, so omitting this check could change or remove
+the label silently. The statement builder resolves CRS types at bind time.
+See Note [Bind-time CRS types] in "Database.DuckDB.Simple.V2.LogicalRep".
+A plain GEOMETRY declaration has no CRS and uses the factory's plain builder.
+
+A VARIANT accepts raw geometry only without a CRS. DuckDB silently removes
+CRS metadata when it casts GEOMETRY to VARIANT, so the binding rejects a
+CRS-tagged payload with ErrorInputInvalid. RawGeometry has no
+DuckDBColumnType or ToDuckValue instance. A list or SizedArray of RawGeometry,
+or a typed row containing it, would declare GEOMETRY without a CRS and lose
+the labels.
+
+An instance factory cannot construct a GEOMETRY type with a CRS. It raises
+"Binder Error: Cannot create GEOMETRY type with coordinate system without a
+connection". This limits toDuckValue for composite values with CRS-tagged
+geometry leaves, including typed NULLs. A connection factory has no such
+limit.
+
+DuckDB 2.0.0 stores GEOMETRY as WKB. The BLOB cast and ST_GeomFromWKB both use
+Geometry::FromBinary (src/function/cast/geo_casts.cpp and
+src/function/scalar/geometry/geometry_functions.cpp). The result reader casts
+GEOMETRY to BLOB with Geometry::ToBinary, which copies the stored bytes
+(src/common/types/geometry.cpp). Thus a result binds again with the same
+bytes. Import can normalize other input: big-endian WKB and EWKB become
+little-endian ISO WKB. It rejects collections with different Z/M member
+layouts. GeometryRegressionTests.hs covers result rebinding, top-level CRS
+casts, composite CRS mismatches, and nested typed NULLs.
+-}
+
+-- | Cast the payload to VARIANT with the default cast of DuckDB. See
+-- Note [User casts and the casts of the library] in
+-- "Database.DuckDB.Simple.Materialize".
+variantDuckValue :: ValueBuilder -> FieldValue -> IO DuckDBV2ValueHandle
+variantDuckValue builder@ValueBuilder{builderFactory = factory, builderType = makeType} value = do
+  (rep, payload) <- variantPayloadType value
+  bracket (makeType (LogicalTypeScalar LogicalTypeIdVariant)) destroyLogicalType \logical ->
+    bracket (fieldValueWithTypeDuckValue builder rep payload) destroyValue \native ->
+      defaultCast factory native logical
+
+-- | Construct a UTC nanosecond value without losing sub-microsecond digits.
+utcTimestampNsDuckValue :: DuckDBV2FactoryHandle -> UTCTimestamp -> IO DuckDBV2ValueHandle
+utcTimestampNsDuckValue factory value =
+  encodeUnbounded (encodeTimestampUnits 1000000000 . utcToLocalTime utc) value
+    >>= (\encoded -> output (c_duckdb_v2_value_create_timestamp_tz_ns factory encoded))
+
+-- | Cast the WKT text of the shape to GEOMETRY with the default cast of DuckDB.
+-- See Note [User casts and the casts of the library] in
+-- <src/Database.DuckDB.Simple.Materialize.html Database.DuckDB.Simple.Materialize>.
+instance ToDuckValue G.Geometry where
+  toDuckValue factory geometry = do
+    wkt <- either (throwInvalidArgument . Text.pack) pure (WKT.encodeWKT geometry)
+    bracket (logicalTypeFromRep factory (LogicalTypeGeometry Nothing)) destroyLogicalType \logical ->
+      bracket (textDuckValue factory wkt) destroyValue \value ->
+        defaultCast factory value logical
+
+instance ToDuckValue Variant where
+  toDuckValue factory = variantDuckValue (plainBuilder factory) . variantPayload
+
+-- | Choose the native type of a VARIANT payload. Containers get VARIANT
+-- elements and fields. A time value with digits below a microsecond uses the
+-- nanosecond type when it fits the range of that type (fitsNanoseconds). Each
+-- other time value uses the microsecond type, as a VARIANT parameter does. See
+-- Note [Nanosecond parameters].
+-- The C API cannot construct a nonempty object whose keys are all empty.
+-- DuckDB 2.0 treats that STRUCT type as a tuple and casts it to a VARIANT array.
+-- A raw geometry without a CRS uses GEOMETRY. See Note [Raw GEOMETRY parameters].
+-- A VARIANT does not keep a UNION, a MAP, an ENUM, or the CRS of a geometry, so
+-- each of these payloads raises an error, at each depth.
+variantPayloadType :: FieldValue -> IO (LogicalTypeRep, FieldValue)
+variantPayloadType value = case value of
+  FieldNull -> pure (variant, value)
+  FieldBool{} -> scalar LogicalTypeIdBoolean
+  FieldInt8{} -> scalar LogicalTypeIdTinyInt
+  FieldInt16{} -> scalar LogicalTypeIdSmallInt
+  FieldInt32{} -> scalar LogicalTypeIdInteger
+  FieldInt64{} -> scalar LogicalTypeIdBigInt
+  FieldWord8{} -> scalar LogicalTypeIdUTinyInt
+  FieldWord16{} -> scalar LogicalTypeIdUSmallInt
+  FieldWord32{} -> scalar LogicalTypeIdUInteger
+  FieldWord64{} -> scalar LogicalTypeIdUBigInt
+  FieldHugeInt{} -> scalar LogicalTypeIdHugeInt
+  FieldUHugeInt{} -> scalar LogicalTypeIdUHugeInt
+  FieldFloat{} -> scalar LogicalTypeIdFloat
+  FieldDouble{} -> scalar LogicalTypeIdDouble
+  FieldDecimal DecimalValue{decimalWidth, decimalScale} -> pure (LogicalTypeDecimal decimalWidth decimalScale, value)
+  FieldText{} -> scalar LogicalTypeIdVarchar
+  FieldBlob{} -> scalar LogicalTypeIdBlob
+  FieldUUID{} -> scalar LogicalTypeIdUUID
+  FieldDate{} -> scalar LogicalTypeIdDate
+  FieldTime time
+    | hasSubMicroseconds time -> scalar LogicalTypeIdTimeNs
+    | otherwise -> scalar LogicalTypeIdTime
+  FieldTimestamp (Finite LocalTime{localTimeOfDay})
+    | hasSubMicroseconds localTimeOfDay && fitsNanoseconds value -> scalar LogicalTypeIdTimestampNs
+  FieldTimestamp{} -> scalar LogicalTypeIdTimestamp
+  FieldTimestampTZ (Finite instant)
+    | hasSubMicroseconds (localTimeOfDay (utcToLocalTime utc instant)) && fitsNanoseconds value -> scalar LogicalTypeIdTimestampTzNs
+  FieldTimestampTZ{} -> scalar LogicalTypeIdTimestampTz
+  FieldTimeTZ{} -> scalar LogicalTypeIdTimeTz
+  FieldInterval{} -> scalar LogicalTypeIdInterval
+  FieldBigNum{} -> scalar LogicalTypeIdBigNum
+  FieldBit{} -> scalar LogicalTypeIdBit
+  FieldList{} -> pure (LogicalTypeList variant, value)
+  FieldArray items -> pure (LogicalTypeList variant, FieldList (elems items))
+  FieldTuple TupleValue{tupleValueFields} -> pure (LogicalTypeList variant, FieldList (elems tupleValueFields))
+  FieldStruct structValue@StructValue{structValueTypes} -> do
+    let names = map structFieldName (elems structValueTypes)
+    when (Set.size (Set.fromList names) /= length names) $
+      throwInvalidArgument "VARIANT objects need unique keys"
+    when (names == [Text.empty]) $
+      throwInvalidArgument "DuckDB's C API cannot construct a VARIANT object with only an empty key"
+    let types = fmap (\field -> field{structFieldValue = variant}) structValueTypes
+    pure (LogicalTypeStruct types, FieldStruct structValue{structValueTypes = types})
+  FieldUnion{} -> throwInvalidArgument "a VARIANT keeps only the member value of a UNION, so a UNION value cannot bind as a VARIANT"
+  FieldGeometry RawGeometry{rawGeometryCRS = Just crs} ->
+    throwInvalidArgument
+      ("a VARIANT does not keep the CRS of a GEOMETRY, so the GEOMETRY value with the CRS " <> quotedCRS crs <> " cannot bind as a VARIANT")
+  FieldGeometry{} -> pure (LogicalTypeGeometry Nothing, value)
+  FieldMap{} -> throwInvalidArgument "a VARIANT stores a MAP as a list of key and value objects, so a MAP value cannot bind as a VARIANT"
+  FieldEnum{} -> throwInvalidArgument "a VARIANT stores an ENUM as its text, so an ENUM value cannot bind as a VARIANT"
+  where
+    variant = LogicalTypeScalar LogicalTypeIdVariant
+    scalar dtype = pure (LogicalTypeScalar dtype, value)
+
+instance ToDuckValue Null where
+  toDuckValue factory _ = nullDuckValue factory
+
+instance ToDuckValue Bool where
+  toDuckValue = boolDuckValue
+
+instance ToDuckValue Int where
+  toDuckValue factory = int64DuckValue factory . fromIntegral
+
+instance ToDuckValue Int8 where
+  toDuckValue = int8DuckValue
+
+instance ToDuckValue Int16 where
+  toDuckValue = int16DuckValue
+
+instance ToDuckValue Int32 where
+  toDuckValue = int32DuckValue
+
+instance ToDuckValue Int64 where
+  toDuckValue = int64DuckValue
+
+instance ToDuckValue BigNum where
+  toDuckValue = bigNumDuckValue
+
+instance ToDuckValue UUID.UUID where
+  toDuckValue = uuidDuckValue
+
+-- | A value from -2^127 to 2^127 - 1 gives a HUGEINT value. Each other value
+-- raises an error. See Note [Integer parameters].
+instance ToDuckValue Integer where
+  toDuckValue factory value = case hugeIntInRange value of
+    Just make -> make factory
+    Nothing -> outsideRange "HUGEINT" value
+
+-- | A value from 0 to 2^127 - 1 gives a HUGEINT value, and a value up to
+-- 2^128 - 1 a UHUGEINT value. Each larger value raises an error. See
+-- Note [Integer parameters].
+instance ToDuckValue Natural where
+  toDuckValue factory value = case hugeIntInRange (toInteger value) of
+    Just make -> make factory
+    Nothing
+      | toInteger value < 1 `shiftL` 128 -> uhugeIntDuckValue factory (toInteger value)
+      | otherwise -> outsideRange "UHUGEINT" (toInteger value)
+
+-- | Raise the range error of 'toDuckValue' for an 'Integer' or a 'Natural'
+-- outside the declared type. See Note [Integer parameters].
+outsideRange :: Text -> Integer -> IO a
+outsideRange typeName value =
+  throwConversionError
+    ("the value " <> Text.pack (show value) <> " is outside the range of " <> typeName <> ". Use BigNum for a larger value.")
+
+instance ToDuckValue Word where
+  toDuckValue factory = uint64DuckValue factory . fromIntegral
+
+instance ToDuckValue Word16 where
+  toDuckValue = uint16DuckValue
+
+instance ToDuckValue Word32 where
+  toDuckValue = uint32DuckValue
+
+instance ToDuckValue Word64 where
+  toDuckValue = uint64DuckValue
+
+instance ToDuckValue Word8 where
+  toDuckValue = uint8DuckValue
+
+instance ToDuckValue Double where
+  toDuckValue = doubleDuckValue
+
+instance ToDuckValue Float where
+  toDuckValue = floatDuckValue
+
+instance ToDuckValue Text where
+  toDuckValue = textDuckValue
+
+instance ToDuckValue String where
+  toDuckValue = stringDuckValue
+
+instance ToDuckValue BS.ByteString where
+  toDuckValue = blobDuckValue
+
+instance ToDuckValue BitString where
+  toDuckValue = bitDuckValue
+
+instance ToDuckValue Day where
+  toDuckValue = dayDuckValue
+
+instance ToDuckValue TimeOfDay where
+  toDuckValue = timeOfDayDuckValue
+
+instance ToDuckValue LocalTime where
+  toDuckValue = localTimeDuckValue
+
+instance ToDuckValue IntervalValue where
+  toDuckValue = intervalDuckValue
+
+instance ToDuckValue TimeWithZone where
+  toDuckValue = timeWithZoneDuckValue
+
+instance ToDuckValue UTCTime where
+  toDuckValue = utcTimeDuckValue
+
+instance ToDuckValue (Unbounded Day) where
+  toDuckValue = dateDuckValue
+
+instance ToDuckValue (Unbounded LocalTime) where
+  toDuckValue = localTimestampDuckValue
+
+instance ToDuckValue (Unbounded UTCTime) where
+  toDuckValue = utcTimestampDuckValue
+
+instance ToDuckValue (StructValue FieldValue) where
+  toDuckValue = structValueDuckValue . plainBuilder
+
+instance ToDuckValue (TupleValue FieldValue) where
+  toDuckValue = tupleValueDuckValue . plainBuilder
+
+instance ToDuckValue (UnionValue FieldValue) where
+  toDuckValue = unionValueDuckValue . plainBuilder
+
+-- | Construct a MAP through the supplied factory with the key type of @k@ and
+-- the value type of @v@. The pairs go in ascending key order. A structured
+-- declaration of a part is its target. See Note [Type declarations].
+instance (DuckDBColumnType k, DuckDBColumnType v, ToDuckValue k, ToDuckValue v) => ToDuckValue (Map.Map k v) where
+  toDuckValue factory =
+    mapDuckValue
+      (withElementType (Proxy @k) builder (declaredTarget (Proxy @k)))
+      (withElementType (Proxy @v) builder (declaredTarget (Proxy @v)))
+      builder
+      (toDuckValue factory)
+      (toDuckValue factory)
+      . Map.toAscList
+    where
+      builder = plainBuilder factory
+
+-- | Construct an ARRAY of size @n@ through the supplied factory with the
+-- element type of @a@. A structured declaration of @a@ is the target of the
+-- elements. See Note [Sized arrays].
+instance (KnownNat n, DuckDBColumnType a, ToDuckValue a) => ToDuckValue (SizedArray n a) where
+  toDuckValue factory = arrayDuckValue (plainBuilder factory) (declaredTarget (Proxy @a)) (toDuckValue factory) . elems . sizedArrayToArray
+
+-- | Construct a LIST through the supplied factory with the element type of @a@.
+-- 'String' keeps its own instance. A structured declaration of @a@ is the
+-- target of the elements. See Note [Type declarations].
+instance {-# OVERLAPPABLE #-} (DuckDBColumnType a, ToDuckValue a) => ToDuckValue [a] where
+  toDuckValue factory = listDuckValue (plainBuilder factory) (declaredTarget (Proxy @a)) (toDuckValue factory)
+
+instance (ToDuckValue a) => ToDuckValue (Maybe a) where
+  toDuckValue factory Nothing = nullDuckValue factory
+  toDuckValue factory (Just value) = toDuckValue factory value
+
+-- | Preserve infinity sentinels and validate finite values before narrowing.
+encodeUnbounded :: (Integral b, Bounded b) => (a -> IO b) -> Unbounded a -> IO b
+encodeUnbounded _ NegInfinity = pure (negate maxBound)
+encodeUnbounded _ PosInfinity = pure maxBound
+encodeUnbounded encode (Finite value) = encode value
+
+-- | Encode finite dates as days from the Unix epoch. A day outside the range
+-- of DuckDB raises an error. See Note [Time ranges].
+encodeDay :: Day -> IO Int32
+encodeDay day = do
+  let days = diffDays day (fromGregorian 1970 1 1)
+  when (days < -2147483646) $
+    throwOutsideTimeRange (show day) "below the smallest DATE of DuckDB, -5877641-06-25"
+  when (days > 2147483646) $
+    throwOutsideTimeRange (show day) "above the largest DATE of DuckDB, 5881580-07-10"
+  pure (fromInteger days)
+
+-- | Encode a time of day at DuckDB microsecond precision.
+encodeTimeOfDay :: TimeOfDay -> IO Int64
+encodeTimeOfDay tod = fromInteger <$> timeOfDayUnits 1000000 tod
+
+-- | Encode finite timestamps without native calendar conversions.
+encodeLocalTime :: LocalTime -> IO Int64
+encodeLocalTime = encodeTimestampUnits 1000000
+
+-- | Encode finite timestamps in the requested number of units per second.
+-- See Note [Time ranges].
+encodeTimestampUnits :: Integer -> LocalTime -> IO Int64
+encodeTimestampUnits units value@LocalTime{localTimeOfDay} = do
+  -- timeOfDayUnits checks the time of day.
+  _ <- timeOfDayUnits units localTimeOfDay
+  checkTimestampRange units value
+  let total = timestampUnits units value
+  -- Only a nanosecond value reaches this check with a value outside the
+  -- storage or at an infinity value. See Note [Time ranges].
+  checkFiniteRange "TIMESTAMP" (minBound :: Int64) maxBound total
+  pure (fromInteger total)
+
+{- Note [Time ranges]
+~~~~~~~~~~~~~~~~~~~~~
+The storage of a DATE and of a TIMESTAMP can hold values that DuckDB 2.0.0
+does not accept. The SQL literal of each type, and the casts to it, reject
+these values:
+
+- DATE: from -5877641-06-25 (5877642-06-25 BC) to 5881580-07-10, days
+  -2147483646 to 2147483646 from the Unix epoch. The INT32 storage also holds
+  day -2147483648.
+
+- TIMESTAMP, TIMESTAMPTZ, TIMESTAMP_S, and TIMESTAMP_MS: from -290308-12-22
+  00:00:00 (290309-12-22 BC) to 294247-01-10 04:00:54.775806, microseconds
+  -9223372022400000000 to 2^63 - 2. The INT64 storage of a microsecond value
+  also holds about four hours before that start, and the storage of a second
+  or a millisecond value holds much more at each end.
+
+A value outside these ranges breaks ordinary SQL in DuckDB 2.0.0. A cast of
+such a TIMESTAMP to VARCHAR raises an INTERNAL error, and DuckDB then
+invalidates the database. A cast of such a TIMESTAMP to TIMESTAMP_S stores the
+first valid value with no error. A DATE before the range sorts before
+-infinity, and a cast of it to TIMESTAMP fails. Thus encodeDay and
+encodeTimestampUnits raise an SQLError of the type ErrorTypeConversion for
+each finite value outside these ranges (throwOutsideTimeRange), before any
+check of the storage, so a value outside the storage and a value at an
+infinity value get this error too. The text names the value and the end of
+the range in the notation of Data.Time, where the year -5877641 is 5877642 BC.
+A nanosecond value has the range of its INT64 storage, and the literal of
+TIMESTAMP_NS accepts that range, so it gets no check here. checkFiniteRange
+then catches only a nanosecond value outside its storage or at an infinity
+value.
+
+A leap second gets no check. A TimeOfDay with 60 seconds binds as the next
+second, as make_time(23, 59, 60) and make_timestamp(2016, 12, 31, 23, 59, 60)
+of DuckDB give it. The SQL literal '23:59:60' raises an error.
+-}
+
+-- | Reject a second, millisecond, or microsecond timestamp outside the range
+-- of DuckDB. See Note [Time ranges].
+checkTimestampRange :: Integer -> LocalTime -> IO ()
+checkTimestampRange units value
+  | units > 1000000 = pure ()
+  | micros < -9223372022400000000 =
+      throwOutsideTimeRange (show value) ("below the smallest " <> name <> " of DuckDB, -290308-12-22 00:00:00")
+  | micros > 9223372036854775806 = throwOutsideTimeRange (show value) ("above the largest " <> name <> " of DuckDB, " <> largest)
+  | otherwise = pure ()
+  where
+    micros = timestampUnits 1000000 value
+    (name, largest) = case units of
+      1 -> ("TIMESTAMP_S", "294247-01-10 04:00:54")
+      1000 -> ("TIMESTAMP_MS", "294247-01-10 04:00:54.775")
+      _ -> ("TIMESTAMP", "294247-01-10 04:00:54.775806")
+
+-- | Raise the error for a date or a timestamp outside the range of DuckDB. The
+-- text names the Haskell value and the end of the range. See
+-- Note [Time ranges].
+throwOutsideTimeRange :: String -> Text -> IO a
+throwOutsideTimeRange value bound = throwConversionError ("the value " <> Text.pack value <> " is " <> bound)
+
+-- | Count the units from the Unix epoch to a timestamp, with the digits below
+-- one unit cut toward the earlier time. The count does not check the time of
+-- day.
+timestampUnits :: Integer -> LocalTime -> Integer
+timestampUnits units LocalTime{localDay, localTimeOfDay} =
+  diffDays localDay (fromGregorian 1970 1 1) * 86400 * units
+    + diffTimeToPicoseconds (timeOfDayToTime localTimeOfDay) `div` (1000000000000 `div` units)
+
+-- | Check storage limits and the two DuckDB infinity sentinels.
+checkFiniteRange :: (Integral a) => String -> a -> a -> Integer -> IO ()
+checkFiniteRange label lower upper value =
+  unless (inFiniteRange lower upper value) $
+    throwConversionError (Text.pack label <> " value out of finite range")
+
+-- | Check storage limits without accepting the two infinity sentinels.
+inFiniteRange :: (Integral a) => a -> a -> Integer -> Bool
+inFiniteRange lower upper value =
+  value >= toInteger lower && value < toInteger upper && value /= negate (toInteger upper)
+
+-- | Validate time components and convert to the requested units per second.
+timeOfDayUnits :: Integer -> TimeOfDay -> IO Integer
+timeOfDayUnits units tod@(TimeOfDay hours minutes seconds) = do
+  -- A time of day that is not a TIME value is outside the range of the type: a
+  -- field outside its own range, for example 23:61:00, and a time after
+  -- 24:00:00 with valid fields, for example 24:00:01, 25:00:00, or 23:59:60.5.
+  -- The two texts name the two cases.
+  when (hours < 0 || minutes < 0 || minutes > 59 || seconds < 0 || seconds >= 61) $
+    throwConversionError "invalid time of day"
+  let picos = diffTimeToPicoseconds (timeOfDayToTime tod)
+  when (hours > 24 || picos > 86400 * 1000000000000) $
+    throwConversionError "time of day out of range"
+  pure (picos `div` (1000000000000 `div` units))
+
+-- | Transfer a newly constructed value to the statement on success.
+bindDuckValue :: Statement -> DuckDBIdx -> IO DuckDBV2ValueHandle -> IO ()
+bindDuckValue statement index make = mask_ do
+  value <- make
+  storeBoundValue statement index value `onException` destroyValue value
diff --git a/src/Database/DuckDB/Simple/ToRow.hs b/src/Database/DuckDB/Simple/ToRow.hs
--- a/src/Database/DuckDB/Simple/ToRow.hs
+++ b/src/Database/DuckDB/Simple/ToRow.hs
@@ -2,64 +2,63 @@
 {-# LANGUAGE FlexibleContexts #-}
 {-# LANGUAGE TypeOperators #-}
 
-{- |
-Module      : Database.DuckDB.Simple.ToRow
-Description : Rendering Haskell collections into parameter rows.
-
-The `ToRow` class converts Haskell values into lists of `FieldBinding`s that
-can be consumed by statement binding functions.
--}
+-- |
+-- Module      : Database.DuckDB.Simple.ToRow
+-- Description : Rendering Haskell collections into parameter rows.
+--
+-- The 'ToRow' class converts Haskell values to lists of 'FieldBinding's for
+-- statement binding.
 module Database.DuckDB.Simple.ToRow (
-    ToRow (..),
-    GToRow (..),
+  ToRow (..),
+  GToRow (..),
 ) where
 
 import Database.DuckDB.Simple.ToField (FieldBinding, ToField (..))
 import Database.DuckDB.Simple.Types (Only (..), (:.) (..))
 import GHC.Generics
 
--- | Types that can be transformed into parameter bindings.
+-- | Types that can convert to parameter bindings.
 class ToRow a where
-    toRow :: a -> [FieldBinding]
-    default toRow :: (Generic a, GToRow (Rep a)) => a -> [FieldBinding]
-    toRow = gtoRow . from
+  toRow :: a -> [FieldBinding]
+  default toRow :: (Generic a, GToRow (Rep a)) => a -> [FieldBinding]
+  toRow = gtoRow . from
 
--- | Generic helper for deriving `ToRow`.
+-- | Generic helper for deriving 'ToRow'.
 class GToRow f where
-    gtoRow :: f p -> [FieldBinding]
+  gtoRow :: f p -> [FieldBinding]
 
 instance GToRow U1 where
-    gtoRow _ = []
+  gtoRow _ = []
 
 instance (ToField a) => GToRow (K1 i a) where
-    gtoRow (K1 a) = [toField a]
+  gtoRow (K1 a) = [toField a]
 
 instance (GToRow a, GToRow b) => GToRow (a :*: b) where
-    gtoRow (a :*: b) = gtoRow a ++ gtoRow b
+  gtoRow (a :*: b) = gtoRow a ++ gtoRow b
 
 instance (GToRow a) => GToRow (M1 i c a) where
-    gtoRow (M1 a) = gtoRow a
+  gtoRow (M1 a) = gtoRow a
 
 instance ToRow () where
-    toRow () = []
+  toRow () = []
 
 instance (ToField a) => ToRow (Only a) where
-    toRow (Only a) = [toField a]
+  toRow (Only a) = [toField a]
 
 instance (ToField a, ToField b) => ToRow (a, b) where
-    toRow (a, b) = [toField a, toField b]
+  toRow (a, b) = [toField a, toField b]
 
 instance (ToField a, ToField b, ToField c) => ToRow (a, b, c) where
-    toRow (a, b, c) = [toField a, toField b, toField c]
+  toRow (a, b, c) = [toField a, toField b, toField c]
 
 instance (ToField a, ToField b, ToField c, ToField d) => ToRow (a, b, c, d) where
-    toRow (a, b, c, d) = [toField a, toField b, toField c, toField d]
+  toRow (a, b, c, d) = [toField a, toField b, toField c, toField d]
 
 instance (ToField a, ToField b, ToField c, ToField d, ToField e) => ToRow (a, b, c, d, e) where
-    toRow (a, b, c, d, e) = [toField a, toField b, toField c, toField d, toField e]
+  toRow (a, b, c, d, e) = [toField a, toField b, toField c, toField d, toField e]
 
 instance (ToField a) => ToRow [a] where
-    toRow = fmap toField
+  toRow = fmap toField
 
 instance (ToRow a, ToRow b) => ToRow (a :. b) where
-    toRow (a :. b) = toRow a ++ toRow b
+  toRow (a :. b) = toRow a ++ toRow b
diff --git a/src/Database/DuckDB/Simple/Tokenizer.hs b/src/Database/DuckDB/Simple/Tokenizer.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/Tokenizer.hs
@@ -0,0 +1,57 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE StrictData #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.Tokenizer
+-- Description : SQL tokenization using the grammar of a V2 connection.
+module Database.DuckDB.Simple.Tokenizer (
+  Token (..),
+  TokenType (..),
+  Tokenization (..),
+  tokenize,
+) where
+
+import Control.Exception (bracket)
+import qualified Data.ByteString as BS
+import Data.Text (Text)
+import qualified Data.Text.Encoding as Text
+import Database.DuckDB.Simple.Internal (Connection, withConnectionHandle)
+import Database.DuckDB.Simple.Native
+import Foreign.Marshal.Alloc (alloca)
+import Foreign.Storable (peek)
+
+-- | A token and its location in the UTF-8 source bytes.
+data Token = Token
+  { tokenType :: TokenType
+  , tokenOffset :: Int
+  , tokenBytes :: BS.ByteString
+  }
+  deriving (Eq, Show)
+
+-- | Tokens and the native indication of an unclosed final token.
+data Tokenization = Tokenization
+  { tokenizationTokens :: [Token]
+  , tokenizationUnterminated :: Bool
+  }
+  deriving (Eq, Show)
+
+-- | Tokenize text, including comments and interior NUL bytes.
+tokenize :: Connection -> Text -> IO Tokenization
+tokenize conn sql = withConnectionHandle conn \handle ->
+  let bytes = Text.encodeUtf8 sql
+  in  withBytes bytes \source ->
+        bracket (output (c_duckdb_v2_tokenize_sql handle source)) (destroy c_duckdb_v2_token_iterator_destroy) \iterator -> do
+          tokens <- alloca \kind -> alloca \start -> alloca \count ->
+            let collect acc = do
+                  checked (c_duckdb_v2_token_iterator_next iterator kind start count)
+                  typ <- peek kind
+                  if typ == DuckDBV2TokenTypeEndOfInput
+                    then pure (reverse acc)
+                    else do
+                      tokenKind <- tokenTypeFromNative typ
+                      offset <- fromIntegral <$> peek start
+                      size <- fromIntegral <$> peek count
+                      collect (Token tokenKind offset (BS.take size (BS.drop offset bytes)) : acc)
+            in  collect []
+          unfinished <- output (c_duckdb_v2_token_iterator_ends_unterminated iterator)
+          pure (Tokenization tokens (unfinished /= 0))
diff --git a/src/Database/DuckDB/Simple/TypeCache.hs b/src/Database/DuckDB/Simple/TypeCache.hs
deleted file mode 100644
--- a/src/Database/DuckDB/Simple/TypeCache.hs
+++ /dev/null
@@ -1,174 +0,0 @@
-{-# LANGUAGE BlockArguments #-}
-{-# LANGUAGE LambdaCase #-}
-{-# LANGUAGE NamedFieldPuns #-}
-{-# LANGUAGE OverloadedStrings #-}
-
-{- | Native types that the C API cannot create. A connection reads them the
-first time a parameter needs one, and destroys them when it closes.
--}
-module Database.DuckDB.Simple.TypeCache (
-    TypeCache,
-    defaultGeometryCRS,
-    createTypeCache,
-    destroyTypeCache,
-    cachedLogicalType,
-) where
-
-import Control.Concurrent.MVar (MVar, modifyMVarMasked, modifyMVar_, newMVar)
-import Control.Exception (bracket, finally, mask_, onException, throwIO)
-import Control.Monad (forM_, when)
-import qualified Data.ByteString as BS
-import Data.List (nub)
-import Data.Map.Strict (Map)
-import qualified Data.Map.Strict as Map
-import Data.Text (Text)
-import qualified Data.Text as Text
-import qualified Data.Text.Encoding as TextEncoding
-import Database.DuckDB.FFI
-import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep (..), destroyLogicalType, logicalTypeToRep)
-import Foreign.Marshal.Alloc (alloca)
-import Foreign.Marshal.Utils (fillBytes)
-import Foreign.Ptr (Ptr, nullPtr)
-import Foreign.Storable (peek, poke, sizeOf)
-
-{- | The configured CRSs and the native types of a connection. The types are
-absent until a parameter needs one. The connection owns the types.
--}
-data TypeCache = TypeCache
-    { typeCacheDatabase :: !DuckDBDatabase
-    , typeCacheCRS :: ![Text]
-    , typeCacheTypes :: !(MVar (Maybe NativeTypes))
-    }
-
-{- | The VARIANT type and the GEOMETRY types for the configured CRSs. Each
-GEOMETRY type has two keys: the configured CRS text and the CRS text that
-DuckDB reports for the type.
--}
-data NativeTypes = NativeTypes
-    { nativeVariant :: !DuckDBLogicalType
-    , nativeGeometry :: !(Map Text DuckDBLogicalType)
-    , nativeOwned :: ![DuckDBLogicalType]
-    }
-
--- | The CRS that a connection reads when the options do not give a list.
-defaultGeometryCRS :: [Text]
-defaultGeometryCRS = ["OGC:CRS84"]
-
-{- | Make an empty cache for a database. The caller must destroy the cache. A
-CRS must be nonempty and must not contain NUL.
--}
-createTypeCache :: DuckDBDatabase -> [Text] -> IO TypeCache
-createTypeCache database crsList = do
-    let crss = nub crsList
-    when (any Text.null crss || any (Text.any (== '\0')) crss) $
-        throwIO (userError "duckdb-simple: a GEOMETRY CRS must be nonempty and must not contain NUL")
-    TypeCache database crss <$> newMVar Nothing
-
--- | Destroy the types in the cache, if the connection read them.
-destroyTypeCache :: TypeCache -> IO ()
-destroyTypeCache TypeCache{typeCacheTypes} =
-    modifyMVar_ typeCacheTypes \types -> Nothing <$ mapM_ (mapM_ destroyLogicalType . nativeOwned) types
-
-{- | Copy a cached type for a leaf that the C API cannot create. The caller
-must destroy the copy. The first VARIANT leaf or GEOMETRY leaf with a CRS
-reads the types. A GEOMETRY CRS that the cache does not hold gives GEOMETRY
-without a CRS.
--}
-cachedLogicalType :: TypeCache -> LogicalTypeRep -> IO DuckDBLogicalType
-cachedLogicalType cache = \case
-    LogicalTypeScalar DuckDBTypeVariant -> nativeTypes cache >>= copyLogicalType . nativeVariant
-    LogicalTypeGeometry (Just crs) -> do
-        NativeTypes{nativeGeometry} <- nativeTypes cache
-        maybe (c_duckdb_create_logical_type DuckDBTypeGeometry) copyLogicalType (Map.lookup crs nativeGeometry)
-    LogicalTypeGeometry Nothing -> c_duckdb_create_logical_type DuckDBTypeGeometry
-    other -> throwIO (userError ("duckdb-simple: the type cache cannot create " <> show other))
-
-{- | Get the native types. Read them on first use with a separate connection,
-so the query does not run in the transaction of the caller. A failed read
-leaves the cache empty.
--}
-nativeTypes :: TypeCache -> IO NativeTypes
-nativeTypes TypeCache{typeCacheDatabase, typeCacheCRS, typeCacheTypes} =
-    modifyMVarMasked typeCacheTypes \cached -> do
-        types <- maybe (withTypeConnection typeCacheDatabase (`readNativeTypes` typeCacheCRS)) pure cached
-        pure (Just types, types)
-
--- | Read the VARIANT type and a GEOMETRY type for each CRS with one query.
-readNativeTypes :: DuckDBConnection -> [Text] -> IO NativeTypes
-readNativeTypes connection crss = do
-    let sql = Text.concat ("SELECT NULL::VARIANT" : [", system.main.ST_SetCRS('POINT EMPTY'::GEOMETRY, ?)" | _ <- crss])
-    withTypeQuery connection sql crss \result -> mask_ do
-        owned <- columnTypes result (length crss + 1)
-        case owned of
-            [] -> throwIO (userError "duckdb-simple: the type query returned no columns")
-            variant : geometry -> do
-                reported <- mapM logicalTypeToRep geometry `onException` mapM_ destroyLogicalType owned
-                pure
-                    NativeTypes
-                        { nativeVariant = variant
-                        , nativeGeometry =
-                            Map.fromList
-                                ( concat
-                                    [ (crs, logical) : [(reportedCRS, logical) | LogicalTypeGeometry (Just reportedCRS) <- [rep]]
-                                    | (crs, rep, logical) <- zip3 crss reported geometry
-                                    ]
-                                )
-                        , nativeOwned = owned
-                        }
-
--- | Take the types of the first columns. Destroy the taken types on failure.
-columnTypes :: Ptr DuckDBResult -> Int -> IO [DuckDBLogicalType]
-columnTypes result count = go [] 0
-  where
-    go taken column
-        | column == count = pure (reverse taken)
-        | otherwise = do
-            logical <- c_duckdb_column_logical_type result (fromIntegral column) `onException` mapM_ destroyLogicalType taken
-            when (logical == nullPtr) do
-                mapM_ destroyLogicalType taken
-                throwIO (userError "duckdb-simple: the type query returned no type")
-            go (logical : taken) (column + 1)
-
--- | Copy a type through a LIST type, because the C API has no copy function.
-copyLogicalType :: DuckDBLogicalType -> IO DuckDBLogicalType
-copyLogicalType logical =
-    -- TODO: use a copy function when the C API has one.
-    -- See https://github.com/Tritlo/duckdb-haskell/issues/30 and
-    -- https://github.com/duckdb/duckdb/issues/26664.
-    bracket (c_duckdb_create_list_type logical) destroyLogicalType c_duckdb_list_type_child_type
-
--- | Run an action with a new connection to the database. Disconnect after it.
-withTypeConnection :: DuckDBDatabase -> (DuckDBConnection -> IO a) -> IO a
-withTypeConnection database action =
-    alloca \connectionPtr -> do
-        connected <- c_duckdb_connect database connectionPtr
-        when (connected /= DuckDBSuccess) $
-            throwIO (userError "duckdb-simple: cannot connect to read the VARIANT and GEOMETRY types")
-        (peek connectionPtr >>= action) `finally` c_duckdb_disconnect connectionPtr
-
--- | Prepare and run a constant query with text parameters, and borrow its result.
-withTypeQuery :: DuckDBConnection -> Text -> [Text] -> (Ptr DuckDBResult -> IO a) -> IO a
-withTypeQuery connection sql parameters action =
-    BS.useAsCString (TextEncoding.encodeUtf8 sql) \sqlPtr ->
-        alloca \statementPtr -> do
-            poke statementPtr nullPtr
-            bracket (c_duckdb_prepare connection sqlPtr statementPtr) (const (c_duckdb_destroy_prepare statementPtr)) \prepared -> do
-                statement <- peek statementPtr
-                when (prepared /= DuckDBSuccess) do
-                    errorPtr <- c_duckdb_prepare_error statement
-                    message <- if errorPtr == nullPtr then pure "prepare failed" else TextEncoding.decodeUtf8 <$> BS.packCString errorPtr
-                    queryFailed message
-                forM_ (zip [1 ..] parameters) \(index, parameter) ->
-                    BS.useAsCStringLen (TextEncoding.encodeUtf8 parameter) \(ptr, len) -> do
-                        bound <- c_duckdb_bind_varchar_length statement index ptr (fromIntegral len)
-                        when (bound /= DuckDBSuccess) (queryFailed ("cannot bind CRS " <> parameter))
-                alloca \result -> do
-                    fillBytes result 0 (sizeOf (undefined :: DuckDBResult))
-                    bracket (c_duckdb_execute_prepared statement result) (const (c_duckdb_destroy_result result)) \executed -> do
-                        when (executed /= DuckDBSuccess) do
-                            errorPtr <- c_duckdb_result_error result
-                            message <- if errorPtr == nullPtr then pure "execution failed" else TextEncoding.decodeUtf8 <$> BS.packCString errorPtr
-                            queryFailed message
-                        action result
-  where
-    queryFailed message = throwIO (userError ("duckdb-simple: cannot read the VARIANT and GEOMETRY types: " <> Text.unpack message))
diff --git a/src/Database/DuckDB/Simple/TypeScope.hs b/src/Database/DuckDB/Simple/TypeScope.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/TypeScope.hs
@@ -0,0 +1,99 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.TypeScope
+-- Description : Scoped ownership of native field types.
+module Database.DuckDB.Simple.TypeScope (
+  TypeScope,
+  newTypeScope,
+  closeTypeScope,
+  withTypeScope,
+  scopedTypeRep,
+) where
+
+import Control.Concurrent.MVar (MVar, modifyMVarMasked, newMVar, putMVar, takeMVar, withMVar)
+import Control.Exception (bracket, bracketOnError, evaluate, finally, throwIO, uninterruptibleMask_)
+import Data.IORef (IORef, newIORef, readIORef, writeIORef)
+import Database.DuckDB.Simple.Conversion (Conversion, liftConversion)
+import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep)
+import Database.DuckDB.Simple.Native (DuckDBV2FactoryHandle, DuckDBV2LogicalTypeHandle, SQLError (..), destroyLogicalType, releaseItems)
+import Database.DuckDB.Simple.V2.LogicalRep (logicalTypeToRep)
+
+-- | The owner of native field types for one result or callback.
+-- See Note [Scoped field types].
+newtype TypeScope = TypeScope (MVar (Maybe [(DuckDBV2LogicalTypeHandle, IORef (Either (IO DuckDBV2FactoryHandle) LogicalTypeRep))]))
+  deriving (Eq)
+
+{- Note [Scoped field types]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A scope owns each native type and its optional Haskell snapshot. The MVar
+serializes acquisition, type reads, and closure. A closed scope rejects each
+read, including a cache hit. A snapshot already returned to the caller is pure
+and remains valid after closure.
+
+Only internal native operations run while the scope is locked. The type and
+factory acquisition actions must not run user code. An uncached read needs a
+live factory owner. A result reads the factory from the connection at that
+point, so a decoder that closed the connection gets an error. An extension
+aggregate can initialize its registration-owned helper at that point.
+logicalTypeToRep reads type ids, names, and parameters, and compares temporary
+alias copies. These operations do not run SQL or callbacks. A failed or
+interrupted read leaves the native type available for another attempt. Only
+a successful read fills the snapshot cache. Until then, the cache holds the
+factory acquisition action. Closure drops that action too, so an escaped field
+cannot retain the connection that it used for the read.
+
+Closure waits for an active metadata operation, then destroys every native
+type and clears every snapshot cache. Cleanup uses only internal metadata
+operations. It is uninterruptible so cancellation cannot leave an owned type
+behind. No user decoder or action runs under this mask. The scope stays locked
+until cleanup ends, and becomes closed even if a destructor raises an
+exception. Thus a concurrent reader or closer cannot use or destroy a released
+handle.
+-}
+
+-- | Start a scope with no native types.
+newTypeScope :: IO TypeScope
+newTypeScope = TypeScope <$> newMVar (Just [])
+
+-- | Release each native type and reject future type reads. Repeated calls are safe.
+-- See Note [Scoped field types].
+closeTypeScope :: TypeScope -> IO ()
+closeTypeScope (TypeScope scope) = uninterruptibleMask_ do
+  owned <- takeMVar scope
+  flip finally (putMVar scope Nothing) $
+    case owned of
+      Nothing -> pure ()
+      Just entries -> releaseItems release entries
+  where
+    release (native, snapshot) = destroyLogicalType native `finally` writeIORef snapshot (Left closedTypeScope)
+
+-- | Run an action in a type scope and close it on every exit path.
+withTypeScope :: (TypeScope -> IO a) -> IO a
+withTypeScope = bracket newTypeScope closeTypeScope
+
+-- | Acquire an owned native type and read its Haskell snapshot on demand.
+-- The acquisition action must use only native metadata operations.
+-- See Note [Scoped field types].
+scopedTypeRep :: TypeScope -> IO DuckDBV2FactoryHandle -> IO DuckDBV2LogicalTypeHandle -> IO (Conversion LogicalTypeRep)
+scopedTypeRep (TypeScope scope) acquireFactory create = modifyMVarMasked scope \case
+  Nothing -> closedTypeScope
+  Just entries -> bracketOnError create destroyLogicalType \native -> do
+    snapshot <- newIORef (Left acquireFactory)
+    let readType = withMVar scope \case
+          Nothing -> closedTypeScope
+          Just _ ->
+            readIORef snapshot >>= \case
+              Right logical -> pure logical
+              Left acquire -> do
+                factory <- acquire
+                logical <- logicalTypeToRep factory native >>= evaluate
+                writeIORef snapshot (Right logical)
+                pure logical
+    pure (Just ((native, snapshot) : entries), liftConversion readType)
+
+-- | Reject an operation after its metadata owner has closed.
+closedTypeScope :: IO a
+closedTypeScope = throwIO (SQLError "duckdb-simple: field type scope is closed" Nothing Nothing Nothing)
diff --git a/src/Database/DuckDB/Simple/Typed.hs b/src/Database/DuckDB/Simple/Typed.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/Typed.hs
@@ -0,0 +1,249 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE DefaultSignatures #-}
+{-# LANGUAGE FlexibleContexts #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications #-}
+{-# LANGUAGE TypeOperators #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.Typed
+-- Description : Read and write callback vectors as typed Haskell values.
+--
+-- Typed registrations use these helpers. An argument reader gives the rows of a
+-- borrowed vector as fields with the names from 'argumentName'.
+-- 'conversionMessage' describes the arguments that do not convert. 'TypedRow'
+-- gives the column types and the column values of a row. The module also
+-- converts a typed replacement function to a native replacement scan callback.
+module Database.DuckDB.Simple.Typed (
+  TypedRow (..),
+  ColumnValue (..),
+  argumentName,
+  rowDeclarations,
+  positionalSignature,
+  readBoundField,
+  ArgumentReader,
+  newArgumentReader,
+  conversionMessage,
+  Replacement (..),
+  replacementScanCallback,
+) where
+
+import Control.Concurrent.MVar (modifyMVarMasked, newMVar)
+import Control.Exception (SomeException, bracket, bracketOnError, finally, fromException, mask_)
+import Control.Monad (forM, forM_)
+import Data.List (intercalate)
+import Data.Proxy (Proxy (..))
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Database.DuckDB.Simple.Callback (RegistrationTarget, targetCastFactory)
+import Database.DuckDB.Simple.FromField (Field (..), ResultError (..))
+import Database.DuckDB.Simple.Materialize (
+  FallbackReaders (..),
+  ReadFactory (InstanceFactory),
+  createHelperInstance,
+  materializeValue,
+  prepareGeometryReader,
+  prepareVectorReader,
+  readCallbackVariant,
+  readFactoryHandle,
+  readInstanceVariant,
+ )
+import Database.DuckDB.Simple.Native
+import Database.DuckDB.Simple.ToField (DuckDBColumnType (..), ToDuckValue (..))
+import Database.DuckDB.Simple.TypeScope (TypeScope, scopedTypeRep)
+import Database.DuckDB.Simple.Types (Only (..))
+import Database.DuckDB.Simple.V2.LogicalRep (logicalTypeToRep)
+import Database.DuckDB.Simple.V2.Registration (
+  ContextCallback,
+  FunctionParameter (parameterKind),
+  FunctionSignature (..),
+  TypeDeclaration,
+  parameter,
+ )
+import GHC.Generics
+
+-- | A row with a fixed list of typed columns. A typed registration uses the
+-- column types in the signature of the SQL object, and writes the column values
+-- to DuckDB. t'Only', tuples of 2 to 7 columns, and @()@ are rows. A record with a
+-- 'Generic' instance is a row when each field has a 'ToDuckValue' instance:
+--
+-- > data Point = Point {x :: Double, y :: Double} deriving (Generic)
+-- > instance TypedRow Point
+--
+-- A @Maybe@ column can hold NULL. A row of arguments has the same rule as a row
+-- of results: each column type needs a 'ToDuckValue' instance, because that
+-- instance gives the SQL type of the column.
+class TypedRow r where
+  -- | The declaration of each column, from 'duckdbTypeDeclaration'. See
+  -- Note [Type declarations] in "Database.DuckDB.Simple.ToField".
+  rowColumnDeclarations :: Proxy r -> [Either Text TypeDeclaration]
+  default rowColumnDeclarations :: (GTypedRow (Rep r)) => Proxy r -> [Either Text TypeDeclaration]
+  rowColumnDeclarations _ = gRowColumnDeclarations (Proxy @(Rep r))
+
+  -- | The value of each column.
+  rowColumnValues :: r -> [ColumnValue]
+  default rowColumnValues :: (Generic r, GTypedRow (Rep r)) => r -> [ColumnValue]
+  rowColumnValues = gRowColumnValues . from
+
+-- | The value of one column of a row. The action makes an owned native value
+-- through a borrowed factory. The caller destroys the value.
+newtype ColumnValue = ColumnValue (DuckDBV2FactoryHandle -> IO DuckDBV2ValueHandle)
+
+-- | The generic implementation of 'TypedRow' for a type with one constructor.
+class GTypedRow f where
+  gRowColumnDeclarations :: Proxy f -> [Either Text TypeDeclaration]
+  gRowColumnValues :: f p -> [ColumnValue]
+
+instance GTypedRow U1 where
+  gRowColumnDeclarations _ = []
+  gRowColumnValues U1 = []
+
+instance (GTypedRow a) => GTypedRow (M1 i c a) where
+  gRowColumnDeclarations _ = gRowColumnDeclarations (Proxy @a)
+  gRowColumnValues (M1 value) = gRowColumnValues value
+
+instance (ToDuckValue a) => GTypedRow (K1 i a) where
+  gRowColumnDeclarations _ = [duckdbTypeDeclaration (Proxy @a)]
+  gRowColumnValues (K1 value) = [ColumnValue (`toDuckValue` value)]
+
+instance (GTypedRow a, GTypedRow b) => GTypedRow (a :*: b) where
+  gRowColumnDeclarations _ = gRowColumnDeclarations (Proxy @a) <> gRowColumnDeclarations (Proxy @b)
+  gRowColumnValues (left :*: right) = gRowColumnValues left <> gRowColumnValues right
+
+instance TypedRow ()
+
+instance (ToDuckValue a) => TypedRow (Only a) where
+  rowColumnDeclarations _ = [duckdbTypeDeclaration (Proxy @a)]
+  rowColumnValues (Only value) = [ColumnValue (`toDuckValue` value)]
+
+instance (ToDuckValue a, ToDuckValue b) => TypedRow (a, b)
+
+instance (ToDuckValue a, ToDuckValue b, ToDuckValue c) => TypedRow (a, b, c)
+
+instance (ToDuckValue a, ToDuckValue b, ToDuckValue c, ToDuckValue d) => TypedRow (a, b, c, d)
+
+instance (ToDuckValue a, ToDuckValue b, ToDuckValue c, ToDuckValue d, ToDuckValue e) => TypedRow (a, b, c, d, e)
+
+instance (ToDuckValue a, ToDuckValue b, ToDuckValue c, ToDuckValue d, ToDuckValue e, ToDuckValue f) => TypedRow (a, b, c, d, e, f)
+
+instance (ToDuckValue a, ToDuckValue b, ToDuckValue c, ToDuckValue d, ToDuckValue e, ToDuckValue f, ToDuckValue g) => TypedRow (a, b, c, d, e, f, g)
+
+-- | The name of the argument at an index, from 0: @arg0@, @arg1@, and so on.
+argumentName :: Int -> Text
+argumentName index = Text.pack ("arg" <> show index)
+
+-- | Give the declaration of each column of a row, or raise the first 'Left' as
+-- an @SQLError@ before a registration. The error names the registration and
+-- the place of the column. The list of places has a name for each column. See
+-- Note [Type declarations] in "Database.DuckDB.Simple.ToField".
+rowDeclarations :: Text -> [Text] -> [Either Text TypeDeclaration] -> IO [TypeDeclaration]
+rowDeclarations name places declarations =
+  forM (zip places declarations) \(place, declaration) ->
+    either (\reason -> throwInvalidArgument (Text.intercalate (Text.pack ": ") [name, place, reason])) pure declaration
+
+-- | Declare the positional arguments of a typed function. A table function
+-- declares its result columns during bind and supplies no return type here.
+positionalSignature :: [TypeDeclaration] -> Maybe TypeDeclaration -> FunctionSignature
+positionalSignature types =
+  FunctionSignature
+    [ (parameter (argumentName index) dtype){parameterKind = DuckDBV2FunctionParameterKindPositionalOnly}
+    | (index, dtype) <- zip [0 ..] types
+    ]
+
+-- | Copy one argument of a table function or pragma. Acquire its logical
+-- type within the value's lifetime. The type scope owns it during conversion.
+readBoundField :: TypeScope -> ReadFactory -> DuckDBV2FunctionBindInfoHandle -> Text -> DuckDBIdx -> IO Field
+readBoundField scope factory info name index =
+  bracket (output (c_duckdb_v2_function_bind_get_arg_value info index)) destroyValue \value ->
+    Field name (fromIntegral index)
+      <$> materializeValue readCallbackVariant factory value
+      <*> scopedTypeRep scope (pure (readFactoryHandle factory)) (output (c_duckdb_v2_value_get_logical_type value))
+
+{- Note [Function argument readers]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A scalar or aggregate function belongs to the catalog. Its callbacks can
+run after the registering connection closes. An extension has no managed
+connection, and an aggregate update has no callback context.
+
+A registration takes the host instance factory when available. An extension
+opens a private instance on the first argument read or aggregate result
+write that needs a factory. GEOMETRY inputs use its built-in cast to BLOB.
+A VARIANT read always needs the private instance because its metadata query
+can run while the caller holds a host instance lock. See Note [VARIANT reads inside callbacks]
+in "Database.DuckDB.Simple.Materialize".
+
+An MVar protects instance creation. Each VARIANT vector gets its own
+connection and decoder state, so concurrent calls can decode independently.
+The native callback owner releases the instance and its environment after
+the last bound or executing function releases the callbacks.
+-}
+
+-- | Prepare a vector's fields within the current callback's type scope.
+type ArgumentReader = TypeScope -> Int -> DuckDBV2VectorHandle -> IO (Int -> IO Field)
+
+-- | Create the argument reader, the action to borrow its instance factory,
+-- and the cleanup for one registration.
+-- Native resources are acquired on demand. See Note [Function argument readers].
+newArgumentReader :: RegistrationTarget -> IO (ArgumentReader, IO DuckDBV2FactoryHandle, IO ())
+newArgumentReader target = do
+  hostFactory <- targetCastFactory target
+  cache <- newMVar Nothing
+  let helper = modifyMVarMasked cache \case
+        Just owned@(_, instance_) -> pure (Just owned, instance_)
+        Nothing -> bracketOnError (output c_duckdb_v2_environment_create) (destroy c_duckdb_v2_environment_destroy) \env -> do
+          instance_ <- createHelperInstance env
+          pure (Just (env, instance_), instance_)
+      close = mask_ do
+        owned <- modifyMVarMasked cache (\state -> pure (Nothing, state))
+        forM_ owned \(env, instance_) ->
+          destroy c_duckdb_v2_instance_destroy instance_ `finally` destroy c_duckdb_v2_environment_destroy env
+      factory = maybe (helper >>= output . c_duckdb_v2_instance_get_factory) pure hostFactory
+      readers =
+        FallbackReaders
+          (\logical -> factory >>= \f -> logicalTypeToRep f logical)
+          (\vector -> helper >>= \instance_ -> readInstanceVariant instance_ vector)
+          (\vector -> factory >>= \f -> prepareGeometryReader (InstanceFactory f) vector)
+      readArgument scope index vector = do
+        readValue <- prepareVectorReader readers vector
+        -- See Note [Scoped field types] in "Database.DuckDB.Simple.TypeScope".
+        argumentType <- scopedTypeRep scope factory (output (c_duckdb_v2_vector_get_logical_type vector))
+        pure \row -> (\value -> Field (argumentName index) index value argumentType) <$> readValue row
+  pure (readArgument, factory, close)
+
+-- | Describe the arguments that 'Database.DuckDB.Simple.FromField.FromField' or
+-- @FromRow@ cannot convert. The text names each argument with the name of its
+-- field.
+conversionMessage :: [SomeException] -> String
+conversionMessage failures = intercalate "; " (map describe failures)
+  where
+    describe failure = case fromException failure of
+      Just result@UnexpectedNull{} -> "argument " <> Text.unpack (errSQLField result) <> " is NULL, but " <> Text.unpack (errHaskellType result) <> " cannot hold NULL"
+      Just result ->
+        "cannot convert argument "
+          <> Text.unpack (errSQLField result)
+          <> " from "
+          <> Text.unpack (errSQLType result)
+          <> " to "
+          <> Text.unpack (errHaskellType result)
+          <> if Text.null (errMessage result) then "" else ": " <> Text.unpack (errMessage result)
+      Nothing -> exceptionText failure
+
+-- | What DuckDB reads in place of an unknown table. DuckDB reads the result
+-- under the name of the table, unless the query gives an alias.
+data Replacement
+  = -- | Read the rows of a query. The text must contain exactly one SELECT
+    --       statement. Other text fails the query with an SQL error.
+    ReplaceWithQuery Text
+  deriving (Eq, Show, Read)
+
+-- | Convert a typed replacement function to a native replacement scan
+-- callback. The callback reads the parts of the unknown name and gives them to the
+-- function. 'Nothing' declines the name.
+replacementScanCallback :: ([Text] -> IO (Maybe Replacement)) -> ContextCallback DuckDBV2ReplacementScanInfoHandle
+replacementScanCallback replace info _ = do
+  parts <- bracket (output (c_duckdb_v2_replacement_scan_get_name info)) (destroy c_duckdb_v2_qname_destroy) \name -> do
+    count <- output (c_duckdb_v2_qname_get_part_count name)
+    forM [0 .. fromIntegral count - 1 :: Int] \index -> output (c_duckdb_v2_qname_get_part name (fromIntegral index)) >>= readIdentifier
+  replace parts >>= mapM_ \case
+    ReplaceWithQuery sql -> withText sql (checked . c_duckdb_v2_replacement_scan_set_subquery info)
diff --git a/src/Database/DuckDB/Simple/Typed/Aggregate.hs b/src/Database/DuckDB/Simple/Typed/Aggregate.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/Typed/Aggregate.hs
@@ -0,0 +1,402 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE ForeignFunctionInterface #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.Typed.Aggregate
+-- Description : Register an aggregate function as a fold over Haskell values.
+--
+-- The Haskell state of a group lives outside DuckDB. The native state holds a
+-- 'StablePtr' to an 'IORef' with the Haskell state. The bind data of each call
+-- site holds a state table with the live stable pointers. See
+-- Note [Aggregate state life cycle].
+module Database.DuckDB.Simple.Typed.Aggregate (
+  Aggregate (..),
+  createAggregateOn,
+) where
+
+import Control.Exception (evaluate, finally, mask_, onException, throwIO)
+import Control.Monad (forM_, unless, when)
+import Data.Array (Array, elems, listArray, (!))
+import Data.IORef (IORef, atomicModifyIORef', newIORef, readIORef, writeIORef)
+import qualified Data.IntSet as IntSet
+import Data.Proxy (Proxy (..))
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Data.Void (Void)
+import Database.DuckDB.Simple.Callback (attachOpaque, ignoreCallbackExceptions)
+import Database.DuckDB.Simple.Conversion (runConversion)
+import Database.DuckDB.Simple.FromField (Field (..), FieldValue (FieldNull))
+import Database.DuckDB.Simple.FromRow (FromRow (..), parseRow)
+import Database.DuckDB.Simple.Function.Internal (FunctionResult, prepareAggregateResultWriter)
+import Database.DuckDB.Simple.Internal (Connection (..), ConnectionOptions (..), defaultAggregateStripes)
+import Database.DuckDB.Simple.Native
+import Database.DuckDB.Simple.Ok (Ok (..))
+import Database.DuckDB.Simple.ToField (DuckDBColumnType (..))
+import Database.DuckDB.Simple.TypeScope (withTypeScope)
+import Database.DuckDB.Simple.Typed (
+  ArgumentReader,
+  TypedRow (..),
+  argumentName,
+  conversionMessage,
+  newArgumentReader,
+  positionalSignature,
+  rowDeclarations,
+ )
+import Database.DuckDB.Simple.V2.Registration (
+  AggregateCallbacks (..),
+  BindCallback,
+  RegistrationTarget (..),
+  aggregateCallbacks,
+  configureFunctionSignature,
+  registerAggregateFunctionWithCleanup,
+  withRegistrationFactory,
+ )
+import Foreign.Ptr (FunPtr, Ptr, castFunPtr, castPtr, intPtrToPtr, nullPtr, ptrToIntPtr)
+import Foreign.StablePtr (StablePtr, castPtrToStablePtr, castStablePtrToPtr, deRefStablePtr, freeStablePtr, newStablePtr)
+import Foreign.Storable (peek, peekElemOff, poke)
+import HsBindgen.Runtime.Marshal (staticSizeOf)
+
+-- | An aggregate function as a fold. DuckDB keeps one state for each group, or
+-- more than one partial state.
+data Aggregate state args result = Aggregate
+  { aggregateInitial :: state
+  -- ^ The state of a group with no rows.
+  , aggregateStep :: state -> args -> IO state
+  -- ^ Add one row to a state.
+  , aggregateCombine :: state -> state -> IO state
+  -- ^ Merge the second partial state of a group into the first.
+  , aggregateResult :: state -> IO result
+  -- ^ Give the result of a group.
+  }
+
+{- Note [Aggregate state life cycle]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The Haskell state of a group lives outside DuckDB. The native state of a group
+has the size of one pointer (setStateSize). It holds a StablePtr to an IORef,
+and the IORef holds the Haskell state.
+
+These are the steps in the life of a state.
+
+- Init (initializeStates). The callback first writes null to all native states
+  of the call, so that an error leaves no native state uninitialized. Then for
+  each state it makes the IORef and the StablePtr, adds the key of the
+  StablePtr to the state table, and writes the StablePtr to the native state.
+
+- Update and combine (updateStates and combineStates). DuckDB can move a native
+  state with a byte copy. Thus these callbacks change only the IORef.
+
+- Release (releaseState). After init, only a release changes the native state:
+  it writes null to the native state. A release does not change a null native
+  state. Thus the null write stops a second release of one native state. A read
+  of a released native state raises an error (stateCell).
+
+The bind data of each call site holds a state table with the keys of the live
+stable pointers (StateTable and bindStateTable). A release removes the key from
+the table, and only the caller that removes it frees the stable pointer. This
+check stops a second free of a stable pointer that a byte copy of the native
+state also holds. It does not stop the release of a byte copy after the runtime
+has given its stable pointer to a new state. DuckDB 2.0.0 destroys each state at
+one location. The destructor of the state table frees the stable pointers that
+remain (releaseStateTable).
+
+The registration always sets a bind callback, so each call site has bind data.
+The code still reads the table as optional (readStateTable). Without bind data,
+only the destroy callback and a failed finalize release the states, and a
+release frees each stable pointer that it reads.
+
+These are the states that DuckDB 2.0.0 destroys and does not destroy.
+
+- The header says that the destroy callback runs on states that are discarded
+  without being finalized. DuckDB 2.0.0 runs the destroy callback on finalized
+  states too: a hash aggregate destroys each chunk of states after it finalizes
+  them, and an ungrouped aggregate and a window destroy their states after
+  finalize (radix_partitioned_hashtable.cpp, physical_ungrouped_aggregate.cpp,
+  and window_segment_tree.cpp).
+
+- DuckDB 2.0.0 does not run the destroy callback on these states:
+
+  - The states of a finalize call that fails, in a hash aggregate and in a
+    window.
+  - The states that no finalize call gets when LIMIT stops a parallel hash
+    aggregate.
+  - The states after a combine call fails in a parallel hash aggregate.
+  - The states after a finalize call fails in a parallel hash aggregate.
+
+  The exception handler of finalizeStates releases the states of the finalize
+  call that fails. The destructor of the state table frees the stable pointers
+  of the other states.
+
+DuckDB runs the destructor of the state table when it drops the bind data of a
+call site. In DuckDB 2.0.0 a hash table and an ungrouped aggregate each hold a
+copy of the bind data, and each copy shares the holder of the state table
+through a shared pointer (CV2AggregateFunctionData::Copy and CV2UserData). Each
+of them runs the destroy callback on its states before it drops its copy
+(~GroupedAggregateHashTable and ~UngroupedAggregateState). In a window, the
+same is true for WindowAggregateStates and WindowCustomAggregatorLocalState.
+The naive aggregator and the segment tree use the copy of the window global
+state, and run the destroy callback during the evaluation. Thus the destructor
+runs after the last destroy callback of these owners that gets this bind data.
+
+See Note [State table stripes] for the form of the table.
+-}
+
+{- Note [State table stripes]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A state table holds the keys of the live states of one call site. Each new
+state adds its key, and each release removes it. DuckDB makes and releases
+states on several threads at the same time.
+
+A stripe is one part of the table: an IORef with a set of keys. The table is an
+array of stripes, and the key of a state selects its stripe (stateStripe). Thus
+two threads change the same IORef only when their keys select the same stripe.
+
+- Why the table has stripes. A change uses atomicModifyIORef', which stores a
+  value that is not evaluated. If the runtime stops a thread during that
+  evaluation, each thread that needs the value waits. With one IORef for all
+  states, the DuckDB threads of a query with many groups waited for each other.
+
+- The number of stripes. The option connectionAggregateStripes of
+  ConnectionOptions sets the number for each aggregate that createAggregate
+  registers through the connection. The registration keeps the number, also
+  when another connection calls the aggregate. The default is
+  defaultAggregateStripes, 64 stripes. A registration on an extension has no
+  connection options, so it uses the default. The bind callback makes the
+  table with this number (bindStateTable).
+
+- No result depends on the number. It changes only how often two threads use
+  the same stripe. A stripe costs one small IORef for each call site.
+
+The destructor of the table reads all stripes (releaseStateTable).
+-}
+
+-- | The live states of one call site, as the keys of their stable pointers.
+-- 'stateStripe' gives the stripe of a key. See Note [State table stripes].
+--
+-- With the table, the library frees the states that DuckDB 2.0.0 does not
+-- destroy. See Note [Aggregate state life cycle].
+type StateTable = Array Int (IORef IntSet.IntSet)
+
+-- | The stripe that holds a key. In GHC 9.14 the key of a stable pointer is
+-- one more than its index in the stable pointer table of the runtime
+-- (@rts\/include\/rts\/StablePtr.h@). Thus consecutive keys go to different
+-- stripes when the table has more than one stripe. The table is correct for
+-- each distribution of the keys. The distribution changes only how often two
+-- threads use the same stripe. See Note [State table stripes].
+stateStripe :: StateTable -> Int -> IORef IntSet.IntSet
+stateStripe table key = table ! (key `mod` length table)
+
+-- | Register a typed aggregate function on a connection or a loading extension.
+-- Check the name and declarations before accessing the registration target.
+-- See Note [Type declarations] in "Database.DuckDB.Simple.ToField" and
+-- Note [Result writers] in "Database.DuckDB.Simple.Function.Internal".
+createAggregateOn
+  :: forall state args result
+   . (FromRow args, TypedRow args, FunctionResult result) => RegistrationTarget -> Text -> Aggregate state args result -> IO ()
+createAggregateOn target name aggregate = do
+  when (Text.null name || Text.any (== '\0') name) $
+    throwInvalidArgument "aggregate function name must be nonempty and must not contain NUL"
+  argumentTypes <- rowDeclarations name ["argument " <> argumentName index | index <- [0 ..]] columnTypes
+  [resultType] <- rowDeclarations name ["result"] [duckdbTypeDeclaration (Proxy @result)]
+  (readArgument, acquireFactory, closeReader) <- newArgumentReader target
+  -- See Note [State table stripes]. Evaluate the count before the registration.
+  -- An unevaluated count keeps the target, and thus the connection, reachable
+  -- from the callbacks.
+  stripes <- evaluate case target of
+    ConnectionTarget connection -> connectionAggregateStripes (connectionOptions connection)
+    ExtensionTarget{} -> defaultAggregateStripes
+  let signature = positionalSignature argumentTypes (Just resultType)
+      callbacks =
+        ( aggregateCallbacks
+            setStateSize
+            (initializeStates aggregate)
+            (updateStates readArgument name aggregate (length columnTypes))
+            (combineStates aggregate)
+            (finalizeStates aggregate acquireFactory)
+        )
+          { aggregateBindCallback = Just (bindStateTable stripes)
+          , aggregateDestroyCallback = Just destroyStates
+          }
+  withRegistrationFactory target \factory ->
+    registerAggregateFunctionWithCleanup target closeReader (configure signature factory) callbacks
+  where
+    columnTypes = rowColumnDeclarations (Proxy @args)
+    configure signature factory function = do
+      withIdentifier name (checked . c_duckdb_v2_aggregate_function_set_name function)
+      output (c_duckdb_v2_aggregate_function_get_signature function) >>= configureFunctionSignature factory signature
+      checked
+        (c_duckdb_v2_aggregate_function_set_property function DuckDBV2FunctionPropertyNullHandling DuckDBV2FunctionPropertyNullHandlingSpecial)
+
+-- | Make a native state the size of one pointer. See
+-- Note [Aggregate state life cycle].
+setStateSize :: DuckDBV2AggregateFunctionSizeInfoHandle -> IO ()
+setStateSize info = checked (c_duckdb_v2_aggregate_function_size_set_state_size info (fromIntegral (staticSizeOf (Proxy @(Ptr ())))))
+
+-- | Make an empty state table with the given number of stripes and transfer it
+-- to the bind data of the call site. See Note [Aggregate state life cycle] and
+-- Note [State table stripes].
+bindStateTable :: Int -> BindCallback DuckDBV2AggregateFunctionBindInfoHandle
+bindStateTable count input _ _ = mask_ do
+  stripes <- mapM (const (newIORef IntSet.empty)) [1 .. count]
+  -- Build the array here, so that no callback thread evaluates it.
+  table <- evaluate (listArray (0, count - 1) stripes :: StateTable)
+  stable <- newStablePtr table
+  attachOpaque (c_duckdb_v2_function_bind_set_bind_data input) (castPtr (castStablePtrToPtr stable)) stateTableDestructor
+    `onException` freeStablePtr stable
+
+-- | Read the state table from the bind data. Without bind data, give 'Nothing'.
+-- See Note [Aggregate state life cycle].
+readStateTable :: (Ptr (Ptr Void) -> Ptr DuckDBV2ErrorInfoHandle -> IO DuckDBV2Error) -> IO (Maybe StateTable)
+readStateTable getter = do
+  raw <- output getter
+  if raw == nullPtr then pure Nothing else Just <$> deRefStablePtr (castPtrToStablePtr (castPtr raw))
+
+-- | Give each new native state the initial Haskell state. First set all native
+-- states to null, so that an error leaves no native state uninitialized. See
+-- Note [Aggregate state life cycle].
+initializeStates :: Aggregate state args result -> DuckDBV2AggregateFunctionInitInfoHandle -> IO ()
+initializeStates Aggregate{aggregateInitial} info = do
+  table <- readStateTable (c_duckdb_v2_aggregate_function_init_get_bind_data info)
+  count <- fromIntegral <$> output (c_duckdb_v2_aggregate_function_init_get_state_count info)
+  states <- output (c_duckdb_v2_aggregate_function_init_get_states info)
+  forM_ [0 .. count - 1] \index -> peekElemOff states index >>= \slot -> poke (castPtr slot) (nullPtr @())
+  forM_ [0 .. count - 1] \index -> do
+    slot <- peekElemOff states index
+    mask_ do
+      stable <- newIORef aggregateInitial >>= newStablePtr
+      let key = stableKey stable
+      forM_ table \keys -> atomicModifyIORef' (stateStripe keys key) \live -> (IntSet.insert key live, ())
+      poke (castPtr slot) stable
+
+-- | Add each row to its state. A row with NULL in an argument does not change
+-- its state. A row that does not convert raises an error that names the
+-- aggregate function. A GEOMETRY argument reads with the instance factory.
+-- See Note [Aggregate state life cycle].
+updateStates
+  :: (FromRow args)
+  => ArgumentReader
+  -> Text
+  -> Aggregate state args result
+  -> Int
+  -> DuckDBV2AggregateFunctionUpdateInfoHandle
+  -> IO ()
+updateStates readArgument name Aggregate{aggregateStep} columns info = withTypeScope \scope -> do
+  count <- fromIntegral <$> output (c_duckdb_v2_aggregate_function_update_get_row_count info)
+  states <- output (c_duckdb_v2_aggregate_function_update_get_states info)
+  readers <-
+    mapM
+      ( \index ->
+          output (c_duckdb_v2_aggregate_function_update_get_arg info (fromIntegral index))
+            >>= readArgument scope index
+      )
+      [0 .. columns - 1]
+  forM_ [0 .. count - 1] \row -> do
+    fields <- mapM ($ row) readers
+    unless (any ((== FieldNull) . fieldValue) fields) do
+      arguments <-
+        runConversion (parseRow fromRow fields) >>= \case
+          Ok arguments -> pure arguments
+          Errors failures -> throwIO (userError ("duckdb-simple: " <> Text.unpack name <> ": " <> conversionMessage failures))
+      cell <- peekElemOff states row >>= stateCell
+      readIORef cell >>= (`aggregateStep` arguments) >>= evaluate >>= writeIORef cell
+
+-- | Merge each source state into its target state. Do not change the source.
+-- Change only the cell of the target. See Note [Aggregate state life cycle].
+combineStates :: Aggregate state args result -> DuckDBV2AggregateFunctionCombineInfoHandle -> IO ()
+combineStates Aggregate{aggregateCombine} info = do
+  count <- fromIntegral <$> output (c_duckdb_v2_aggregate_function_combine_get_state_count info)
+  sources <- output (c_duckdb_v2_aggregate_function_combine_get_sources info)
+  targets <- output (c_duckdb_v2_aggregate_function_combine_get_targets info)
+  forM_ [0 .. count - 1] \index -> do
+    source <- peekElemOff sources index >>= stateCell >>= readIORef
+    target <- peekElemOff targets index >>= stateCell
+    current <- readIORef target
+    aggregateCombine current source >>= evaluate >>= writeIORef target
+
+-- | Write each state at its offset in the result vector. DuckDB does not
+-- destroy the states when finalize fails. See Note [Aggregate state life cycle].
+finalizeStates
+  :: (FunctionResult result) => Aggregate state args result -> IO DuckDBV2FactoryHandle -> DuckDBV2AggregateFunctionFinalizeInfoHandle -> IO ()
+finalizeStates Aggregate{aggregateResult} acquireFactory info = do
+  table <- readStateTable (c_duckdb_v2_aggregate_function_finalize_get_bind_data info)
+  count <- output (c_duckdb_v2_aggregate_function_finalize_get_state_count info)
+  states <- output (c_duckdb_v2_aggregate_function_finalize_get_states info)
+  let rows = [0 .. fromIntegral count - 1]
+      finalize = when (count /= 0) do
+        offset <- output (c_duckdb_v2_aggregate_function_finalize_get_result_offset info)
+        vector <- output (c_duckdb_v2_aggregate_function_finalize_get_result info)
+        write <- prepareAggregateResultWriter acquireFactory vector (offset + count)
+        forM_ rows \index ->
+          peekElemOff states index >>= stateCell >>= readIORef >>= aggregateResult >>= write (fromIntegral offset + index)
+  finalize `onException` forM_ rows \index -> peekElemOff states index >>= releaseState table
+
+-- | Release each state. See Note [Aggregate state life cycle].
+destroyStates :: DuckDBV2AggregateFunctionDestroyInfoHandle -> IO ()
+destroyStates info = do
+  table <- readStateTable (c_duckdb_v2_aggregate_function_destroy_get_bind_data info)
+  count <- fromIntegral <$> output (c_duckdb_v2_aggregate_function_destroy_get_state_count info)
+  states <- output (c_duckdb_v2_aggregate_function_destroy_get_states info)
+  forM_ [0 .. count - 1 :: Int] \index -> peekElemOff states index >>= releaseState table
+
+-- | Read the cell of a native state. A released native state raises an error.
+-- See Note [Aggregate state life cycle].
+stateCell :: Ptr Void -> IO (IORef state)
+stateCell slot = do
+  stable <- peek (castPtr slot)
+  when (castStablePtrToPtr stable == nullPtr) $
+    throwInternalError "the aggregate state was released"
+  deRefStablePtr stable
+
+-- | Release the Haskell state of a native state, and set the native state to
+-- null. A null native state does not change. With a table, only the caller that
+-- removes the key from the table frees the stable pointer. See
+-- Note [Aggregate state life cycle].
+releaseState :: Maybe StateTable -> Ptr Void -> IO ()
+releaseState table slot = mask_ do
+  stable <- peek (castPtr slot) :: IO (StablePtr ())
+  unless (castStablePtrToPtr stable == nullPtr) do
+    poke (castPtr slot) (nullPtr @())
+    let key = stableKey stable
+    owner <- case table of
+      Nothing -> pure True
+      Just keys -> atomicModifyIORef' (stateStripe keys key) \live -> (IntSet.delete key live, IntSet.member key live)
+    when owner (freeStablePtr stable)
+
+-- | The key of a stable pointer in a state table, from 'castStablePtrToPtr'
+-- and 'ptrToIntPtr' of base. Base has no single function for the two steps.
+-- 'stableFromKey' is the inverse.
+stableKey :: StablePtr a -> Int
+stableKey = fromIntegral . ptrToIntPtr . castStablePtrToPtr
+
+-- | The stable pointer of a key in a state table, from 'intPtrToPtr' and
+-- 'castPtrToStablePtr' of base. This is the inverse of 'stableKey'.
+stableFromKey :: Int -> StablePtr a
+stableFromKey = castPtrToStablePtr . intPtrToPtr . fromIntegral
+
+-- | Free the remaining group states and the state table owner.
+-- DuckDB calls this when it drops the bind data of a call site. See
+-- Note [Aggregate state life cycle], and Note [Callback ownership] in
+-- "Database.DuckDB.Simple.Callback" for the rules of a destructor.
+releaseStateTable :: Ptr Void -> IO ()
+releaseStateTable raw =
+  mask_ $ ignoreCallbackExceptions $ unless (raw == nullPtr) do
+    let stable = castPtrToStablePtr (castPtr raw) :: StablePtr StateTable
+    ( do
+        remaining <- deRefStablePtr stable >>= fmap IntSet.unions . mapM readIORef . elems
+        forM_ (IntSet.toList remaining) (freeStablePtr . stableFromKey)
+      )
+      `finally` freeStablePtr stable
+
+foreign export ccall "duckdb_simple_release_aggregate_states"
+  releaseStateTable :: Ptr Void -> IO ()
+
+foreign import ccall "&duckdb_simple_release_aggregate_states"
+  stateTableDestructorAddress :: FunPtr (Ptr Void -> IO ())
+
+-- | Use the generated callback type for the static state table destructor.
+stateTableDestructor :: DuckDBV2OpaqueDestroyFn
+stateTableDestructor = DuckDBV2OpaqueDestroyFn (castFunPtr stateTableDestructorAddress)
diff --git a/src/Database/DuckDB/Simple/Typed/Table.hs b/src/Database/DuckDB/Simple/Typed/Table.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/Typed/Table.hs
@@ -0,0 +1,220 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.Typed.Table
+-- Description : Register typed table functions and write typed rows to output chunks.
+--
+-- A typed table function converts its arguments with 'FromRow'. It gives the rows
+-- of a scan as a Haskell list of 'TypedRow' values. The exec callback writes the
+-- list to DuckDB one output chunk at a time. See Note [Row lists of typed scans].
+module Database.DuckDB.Simple.Typed.Table (
+  createTableFunctionOn,
+  writeRows,
+) where
+
+import Control.Concurrent.MVar (MVar, modifyMVar_, newMVar)
+import Control.Exception (bracket, throwIO)
+import Control.Monad (forM, forM_, when, zipWithM_)
+import Data.Proxy (Proxy (..))
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Database.DuckDB.Simple.Callback (attachOpaque, readCallbackState, targetCastFactory, transferCallbackState)
+import Database.DuckDB.Simple.Conversion (runConversion)
+import Database.DuckDB.Simple.FromRow (FromRow (..), parseRow)
+import Database.DuckDB.Simple.Materialize (ReadFactory, callbackReadFactory)
+import Database.DuckDB.Simple.Native
+import Database.DuckDB.Simple.Ok (Ok (..))
+import Database.DuckDB.Simple.TypeScope (TypeScope, withTypeScope)
+import Database.DuckDB.Simple.Typed (
+  ColumnValue (..),
+  TypedRow (..),
+  argumentName,
+  conversionMessage,
+  positionalSignature,
+  readBoundField,
+  rowDeclarations,
+ )
+import Database.DuckDB.Simple.V2.Registration (
+  RegistrationTarget,
+  TableCallbacks (..),
+  configureFunctionSignature,
+  registerTableFunctionWith,
+  tableCallbacks,
+  withRegistrationFactory,
+  withTypeDeclaration,
+ )
+
+{- Note [Row lists of typed scans]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A typed table function (createTableFunctionOn) and the COPY FROM side of a
+typed format (copyFromSide) give the rows of a scan as a Haskell list of
+TypedRow values. The two use the same callbacks.
+
+- The bind callback reads the inputs of the call. Its bind data is the action
+  that gives the list.
+
+- The global init callback runs the action, and keeps the list in an MVar in
+  the global state. The action runs one time for each scan.
+
+- The exec callback takes the list from the MVar, writes the first rows to the
+  output chunk (writeRows), and puts the other rows back. In the exec callback
+  of a table function, a call that writes no row ends the scan.
+
+DuckDB can run exec callbacks of one scan at the same time. For a plain table
+function, the maximum number of threads of a scan "Defaults to 1, a
+single-threaded scan" (duckdb_v2_table_function_init_global_set_max_threads in
+the header), and the typed scans do not change it. But a multi-file function
+(registerMultiFileFunction) over the table function "claims the batches of the
+function itself, so that the rows of a file keep their order also when several
+threads scan it" (duckdb_v2_table_function_set_claim_batch_callback in the
+header). Then DuckDB 2.0.0 runs several exec callbacks of the scan of one file
+at the same time. The lock of the MVar gives each row to one call only.
+
+A typed table function declares projection pushdown. DuckDB then asks the exec
+callback for only the columns that the query uses. When the query uses no
+column, for example in SELECT count(*), DuckDB 2.0.0 asks for the first column:
+the function declares no virtual column, so LogicalGet::GetAnyColumn gives
+column 0 (logical_get.cpp), and CV2TableScanColumns gives column 0 for an empty
+projection (capi_v2_func_table.cpp). writeRows makes the values of the
+requested columns only, so it does not evaluate the other columns of a row. But
+it evaluates each row that it writes to its constructor, and this evaluates
+each strict field of the row. The COPY FROM side asks writeRows for all
+columns.
+
+writeRows evaluates only the spine of the rows that fit in the chunk
+(splitRows). It does not evaluate the other rows. The list that it gives back
+is the list after the written rows, not a reference to the whole list. DuckDB
+takes the rows one chunk at a time, so the list can be lazy. DuckDB stops when
+the query needs no more rows, so the list can be long or infinite.
+-}
+
+-- | Register a typed table function on a connection or a loading extension.
+-- 'Database.DuckDB.Simple.Function.createTableFunction' gives the rules.
+--
+-- The bind callback converts the arguments and declares the result columns.
+-- See Note [Row lists of typed scans]. A parameter type or a column type with
+-- no declaration raises an error at registration. See
+-- Note [Type declarations] in "Database.DuckDB.Simple.ToField".
+createTableFunctionOn
+  :: forall params row. (FromRow params, TypedRow params, TypedRow row) => RegistrationTarget -> Text -> [Text] -> (params -> IO [row]) -> IO ()
+createTableFunctionOn target name columns function = do
+  when (Text.null name || Text.any (== '\0') name) $
+    throwInvalidArgument "table function name must be nonempty and must not contain NUL"
+  when (null columnDeclarations) $
+    throwInvalidArgument (name <> ": a table function must have at least one result column")
+  when (length columns /= length columnDeclarations) $
+    throwInvalidArgument (name <> ": " <> count columns <> " column names for " <> count columnDeclarations <> " result columns")
+  parameterTypes <-
+    rowDeclarations name ["parameter " <> argumentName index | index <- [0 ..]] (rowColumnDeclarations (Proxy @params))
+  columnTypes <- rowDeclarations name (map ("column " <>) columns) columnDeclarations
+  casts <- targetCastFactory target
+  let signature = positionalSignature parameterTypes Nothing
+      configure factory tableFunction = do
+        withIdentifier name (checked . c_duckdb_v2_table_function_set_name tableFunction)
+        output (c_duckdb_v2_table_function_get_signature tableFunction) >>= configureFunctionSignature factory signature
+      bind input result context = withTypeScope \scope -> withContextFactory context \factory -> do
+        params <- readArguments scope name (length parameterTypes) (callbackReadFactory casts factory) input
+        forM_ (zip columns columnTypes) \(column, dtype) ->
+          withTypeDeclaration factory dtype \logical ->
+            withIdentifier column \identifier -> checked (c_duckdb_v2_table_function_bind_add_result_column result identifier logical)
+        transferCallbackState (attachOpaque (c_duckdb_v2_function_bind_set_bind_data input)) (function params)
+  withRegistrationFactory target \factory ->
+    registerTableFunctionWith
+      target
+      (configure factory)
+      (tableCallbacks bind execute){tableInitGlobalCallback = Just initialize, tableProjectionPushdown = True}
+  where
+    count = Text.pack . show . length
+    columnDeclarations = rowColumnDeclarations (Proxy @row)
+    initialize info _ = do
+      scan <- readCallbackState (c_duckdb_v2_table_function_init_global_get_bind_data info)
+      remaining <- scan >>= newMVar :: IO (MVar [row])
+      transferCallbackState (attachOpaque (c_duckdb_v2_table_function_init_global_set_global_state info)) remaining
+    execute info context = withContextFactory context \factory -> do
+      remaining <- readCallbackState (c_duckdb_v2_table_function_exec_get_global_state info) :: IO (MVar [row])
+      chunk <- output (c_duckdb_v2_table_function_exec_get_output_chunk info)
+      -- The declared column of each vector. See Note [Row lists of typed scans].
+      requested <- output (c_duckdb_v2_table_function_exec_get_column_count info)
+      selected <- forM (takeWhile (< requested) [0 ..]) \index ->
+        fromIntegral <$> output (c_duckdb_v2_table_function_exec_get_column_index info index)
+      -- The lock gives each row to one call only. See
+      -- Note [Row lists of typed scans].
+      modifyMVar_ remaining (writeRows factory chunk selected)
+
+-- | Write the first rows of a list to the vectors of an output chunk. Return
+-- the rows that do not fit in the chunk. The function does not evaluate those
+-- rows. The list of columns gives the column of the row for each vector of the
+-- chunk, in the order of the vectors. The function makes the values of these
+-- columns only, so it does not evaluate the other columns. It evaluates each
+-- written row to its constructor, so it evaluates each strict field of the row.
+-- The values come from the borrowed factory. The function destroys each value
+-- after it writes it. The size of each vector becomes the number of written
+-- rows. An empty list writes no row. In the exec callback of a table function,
+-- no row ends the scan. See Note [Row lists of typed scans].
+writeRows :: forall row. (TypedRow row) => DuckDBV2FactoryHandle -> DuckDBV2DataChunkHandle -> [Int] -> [row] -> IO [row]
+writeRows factory chunk columns rows = do
+  capacity <- fromIntegral <$> output (c_duckdb_v2_data_chunk_get_capacity chunk)
+  vectorCount <- output (c_duckdb_v2_data_chunk_get_vector_count chunk)
+  let width = length (rowColumnDeclarations (Proxy @row))
+  when (fromIntegral vectorCount /= length columns || any (\column -> column < 0 || column >= width) columns) $
+    throwInternalError
+      ( "the output chunk has "
+          <> Text.pack (show vectorCount)
+          <> " vectors for the columns "
+          <> Text.pack (show columns)
+          <> " of a row of "
+          <> Text.pack (show width)
+          <> " columns"
+      )
+  case splitRows capacity rows of
+    (now, later) -> do
+      let size = fromIntegral (length now)
+      vectors <- forM (take (length columns) [0 ..]) \index -> do
+        vector <- output (c_duckdb_v2_data_chunk_get_vector chunk index)
+        -- Flatten after the size changes. See Note [Vector flatten] in
+        -- "Database.DuckDB.Simple.Materialize".
+        checked (c_duckdb_v2_vector_set_size vector size)
+        checked (c_duckdb_v2_vector_flatten vector)
+        pure vector
+      -- Use loops with a constant stack. See Note [Constant stack at safe calls]
+      -- in "Database.DuckDB.Simple.Native".
+      let select
+            | columns == [0 .. width - 1] = id
+            | otherwise = \values -> map (values !!) columns
+      forM_ (zip [0 ..] now) \(index, row) -> do
+        zipWithM_
+          (\vector (ColumnValue make) -> bracket (make factory) destroyValue (checked . c_duckdb_v2_vector_set_value vector index))
+          vectors
+          (select (rowColumnValues row))
+      pure later
+
+-- | Split a list after at most the given number of elements. Evaluate the
+-- spine of the first part only. The second part is the list after those
+-- elements, not a reference to the whole list. See
+-- Note [Row lists of typed scans].
+--
+-- In GHC 9.14.1, 'splitAt' of base gives its second part through a lazy
+-- pattern binding on the pair of each recursive call, so that part is a thunk
+-- on the inner pairs. This function gives the second part as the plain rest of
+-- the list.
+splitRows :: Int -> [a] -> ([a], [a])
+splitRows = go []
+  where
+    go taken 0 rest = (reverse taken, rest)
+    go taken _ [] = (reverse taken, [])
+    go taken limit (row : rest) = go (row : taken) (limit - 1) rest
+
+-- | Read the constant arguments of one call and convert them with 'FromRow'.
+-- A NULL argument is @FieldNull@. An argument that does not convert raises an
+-- error that names the table function.
+readArguments :: (FromRow params) => TypeScope -> Text -> Int -> ReadFactory -> DuckDBV2FunctionBindInfoHandle -> IO params
+readArguments scope name count factory input = do
+  fields <- forM (take count [0 ..]) \index ->
+    readBoundField scope factory input (argumentName index) (fromIntegral index)
+  converted <- runConversion (parseRow fromRow fields)
+  case converted of
+    Ok params -> pure params
+    Errors failures -> throwIO (userError ("duckdb-simple: " <> Text.unpack name <> ": " <> conversionMessage failures))
diff --git a/src/Database/DuckDB/Simple/Types.hs b/src/Database/DuckDB/Simple/Types.hs
--- a/src/Database/DuckDB/Simple/Types.hs
+++ b/src/Database/DuckDB/Simple/Types.hs
@@ -1,69 +1,69 @@
 {-# LANGUAGE TypeOperators #-}
 
-{- |
-Module      : Database.DuckDB.Simple.Types
-Description : Shared data types for the duckdb-simple public surface.
-
-The datatypes in this module are intentionally kept lightweight.  The main
-`Database.DuckDB.Simple` module exposes the types without their constructors so
-that callers interact with them through the high-level API.  The actual
-definitions live in @Database.DuckDB.Simple.Internal@.
--}
+-- |
+-- Module      : Database.DuckDB.Simple.Types
+-- Description : Shared data types for the duckdb-simple public surface.
+--
+-- This module defines t'Null', t'Only', @(:.)@, and t'FormatError'. It re-exports
+-- 'Connection', 'Statement', t'Query', t'SQLError', and 'ErrorType' from
+-- @Database.DuckDB.Simple.Internal@. This module and @Database.DuckDB.Simple@
+-- export 'Connection' and 'Statement' without their constructors. They export
+-- the other types with their constructors.
 module Database.DuckDB.Simple.Types (
-    Connection,
-    Statement,
-    Query (..),
-    SQLError (..),
-    FormatError (..),
-    Null (..),
-    Only (..),
-    (:.) (..),
+  Connection,
+  Statement,
+  Query (..),
+  SQLError (..),
+  ErrorType (..),
+  FormatError (..),
+  Null (..),
+  Only (..),
+  (:.) (..),
 ) where
 
 import Control.Exception (Exception)
 import Data.Text (Text)
 import qualified Data.Text as Text
-
 import Database.DuckDB.Simple.FromField (Field (..), FieldValue (..), FromField (..), ResultError (..), returnError)
 import Database.DuckDB.Simple.Internal (
-    Connection,
-    Query (..),
-    SQLError (..),
-    Statement,
+  Connection,
+  ErrorType (..),
+  Query (..),
+  SQLError (..),
+  Statement,
  )
-import Database.DuckDB.Simple.Ok (Ok (..))
 
 -- | Placeholder representing SQL @NULL@.
 data Null = Null
-    deriving (Eq, Ord, Show, Read)
+  deriving (Eq, Ord, Show, Read)
 
-{- | This instance is in this module because @Internal@ imports @FromField@.
-An import of this module from @FromField@ would cause an import cycle.
--}
+-- | Reads only a NULL value, of each SQL type. This instance is in this module
+-- because @Internal@ imports @FromField@. An import of this module from
+-- @FromField@ would cause an import cycle.
 instance FromField Null where
-    fromField f = case fieldValue f of
-        FieldNull -> Ok Null
-        _ -> returnError Incompatible f (Text.pack "expected NULL")
+  fromField f = case fieldValue f of
+    FieldNull -> pure Null
+    _ -> returnError Incompatible f (Text.pack "expected NULL")
 
 -- | Wrapper used for single-column rows.
 newtype Only a = Only {fromOnly :: a}
-    deriving (Eq, Ord, Show, Read)
+  deriving (Eq, Ord, Show, Read)
 
 -- | Convenience product type for combining @FromRow@ and @ToRow@ instances.
 data h :. t = h :. t
-    deriving (Eq, Ord, Show, Read)
+  deriving (Eq, Ord, Show, Read)
 
 infixr 3 :.
 
 -- | Raised when parameter formatting fails before a statement is executed.
 data FormatError = FormatError
-    { formatErrorMessage :: !Text
-    -- ^ Human-readable description of the mismatch (e.g. parameter counts).
-    , formatErrorQuery :: !Query
-    -- ^ Query that triggered the formatting failure.
-    , formatErrorParams :: ![String]
-    -- ^ Rendered parameter values supplied by the caller (used for diagnostics).
-    }
-    deriving (Eq, Show)
+  { formatErrorMessage :: !Text
+  -- ^ Human-readable description of the mismatch (e.g. parameter counts).
+  , formatErrorQuery :: !Query
+  -- ^ Query that triggered the formatting failure.
+  , formatErrorParams :: ![String]
+  -- ^ Rendered parameter values supplied by the caller (used for diagnostics).
+  }
+  deriving (Eq, Show)
 
 instance Exception FormatError
diff --git a/src/Database/DuckDB/Simple/V2/Config.hs b/src/Database/DuckDB/Simple/V2/Config.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/V2/Config.hs
@@ -0,0 +1,56 @@
+{-# LANGUAGE BlockArguments #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.V2.Config
+-- Description : Register custom options with native builders and update callbacks.
+--
+-- The functions of this module give native handles to their actions.
+-- "Database.DuckDB.Simple.Config" has the typed custom options.
+--
+-- Use 'registerCustomOptionWith' when the update callback needs the native update info. With that info, the
+-- callback can replace the new value with @c_duckdb_v2_custom_option_update_set_value@, read the scope of
+-- the write, or find if the update is a RESET. The configuration action sets the name, the type, and the
+-- other properties of the option with the @c_duckdb_v2_custom_option_set_@ functions of @Database.DuckDB.FFI.V2@.
+module Database.DuckDB.Simple.V2.Config (
+  registerCustomOptionWith,
+) where
+
+import Database.DuckDB.Simple.Callback (
+  attachOpaque,
+  checkTargetThreads,
+  guardContext,
+  install,
+  installOptional,
+  withCallbackResources,
+  withTarget,
+ )
+import Database.DuckDB.Simple.Native
+import Database.DuckDB.Simple.V2.Registration (ContextCallback, RegistrationTarget (..))
+
+-- | Configure and register a custom option with managed callback cleanup.
+-- The configuration action borrows the builder. Do not set user data or callbacks.
+-- An extension target includes the borrowed initialization context.
+registerCustomOptionWith
+  :: RegistrationTarget -> (DuckDBV2CustomOptionHandle -> IO ()) -> Maybe (ContextCallback DuckDBV2CustomOptionUpdateInfoHandle) -> IO ()
+registerCustomOptionWith target configure callback =
+  withTarget
+    target
+    c_duckdb_v2_custom_option_create
+    c_duckdb_v2_custom_option_destroy
+    c_duckdb_v2_connection_register_custom_option
+    c_duckdb_v2_extension_register_custom_option
+    \option register ->
+      withCallbackResources
+        (checkTargetThreads target)
+        ( \allocate -> installOptional callback \update ->
+            install
+              allocate
+              DuckDBV2CustomOptionUpdateCallbackFn
+              (DuckDBV2CustomOptionUpdateCallbackFn_Aux (guardContext update))
+              (c_duckdb_v2_custom_option_set_update_callback option)
+        )
+        (attachOpaque (c_duckdb_v2_custom_option_set_user_data option))
+        \installCallback -> do
+          configure option
+          installCallback
+          register
diff --git a/src/Database/DuckDB/Simple/V2/Copy.hs b/src/Database/DuckDB/Simple/V2/Copy.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/V2/Copy.hs
@@ -0,0 +1,295 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE RankNTypes #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.V2.Copy
+-- Description : Managed V2 COPY callbacks and multi-file table functions.
+--
+-- Callback info and context handles are borrowed and must not escape a callback.
+-- The registration user-data slot is reserved for callback cleanup. Use closures
+-- for registration data and 'setCallbackState' for bind, init, and batch state.
+-- Transfer state to each slot once. Use an @IORef@ to change existing state.
+-- COPY format callbacks require the threaded GHC runtime (@-threaded@).
+-- Batch preparation may run concurrently. Flushes for one output file are serial.
+-- Destroy a collection acquired with @copy_to_batch_take_input@ after use.
+-- Multi-file functions use the callbacks of a registered single-file table
+-- function.
+--
+-- Use this module when the row-oriented functions of "Database.DuckDB.Simple.Copy" are not sufficient, for
+-- example to get a batch as a native column data collection, to set the batch size, or to give the
+-- statistics for @RETURN_STATS@. Make a record of callbacks with 'copyToCallbacks' or 'copyFromCallbacks'.
+-- Then register it with 'registerCopyToCallbacks' or 'registerCopyFromCallbacks', or register both sides
+-- with 'registerCopyFunction'. 'registerMultiFileFunctionWith' adds file lists, globs, and hive partitions to
+-- a registered single-file table function.
+--
+-- The examples use the imports and the definitions of the module header of
+-- "Database.DuckDB.Simple.V2.Registration".
+module Database.DuckDB.Simple.V2.Copy (
+  CopyToCallbacks (..),
+  copyToCallbacks,
+  CopyFromCallbacks (..),
+  copyFromCallbacks,
+  registerCopyFunction,
+  registerCopyFunctionWith,
+  registerCopyToCallbacks,
+  registerCopyFromCallbacks,
+  registerMultiFileFunctionWith,
+  RegistrationTarget (..),
+  ContextCallback,
+  setCallbackState,
+  getCallbackState,
+) where
+
+import Control.Monad (when)
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Database.DuckDB.Simple.Callback (
+  Allocator,
+  attachOpaque,
+  guardContext,
+  install,
+  installAll,
+  installOptional,
+  requireWorkerCallbackRuntime,
+  withCallbackResources,
+  withTarget,
+ )
+import Database.DuckDB.Simple.Internal (Connection)
+import Database.DuckDB.Simple.Native
+import Database.DuckDB.Simple.V2.Registration (ContextCallback, RegistrationTarget (..), getCallbackState, setCallbackState)
+
+-- | Every COPY TO callback in the pinned V2 API. Batch and flush are required.
+data CopyToCallbacks = CopyToCallbacks
+  { copyToBindCallback :: Maybe (ContextCallback DuckDBV2CopyToBindInfoHandle)
+  , copyToBatchSizeCallback :: Maybe (ContextCallback DuckDBV2CopyToBatchSizeInfoHandle)
+  , copyToInitCallback :: Maybe (ContextCallback DuckDBV2CopyToInitInfoHandle)
+  , copyToBatchCallback :: ContextCallback DuckDBV2CopyToBatchInfoHandle
+  , copyToFlushCallback :: ContextCallback DuckDBV2CopyToFlushInfoHandle
+  , copyToFinalizeCallback :: Maybe (ContextCallback DuckDBV2CopyToFinalizeInfoHandle)
+  , copyToStatisticsCallback :: Maybe (ContextCallback DuckDBV2CopyToStatisticsInfoHandle)
+  }
+
+-- | Use batch and flush callbacks with no optional COPY TO callbacks.
+copyToCallbacks :: ContextCallback DuckDBV2CopyToBatchInfoHandle -> ContextCallback DuckDBV2CopyToFlushInfoHandle -> CopyToCallbacks
+copyToCallbacks batch flush = CopyToCallbacks Nothing Nothing Nothing batch flush Nothing Nothing
+
+-- | Every COPY FROM callback in the pinned V2 API. Bind and exec are required.
+data CopyFromCallbacks = CopyFromCallbacks
+  { copyFromBindCallback :: ContextCallback DuckDBV2CopyFromBindInfoHandle
+  , copyFromInitGlobalCallback :: Maybe (ContextCallback DuckDBV2CopyFromInitGlobalInfoHandle)
+  , copyFromInitLocalCallback :: Maybe (ContextCallback DuckDBV2CopyFromInitLocalInfoHandle)
+  , copyFromExecCallback :: ContextCallback DuckDBV2CopyFromExecInfoHandle
+  , copyFromProgressCallback :: Maybe (ContextCallback DuckDBV2CopyFromProgressInfoHandle)
+  }
+
+-- | Use bind and exec callbacks with no optional COPY FROM callbacks.
+copyFromCallbacks :: ContextCallback DuckDBV2CopyFromBindInfoHandle -> ContextCallback DuckDBV2CopyFromExecInfoHandle -> CopyFromCallbacks
+copyFromCallbacks bind execute = CopyFromCallbacks bind Nothing Nothing execute Nothing
+
+-- | Register either direction or both. The library allocates the callback pointers. It gives their cleanup
+-- to DuckDB in the user data of the native object. DuckDB runs the cleanup when it releases the object. See
+-- Note [Callback ownership] in
+-- <src/Database.DuckDB.Simple.Callback.html Database.DuckDB.Simple.Callback>.
+registerCopyFunction :: Connection -> Text -> Maybe CopyToCallbacks -> Maybe CopyFromCallbacks -> IO ()
+registerCopyFunction connection name to from = do
+  when (Text.null name || Text.any (== '\0') name) $ throwInvalidArgument "invalid copy function name"
+  registerCopyFunctionWith
+    (ConnectionTarget connection)
+    (\function -> withIdentifier name (checked . c_duckdb_v2_copy_function_set_name function))
+    to
+    from
+
+-- | Register COPY callbacks on a connection or a borrowed extension target.
+-- The configuration action sets the name of the format:
+--
+-- > V2Copy.registerCopyFunctionWith
+-- >   target
+-- >   (\function -> R.withIdentifier "managed_output" (R.checked . c_duckdb_v2_copy_function_set_name function))
+-- >   (Just callbacks)
+-- >   Nothing
+registerCopyFunctionWith
+  :: RegistrationTarget -> (DuckDBV2CopyFunctionHandle -> IO ()) -> Maybe CopyToCallbacks -> Maybe CopyFromCallbacks -> IO ()
+registerCopyFunctionWith target configure to from =
+  withTarget
+    target
+    c_duckdb_v2_copy_function_create
+    c_duckdb_v2_copy_function_destroy
+    c_duckdb_v2_connection_register_copy_function
+    c_duckdb_v2_extension_register_copy_function
+    \function register ->
+      withCallbackResources
+        (requireWorkerCallbackRuntime "COPY")
+        (\allocate -> installAll (toInstallers allocate function to <> fromInstallers allocate function from))
+        (attachOpaque (c_duckdb_v2_copy_function_set_user_data function))
+        \installCallbacks -> do
+          configure function
+          installCallbacks
+          register
+
+-- | Register the advanced COPY TO callback interface.
+--
+-- The example registers the format @managed_output@, which counts the rows. The init callback makes the
+-- output file and stores a counter as init data. The batch callback takes the rows of a batch and stores
+-- their count as batch data. The flush callback adds that count to the counter. The example does not write
+-- the rows. A format that writes rows converts them in the batch callback and writes them in the flush
+-- callback.
+--
+-- > withConnection ":memory:" \connection -> do
+-- >   total <- newIORef (0 :: DuckDBIdx)
+-- >   let initialize info _ = do
+-- >         path <- R.output (c_duckdb_v2_copy_to_init_get_file_path info) >>= R.readText
+-- >         writeFile (Text.unpack path) ""
+-- >         R.setCallbackState (c_duckdb_v2_copy_to_init_set_init_data info) total
+-- >       batch info _ = do
+-- >         count <-
+-- >           bracket
+-- >             (R.output (c_duckdb_v2_copy_to_batch_take_input info))
+-- >             (R.destroy c_duckdb_v2_column_data_collection_destroy)
+-- >             (R.output . c_duckdb_v2_column_data_collection_row_count)
+-- >         R.setCallbackState (c_duckdb_v2_copy_to_batch_set_batch_data info) count
+-- >       flush info _ = do
+-- >         count <- R.getCallbackState (c_duckdb_v2_copy_to_flush_get_batch_data info) :: IO DuckDBIdx
+-- >         state <- R.getCallbackState (c_duckdb_v2_copy_to_flush_get_init_data info) :: IO (IORef DuckDBIdx)
+-- >         atomicModifyIORef' state (\n -> (n + count, ()))
+-- >       callbacks = (V2Copy.copyToCallbacks batch flush){V2Copy.copyToInitCallback = Just initialize}
+-- >   V2Copy.registerCopyToCallbacks connection "managed_output" callbacks
+-- >   _ <- execute_ connection "COPY (SELECT i FROM range(5000) t(i)) TO 'numbers.out' (FORMAT managed_output)"
+-- >   readIORef total >>= print -- DuckDBIdx {unwrap = 5000}
+registerCopyToCallbacks :: Connection -> Text -> CopyToCallbacks -> IO ()
+registerCopyToCallbacks connection name callbacks = registerCopyFunction connection name (Just callbacks) Nothing
+
+-- | Register the advanced COPY FROM callback interface.
+registerCopyFromCallbacks :: Connection -> Text -> CopyFromCallbacks -> IO ()
+registerCopyFromCallbacks connection name callbacks = registerCopyFunction connection name Nothing (Just callbacks)
+
+-- | Allocate the configured COPY TO callbacks before installing them.
+toInstallers :: Allocator -> DuckDBV2CopyFunctionHandle -> Maybe CopyToCallbacks -> [IO (IO ())]
+toInstallers _ _ Nothing = []
+toInstallers allocate function (Just callbacks) =
+  [ installOptional (copyToBindCallback callbacks) $ \callback ->
+      install
+        allocate
+        DuckDBV2CopyToBindCallbackFn
+        (DuckDBV2CopyToBindCallbackFn_Aux (guardContext callback))
+        (c_duckdb_v2_copy_to_set_bind_callback function)
+  , installOptional (copyToBatchSizeCallback callbacks) $ \callback ->
+      install
+        allocate
+        DuckDBV2CopyToBatchSizeCallbackFn
+        (DuckDBV2CopyToBatchSizeCallbackFn_Aux (guardContext callback))
+        (c_duckdb_v2_copy_to_set_batch_size_callback function)
+  , installOptional (copyToInitCallback callbacks) $ \callback ->
+      install
+        allocate
+        DuckDBV2CopyToInitCallbackFn
+        (DuckDBV2CopyToInitCallbackFn_Aux (guardContext callback))
+        (c_duckdb_v2_copy_to_set_init_callback function)
+  , install
+      allocate
+      DuckDBV2CopyToBatchCallbackFn
+      (DuckDBV2CopyToBatchCallbackFn_Aux (guardContext (copyToBatchCallback callbacks)))
+      (c_duckdb_v2_copy_to_set_batch_callback function)
+  , install
+      allocate
+      DuckDBV2CopyToFlushCallbackFn
+      (DuckDBV2CopyToFlushCallbackFn_Aux (guardContext (copyToFlushCallback callbacks)))
+      (c_duckdb_v2_copy_to_set_flush_callback function)
+  , installOptional (copyToFinalizeCallback callbacks) $ \callback ->
+      install
+        allocate
+        DuckDBV2CopyToFinalizeCallbackFn
+        (DuckDBV2CopyToFinalizeCallbackFn_Aux (guardContext callback))
+        (c_duckdb_v2_copy_to_set_finalize_callback function)
+  , installOptional (copyToStatisticsCallback callbacks) $ \callback ->
+      install
+        allocate
+        DuckDBV2CopyToStatisticsCallbackFn
+        (DuckDBV2CopyToStatisticsCallbackFn_Aux (guardContext callback))
+        (c_duckdb_v2_copy_to_set_statistics_callback function)
+  ]
+
+-- | Allocate the configured COPY FROM callbacks before installing them.
+fromInstallers :: Allocator -> DuckDBV2CopyFunctionHandle -> Maybe CopyFromCallbacks -> [IO (IO ())]
+fromInstallers _ _ Nothing = []
+fromInstallers allocate function (Just callbacks) =
+  [ install
+      allocate
+      DuckDBV2CopyFromBindCallbackFn
+      (DuckDBV2CopyFromBindCallbackFn_Aux (guardContext (copyFromBindCallback callbacks)))
+      (c_duckdb_v2_copy_from_set_bind_callback function)
+  , installOptional (copyFromInitGlobalCallback callbacks) $ \callback ->
+      install
+        allocate
+        DuckDBV2CopyFromInitGlobalCallbackFn
+        (DuckDBV2CopyFromInitGlobalCallbackFn_Aux (guardContext callback))
+        (c_duckdb_v2_copy_from_set_init_global_callback function)
+  , installOptional (copyFromInitLocalCallback callbacks) $ \callback ->
+      install
+        allocate
+        DuckDBV2CopyFromInitLocalCallbackFn
+        (DuckDBV2CopyFromInitLocalCallbackFn_Aux (guardContext callback))
+        (c_duckdb_v2_copy_from_set_init_local_callback function)
+  , install
+      allocate
+      DuckDBV2CopyFromExecCallbackFn
+      (DuckDBV2CopyFromExecCallbackFn_Aux (guardContext (copyFromExecCallback callbacks)))
+      (c_duckdb_v2_copy_from_set_exec_callback function)
+  , installOptional (copyFromProgressCallback callbacks) $ \callback ->
+      install
+        allocate
+        DuckDBV2CopyFromProgressCallbackFn
+        (DuckDBV2CopyFromProgressCallbackFn_Aux (guardContext callback))
+        (c_duckdb_v2_copy_from_set_progress_callback function)
+  ]
+
+-- | Configure a multi-file wrapper on a connection or borrowed extension target.
+-- 'Database.DuckDB.Simple.Copy.registerMultiFileFunction' sets the same fields without a native handle.
+--
+-- The example registers the table function @managed_single@, which reads the integer in one file. Then it
+-- registers the multi-file function @managed_files@, which calls @managed_single@ for each file. The
+-- configuration action sets the two names. DuckDB can run the exec callback of the single-file function on
+-- more than one thread for one scan. Thus the exec callback takes its state with @atomicModifyIORef\'@.
+--
+-- > withConnection ":memory:" \connection -> do
+-- >   let bind input result context = do
+-- >         path <- bracket (R.output (c_duckdb_v2_function_bind_get_arg_value input 0)) (R.destroy c_duckdb_v2_value_destroy) \value ->
+-- >           R.output (c_duckdb_v2_value_get_varchar value) >>= R.readText
+-- >         value <- read <$> readFile (Text.unpack path) :: IO Int64
+-- >         R.setCallbackState (c_duckdb_v2_function_bind_set_bind_data input) value
+-- >         factory <- R.output (c_duckdb_v2_context_get_factory context)
+-- >         R.withTypeDeclaration factory bigint \dtype ->
+-- >           R.withIdentifier "value" \name -> R.checked (c_duckdb_v2_table_function_bind_add_result_column result name dtype)
+-- >       initialize info _ = do
+-- >         value <- R.getCallbackState (c_duckdb_v2_table_function_init_global_get_bind_data info)
+-- >         state <- newIORef (Just (value :: Int64))
+-- >         R.setCallbackState (c_duckdb_v2_table_function_init_global_set_global_state info) state
+-- >       executeRows info _ = do
+-- >         state <- R.getCallbackState (c_duckdb_v2_table_function_exec_get_global_state info) :: IO (IORef (Maybe Int64))
+-- >         value <- atomicModifyIORef' state (\previous -> (Nothing, previous))
+-- >         chunk <- R.output (c_duckdb_v2_table_function_exec_get_output_chunk info)
+-- >         vector <- R.output (c_duckdb_v2_data_chunk_get_vector chunk 0)
+-- >         writeIntegers vector (maybe [] pure value)
+-- >   R.registerTableFunction
+-- >     connection
+-- >     "managed_single"
+-- >     [R.parameter "path" (R.TypeExpression "VARCHAR")]
+-- >     (R.tableCallbacks bind executeRows){R.tableInitGlobalCallback = Just initialize}
+-- >   V2Copy.registerMultiFileFunctionWith (R.ConnectionTarget connection) \function -> do
+-- >     R.withText "managed_files" \(ConstPtr view) -> R.checked (c_duckdb_v2_multi_file_function_set_name function view)
+-- >     R.withText "managed_single" \(ConstPtr view) -> R.checked (c_duckdb_v2_multi_file_function_set_single_file_function function view)
+-- >   writeFile "first.mock" "7"
+-- >   writeFile "second.mock" "11"
+-- >   rows <- query_ connection "SELECT value FROM managed_files('*.mock') ORDER BY value"
+-- >   print (map fromOnly rows :: [Int64]) -- [7,11]
+registerMultiFileFunctionWith :: RegistrationTarget -> (DuckDBV2MultiFileFunctionHandle -> IO ()) -> IO ()
+registerMultiFileFunctionWith target configure =
+  withTarget
+    target
+    c_duckdb_v2_multi_file_function_create
+    c_duckdb_v2_multi_file_function_destroy
+    c_duckdb_v2_connection_register_multi_file_function
+    c_duckdb_v2_extension_register_multi_file_function
+    \function register -> do
+      configure function
+      register
diff --git a/src/Database/DuckDB/Simple/V2/FunctionDocs.hs b/src/Database/DuckDB/Simple/V2/FunctionDocs.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/V2/FunctionDocs.hs
@@ -0,0 +1,51 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE NamedFieldPuns #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.V2.FunctionDocs
+-- Description : Documentation attached to scalar, aggregate, table, macro, and pragma functions.
+--
+-- The examples use the imports of the module header of "Database.DuckDB.Simple.V2.Registration".
+module Database.DuckDB.Simple.V2.FunctionDocs (
+  FunctionDocs (..),
+  defaultFunctionDocs,
+  setFunctionDocs,
+) where
+
+import Control.Monad (forM_)
+import Data.Text (Text)
+import Database.DuckDB.Simple.Native
+
+-- | A description, titled SQL examples, and category names.
+-- Each example is a pair of a title and the SQL text:
+--
+-- > Docs.FunctionDocs (Just "Preserve the input type.") [("Example", "SELECT managed_resolved(42)")] ["test"]
+data FunctionDocs = FunctionDocs
+  { functionDescription :: Maybe Text
+  , functionExamples :: [(Text, Text)]
+  , functionCategories :: [Text]
+  }
+  deriving (Eq, Show, Read)
+
+-- | Leave the description unset and add no examples or categories.
+defaultFunctionDocs :: FunctionDocs
+defaultFunctionDocs = FunctionDocs Nothing [] []
+
+-- | Apply documentation to a borrowed native documentation handle.
+-- Get the handle from the function builder in its configuration action.
+-- The action replaces the description when present and appends examples and categories.
+-- DuckDB copies all text before the action returns.
+-- For example, in the configuration action of
+-- 'Database.DuckDB.Simple.V2.Registration.registerScalarFunctionWith':
+--
+-- > docs <- R.output (c_duckdb_v2_scalar_function_get_docs function)
+-- > Docs.setFunctionDocs docs Docs.defaultFunctionDocs{Docs.functionDescription = Just "Add two BIGINT values."}
+setFunctionDocs :: DuckDBV2FunctionDocsHandle -> FunctionDocs -> IO ()
+setFunctionDocs docs FunctionDocs{functionDescription, functionExamples, functionCategories} = do
+  forM_ functionDescription \description ->
+    withText description (checked . c_duckdb_v2_function_docs_set_description docs)
+  forM_ functionExamples \(title, sql) ->
+    withText title \nativeTitle ->
+      withText sql \nativeSQL -> checked (c_duckdb_v2_function_docs_add_example docs nativeTitle nativeSQL)
+  forM_ functionCategories \category ->
+    withText category (checked . c_duckdb_v2_function_docs_add_category docs)
diff --git a/src/Database/DuckDB/Simple/V2/Logging.hs b/src/Database/DuckDB/Simple/V2/Logging.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/V2/Logging.hs
@@ -0,0 +1,27 @@
+{-# LANGUAGE BlockArguments #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.V2.Logging
+-- Description : Write log messages through the context of a native callback.
+--
+-- The function of this module gets the borrowed context of a native callback.
+-- "Database.DuckDB.Simple.Logging" has the log sinks and the functions that write
+-- messages for a connection or an instance.
+--
+-- The example uses the imports of the module header of "Database.DuckDB.Simple.V2.Registration".
+module Database.DuckDB.Simple.V2.Logging (
+  logMessage,
+) where
+
+import Data.Text (Text)
+import Database.DuckDB.Simple.Native
+
+-- | Emit a message from a native callback's borrowed context.
+-- A log sink gets the first text as 'Database.DuckDB.Simple.Logging.logEntryType' and the second text as
+-- 'Database.DuckDB.Simple.Logging.logEntryMessage'. For example, in the exec callback of a scalar function:
+--
+-- > V2Logging.logMessage context Logging.LogLevelWarning "HaskellContext" "from a callback"
+logMessage :: DuckDBV2ContextHandle -> LogLevel -> Text -> Text -> IO ()
+logMessage context level category message =
+  withText category \kind -> withText message \body ->
+    checked (c_duckdb_v2_context_log context (logLevelToNative level) kind body)
diff --git a/src/Database/DuckDB/Simple/V2/LogicalRep.hs b/src/Database/DuckDB/Simple/V2/LogicalRep.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/V2/LogicalRep.hs
@@ -0,0 +1,304 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE LambdaCase #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.V2.LogicalRep
+-- Description : Convert logical type trees to and from native logical types.
+--
+-- The functions of this module read and create native logical type handles.
+-- "Database.DuckDB.Simple.LogicalRep" has the Haskell type trees.
+--
+-- The examples use the imports of the module header of "Database.DuckDB.Simple.V2.Registration".
+module Database.DuckDB.Simple.V2.LogicalRep (
+  logicalTypeToRep,
+  logicalTypeToBaseRep,
+  valuesHaveType,
+  logicalTypeFromRep,
+  logicalTypeFromRepWith,
+  bindingLogicalType,
+  destroyLogicalType,
+) where
+
+import Control.Exception (bracket, mask_, onException, tryJust)
+import Control.Monad (foldM, forM, when)
+import Data.Array (elems, listArray)
+import Data.Char (isSpace)
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep (..), StructField (..), UnionMemberType (..))
+import Database.DuckDB.Simple.Native
+import Foreign.C.ConstPtr (ConstPtr (..))
+import Foreign.Marshal.Alloc (alloca)
+import Foreign.Marshal.Array (withArray)
+import Foreign.Marshal.Utils (with)
+import Foreign.Ptr (nullPtr)
+import Foreign.Storable (peek)
+
+-- | Copy a native logical type into a Haskell type tree. A type with an alias
+-- gives 'LogicalTypeAlias', at each depth. See Note [Type aliases] in
+-- "Database.DuckDB.Simple.LogicalRep". The function does not destroy the
+-- handle. Keep the factory's owner alive until the function returns:
+--
+-- > bracket (R.output (c_duckdb_v2_vector_get_logical_type vector)) destroyLogicalType (logicalTypeToRep factory)
+logicalTypeToRep :: DuckDBV2FactoryHandle -> DuckDBV2LogicalTypeHandle -> IO LogicalTypeRep
+logicalTypeToRep factory = convertLogicalType (Just factory) ReadEnumDictionary
+
+-- | Copy a native logical type into a Haskell type tree with no alias, at each
+-- depth. Use it when decoding or binding needs only base types. The function
+-- reads no type name. See Note [Type aliases] in
+-- "Database.DuckDB.Simple.LogicalRep". The function does not destroy the
+-- handle.
+logicalTypeToBaseRep :: DuckDBV2LogicalTypeHandle -> IO LogicalTypeRep
+logicalTypeToBaseRep = convertLogicalType Nothing ReadEnumDictionary
+
+-- | Check the types of borrowed values against a borrowed logical type,
+-- including exact field names, collations, and CRS definitions. Each temporary
+-- value type is released before the next value is checked. See
+-- Note [Element types of a list] in "Database.DuckDB.Simple.ToField".
+valuesHaveType :: DuckDBV2LogicalTypeHandle -> [DuckDBV2ValueHandle] -> IO Bool
+valuesHaveType logical values = do
+  expected <- key logical
+  let check [] = pure True
+      check (value : remaining) = do
+        matches <- bracket (output (c_duckdb_v2_value_get_logical_type value)) destroyLogicalType \actual -> do
+          equal <- output (c_duckdb_v2_logical_type_is_equal logical actual)
+          if equal == 0 then pure False else (== expected) <$> key actual
+        if matches then check remaining else pure False
+  check values
+  where
+    -- Native equality checks aliases and ENUM dictionaries. The partial trees
+    -- are comparison keys only. They do not leave this function.
+    key = convertLogicalType Nothing OmitEnumDictionary
+
+-- | Select complete dictionaries or private comparison keys.
+data EnumDictionary = ReadEnumDictionary | OmitEnumDictionary
+
+-- | Copy a native logical type into a Haskell type tree. With a factory, keep
+-- each alias. Without a factory, read no type name.
+convertLogicalType :: Maybe DuckDBV2FactoryHandle -> EnumDictionary -> DuckDBV2LogicalTypeHandle -> IO LogicalTypeRep
+convertLogicalType factory dictionary logical = do
+  dtype <- output (c_duckdb_v2_logical_type_get_id logical)
+  let parameter index action = alloca \nameSlot ->
+        bracket (output (c_duckdb_v2_logical_type_get_param logical index nameSlot)) (destroy c_duckdb_v2_value_destroy) \value -> do
+          name <- peek nameSlot >>= readIdentifier
+          action name value
+      child index = parameter index \_ value ->
+        bracket (output (c_duckdb_v2_value_get_type value)) destroyLogicalType (convertLogicalType factory dictionary)
+      string index = parameter index \_ value -> output (c_duckdb_v2_value_get_varchar value) >>= readText
+      count = output (c_duckdb_v2_logical_type_get_param_count logical) >>= word64ToInt
+      fields make = do
+        size <- count
+        listArray (0, size - 1)
+          <$> forM
+            [0 .. size - 1]
+            ( \index -> parameter (fromIntegral index) \name value -> do
+                rep <- bracket (output (c_duckdb_v2_value_get_type value)) destroyLogicalType (convertLogicalType factory dictionary)
+                pure (make name rep)
+            )
+  base <- case dtype of
+    DuckDBV2LogicalTypeIdGeometry -> do
+      size <- count
+      LogicalTypeGeometry <$> if size == 0 then pure Nothing else Just <$> string 0
+    DuckDBV2LogicalTypeIdStruct -> LogicalTypeStruct <$> fields StructField
+    DuckDBV2LogicalTypeIdTuple -> LogicalTypeTuple <$> fields (\_ rep -> rep)
+    DuckDBV2LogicalTypeIdVarchar -> do
+      size <- count
+      if size == 0 then pure (LogicalTypeScalar LogicalTypeIdVarchar) else LogicalTypeCollatedVarchar <$> string 0
+    DuckDBV2LogicalTypeIdUnion -> LogicalTypeUnion <$> fields UnionMemberType
+    DuckDBV2LogicalTypeIdList -> LogicalTypeList <$> child 0
+    DuckDBV2LogicalTypeIdArray -> do
+      element <- child 0
+      size <- parameter 1 \_ value -> output (c_duckdb_v2_value_get_bigint value)
+      pure (LogicalTypeArray element (fromIntegral size))
+    DuckDBV2LogicalTypeIdMap -> LogicalTypeMap <$> child 0 <*> child 1
+    DuckDBV2LogicalTypeIdDecimal ->
+      LogicalTypeDecimal
+        <$> parameter 0 (\_ value -> output (c_duckdb_v2_value_get_utinyint value))
+        <*> parameter 1 (\_ value -> output (c_duckdb_v2_value_get_utinyint value))
+    DuckDBV2LogicalTypeIdEnum -> case dictionary of
+      OmitEnumDictionary -> pure (LogicalTypeEnum (listArray (0, -1) []))
+      ReadEnumDictionary -> do
+        size <- count
+        -- A dictionary can have many entries, and each entry makes native
+        -- calls. The fold keeps a constant stack. See
+        -- Note [Constant stack at safe calls] in "Database.DuckDB.Simple.Native".
+        LogicalTypeEnum . listArray (0, size - 1) . reverse
+          <$> foldM (\entries index -> (: entries) <$> string (fromIntegral index)) [] [0 .. size - 1]
+    _ -> LogicalTypeScalar <$> logicalTypeIdFromNative dtype
+  case factory of
+    Nothing -> pure base
+    Just nativeFactory -> do
+      ident <- logicalTypeIdFromNative dtype
+      typeName <- output (c_duckdb_v2_logical_type_get_name logical) >>= readIdentifier
+      -- See Note [Type aliases] in "Database.DuckDB.Simple.LogicalRep".
+      hasAlias <-
+        if typeName /= logicalTypeIdName ident
+          then pure True
+          else withIdentifier typeName \name ->
+            bracket
+              (output (c_duckdb_v2_factory_create_type_with_alias nativeFactory logical name))
+              destroyLogicalType
+              (\aliased -> (/= 0) <$> output (c_duckdb_v2_logical_type_is_equal logical aliased))
+      pure (if hasAlias then LogicalTypeAlias typeName base else base)
+
+-- | Construct an owned logical type through a borrowed native factory.
+-- Keep the owner of the factory alive until you destroy the type.
+-- CRS labels must be recognized by the native type constructor. Use the resolver
+-- in 'logicalTypeFromRepWith' for SQL-derived types with arbitrary CRS labels.
+-- 'Database.DuckDB.Simple.V2.Registration.withTypeDeclaration' constructs the type for an action and then destroys it.
+--
+-- > bracket (logicalTypeFromRep factory (LogicalTypeList (LogicalTypeScalar LogicalTypeIdBigInt))) destroyLogicalType (logicalTypeToRep factory)
+logicalTypeFromRep :: DuckDBV2FactoryHandle -> LogicalTypeRep -> IO DuckDBV2LogicalTypeHandle
+logicalTypeFromRep factory = logicalTypeFromRepWith factory (const (pure Nothing))
+
+-- | Construct a type tree through a borrowed native factory. Use the resolver
+-- for owned native leaf types. It runs before the parent types are constructed.
+logicalTypeFromRepWith
+  :: DuckDBV2FactoryHandle -> (LogicalTypeRep -> IO (Maybe DuckDBV2LogicalTypeHandle)) -> LogicalTypeRep -> IO DuckDBV2LogicalTypeHandle
+logicalTypeFromRepWith factory resolve = create
+  where
+    boxed rep = bracket (create rep) destroyLogicalType (output . c_duckdb_v2_value_create_type factory)
+    text value = withText value (output . c_duckdb_v2_value_create_varchar factory)
+    fromText value = withText value (output . c_duckdb_v2_factory_create_type_from_text factory)
+    fromName value = withIdentifier value \part ->
+      bracket (output (c_duckdb_v2_qname_create part 1)) (destroy c_duckdb_v2_qname_destroy) \name ->
+        output (c_duckdb_v2_factory_create_type_from_name factory name (ConstPtr nullPtr) (ConstPtr nullPtr) 0)
+    construct dtype names actions = do
+      when (any (Text.any (== '\0')) names) $
+        throwInvalidArgument (Text.pack "logical type name contains NUL")
+      withCreatedValues actions \values ->
+        withArray values \valuePtr ->
+          if null names
+            then output (c_duckdb_v2_factory_create_type_from_id factory dtype (ConstPtr nullPtr) (ConstPtr valuePtr) (fromIntegral (length values)))
+            else withIdentifierArray names \namePtr ->
+              output (c_duckdb_v2_factory_create_type_from_id factory dtype (ConstPtr namePtr) (ConstPtr valuePtr) (fromIntegral (length values)))
+    -- The binding resolver supplies CRS leaves. See Note [Bind-time CRS types].
+    create rep = resolve rep >>= maybe (constructRep rep) pure
+    constructRep = \case
+      LogicalTypeScalar LogicalTypeIdVariant -> fromName (Text.pack "VARIANT")
+      LogicalTypeScalar LogicalTypeIdGeometry -> fromText (Text.pack "GEOMETRY")
+      LogicalTypeScalar LogicalTypeIdSQLNull -> fromName (Text.pack "NULL")
+      LogicalTypeScalar dtype -> construct (logicalTypeIdToNative dtype) [] []
+      LogicalTypeCollatedVarchar collation -> construct DuckDBV2LogicalTypeIdVarchar [Text.pack "collation"] [text collation]
+      LogicalTypeGeometry Nothing -> fromText (Text.pack "GEOMETRY")
+      LogicalTypeGeometry (Just crs) ->
+        directGeometryType factory crs
+          >>= maybe
+            ( throwInvalidArgument
+                (Text.pack "DuckDB did not preserve the requested GEOMETRY CRS; use a recognized identifier or a complete CRS definition")
+            )
+            pure
+      LogicalTypeDecimal width scale -> do
+        when (width < 1 || width > 38 || scale > width) $
+          throwInvalidArgument (Text.pack "invalid DECIMAL width or scale")
+        construct
+          DuckDBV2LogicalTypeIdDecimal
+          []
+          [output (c_duckdb_v2_value_create_utinyint factory width), output (c_duckdb_v2_value_create_utinyint factory scale)]
+      LogicalTypeList element -> construct DuckDBV2LogicalTypeIdList [] [boxed element]
+      -- See Note [Sized ARRAY bounds] in "Database.DuckDB.Simple.Native".
+      LogicalTypeArray element size -> do
+        maybe (pure ()) throwInvalidArgument (arraySizeReason (toInteger size))
+        construct DuckDBV2LogicalTypeIdArray [] [boxed element, output (c_duckdb_v2_value_create_bigint factory (fromIntegral size))]
+      LogicalTypeMap key value -> construct DuckDBV2LogicalTypeIdMap [] [boxed key, boxed value]
+      LogicalTypeStruct fields
+        | null (elems fields) ->
+            bracket
+              (output (c_duckdb_v2_value_create_struct factory (ConstPtr nullPtr) (ConstPtr nullPtr) 0))
+              destroyValue
+              (output . c_duckdb_v2_value_get_logical_type)
+      LogicalTypeStruct fields -> construct DuckDBV2LogicalTypeIdStruct (map structFieldName (elems fields)) (map (boxed . structFieldValue) (elems fields))
+      LogicalTypeTuple fields
+        | null (elems fields) ->
+            bracket (output (c_duckdb_v2_value_create_tuple factory (ConstPtr nullPtr) 0)) destroyValue (output . c_duckdb_v2_value_get_logical_type)
+        | otherwise -> construct DuckDBV2LogicalTypeIdTuple [] (map boxed (elems fields))
+      LogicalTypeUnion members -> construct DuckDBV2LogicalTypeIdUnion (map unionMemberName (elems members)) (map (boxed . unionMemberType) (elems members))
+      LogicalTypeEnum entries -> construct DuckDBV2LogicalTypeIdEnum [] (map text (elems entries))
+      -- See Note [Type aliases] in "Database.DuckDB.Simple.LogicalRep".
+      LogicalTypeAlias name base -> do
+        when (Text.any (== '\0') name) $
+          throwInvalidArgument (Text.pack "logical type name contains NUL")
+        bracket (create base) destroyLogicalType \logical ->
+          withIdentifier name (output . c_duckdb_v2_factory_create_type_with_alias factory logical)
+
+-- | Reject a native count that does not fit a Haskell array index.
+word64ToInt :: (Integral a) => a -> IO Int
+word64ToInt value
+  | toInteger value <= toInteger (maxBound :: Int) = pure (fromIntegral value)
+  | otherwise = throwInternalError (Text.pack "logical type parameter count exceeds Int range")
+
+-- | Construct an owned binding type. Resolve CRS leaves at every depth.
+-- The factory must belong to a connection on the supplied instance.
+bindingLogicalType
+  :: DuckDBV2FactoryHandle
+  -> DuckDBV2InstanceHandle
+  -> LogicalTypeRep
+  -> IO DuckDBV2LogicalTypeHandle
+bindingLogicalType factory instance_ = logicalTypeFromRepWith factory resolve
+  where
+    resolve (LogicalTypeGeometry (Just crs)) = do
+      direct <- tryJust unrecognized (directGeometryType factory crs)
+      Just <$> case direct of
+        Right (Just logical) -> pure logical
+        _ -> queryGeometryType crs instance_
+    resolve _ = pure Nothing
+    unrecognized err
+      | sqlErrorType err == Just ErrorQueryBinder
+      , Just body <- sqlErrorBody err
+      , Text.pack "Encountered unrecognized coordinate system '" `Text.isPrefixOf` body =
+          Just ()
+      | otherwise = Nothing
+
+{- Note [Bind-time CRS types]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Bindings construct native types from their declarations at every depth. The
+connection factory constructs recognized CRS types directly. For an unknown
+label, DuckDB either reports its specific binder error or drops the CRS when
+ignore_unknown_crs is set. Only these two outcomes use the SQL fallback.
+Any other error from the native constructor propagates to the caller.
+
+The fallback opens a separate connection on the same instance. It cannot run
+SQL on the caller connection because the caller can have an active result.
+The query applies fully qualified built-ins to a WKB literal and the bound label.
+The SELECT has a schema before its first execution step. Copy its field type
+while the schema is live. The helper can close without fetching a row.
+Typed NULLs and empty containers use the same resolver as nonempty values.
+-}
+
+-- | Construct a CRS type directly. Return 'Nothing' if DuckDB drops its CRS.
+-- Keep native errors so the binding resolver can select the unknown CRS error.
+directGeometryType :: DuckDBV2FactoryHandle -> Text -> IO (Maybe DuckDBV2LogicalTypeHandle)
+directGeometryType factory crs = mask_ do
+  validateGeometryCRS crs
+  logical <- withText crs \text ->
+    bracket (output (c_duckdb_v2_value_create_varchar factory text)) destroyValue \value ->
+      with value \values ->
+        output (c_duckdb_v2_factory_create_type_from_id factory DuckDBV2LogicalTypeIdGeometry (ConstPtr nullPtr) (ConstPtr values) 1)
+  count <- output (c_duckdb_v2_logical_type_get_param_count logical) `onException` destroyLogicalType logical
+  if count == 0 then destroyLogicalType logical >> pure Nothing else pure (Just logical)
+
+-- | Reject CRS text that cannot identify a coordinate system.
+validateGeometryCRS :: Text -> IO ()
+validateGeometryCRS crs =
+  when (Text.all isSpace crs || Text.any (== '\0') crs) $
+    throwInvalidArgument (Text.pack "a GEOMETRY CRS must be nonblank and must not contain NUL")
+
+-- | Read one owned GEOMETRY type from a short-lived helper connection.
+queryGeometryType :: Text -> DuckDBV2InstanceHandle -> IO DuckDBV2LogicalTypeHandle
+queryGeometryType crs instance_ = mask_ $
+  bracket (output (c_duckdb_v2_connection_create instance_)) (destroy c_duckdb_v2_connection_destroy) \connection ->
+    withSQLStatement connection sql \parsed -> withConnectionFactory connection \factory ->
+      withText crs \name -> bracket (output (c_duckdb_v2_value_create_varchar factory name)) destroyValue \label ->
+        with label \param ->
+          bracket
+            (output (c_duckdb_v2_statement_execute connection parsed (ConstPtr nullPtr) (ConstPtr param) 1))
+            (destroy c_duckdb_v2_result_destroy)
+            \result ->
+              bracket (output (c_duckdb_v2_result_get_schema result)) (destroy c_duckdb_v2_schema_destroy) \schema -> alloca \nameSlot -> do
+                logical <- output (c_duckdb_v2_schema_get_field schema 0 nameSlot)
+                count <- output (c_duckdb_v2_logical_type_get_param_count logical)
+                when (count == 0) $ throwInvalidArgument (Text.pack "the type query did not preserve the GEOMETRY CRS")
+                output (c_duckdb_v2_logical_type_copy logical)
+  where
+    -- Little-endian WKB for GEOMETRYCOLLECTION EMPTY. The hex literal has type BLOB.
+    sql = Text.pack "SELECT system.main.ST_SetCRS(system.main.ST_GeomFromWKB(X'010700000000000000'), ?)"
diff --git a/src/Database/DuckDB/Simple/V2/Pragma.hs b/src/Database/DuckDB/Simple/V2/Pragma.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/V2/Pragma.hs
@@ -0,0 +1,121 @@
+{-# LANGUAGE BlockArguments #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.V2.Pragma
+-- Description : Register PRAGMA functions with callbacks that get native handles.
+--
+-- The callbacks of this module get the borrowed bind info and context of the
+-- call. "Database.DuckDB.Simple.Pragma" has the typed callbacks.
+--
+-- Use this module to read the arguments of a call as native values, to set the documentation of a pragma,
+-- or to register a pragma on an extension target. 'registerPragmaFunctionOn' declares the name and the
+-- parameters. 'registerPragmaFunctionWith' gives the native builder to a configuration action. A pragma has
+-- one callback: a 'QueryPragma' or an 'ExecPragma'.
+--
+-- The example uses the imports and the definitions of the module header of
+-- "Database.DuckDB.Simple.V2.Registration".
+module Database.DuckDB.Simple.V2.Pragma (
+  PragmaCallback (..),
+  registerPragmaFunctionOn,
+  registerPragmaFunctionWith,
+) where
+
+import Control.Monad (when)
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Database.DuckDB.Simple.Callback (
+  attachOpaque,
+  checkTargetThreads,
+  guardContext,
+  install,
+  runCallback,
+  withCallbackResources,
+  withTarget,
+ )
+import Database.DuckDB.Simple.Native
+import Database.DuckDB.Simple.V2.Registration (
+  ContextCallback,
+  FunctionParameter,
+  FunctionSignature (..),
+  RegistrationTarget (..),
+  configureFunctionSignature,
+  withRegistrationFactory,
+ )
+
+-- | A query callback returns SQL to run in place of the PRAGMA statement.
+-- An execution callback performs an action and returns no rows. Callback handles
+-- are borrowed. Exceptions become SQL errors. DuckDB permits exactly one callback.
+data PragmaCallback
+  = QueryPragma (DuckDBV2FunctionBindInfoHandle -> DuckDBV2ContextHandle -> IO Text)
+  | ExecPragma (ContextCallback DuckDBV2FunctionBindInfoHandle)
+
+-- | Register a pragma on a connection or a loading extension. The name must not
+-- be empty and must not contain NUL.
+registerPragmaFunctionOn :: RegistrationTarget -> Text -> [FunctionParameter] -> PragmaCallback -> IO ()
+registerPragmaFunctionOn target name parameters callback = do
+  when (Text.null name || Text.any (== '\0') name) $
+    throwInvalidArgument (Text.pack "pragma function name must be nonempty and must not contain NUL")
+  withRegistrationFactory target \factory ->
+    registerPragmaFunctionWith
+      target
+      ( \function -> do
+          withIdentifier name (checked . c_duckdb_v2_pragma_function_set_name function)
+          signature <- output (c_duckdb_v2_pragma_function_get_signature function)
+          configureFunctionSignature factory (FunctionSignature parameters Nothing) signature
+      )
+      callback
+
+-- | Configure a pragma on a connection or a loading extension.
+-- The action borrows the builder and can set its name, signature, and documentation.
+-- Do not set native callbacks or user data. The library owns the callback pointer.
+-- Use Haskell closures to retain registration data.
+--
+-- The example registers an execution pragma that counts its calls. The configuration action sets the name
+-- and the description of the pragma.
+--
+-- > withConnection ":memory:" \connection -> do
+-- >   calls <- newIORef (0 :: Int)
+-- >   Pragma.registerPragmaFunctionWith
+-- >     (R.ConnectionTarget connection)
+-- >     ( \function -> do
+-- >         R.withIdentifier "managed_exec" (R.checked . c_duckdb_v2_pragma_function_set_name function)
+-- >         docs <- R.output (c_duckdb_v2_pragma_function_get_docs function)
+-- >         Docs.setFunctionDocs docs Docs.defaultFunctionDocs{Docs.functionDescription = Just "Count calls."}
+-- >     )
+-- >     (Pragma.ExecPragma (\_ _ -> modifyIORef' calls (+ 1)))
+-- >   _ <- execute_ connection "PRAGMA managed_exec"
+-- >   readIORef calls >>= print -- 1
+registerPragmaFunctionWith :: RegistrationTarget -> (DuckDBV2PragmaFunctionHandle -> IO ()) -> PragmaCallback -> IO ()
+registerPragmaFunctionWith target configure callback =
+  withTarget
+    target
+    c_duckdb_v2_pragma_function_create
+    c_duckdb_v2_pragma_function_destroy
+    c_duckdb_v2_connection_register_pragma_function
+    c_duckdb_v2_extension_register_pragma_function
+    \function register ->
+      withCallbackResources
+        (checkTargetThreads target)
+        ( \allocate -> case callback of
+            QueryPragma action ->
+              install
+                allocate
+                DuckDBV2PragmaFunctionQueryCallbackFn
+                ( DuckDBV2PragmaFunctionQueryCallbackFn_Aux \info result context err ->
+                    runCallback err do
+                      sql <- action info context
+                      withText sql (checked . c_duckdb_v2_pragma_function_query_set_query result)
+                )
+                (c_duckdb_v2_pragma_function_set_query_callback function)
+            ExecPragma action ->
+              install
+                allocate
+                DuckDBV2PragmaFunctionExecCallbackFn
+                (DuckDBV2PragmaFunctionExecCallbackFn_Aux (guardContext action))
+                (c_duckdb_v2_pragma_function_set_exec_callback function)
+        )
+        (attachOpaque (c_duckdb_v2_pragma_function_set_user_data function))
+        \installCallback -> do
+          configure function
+          installCallback
+          register
diff --git a/src/Database/DuckDB/Simple/V2/Registration.hs b/src/Database/DuckDB/Simple/V2/Registration.hs
new file mode 100644
--- /dev/null
+++ b/src/Database/DuckDB/Simple/V2/Registration.hs
@@ -0,0 +1,962 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications #-}
+
+-- |
+-- Module      : Database.DuckDB.Simple.V2.Registration
+-- Description : Advanced V2 registration with Haskell callbacks.
+--
+-- The library allocates the callback pointers. It gives their cleanup to DuckDB in the user data of the
+-- native object. DuckDB runs the cleanup when it releases the object. See Note [Callback ownership] in
+-- <src/Database.DuckDB.Simple.Callback.html Database.DuckDB.Simple.Callback>.
+-- Callback info and context handles are borrowed and must
+-- not escape the callback. Use @Database.DuckDB.FFI.V2@ operations with 'checked'
+-- and 'output' in callbacks.
+--
+-- The registration user-data slot is reserved for callback cleanup. Use Haskell
+-- closures for registration data and 'setCallbackState' for bind or execution
+-- state. A state getter with a different type than its setter raises an error.
+-- Synchronize access to state that DuckDB shares between workers.
+--
+-- The pinned V2 API has no custom file-system registration API. Use
+-- @Database.DuckDB.Simple.Logging@ for managed log-sink registration.
+--
+-- Use this module when the typed functions of "Database.DuckDB.Simple.Function" cannot express a
+-- registration. This module adds named-only and variadic parameters, parameter defaults, a return type that
+-- a callback resolves, function properties, function documentation, and callbacks that read and write
+-- native vectors. A registration has three parts: the parameters from 'parameter', a record of callbacks
+-- from 'scalarCallbacks', 'aggregateCallbacks', or 'tableCallbacks', and a call of
+-- 'registerScalarFunction', 'registerAggregateFunction', or 'registerTableFunction'. The functions with the
+-- suffix @With@ give the native builder to a configuration action and accept an extension target.
+--
+-- The examples of the V2 modules use the extensions @BlockArguments@ and @OverloadedStrings@, and these
+-- imports:
+--
+-- > import Control.Exception (bracket)
+-- > import Control.Monad (forM, forM_)
+-- > import Data.IORef (IORef, atomicModifyIORef', modifyIORef', newIORef, readIORef)
+-- > import Data.Int (Int64)
+-- > import qualified Data.Text as Text
+-- > import Database.DuckDB.FFI.V2
+-- > import Database.DuckDB.Simple hiding (bind, execute)
+-- > import qualified Database.DuckDB.Simple.Logging as Logging
+-- > import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep (..))
+-- > import qualified Database.DuckDB.Simple.V2.Copy as V2Copy
+-- > import qualified Database.DuckDB.Simple.V2.FunctionDocs as Docs
+-- > import qualified Database.DuckDB.Simple.V2.Logging as V2Logging
+-- > import Database.DuckDB.Simple.V2.LogicalRep (destroyLogicalType, logicalTypeFromRep, logicalTypeToRep)
+-- > import qualified Database.DuckDB.Simple.V2.Pragma as Pragma
+-- > import qualified Database.DuckDB.Simple.V2.Registration as R
+-- > import Foreign.C.ConstPtr (ConstPtr (..))
+-- > import Foreign.Ptr (castPtr)
+-- > import Foreign.Storable (peek, peekElemOff, poke, pokeElemOff, sizeOf)
+--
+-- The examples also use these definitions. The helpers read and write the rows of a BIGINT vector. Each
+-- helper flattens the vector before it reads or writes the data. Then each row has its own slot in the data.
+--
+-- > bigint :: R.TypeDeclaration
+-- > bigint = R.StructuredType (LogicalTypeScalar LogicalTypeIdBigInt)
+-- >
+-- > readIntegers :: Int -> DuckDBV2VectorHandle -> IO [Int64]
+-- > readIntegers count vector = do
+-- >   R.checked (c_duckdb_v2_vector_flatten vector)
+-- >   raw <- R.output (c_duckdb_v2_vector_get_data_mutable vector)
+-- >   mapM (peekElemOff (castPtr raw)) [0 .. count - 1]
+-- >
+-- > writeIntegers :: DuckDBV2VectorHandle -> [Int64] -> IO ()
+-- > writeIntegers vector values = do
+-- >   R.checked (c_duckdb_v2_vector_set_size vector (fromIntegral (length values)))
+-- >   R.checked (c_duckdb_v2_vector_flatten vector)
+-- >   raw <- R.output (c_duckdb_v2_vector_get_data_mutable vector)
+-- >   forM_ (zip [0 ..] values) \(index, value) -> pokeElemOff (castPtr raw) index value
+module Database.DuckDB.Simple.V2.Registration (
+  RegistrationTarget (..),
+  withRegistrationFactory,
+  TypeDeclaration (..),
+  DefaultValue (..),
+  defaultValue,
+  FunctionParameter (..),
+  parameter,
+  FunctionSignature (..),
+  FunctionProperties,
+  ContextCallback,
+  BindCallback,
+  ScalarCallbacks (..),
+  scalarCallbacks,
+  AggregateCallbacks (..),
+  aggregateCallbacks,
+  TableCallbacks (..),
+  tableCallbacks,
+  registerScalarFunction,
+  registerScalarFunctionWith,
+  registerAggregateFunction,
+  registerAggregateFunctionWith,
+  registerAggregateFunctionWithCleanup,
+  registerTableFunction,
+  registerTableFunctionWith,
+  registerCast,
+  registerCastWith,
+  registerCustomType,
+  registerCustomTypeOn,
+  registerCustomTypeWith,
+  registerMacroFunctionWith,
+  registerReplacementScan,
+  registerReplacementScanOn,
+  registerInstanceReplacementScan,
+  setCallbackState,
+  getCallbackState,
+  withTypeDeclaration,
+  configureFunctionSignature,
+  checked,
+  output,
+  destroy,
+  nullHandle,
+  withText,
+  readText,
+  withIdentifier,
+  readIdentifier,
+) where
+
+import Control.Exception (bracket, throwIO)
+import Control.Monad (forM_, when)
+import Data.Dynamic (dynTypeRep, fromDynamic, toDyn)
+import Data.Int (Int64)
+import Data.Proxy (Proxy (..))
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Data.Typeable (Typeable, typeRep)
+import Data.Void (Void)
+import Database.DuckDB.Simple.Callback (
+  RegistrationTarget (..),
+  attachOpaque,
+  checkQueryThreads,
+  checkTargetThreads,
+  guardContext,
+  install,
+  installAll,
+  installOptional,
+  readCallbackState,
+  runCallback,
+  runCallbackWith,
+  transferCallbackState,
+  withCallbackResources,
+  withCallbackResourcesFinally,
+  withRegistrationFactory,
+  withTarget,
+ )
+import Database.DuckDB.Simple.Internal (Connection, Instance, withConnectionHandle, withInstanceHandle)
+import Database.DuckDB.Simple.LogicalRep (TypeDeclaration (..))
+import Database.DuckDB.Simple.Native
+import Database.DuckDB.Simple.ToField (ToDuckValue (..))
+import Database.DuckDB.Simple.V2.LogicalRep (logicalTypeFromRep)
+import Foreign.Ptr (Ptr)
+
+-- | Construct an owned native default value through the borrowed factory of
+-- the registration target. Registration releases the value.
+--
+-- > R.DefaultValue (\factory -> R.output (c_duckdb_v2_value_create_bigint factory 35))
+newtype DefaultValue = DefaultValue (DuckDBV2FactoryHandle -> IO DuckDBV2ValueHandle)
+
+-- | Use a typed Haskell value as a default. It works on a connection target and
+-- on an extension target.
+defaultValue :: (ToDuckValue a) => a -> DefaultValue
+defaultValue value = DefaultValue (\factory -> toDuckValue factory value)
+
+-- | One parameter. Native V2 validates parameter order, names, and defaults.
+data FunctionParameter = FunctionParameter
+  { parameterName :: Text
+  -- ^ The parameter name.
+  , parameterType :: TypeDeclaration
+  -- ^ The declared parameter type.
+  , parameterDefault :: Maybe DefaultValue
+  -- ^ The optional default value.
+  , parameterKind :: DuckDBV2FunctionParameterKind
+  }
+
+-- | Declare a required parameter accepted by position or by name.
+-- Change a field to add a default or to use another parameter kind:
+--
+-- > (R.parameter "count" bigint){R.parameterDefault = Just (R.defaultValue (3 :: Int64))}
+-- > (R.parameter "right" bigint){R.parameterKind = DuckDBV2FunctionParameterKindNamedOnly}
+parameter :: Text -> TypeDeclaration -> FunctionParameter
+parameter name dtype = FunctionParameter name dtype Nothing DuckDBV2FunctionParameterKindStandard
+
+-- | Function parameters and an optional return type. Table functions use Nothing.
+data FunctionSignature = FunctionSignature
+  { signatureParameters :: [FunctionParameter]
+  , signatureReturnType :: Maybe TypeDeclaration
+  }
+
+-- | Native function properties. Scalar and aggregate functions default to fallible.
+type FunctionProperties = [(DuckDBV2FunctionPropertyKey, DuckDBV2FunctionPropertyValue)]
+
+-- | A callback with a borrowed execution context. Exceptions become SQL errors.
+type ContextCallback info = info -> DuckDBV2ContextHandle -> IO ()
+
+-- | A bind callback with borrowed input metadata, output metadata, and context.
+type BindCallback result = DuckDBV2FunctionBindInfoHandle -> result -> DuckDBV2ContextHandle -> IO ()
+
+-- | All scalar function callbacks. The exec callback is required.
+data ScalarCallbacks = ScalarCallbacks
+  { scalarResolveTypesCallback :: Maybe (BindCallback DuckDBV2ScalarFunctionResolveTypesInfoHandle)
+  , scalarBindCallback :: Maybe (BindCallback DuckDBV2ScalarFunctionBindInfoHandle)
+  , scalarInitCallback :: Maybe (ContextCallback DuckDBV2ScalarFunctionInitInfoHandle)
+  , scalarExecCallback :: ContextCallback DuckDBV2ScalarFunctionExecInfoHandle
+  }
+
+-- | Use one exec callback and no optional scalar callbacks.
+scalarCallbacks :: ContextCallback DuckDBV2ScalarFunctionExecInfoHandle -> ScalarCallbacks
+scalarCallbacks execute = ScalarCallbacks Nothing Nothing Nothing execute
+
+-- | All aggregate callbacks. Bind and state destruction are optional.
+-- Aggregate state callbacks have no context in native V2. Native cleanup ignores
+-- destroy-callback errors after exception containment.
+data AggregateCallbacks = AggregateCallbacks
+  { aggregateBindCallback :: Maybe (BindCallback DuckDBV2AggregateFunctionBindInfoHandle)
+  , aggregateSizeCallback :: DuckDBV2AggregateFunctionSizeInfoHandle -> IO ()
+  , aggregateInitCallback :: DuckDBV2AggregateFunctionInitInfoHandle -> IO ()
+  , aggregateUpdateCallback :: DuckDBV2AggregateFunctionUpdateInfoHandle -> IO ()
+  , aggregateCombineCallback :: DuckDBV2AggregateFunctionCombineInfoHandle -> IO ()
+  , aggregateFinalizeCallback :: DuckDBV2AggregateFunctionFinalizeInfoHandle -> IO ()
+  , aggregateDestroyCallback :: Maybe (DuckDBV2AggregateFunctionDestroyInfoHandle -> IO ())
+  }
+
+-- | Use the required aggregate callbacks and no optional callbacks.
+aggregateCallbacks
+  :: (DuckDBV2AggregateFunctionSizeInfoHandle -> IO ())
+  -> (DuckDBV2AggregateFunctionInitInfoHandle -> IO ())
+  -> (DuckDBV2AggregateFunctionUpdateInfoHandle -> IO ())
+  -> (DuckDBV2AggregateFunctionCombineInfoHandle -> IO ())
+  -> (DuckDBV2AggregateFunctionFinalizeInfoHandle -> IO ())
+  -> AggregateCallbacks
+aggregateCallbacks size initialize update combine finalize =
+  AggregateCallbacks Nothing size initialize update combine finalize Nothing
+
+-- | All table callbacks and the projection-pushdown setting.
+-- The claim-batch callback is part of the pinned unstable V2 API.
+--
+-- A filter pushdown callback must not accept a BETWEEN predicate. DuckDB 2.0
+-- merges two range comparisons on one column into one BETWEEN node, and the C API
+-- has no call that reads whether a bound is inclusive
+-- (<https://github.com/duckdb/duckdb/issues/25391 DuckDB issue 25391>). DuckDB
+-- removes an accepted predicate from the query, so the scan returns wrong rows.
+data TableCallbacks = TableCallbacks
+  { tableBindCallback :: BindCallback DuckDBV2TableFunctionBindInfoHandle
+  , tableInitGlobalCallback :: Maybe (ContextCallback DuckDBV2TableFunctionInitGlobalInfoHandle)
+  , tableInitLocalCallback :: Maybe (ContextCallback DuckDBV2TableFunctionInitLocalInfoHandle)
+  , tableExecCallback :: ContextCallback DuckDBV2TableFunctionExecInfoHandle
+  , tableProgressCallback :: Maybe (ContextCallback DuckDBV2TableFunctionProgressInfoHandle)
+  , tableFilterPushdownCallback :: Maybe (ContextCallback DuckDBV2TableFunctionFilterPushdownInfoHandle)
+  , tablePartitionDataCallback :: Maybe (ContextCallback DuckDBV2TableFunctionPartitionDataInfoHandle)
+  , tablePartitioningCallback :: Maybe (ContextCallback DuckDBV2TableFunctionPartitioningInfoHandle)
+  , tableClaimBatchCallback :: Maybe (ContextCallback DuckDBV2TableFunctionClaimBatchInfoHandle)
+  , tableGetBindInfoCallback :: Maybe (ContextCallback DuckDBV2TableFunctionGetBindInfoInfoHandle)
+  , tableProjectionPushdown :: Bool
+  }
+
+-- | Use bind and exec callbacks. Disable optional callbacks and projection pushdown.
+tableCallbacks :: BindCallback DuckDBV2TableFunctionBindInfoHandle -> ContextCallback DuckDBV2TableFunctionExecInfoHandle -> TableCallbacks
+tableCallbacks bind execute = TableCallbacks bind Nothing Nothing execute Nothing Nothing Nothing Nothing Nothing Nothing False
+
+-- | Register an advanced scalar function on the connection's database.
+-- Set an ANY return type only when the resolve-types callback supplies a concrete type.
+--
+-- The example registers a function with two BIGINT parameters. Each parameter has a default, and the second
+-- parameter is named-only. The exec callback adds the two arguments of each row.
+--
+-- > scalarSum :: R.ContextCallback DuckDBV2ScalarFunctionExecInfoHandle
+-- > scalarSum info _ = do
+-- >   count <- R.output (c_duckdb_v2_scalar_function_exec_get_row_count info)
+-- >   columns <- forM [0, 1 :: Int] \index ->
+-- >     R.output (c_duckdb_v2_scalar_function_exec_get_arg info (fromIntegral index)) >>= readIntegers (fromIntegral count)
+-- >   vector <- R.output (c_duckdb_v2_scalar_function_exec_get_result info)
+-- >   writeIntegers vector [sum [column !! row | column <- columns] | row <- [0 .. fromIntegral count - 1]]
+-- >
+-- > withConnection ":memory:" \connection -> do
+-- >   let left = (R.parameter "left" bigint){R.parameterDefault = Just (R.defaultValue (7 :: Int64))}
+-- >       right =
+-- >         (R.parameter "right" bigint)
+-- >           { R.parameterDefault = Just (R.defaultValue (35 :: Int64))
+-- >           , R.parameterKind = DuckDBV2FunctionParameterKindNamedOnly
+-- >           }
+-- >   R.registerScalarFunction
+-- >     connection
+-- >     "managed_default"
+-- >     (R.FunctionSignature [left, right] (Just bigint))
+-- >     []
+-- >     (R.scalarCallbacks scalarSum)
+-- >   rows <- query_ connection "SELECT managed_default(), managed_default(right := 5, left := 3)"
+-- >   print (rows :: [(Int64, Int64)]) -- [(42,8)]
+registerScalarFunction :: Connection -> Text -> FunctionSignature -> FunctionProperties -> ScalarCallbacks -> IO ()
+registerScalarFunction connection name signature properties callbacks = do
+  validateName name
+  withConnectionHandle connection \native -> withConnectionFactory native \factory ->
+    registerScalarFunctionWith
+      (ConnectionTarget connection)
+      ( \function -> do
+          withIdentifier name $ checked . c_duckdb_v2_scalar_function_set_name function
+          output (c_duckdb_v2_scalar_function_get_signature function) >>= configureFunctionSignature factory signature
+          forM_ properties $ \(key, value) -> checked (c_duckdb_v2_scalar_function_set_property function key value)
+      )
+      callbacks
+
+-- | Configure and register a managed scalar function on a connection or extension.
+-- The configuration action borrows the builder. Do not set callbacks or user data.
+--
+-- The example sets the name, the signature, and the description of the function. It uses @scalarSum@ from
+-- the example of 'registerScalarFunction'. 'withRegistrationFactory' gives the factory for the types of the
+-- signature.
+--
+-- > withConnection ":memory:" \connection -> do
+-- >   let target = R.ConnectionTarget connection
+-- >   R.withRegistrationFactory target \factory ->
+-- >     R.registerScalarFunctionWith
+-- >       target
+-- >       ( \function -> do
+-- >           R.withIdentifier "managed_target_default" (R.checked . c_duckdb_v2_scalar_function_set_name function)
+-- >           signature <- R.output (c_duckdb_v2_scalar_function_get_signature function)
+-- >           R.configureFunctionSignature
+-- >             factory
+-- >             (R.FunctionSignature [R.parameter "left" bigint, R.parameter "right" bigint] (Just bigint))
+-- >             signature
+-- >           docs <- R.output (c_duckdb_v2_scalar_function_get_docs function)
+-- >           Docs.setFunctionDocs docs Docs.defaultFunctionDocs{Docs.functionDescription = Just "Add two BIGINT values."}
+-- >       )
+-- >       (R.scalarCallbacks scalarSum)
+-- >   rows <- query_ connection "SELECT description FROM duckdb_functions() WHERE function_name = 'managed_target_default'"
+-- >   print (map fromOnly rows :: [Text.Text]) -- ["Add two BIGINT values."]
+registerScalarFunctionWith :: RegistrationTarget -> (DuckDBV2ScalarFunctionHandle -> IO ()) -> ScalarCallbacks -> IO ()
+registerScalarFunctionWith target configure callbacks =
+  withTarget
+    target
+    c_duckdb_v2_scalar_function_create
+    c_duckdb_v2_scalar_function_destroy
+    c_duckdb_v2_connection_register_scalar_function
+    c_duckdb_v2_extension_register_scalar_function
+    \function register ->
+      withCallbackResources
+        (checkTargetThreads target)
+        ( \allocate ->
+            installAll
+              [ installOptional (scalarResolveTypesCallback callbacks) $ \callback ->
+                  install
+                    allocate
+                    DuckDBV2ScalarFunctionResolveTypesCallbackFn
+                    (DuckDBV2ScalarFunctionResolveTypesCallbackFn_Aux (guardBind callback))
+                    (c_duckdb_v2_scalar_function_set_resolve_types_callback function)
+              , installOptional (scalarBindCallback callbacks) $ \callback ->
+                  install
+                    allocate
+                    DuckDBV2ScalarFunctionBindCallbackFn
+                    (DuckDBV2ScalarFunctionBindCallbackFn_Aux (guardBind callback))
+                    (c_duckdb_v2_scalar_function_set_bind_callback function)
+              , installOptional (scalarInitCallback callbacks) $ \callback ->
+                  install
+                    allocate
+                    DuckDBV2ScalarFunctionInitCallbackFn
+                    (DuckDBV2ScalarFunctionInitCallbackFn_Aux (guardContext callback))
+                    (c_duckdb_v2_scalar_function_set_init_callback function)
+              , install
+                  allocate
+                  DuckDBV2ScalarFunctionExecCallbackFn
+                  (DuckDBV2ScalarFunctionExecCallbackFn_Aux (guardContext (scalarExecCallback callbacks)))
+                  (c_duckdb_v2_scalar_function_set_exec_callback function)
+              ]
+        )
+        (attachOpaque (c_duckdb_v2_scalar_function_set_user_data function))
+        \installCallbacks -> do
+          checked (c_duckdb_v2_scalar_function_set_property function DuckDBV2FunctionPropertyFallibility DuckDBV2FunctionPropertyFallibilityFallible)
+          configure function
+          installCallbacks
+          register
+
+-- | Register an aggregate function on the connection's database.
+-- State memory and its size follow the native V2 aggregate contract.
+--
+-- The example registers a sum of BIGINT values. The state of a group is one 'Int64' in native memory. The
+-- size callback gives the size of the state. The other callbacks read and write the state with @peek@ and
+-- @poke@. The finalize callback writes each total at the result offset of the result vector.
+--
+-- > sumCallbacks :: R.AggregateCallbacks
+-- > sumCallbacks = R.aggregateCallbacks stateSize initialize update combine finalize
+-- >   where
+-- >     stateSize info = R.checked (c_duckdb_v2_aggregate_function_size_set_state_size info (fromIntegral (sizeOf (0 :: Int64))))
+-- >     initialize info = do
+-- >       count <- R.output (c_duckdb_v2_aggregate_function_init_get_state_count info)
+-- >       states <- R.output (c_duckdb_v2_aggregate_function_init_get_states info)
+-- >       forM_ [0 .. fromIntegral count - 1] \index -> peekElemOff states index >>= \state -> poke (castPtr state) (0 :: Int64)
+-- >     update info = do
+-- >       count <- R.output (c_duckdb_v2_aggregate_function_update_get_row_count info)
+-- >       states <- R.output (c_duckdb_v2_aggregate_function_update_get_states info)
+-- >       values <- R.output (c_duckdb_v2_aggregate_function_update_get_arg info 0) >>= readIntegers (fromIntegral count)
+-- >       forM_ (zip [0 ..] values) \(index, value) -> do
+-- >         state <- castPtr <$> peekElemOff states index
+-- >         total <- peek state
+-- >         poke state (total + value :: Int64)
+-- >     combine info = do
+-- >       count <- R.output (c_duckdb_v2_aggregate_function_combine_get_state_count info)
+-- >       sources <- R.output (c_duckdb_v2_aggregate_function_combine_get_sources info)
+-- >       targets <- R.output (c_duckdb_v2_aggregate_function_combine_get_targets info)
+-- >       forM_ [0 .. fromIntegral count - 1] \index -> do
+-- >         source <- peekElemOff sources index >>= peek . castPtr
+-- >         target <- castPtr <$> peekElemOff targets index
+-- >         total <- peek target
+-- >         poke target (total + source :: Int64)
+-- >     finalize info = do
+-- >       count <- R.output (c_duckdb_v2_aggregate_function_finalize_get_state_count info)
+-- >       states <- R.output (c_duckdb_v2_aggregate_function_finalize_get_states info)
+-- >       offset <- R.output (c_duckdb_v2_aggregate_function_finalize_get_result_offset info)
+-- >       result <- R.output (c_duckdb_v2_aggregate_function_finalize_get_result info)
+-- >       raw <- R.output (c_duckdb_v2_vector_get_data_mutable result)
+-- >       forM_ [0 .. fromIntegral count - 1] \index -> do
+-- >         total <- peekElemOff states index >>= peek . castPtr
+-- >         pokeElemOff (castPtr raw) (fromIntegral offset + index) (total :: Int64)
+-- >
+-- > withConnection ":memory:" \connection -> do
+-- >   R.registerAggregateFunction connection "managed_sum" (R.FunctionSignature [R.parameter "value" bigint] (Just bigint)) [] sumCallbacks
+-- >   rows <- query_ connection "SELECT managed_sum(i::BIGINT) FROM range(12) t(i) GROUP BY i % 3 ORDER BY i % 3"
+-- >   print (map fromOnly rows :: [Int64]) -- [18,22,26]
+registerAggregateFunction :: Connection -> Text -> FunctionSignature -> FunctionProperties -> AggregateCallbacks -> IO ()
+registerAggregateFunction connection name signature properties callbacks = do
+  validateName name
+  withConnectionHandle connection \native -> withConnectionFactory native \factory ->
+    registerAggregateFunctionWith
+      (ConnectionTarget connection)
+      ( \function -> do
+          withIdentifier name $ checked . c_duckdb_v2_aggregate_function_set_name function
+          output (c_duckdb_v2_aggregate_function_get_signature function) >>= configureFunctionSignature factory signature
+          forM_ properties $ \(key, value) -> checked (c_duckdb_v2_aggregate_function_set_property function key value)
+      )
+      callbacks
+
+-- | Configure and register a managed aggregate function on a connection or extension.
+-- The configuration action borrows the builder. Do not set callbacks or user data.
+registerAggregateFunctionWith :: RegistrationTarget -> (DuckDBV2AggregateFunctionHandle -> IO ()) -> AggregateCallbacks -> IO ()
+registerAggregateFunctionWith target = registerAggregateFunctionWithCleanup target (pure ())
+
+-- | Register an aggregate with cleanup owned by its native callback resources.
+-- Acquire resources for this cleanup only from the callbacks. Native builder
+-- acquisition can fail before setup of callback resources starts. Cleanup runs
+-- if that setup fails. After attachment, it runs when the last native
+-- callback owner is released, including after a failed configuration or
+-- registration. Cleanup exceptions are contained. Cleanup must not use a
+-- borrowed registration context. The configuration action must not set callbacks
+-- or user data.
+registerAggregateFunctionWithCleanup
+  :: RegistrationTarget -> IO () -> (DuckDBV2AggregateFunctionHandle -> IO ()) -> AggregateCallbacks -> IO ()
+registerAggregateFunctionWithCleanup target cleanup configure callbacks =
+  withTarget
+    target
+    c_duckdb_v2_aggregate_function_create
+    c_duckdb_v2_aggregate_function_destroy
+    c_duckdb_v2_connection_register_aggregate_function
+    c_duckdb_v2_extension_register_aggregate_function
+    \function register ->
+      withCallbackResourcesFinally
+        (checkTargetThreads target)
+        cleanup
+        ( \allocate ->
+            installAll
+              [ installOptional (aggregateBindCallback callbacks) $ \callback ->
+                  install
+                    allocate
+                    DuckDBV2AggregateFunctionBindCallbackFn
+                    (DuckDBV2AggregateFunctionBindCallbackFn_Aux (guardBind callback))
+                    (c_duckdb_v2_aggregate_function_set_bind_callback function)
+              , install
+                  allocate
+                  DuckDBV2AggregateFunctionSizeCallbackFn
+                  (DuckDBV2AggregateFunctionSizeCallbackFn_Aux (guardCallback (aggregateSizeCallback callbacks)))
+                  (c_duckdb_v2_aggregate_function_set_size_callback function)
+              , install
+                  allocate
+                  DuckDBV2AggregateFunctionInitCallbackFn
+                  (DuckDBV2AggregateFunctionInitCallbackFn_Aux (guardCallback (aggregateInitCallback callbacks)))
+                  (c_duckdb_v2_aggregate_function_set_init_callback function)
+              , install
+                  allocate
+                  DuckDBV2AggregateFunctionUpdateCallbackFn
+                  (DuckDBV2AggregateFunctionUpdateCallbackFn_Aux (guardCallback (aggregateUpdateCallback callbacks)))
+                  (c_duckdb_v2_aggregate_function_set_update_callback function)
+              , install
+                  allocate
+                  DuckDBV2AggregateFunctionCombineCallbackFn
+                  (DuckDBV2AggregateFunctionCombineCallbackFn_Aux (guardCallback (aggregateCombineCallback callbacks)))
+                  (c_duckdb_v2_aggregate_function_set_combine_callback function)
+              , install
+                  allocate
+                  DuckDBV2AggregateFunctionFinalizeCallbackFn
+                  (DuckDBV2AggregateFunctionFinalizeCallbackFn_Aux (guardCallback (aggregateFinalizeCallback callbacks)))
+                  (c_duckdb_v2_aggregate_function_set_finalize_callback function)
+              , installOptional (aggregateDestroyCallback callbacks) $ \callback ->
+                  install
+                    allocate
+                    DuckDBV2AggregateFunctionDestroyCallbackFn
+                    (DuckDBV2AggregateFunctionDestroyCallbackFn_Aux (guardCallback callback))
+                    (c_duckdb_v2_aggregate_function_set_destroy_callback function)
+              ]
+        )
+        (attachOpaque (c_duckdb_v2_aggregate_function_set_user_data function))
+        \installCallbacks -> do
+          checked
+            (c_duckdb_v2_aggregate_function_set_property function DuckDBV2FunctionPropertyFallibility DuckDBV2FunctionPropertyFallibilityFallible)
+          configure function
+          installCallbacks
+          register
+
+-- | Register a table function. Its bind callback declares the result columns.
+--
+-- The example registers a table function with one BIGINT parameter. The bind callback stores the argument as
+-- bind data and declares the result column. The 'tableInitGlobalCallback' callback copies the bind data into
+-- a global state. The exec callback takes the state one time. Thus the first chunk has the rows and the
+-- next chunk is empty. An empty chunk ends the scan.
+--
+-- > tableDefinition :: R.TableCallbacks
+-- > tableDefinition = (R.tableCallbacks bind execute){R.tableInitGlobalCallback = Just initialize}
+-- >   where
+-- >     bind input result context = do
+-- >       amount <- bracket (R.output (c_duckdb_v2_function_bind_get_arg_value input 0)) (R.destroy c_duckdb_v2_value_destroy) \value ->
+-- >         R.output (c_duckdb_v2_value_get_bigint value)
+-- >       R.setCallbackState (c_duckdb_v2_function_bind_set_bind_data input) (amount :: Int64)
+-- >       factory <- R.output (c_duckdb_v2_context_get_factory context)
+-- >       R.withTypeDeclaration factory bigint \dtype ->
+-- >         R.withIdentifier "amount" \name -> R.checked (c_duckdb_v2_table_function_bind_add_result_column result name dtype)
+-- >     initialize info _ = do
+-- >       amount <- R.getCallbackState (c_duckdb_v2_table_function_init_global_get_bind_data info)
+-- >       state <- newIORef (Just (amount :: Int64))
+-- >       R.setCallbackState (c_duckdb_v2_table_function_init_global_set_global_state info) state
+-- >     execute info _ = do
+-- >       state <- R.getCallbackState (c_duckdb_v2_table_function_exec_get_global_state info) :: IO (IORef (Maybe Int64))
+-- >       amount <- atomicModifyIORef' state (\value -> (Nothing, value))
+-- >       chunk <- R.output (c_duckdb_v2_table_function_exec_get_output_chunk info)
+-- >       vector <- R.output (c_duckdb_v2_data_chunk_get_vector chunk 0)
+-- >       writeIntegers vector (maybe [] (\count -> [42 .. 41 + count]) amount)
+-- >
+-- > withConnection ":memory:" \connection -> do
+-- >   let count = (R.parameter "count" bigint){R.parameterDefault = Just (R.defaultValue (3 :: Int64))}
+-- >   R.registerTableFunction connection "managed_scan" [count] tableDefinition
+-- >   rows <- query_ connection "SELECT amount FROM managed_scan()"
+-- >   print (map fromOnly rows :: [Int64]) -- [42,43,44]
+registerTableFunction :: Connection -> Text -> [FunctionParameter] -> TableCallbacks -> IO ()
+registerTableFunction connection name parameters callbacks = do
+  validateName name
+  withConnectionHandle connection \native -> withConnectionFactory native \factory ->
+    registerTableFunctionWith
+      (ConnectionTarget connection)
+      ( \function -> do
+          withIdentifier name $ checked . c_duckdb_v2_table_function_set_name function
+          output (c_duckdb_v2_table_function_get_signature function) >>= configureFunctionSignature factory (FunctionSignature parameters Nothing)
+      )
+      callbacks
+
+-- | Configure and register a managed table function on a connection or extension.
+-- The configuration action borrows the builder. Do not set callbacks or user data.
+registerTableFunctionWith :: RegistrationTarget -> (DuckDBV2TableFunctionHandle -> IO ()) -> TableCallbacks -> IO ()
+registerTableFunctionWith target configure callbacks =
+  withTarget
+    target
+    c_duckdb_v2_table_function_create
+    c_duckdb_v2_table_function_destroy
+    c_duckdb_v2_connection_register_table_function
+    c_duckdb_v2_extension_register_table_function
+    \function register ->
+      withCallbackResources
+        (checkTargetThreads target)
+        ( \allocate ->
+            installAll
+              [ install
+                  allocate
+                  DuckDBV2TableFunctionBindCallbackFn
+                  (DuckDBV2TableFunctionBindCallbackFn_Aux (guardBind (tableBindCallback callbacks)))
+                  (c_duckdb_v2_table_function_set_bind_callback function)
+              , installOptional (tableInitGlobalCallback callbacks) $ \callback ->
+                  install
+                    allocate
+                    DuckDBV2TableFunctionInitGlobalCallbackFn
+                    (DuckDBV2TableFunctionInitGlobalCallbackFn_Aux (guardContext callback))
+                    (c_duckdb_v2_table_function_set_init_global_callback function)
+              , installOptional (tableInitLocalCallback callbacks) $ \callback ->
+                  install
+                    allocate
+                    DuckDBV2TableFunctionInitLocalCallbackFn
+                    (DuckDBV2TableFunctionInitLocalCallbackFn_Aux (guardContext callback))
+                    (c_duckdb_v2_table_function_set_init_local_callback function)
+              , install
+                  allocate
+                  DuckDBV2TableFunctionExecCallbackFn
+                  (DuckDBV2TableFunctionExecCallbackFn_Aux (guardContext (tableExecCallback callbacks)))
+                  (c_duckdb_v2_table_function_set_exec_callback function)
+              , installOptional (tableProgressCallback callbacks) $ \callback ->
+                  install
+                    allocate
+                    DuckDBV2TableFunctionProgressCallbackFn
+                    (DuckDBV2TableFunctionProgressCallbackFn_Aux (guardContext callback))
+                    (c_duckdb_v2_table_function_set_progress_callback function)
+              , installOptional (tableFilterPushdownCallback callbacks) $ \callback ->
+                  install
+                    allocate
+                    DuckDBV2TableFunctionFilterPushdownCallbackFn
+                    (DuckDBV2TableFunctionFilterPushdownCallbackFn_Aux (guardContext callback))
+                    (c_duckdb_v2_table_function_set_filter_pushdown_callback function)
+              , installOptional (tablePartitionDataCallback callbacks) $ \callback ->
+                  install
+                    allocate
+                    DuckDBV2TableFunctionPartitionDataCallbackFn
+                    (DuckDBV2TableFunctionPartitionDataCallbackFn_Aux (guardContext callback))
+                    (c_duckdb_v2_table_function_set_partition_data_callback function)
+              , installOptional (tablePartitioningCallback callbacks) $ \callback ->
+                  install
+                    allocate
+                    DuckDBV2TableFunctionPartitioningCallbackFn
+                    (DuckDBV2TableFunctionPartitioningCallbackFn_Aux (guardContext callback))
+                    (c_duckdb_v2_table_function_set_partitioning_callback function)
+              , installOptional (tableClaimBatchCallback callbacks) $ \callback ->
+                  install
+                    allocate
+                    DuckDBV2TableFunctionClaimBatchCallbackFn
+                    (DuckDBV2TableFunctionClaimBatchCallbackFn_Aux (guardContext callback))
+                    (c_duckdb_v2_table_function_set_claim_batch_callback function)
+              , installOptional (tableGetBindInfoCallback callbacks) $ \callback ->
+                  install
+                    allocate
+                    DuckDBV2TableFunctionGetBindInfoCallbackFn
+                    (DuckDBV2TableFunctionGetBindInfoCallbackFn_Aux (guardContext callback))
+                    (c_duckdb_v2_table_function_set_get_bind_info_callback function)
+              ]
+        )
+        (attachOpaque (c_duckdb_v2_table_function_set_user_data function))
+        \installCallbacks -> do
+          checked (c_duckdb_v2_table_function_set_projection_pushdown function (if tableProjectionPushdown callbacks then 1 else 0))
+          configure function
+          installCallbacks
+          register
+
+-- | Register a cast. Nothing keeps the native explicit-cast cost.
+-- The callback must inspect the native cast mode to implement TRY_CAST behavior.
+-- An exception in the callback fails the cast with the error type
+-- 'ErrorTypeMismatch', whatever the type of the exception. With another error
+-- code, DuckDB can invalidate the database. When DuckDB casts a constant
+-- through the cast while it binds the query, the error has the type
+-- 'ErrorInputInvalid' and the text @Failed to cast value: @ before the text of
+-- the exception. See the section /Errors/ of the README and
+-- Note [The error code of a failed cast].
+-- A target type from SQL @CREATE TYPE name AS base@ is only another name for
+-- the base type, so the cast is a cast to the base type. A type from
+-- 'registerCustomType' keeps its name. See 'TypeDeclaration'.
+--
+-- The cast replaces the cast of DuckDB for the pair of types on each
+-- connection of the instance. A second registration of the same pair returns
+-- with no error and has no effect, because DuckDB keeps the first cast.
+--
+-- Warning: DuckDB does not always run the callback. Three rules of the
+-- optimizer of DuckDB 2.0.0 use the two types of a cast and not the cast
+-- function:
+--
+-- * expression_rewriter (ComparisonSimplificationRule, with
+--   BoundCastExpression::CastIsInvertible) casts the constant of a comparison
+--   to the type of the column, and compares the column without the cast.
+-- * join_filter_pushdown makes a filter of a join from the values of the other
+--   side through an integral cast.
+-- * statistics_propagation gives min and max from the statistics of the
+--   column through the cast.
+--
+-- In runs with DuckDB 2.0.0, a cast from INTEGER to BIGINT, from BIGINT to a
+-- custom type with the base type BIGINT, and from that type to BIGINT, with a
+-- callback that changes the value, gave wrong rows and no error. This occurred
+-- in a filter, a filter with a parameter, IN, BETWEEN, a comparison of two
+-- columns, a join, and min and max. The callback did not run on the column,
+-- or, in a comparison of two columns, it ran on one side only. A cast with
+-- VARCHAR or BLOB on one side gave the same rows with the optimizer on and off
+-- in each of these runs: with 10 rows, and with 300000 rows except min and max
+-- of a cast from BLOB to a custom type with the base type BLOB, which did not
+-- run. For a custom target type, DuckDB also casts the constant of a
+-- comparison through the callback. With a cast from INTEGER to BIGINT, DuckDB
+-- also converts each INTEGER literal that must be a BIGINT through the cast:
+-- @range(10)@ gave no row, and @LIMIT 5@ gave 10 rows. Use a scalar function
+-- for a conversion that changes the value.
+--
+-- The source type is the first type, and the target type is the second type. The example registers a cast
+-- from BIGINT to a custom type. The callback copies each value.
+--
+-- > withConnection ":memory:" \connection -> do
+-- >   R.registerCustomType connection "managed_copy" bigint
+-- >   R.registerCast connection bigint (R.TypeExpression "managed_copy") Nothing \info _ -> do
+-- >     count <- R.output (c_duckdb_v2_cast_function_exec_get_row_count info)
+-- >     values <- R.output (c_duckdb_v2_cast_function_exec_get_input info) >>= readIntegers (fromIntegral count)
+-- >     result <- R.output (c_duckdb_v2_cast_function_exec_get_output info)
+-- >     writeIntegers result values
+-- >   rows <- query_ connection "SELECT CAST(i::BIGINT AS managed_copy)::BIGINT FROM range(3) t(i)"
+-- >   print (map fromOnly rows :: [Int64]) -- [0,1,2]
+registerCast
+  :: Connection -> TypeDeclaration -> TypeDeclaration -> Maybe Int64 -> ContextCallback DuckDBV2CastFunctionExecInfoHandle -> IO ()
+registerCast connection source target implicitCost execute =
+  withConnectionHandle connection \native -> withConnectionFactory native \factory ->
+    registerCastWith
+      (ConnectionTarget connection)
+      ( \function -> do
+          withTypeDeclaration factory source $ checked . c_duckdb_v2_cast_function_set_source_type function
+          withTypeDeclaration factory target $ checked . c_duckdb_v2_cast_function_set_target_type function
+          forM_ implicitCost $ checked . c_duckdb_v2_cast_function_set_implicit_cast_cost function
+      )
+      execute
+
+-- | Configure and register a managed cast on a connection or extension.
+-- The configuration action borrows the builder. Do not set callbacks or user data.
+-- An exception in the callback fails the cast with the error type
+-- 'ErrorTypeMismatch', whatever the type of the exception. With another error
+-- code, DuckDB can invalidate the database. See the section /Errors/ of the
+-- README and Note [The error code of a failed cast].
+registerCastWith
+  :: RegistrationTarget -> (DuckDBV2CastFunctionHandle -> IO ()) -> ContextCallback DuckDBV2CastFunctionExecInfoHandle -> IO ()
+registerCastWith target configure execute =
+  withTarget
+    target
+    c_duckdb_v2_cast_function_create
+    c_duckdb_v2_cast_function_destroy
+    c_duckdb_v2_connection_register_cast_function
+    c_duckdb_v2_extension_register_cast_function
+    \function register ->
+      withCallbackResources
+        (checkTargetThreads target)
+        ( \allocate ->
+            install
+              allocate
+              DuckDBV2CastFunctionExecCallbackFn
+              (DuckDBV2CastFunctionExecCallbackFn_Aux \info context err -> runCallbackWith DuckDBV2ErrorTypeMismatch err (execute info context))
+              (c_duckdb_v2_cast_function_set_exec_callback function)
+        )
+        (attachOpaque (c_duckdb_v2_cast_function_set_user_data function))
+        \installCallback -> do
+          configure function
+          installCallback
+          register
+
+{- Note [The error code of a failed cast]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+DuckDB 2.0.0 runs each cast as its scalar function "__cast". It marks this
+function as fallible only from the source type and the target type
+(CreateCastExpression in src/function/scalar/operator/cast.cpp, lines 174 to
+190, and BoundCastExpression::CastCanThrow in
+src/planner/expression/bound_cast_expression.cpp, lines 337 to 396). It does
+not examine a registered cast. Thus DuckDB marks a cast to VARCHAR, a widening
+cast such as INTEGER to BIGINT or FLOAT to DOUBLE, and a cast from an ENUM, a
+LIST, or a STRUCT to VARCHAR as a function that cannot fail. The cast builder
+of the C API has no property that changes this.
+
+A function that cannot fail must not raise an Invalid Input, Out of Range, or
+Conversion error. DuckDB changes such an error to an INTERNAL error
+(ThrowNonFallibleFunctionError in src/function/scalar_function.cpp, lines 17
+to 25). A code with no exception type, for example Api, becomes an Invalid
+Input error first. An INTERNAL error during the execution of a query
+invalidates the database (FailQueryInternal in
+src/main/client_context_execution.cpp, lines 439 to 443). Then each statement
+on each connection of the database fails until the database opens again. The
+header says for DUCKDB_V2_CAST_MODE_NORMAL: "A conversion failure reported
+through the error slot aborts the query." DuckDB does not keep this sentence.
+
+Thus each cast callback of the library writes the code
+DUCKDB_V2_ERROR_TYPE_MISMATCH for each failure (runCallbackWith in
+"Database.DuckDB.Simple.Callback"). The code of a cast does not depend on the
+exception. It replaces the type of each t'SQLError' from the callback, also the
+type Conversion of a failed query in the callback. Thus a change of the code
+of runCallback does not change the code of a cast. DuckDB rethrows an error of
+this type with no change. The statement fails with "Mismatch Type Error: " and
+the text of the failure. An explicit transaction is aborted under each
+transaction invalidation policy. The code is the same for a cast that DuckDB
+marks as fallible.
+
+The 49 codes of 'ErrorType' give these results in the column form and in an
+explicit transaction:
+
+- 30 codes, ErrorTypeMismatch included, keep their type and the database, and
+  abort an explicit transaction under each policy.
+- 7 codes keep an explicit transaction open under the policy
+  SYNTACTIC_ERRORS_DO_NOT_INVALIDATE: ErrorQueryBinder, ErrorDatabaseCatalog,
+  ErrorResourceConnection, ErrorQueryParameterNotAllowed, ErrorQueryParser,
+  ErrorConfigurationPermission, and ErrorResourceInUse.
+- 11 codes invalidate the database. ErrorApi, ErrorIOFileNotFound,
+  ErrorIOReadFailure, ErrorIOEof, ErrorInputInvalid,
+  ErrorInputParameterInvalid, ErrorInputOutOfRange,
+  ErrorInputMetadataDeferred, ErrorTypeConversion, and ErrorRuntimeInternal
+  give an INTERNAL error. ErrorRuntimeFatal gives a FATAL error.
+- ErrorIONetwork keeps the database, but the error has the type ErrorApi.
+
+Do not replace the code without a run of each code in the column form and in
+an explicit transaction under each policy.
+
+In DUCKDB_V2_CAST_MODE_TRY, DuckDB discards the error and keeps what the
+callback wrote, so TRY_CAST gives NULL for a failed row only when the callback
+wrote NULL there. TRY(...) catches only the Invalid Input, Out of Range, and
+Conversion errors, so TRY(CAST(...)) raises the error of a failed cast.
+-}
+
+-- | Register a custom type with a native base type. Casts are registered separately.
+registerCustomType :: Connection -> Text -> TypeDeclaration -> IO ()
+registerCustomType connection = registerCustomTypeOn (ConnectionTarget connection)
+
+-- | Register a custom type with a native base type on a connection or a
+-- loading extension. The name must not be empty and must not contain NUL.
+registerCustomTypeOn :: RegistrationTarget -> Text -> TypeDeclaration -> IO ()
+registerCustomTypeOn target name baseType = do
+  validateName name
+  withRegistrationFactory target \factory ->
+    registerCustomTypeWith target \custom -> do
+      withIdentifier name $ checked . c_duckdb_v2_custom_type_set_name custom
+      withTypeDeclaration factory baseType $ checked . c_duckdb_v2_custom_type_set_base_type custom
+
+-- | Configure and register a custom type on a connection or extension.
+-- The configuration action borrows the builder.
+registerCustomTypeWith :: RegistrationTarget -> (DuckDBV2CustomTypeHandle -> IO ()) -> IO ()
+registerCustomTypeWith target configure =
+  withTarget
+    target
+    c_duckdb_v2_custom_type_create
+    c_duckdb_v2_custom_type_destroy
+    c_duckdb_v2_connection_register_custom_type
+    c_duckdb_v2_extension_register_custom_type
+    \custom register ->
+      configure custom >> register
+
+-- | Configure and register a macro of a loading extension. The configuration
+-- action borrows the builder. It can set the name, the body, the signature, and
+-- the documentation. DuckDB keeps copies after this action returns. The V2 API
+-- registers a macro only for an extension. A connection target raises an
+-- @SQLError@ before a native call. Use SQL @CREATE MACRO@ on a connection.
+registerMacroFunctionWith :: RegistrationTarget -> MacroFunctionType -> (DuckDBV2MacroFunctionHandle -> IO ()) -> IO ()
+registerMacroFunctionWith target kind configure = case target of
+  ConnectionTarget _ -> throwInvalidArgument "the V2 API registers a macro only for an extension; use CREATE MACRO on a connection"
+  ExtensionTarget extension context ->
+    withContextFactory context \factory ->
+      bracket (output (c_duckdb_v2_macro_function_create factory (macroFunctionTypeToNative kind))) (destroy c_duckdb_v2_macro_function_destroy) \function -> do
+        configure function
+        checked (c_duckdb_v2_extension_register_macro_function extension function)
+
+-- | Register a connection-local replacement scan. It precedes instance scans.
+registerReplacementScan :: Connection -> ContextCallback DuckDBV2ReplacementScanInfoHandle -> IO ()
+registerReplacementScan connection = registerReplacementScanOn (ConnectionTarget connection)
+
+-- | Register a managed replacement scan on a connection or loading extension.
+-- Extension scans belong to the instance.
+registerReplacementScanOn :: RegistrationTarget -> ContextCallback DuckDBV2ReplacementScanInfoHandle -> IO ()
+registerReplacementScanOn target callback =
+  withTarget
+    target
+    c_duckdb_v2_replacement_scan_create
+    c_duckdb_v2_replacement_scan_destroy
+    c_duckdb_v2_connection_register_replacement_scan
+    c_duckdb_v2_extension_register_replacement_scan
+    (configureScan (checkTargetThreads target) callback)
+
+-- | Register an instance-wide replacement scan. It is shared by its connections.
+-- Register the scan before a connection runs a query. Registration while another
+-- connection binds a query is not thread safe.
+registerInstanceReplacementScan :: Instance -> ContextCallback DuckDBV2ReplacementScanInfoHandle -> IO ()
+registerInstanceReplacementScan instance' callback = withInstanceHandle instance' $ \native ->
+  withInstanceFactory native $ \factory ->
+    bracket (output (c_duckdb_v2_replacement_scan_create factory)) (destroy c_duckdb_v2_replacement_scan_destroy) $ \scan ->
+      configureScan
+        (checkQueryThreads (output (c_duckdb_v2_instance_get_config native)))
+        callback
+        scan
+        (checked (c_duckdb_v2_instance_register_replacement_scan native scan))
+
+-- | Store Haskell state in a native-owned bind, global, local, or init data slot.
+-- Pass the corresponding native opaque setter. Do not use registration user data.
+-- This helper uses native default equality. Use raw opaque callbacks for custom equality.
+-- Transfer a value at most once to each native state slot. In DuckDB 2.0.0, a
+-- setter for init data, batch data, global state, or local state does not release
+-- a pointer that it replaces. See Note [Callback ownership] in
+-- <src/Database.DuckDB.Simple.Callback.html Database.DuckDB.Simple.Callback>. Store an @IORef@ or another mutable state
+-- cell when the callback must change its state.
+--
+-- > R.setCallbackState (c_duckdb_v2_function_bind_set_bind_data input) (amount :: Int64)
+setCallbackState :: (Typeable a) => (Ptr DuckDBV2Opaque -> Ptr DuckDBV2ErrorInfoHandle -> IO DuckDBV2Error) -> a -> IO ()
+setCallbackState setter = transferCallbackState (attachOpaque setter) . toDyn
+
+-- | Read state previously stored with 'setCallbackState'.
+-- Pass the corresponding native pointer getter. A missing state or a state of
+-- another type raises an error.
+--
+-- > amount <- R.getCallbackState (c_duckdb_v2_table_function_init_global_get_bind_data info) :: IO Int64
+getCallbackState :: forall a. (Typeable a) => (Ptr (Ptr Void) -> Ptr DuckDBV2ErrorInfoHandle -> IO DuckDBV2Error) -> IO a
+getCallbackState getter = do
+  stored <- readCallbackState getter
+  case fromDynamic stored of
+    Just value -> pure value
+    Nothing ->
+      throwIO
+        ( SQLError
+            ( "duckdb-simple: callback state has type "
+                <> Text.pack (show (dynTypeRep stored))
+                <> ", not "
+                <> Text.pack (show (typeRep (Proxy @a)))
+            )
+            Nothing
+            Nothing
+            Nothing
+        )
+
+-- | Construct a type through a borrowed factory, borrow it for an action, and
+-- release it on every exit path. The factory can come from a connection or from
+-- an extension context.
+--
+-- > R.withTypeDeclaration factory bigint $ R.checked . c_duckdb_v2_cast_function_set_source_type function
+withTypeDeclaration :: DuckDBV2FactoryHandle -> TypeDeclaration -> (DuckDBV2LogicalTypeHandle -> IO a) -> IO a
+withTypeDeclaration factory declaration = bracket acquire destroyLogicalType
+  where
+    acquire = case declaration of
+      StructuredType rep -> logicalTypeFromRep factory rep
+      TypeExpression sql -> withText sql (output . c_duckdb_v2_factory_create_type_from_text factory)
+
+-- | Add parameters and an optional return type to a borrowed native signature.
+-- Types and defaults use the borrowed factory. The factory can come from a
+-- connection or from an extension context.
+-- Get the signature from the builder:
+--
+-- > R.output (c_duckdb_v2_scalar_function_get_signature function)
+-- >   >>= R.configureFunctionSignature factory (R.FunctionSignature [R.parameter "value" bigint] (Just bigint))
+configureFunctionSignature :: DuckDBV2FactoryHandle -> FunctionSignature -> DuckDBV2FunctionSignatureHandle -> IO ()
+configureFunctionSignature factory FunctionSignature{signatureParameters, signatureReturnType} signature = do
+  forM_ signatureParameters $ \FunctionParameter{parameterName, parameterType, parameterDefault, parameterKind} ->
+    withIdentifier parameterName $ \name ->
+      withTypeDeclaration factory parameterType $ \dtype ->
+        case parameterDefault of
+          Nothing -> checked (c_duckdb_v2_function_signature_add_parameter signature name dtype nullHandle parameterKind)
+          Just (DefaultValue make) -> bracket (make factory) destroyValue $ \native ->
+            checked (c_duckdb_v2_function_signature_add_parameter signature name dtype native parameterKind)
+  forM_ signatureReturnType $ \dtype ->
+    withTypeDeclaration factory dtype $ checked . c_duckdb_v2_function_signature_set_return_type signature
+
+-- | Set the callback of a replacement scan builder, and then run the
+-- registration action. The user data of the scan releases the callback pointer.
+configureScan
+  :: IO () -> ContextCallback DuckDBV2ReplacementScanInfoHandle -> DuckDBV2ReplacementScanHandle -> IO () -> IO ()
+configureScan checkRuntime callback scan register =
+  withCallbackResources
+    checkRuntime
+    ( \allocate ->
+        install
+          allocate
+          DuckDBV2ReplacementScanCallbackFn
+          (DuckDBV2ReplacementScanCallbackFn_Aux (guardContext callback))
+          (c_duckdb_v2_replacement_scan_set_callback scan)
+    )
+    (attachOpaque (c_duckdb_v2_replacement_scan_set_user_data scan))
+    \installCallback -> installCallback >> register
+
+-- | Run a callback that gets no context. An exception becomes a native error.
+guardCallback :: (info -> IO ()) -> info -> Ptr DuckDBV2ErrorInfoHandle -> IO ()
+guardCallback action info err = runCallback err (action info)
+
+-- | Run a bind callback. An exception becomes a native error.
+guardBind
+  :: BindCallback result -> DuckDBV2FunctionBindInfoHandle -> result -> DuckDBV2ContextHandle -> Ptr DuckDBV2ErrorInfoHandle -> IO ()
+guardBind action info result context err = runCallback err (action info result context)
+
+-- | Reject an empty registration name and a name that contains NUL.
+validateName :: Text -> IO ()
+validateName name =
+  when (Text.null name || Text.any (== '\0') name) $
+    throwInvalidArgument "registration name must be nonempty and must not contain NUL"
diff --git a/src/Database/DuckDB/Simple/Variant.hs b/src/Database/DuckDB/Simple/Variant.hs
--- a/src/Database/DuckDB/Simple/Variant.hs
+++ b/src/Database/DuckDB/Simple/Variant.hs
@@ -1,40 +1,97 @@
+{-# LANGUAGE LambdaCase #-}
 {-# LANGUAGE NamedFieldPuns #-}
-{-# LANGUAGE PatternSynonyms #-}
 
--- | DuckDB VARIANT values.
+-- |
+-- Module      : Database.DuckDB.Simple.Variant
+-- Description : DuckDB VARIANT values.
 module Database.DuckDB.Simple.Variant (
-    Variant (..),
-    variantObject,
+  Variant (..),
+  variantObject,
 ) where
 
-import Data.Array (listArray)
+import Data.Array (elems, listArray)
 import qualified Data.Map.Strict as Map
 import Data.Text (Text)
-import Database.DuckDB.FFI (pattern DuckDBTypeVariant)
-import Database.DuckDB.Simple.FromField (Field (..), FieldValue (..), FromField (..))
-import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep (..), StructField (..), StructValue (..))
-import Database.DuckDB.Simple.Ok (Ok (..))
+import qualified Data.Text as Text
+import Database.DuckDB.Simple.Element (containsType)
+import Database.DuckDB.Simple.FromField (Field (..), FieldValue (..), FromField (..), ResultError (..), returnError)
+import Database.DuckDB.Simple.Geometry (RawGeometry (..))
+import Database.DuckDB.Simple.LogicalRep (LogicalTypeId (..), LogicalTypeRep (..), StructField (..), StructValue (..), withoutAliases)
 
-{- | A VARIANT value. The payload is a 'FieldValue' with the native type of the
-stored value. Arrays are 'FieldList' values. Objects are 'FieldStruct' values
-whose fields have the VARIANT type. SQL NULL is 'FieldNull'.
-A t'Variant' parameter binds its payload as a VARIANT.
--}
+-- | A VARIANT value. The payload is a 'FieldValue' with the native type of the
+-- stored value. Arrays are 'FieldList' values. Objects are 'FieldStruct' values
+-- whose fields have the VARIANT type. Decoded object keys use DuckDB's native
+-- lexicographic order. Array elements retain their order. SQL NULL is 'FieldNull'.
+-- A t'Variant' parameter binds its payload as a VARIANT. A VARIANT does not keep
+-- a UNION, a MAP, an ENUM, or the CRS of a GEOMETRY, so a parameter with such a
+-- payload, at any depth, raises an error. Results preserve their native scalar
+-- types and nested values through public V2 operations.
 newtype Variant = Variant {variantPayload :: FieldValue}
-    deriving (Eq, Show)
+  deriving (Eq, Show)
 
-{- | Build the payload of a VARIANT object. Each field has the VARIANT type,
-in the order of the entries.
--}
+-- | Build the payload of a VARIANT object. Each field has the VARIANT type,
+-- in the order of the entries.
 variantObject :: [(Text, FieldValue)] -> FieldValue
 variantObject entries =
-    FieldStruct
-        StructValue
-            { structValueFields = listArray (0, length entries - 1) [StructField name value | (name, value) <- entries]
-            , structValueTypes = listArray (0, length entries - 1) [StructField name (LogicalTypeScalar DuckDBTypeVariant) | (name, _) <- entries]
-            , structValueIndex = Map.fromList (zip (map fst entries) [0 ..])
-            }
+  FieldStruct
+    StructValue
+      { structValueFields = listArray (0, length entries - 1) [StructField name value | (name, value) <- entries]
+      , structValueTypes = listArray (0, length entries - 1) [StructField name (LogicalTypeScalar LogicalTypeIdVariant) | (name, _) <- entries]
+      , structValueIndex = Map.fromList (zip (map fst entries) [0 ..])
+      }
 
--- | Read any column. A VARIANT column gives its decoded payload.
+-- | Reads a value that a VARIANT can hold: the value of a VARIANT column, or a
+-- value of another SQL type with that shape. The shape is a scalar that is not
+-- an ENUM, a GEOMETRY with no CRS, a LIST of such values, or a STRUCT in the
+-- form of a VARIANT object: its fields have the type VARIANT and hold such
+-- values, and its keys are in ascending order. A value of another shape fails
+-- with 'Incompatible', because the cast of DuckDB to VARIANT gives another
+-- value. Write @c::VARIANT@ in SQL for such a column. A column whose type is or
+-- contains JSON, at each depth, also fails with 'Incompatible': DuckDB casts
+-- JSON to VARIANT by parsing the text, so @c::VARIANT@ gives the parsed value,
+-- not the text. See Note [Reads of another SQL type] in
+-- "Database.DuckDB.Simple.FromField".
 instance FromField Variant where
-    fromField Field{fieldValue} = Ok (Variant fieldValue)
+  fromField field@Field{fieldName, fieldValue, fieldType} = do
+    logical <- fieldType
+    if containsType isJson logical
+      then
+        returnError
+          Incompatible
+          field
+          (Text.concat [Text.pack "DuckDB casts JSON to VARIANT by parsing the text; write ", column, Text.pack "::VARIANT"])
+      else
+        if variantShape fieldValue
+          then pure (Variant fieldValue)
+          else returnError Incompatible field (Text.pack "a VARIANT does not hold a value of this shape; write c::VARIANT")
+    where
+      isJson (LogicalTypeAlias name (LogicalTypeScalar LogicalTypeIdVarchar)) = name == Text.pack "JSON"
+      isJson (LogicalTypeAlias name LogicalTypeCollatedVarchar{}) = name == Text.pack "JSON"
+      isJson _ = False
+      column = if Text.null fieldName then Text.pack "c" else fieldName
+
+-- | Whether a VARIANT can hold a decoded value. A VARIANT column decodes only to
+-- these values: a scalar that is not an ENUM, a GEOMETRY with no CRS, a
+-- 'FieldList' of such values, and a 'FieldStruct' in the form of a VARIANT
+-- object. Such an object has fields of the type VARIANT that hold such values,
+-- and its keys are in ascending order: DuckDB sorts the keys of an object by
+-- their UTF-8 bytes. The order of 'Text' is the order of code points, and UTF-8
+-- keeps that order in its bytes, so the two orders are the same. Each other
+-- value has no VARIANT form: a 'FieldArray', a 'FieldTuple', another
+-- 'FieldStruct', a 'FieldEnum', a 'FieldMap', a 'FieldUnion', and a GEOMETRY
+-- with a CRS.
+variantShape :: FieldValue -> Bool
+variantShape = \case
+  FieldEnum{} -> False
+  FieldGeometry RawGeometry{rawGeometryCRS = Just _} -> False
+  FieldMap{} -> False
+  FieldUnion{} -> False
+  FieldArray{} -> False
+  FieldTuple{} -> False
+  FieldList values -> all variantShape values
+  FieldStruct StructValue{structValueFields, structValueTypes} ->
+    let names = map structFieldName (elems structValueTypes)
+    in  all ((== LogicalTypeScalar LogicalTypeIdVariant) . withoutAliases . structFieldValue) (elems structValueTypes)
+          && and (zipWith (<) names (drop 1 names))
+          && all (variantShape . structFieldValue) (elems structValueFields)
+  _ -> True
diff --git a/src/Database/DuckDB/Simple/VariantCodec.hs b/src/Database/DuckDB/Simple/VariantCodec.hs
--- a/src/Database/DuckDB/Simple/VariantCodec.hs
+++ b/src/Database/DuckDB/Simple/VariantCodec.hs
@@ -1,452 +1,499 @@
 {-# LANGUAGE BlockArguments #-}
 {-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE NamedFieldPuns #-}
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE StrictData #-}
 
-{- | Checked access to DuckDB 1.5's private VARIANT payload.
-Only public C handles and vector accessors cross the native boundary.
--}
+-- |
+-- Module      : Database.DuckDB.Simple.VariantCodec
+-- Description : Lossless VARIANT decoding through public V2 values and SQL type metadata.
 module Database.DuckDB.Simple.VariantCodec (
-    decodeVariant,
-    prepareVariantDecoder,
-    decodeVariantPayload,
+  VariantState,
+  variantConnection,
+  newVariantState,
+  destroyVariantState,
+  prepareVariantDecoder,
 ) where
 
-import Control.Exception (bracket, throwIO)
-import Control.Monad (forM, forM_, unless, when)
-import Control.Monad.Trans.Class (lift)
-import Control.Monad.Trans.State.Strict (StateT, evalStateT, gets, modify')
-import Data.Array (Array, bounds, listArray, (!))
-import Data.Bits (complement, finiteBitSize, shiftL, (.&.), (.|.))
-import Data.ByteString (ByteString)
-import qualified Data.ByteString as BS
+import Control.Exception (bracket, evaluate, mask_)
+import Control.Monad (forM, unless)
+import Data.Array (elems, listArray, (!))
+import Data.IORef (IORef, modifyIORef', newIORef, readIORef, writeIORef)
 import qualified Data.IntMap.Strict as IntMap
-import qualified Data.IntSet as IntSet
+import qualified Data.Map.Strict as Map
 import qualified Data.Set as Set
 import Data.Text (Text)
 import qualified Data.Text as Text
-import qualified Data.Text.Encoding as Text
-import Data.Word (Word32, Word8)
-import Database.DuckDB.FFI
-import Database.DuckDB.Simple.Element (bitStringFromBytes, chunkDecodeBlob, chunkIsRowValid, decodeElement)
-import Database.DuckDB.Simple.FromField (
-    BigNum (..),
-    DecimalValue (..),
-    FieldValue (..),
-    RawGeometry (..),
-    fromBigNumBytes,
- )
-import Database.DuckDB.Simple.Internal (destroyLogicalType)
+import qualified Data.Text.Foreign as TextForeign
+import Database.DuckDB.Simple.FromField (FieldValue (..))
+import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep (..), StructField (..), StructValue (..))
+import Database.DuckDB.Simple.Native
+import Database.DuckDB.Simple.V2.LogicalRep (logicalTypeFromRep)
 import Database.DuckDB.Simple.Variant (variantObject)
-import Foreign.C.String (peekCString)
-import Foreign.Marshal.Alloc (alloca, allocaBytesAligned)
-import Foreign.Marshal.Utils (copyBytes)
-import Foreign.Ptr (Ptr, castPtr, nullPtr)
-import Foreign.Storable (Storable, peek, peekElemOff, poke, sizeOf)
-import Text.Read (readMaybe)
+import Foreign.C.ConstPtr (ConstPtr (..))
+import Foreign.Marshal.Array (withArray)
+import Foreign.Marshal.Utils (with)
+import Foreign.Ptr (nullPtr)
 
--- | Raise a codec error before an invalid native operation.
-codecError :: String -> IO a
-codecError message = throwIO (userError ("duckdb-simple: VARIANT: " <> message))
+{- Note [VARIANT decoding]
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+The decoder copies each VARIANT row of a vector to a FieldValue with the native
+type of the stored value. It uses SQL metadata and native casts on a helper
+connection. It does not read the private payload format of DuckDB.
 
--- | Convert a checked pure result to an IO result.
-checked :: Either String a -> IO a
-checked = either codecError pure
+- Why SQL. The header commits to no view layout for VARIANT, so the decoder
+  reads each row with duckdb_v2_vector_get_value. V2 has no accessor for the
+  children of a VARIANT value. SQL functions and native casts give the tag, the
+  keys, and the children of a value.
 
--- | Reject native versions outside the supported private-format range.
-checkVersion :: IO ()
-checkVersion = do
-    version <- c_duckdb_library_version >>= peekCString
-    let parts = Text.splitOn "." (Text.pack version)
-        patch = case parts of
-            ["v1", "5", p] -> readMaybe (Text.unpack p) :: Maybe Int
-            _ -> Nothing
-    unless (maybe False (>= 3) patch) (codecError ("unsupported native version " <> version))
+- The metadata statement (metadataStatement). One statement gives the tag
+  (variant_typeof) and the object keys (variant_keys) of each value in a
+  VARIANT list. The state keeps one prepared statement, so executions reuse
+  its bound plan. Its parameter has the fixed type VARIANT[]. The decoder
+  reads the borrowed result vector before its chunk closes. This avoids copying the
+  complete metadata list into an owned value and then into another vector.
 
--- | Check the byte order and pointer width required by native scalar loads.
-checkPlatform :: IO ()
-checkPlatform = alloca \ptr -> do
-    poke ptr (1 :: Word32)
-    first <- peek (castPtr ptr :: Ptr Word8)
-    unless (first == 1 && sizeOf (nullPtr :: Ptr ()) == 8) $
-        codecError "the private codec requires a 64-bit little-endian host"
+- The casts. The tag of a scalar is the text of variant_typeof. scalarType
+  gives the type text of the exact cast target of each tag. The scalars with
+  the same tag share one cast to a list of the target type. A tag with one
+  scalar gets a direct cast of that scalar. Each array gets its own cast to a
+  VARIANT list. The state keeps each parsed type (castType).
 
--- | Acquire a non-NULL native handle.
-nonNull :: String -> IO (Ptr a) -> IO (Ptr a)
-nonNull label action = do
-    ptr <- action
-    when (ptr == nullPtr) (codecError (label <> " returned NULL"))
-    pure ptr
+- The objects (withObjectChildren). The objects with the same keys share one
+  extraction. If the keys can be STRUCT field names (validStructFields), one
+  cast to a STRUCT list extracts the children. Otherwise one extraction query
+  binds the keys as values, so empty and NUL keys stay exact. The SQL text of
+  the query depends only on the key count. The state keeps the parsed
+  extraction statement of the last key count (extractionStatement). A group
+  with another key count replaces that statement. The state keeps one
+  extraction statement only. Thus the memory of the state does not grow with
+  the number of key counts in the data. An object without keys needs no
+  extraction (queryObjectGroup).
 
--- | Check a logical type's tag.
-expectType :: DuckDBType -> DuckDBLogicalType -> IO ()
-expectType expected logical = do
-    actual <- c_duckdb_get_type_id logical
-    unless (actual == expected) (codecError "unexpected physical child type")
+- The levels (decodeValues). The decoder reads the metadata of all values of
+  one nesting level together. Then it decodes the children of all nodes of the
+  level together, and then it builds the nodes of the level (assemble).
 
--- | Check a STRUCT's names and owned child descriptors.
-checkStruct :: DuckDBLogicalType -> [(Text, DuckDBLogicalType -> IO ())] -> IO ()
-checkStruct logical fields = do
-    count <- c_duckdb_struct_type_child_count logical
-    unless (count == fromIntegral (length fields)) (codecError "unexpected physical child count")
-    sequence_
-        [ do
-            bracket (nonNull "child name" (c_duckdb_struct_type_child_name logical index)) (c_duckdb_free . castPtr) \name -> do
-                bytes <- BS.packCString name
-                unless (bytes == Text.encodeUtf8 expectedName) (codecError "unexpected physical child name")
-            bracket (nonNull "child type" (c_duckdb_struct_type_child_type logical index)) destroyLogicalType checkChild
-        | (index, (expectedName, checkChild)) <- zip [0 ..] fields
-        ]
+The helper connection. The queries of the decoder do not run on the caller
+connection. An explicit stream keeps its result open on the caller connection
+between two fetches, and the decoder reads the rows of each chunk while that
+result is open (fetchChunk in "Database.DuckDB.Simple.Result"). DuckDB permits
+one open result for each connection, and it rejects a second execution. Thus
+the queries of the decoder run on a helper connection, so that the decode does
+not interrupt the stream. See Note [Connection lock] in
+"Database.DuckDB.Simple.Internal". A materialized result closes before its rows
+are decoded, but it uses the same reader. A helper connection on the host
+instance has its GLOBAL settings, not the caller's SESSION settings. The
+metadata query needs an expression depth of 11 when it is prepared. A GLOBAL
+max_expression_depth below 11 fails its preparation with a Binder Error.
 
--- | Check a LIST and its owned element descriptor.
-checkList :: (DuckDBLogicalType -> IO ()) -> DuckDBLogicalType -> IO ()
-checkList checkChild logical = do
-    expectType DuckDBTypeList logical
-    bracket (nonNull "list child type" (c_duckdb_list_type_child_type logical)) destroyLogicalType checkChild
+VariantState holds the helper connection, the prepared metadata statement, the
+parsed extraction statement of the last key count, and the cast types. The
+owner of the helper connection destroys the state before the connection.
 
--- | Check the complete, unshredded four-child VARIANT schema.
-checkSchema :: DuckDBLogicalType -> IO ()
-checkSchema logical = do
-    expectType DuckDBTypeVariant logical
-    checkStruct
-        logical
-        [ ("keys", checkList (expectType DuckDBTypeVarchar))
-        ,
-            ( "children"
-            , checkList \child -> do
-                expectType DuckDBTypeStruct child
-                checkStruct child [("keys_index", expectType DuckDBTypeUInteger), ("values_index", expectType DuckDBTypeUInteger)]
-            )
-        ,
-            ( "values"
-            , checkList \child -> do
-                expectType DuckDBTypeStruct child
-                checkStruct child [("type_id", expectType DuckDBTypeUTinyInt), ("byte_offset", expectType DuckDBTypeUInteger)]
-            )
-        , ("data", expectType DuckDBTypeBlob)
-        ]
+- Each caller connection reuses its own decoder. See Note [Concurrent VARIANT
+  decoding] in "Database.DuckDB.Simple.Internal".
 
--- | Check an element index before native pointer arithmetic.
-checkIndex :: Int -> Int -> IO ()
-checkIndex width index =
-    when (index < 0 || index > maxBound `div` width) (codecError "native element index exceeds Int range")
+- A connection's COPY TO reader uses a helper connection of that instance
+  for each vector. An extension's COPY TO reader and typed argument readers
+  use a private instance. Scalar and aggregate functions reuse that instance
+  across vectors. See Note [VARIANT reads inside callbacks] in
+  "Database.DuckDB.Simple.Materialize".
 
--- | Prepare validity access for a chunk. The caller checks row bounds.
-prepareValidity :: DuckDBVector -> IO (Int -> IO Bool)
-prepareValidity vector = do
-    validity <- c_duckdb_vector_get_validity vector
-    pure (chunkIsRowValid validity . fromIntegral)
+TODO: When V2 exposes VARIANT tags and children directly, use those accessors
+to replace the metadata and object extraction queries. Preserve exact scalar
+types and object keys, including empty keys and keys containing NUL.
 
--- | Borrow a fixed-width buffer until its chunk is destroyed.
-prepareElementReader :: (Storable a) => DuckDBVector -> IO (Int -> IO a)
-prepareElementReader vector = do
-    ptr <- c_duckdb_vector_get_data vector
-    valid <- prepareValidity vector
-    pure (readAt valid (castPtr ptr))
-  where
-    readAt :: (Storable a) => (Int -> IO Bool) -> Ptr a -> Int -> IO a
-    readAt valid ptr index = do
-        checkIndex (sizeOfElement ptr) index
-        when (ptr == nullPtr) (codecError "NULL vector data")
-        present <- valid index
-        unless present (codecError "NULL physical payload element")
-        peekElemOff ptr index
-    sizeOfElement :: (Storable a) => Ptr a -> Int
-    sizeOfElement ptr = sizeOf (undefined `asTypeOf` element ptr)
-    element :: Ptr a -> a
-    element _ = undefined
+The decoder casts with the factory of the instance (variantCasts). It decodes
+each value that contains no VARIANT, such as a cast result, with the same
+factory. See Note [User casts and the casts of the library] in
+"Database.DuckDB.Simple.Materialize".
+-}
 
--- | Borrow a string buffer and copy each requested value into Haskell memory.
-prepareBytesReader :: DuckDBVector -> IO (Int -> IO ByteString)
-prepareBytesReader vector = do
-    base <- c_duckdb_vector_get_data vector
-    valid <- prepareValidity vector
-    pure \index -> do
-        checkIndex 16 index
-        present <- valid index
-        unless present (codecError "NULL physical string element")
-        when (base == nullPtr) (codecError "NULL string vector data")
-        chunkDecodeBlob base (fromIntegral index)
+-- | The helper connection of the VARIANT decoder, and the native objects that
+-- the decoder keeps for it: the prepared metadata statement, the parsed
+-- extraction statement of the last key count, and the types for casts and
+-- VARIANT lists. The state borrows the connection. The owner destroys
+-- the state with 'destroyVariantState' before it destroys the connection. Use
+-- the state from one thread at a time. See Note [VARIANT decoding].
+data VariantState = VariantState
+  { variantConnection :: DuckDBV2ConnectionHandle
+  -- ^ The helper on which the decoder runs its queries.
+  , variantCasts :: DuckDBV2FactoryHandle
+  -- ^ The factory of the instance of the helper connection. The decoder casts
+  --     with it.
+  , variantStatement :: IORef (Maybe DuckDBV2PreparedStatementHandle)
+  , variantExtraction :: IORef (Maybe (Int, DuckDBV2SqlStatementHandle))
+  , variantTypes :: CastTypes
+  }
 
--- | Convert a nonnegative bounded integer to Int.
-checkedInt :: Integer -> IO Int
-checkedInt n
-    | n < 0 || n > toInteger (maxBound :: Int) = codecError "payload size exceeds Int range"
-    | otherwise = pure (fromInteger n)
+-- | Make an empty state for a helper connection and the factory of its
+-- instance. This allocates no native object.
+newVariantState :: DuckDBV2ConnectionHandle -> DuckDBV2FactoryHandle -> IO VariantState
+newVariantState connection casts = VariantState connection casts <$> newIORef Nothing <*> newIORef Nothing <*> newIORef Map.empty
 
--- | Prepare LIST bounds checks against the chunk's fixed child size.
-prepareListBounds :: DuckDBVector -> IO (Int -> IO (Int, Int))
-prepareListBounds vector = do
-    readEntry <- prepareElementReader vector
-    size <- c_duckdb_list_vector_get_size vector
-    pure \row -> do
-        DuckDBListEntry offset count <- readEntry row
-        unless (offset <= size && count <= size - offset) (codecError "LIST bounds exceed child size")
-        start <- checkedInt (toInteger offset)
-        len <- checkedInt (toInteger count)
-        _ <- checkedInt (toInteger offset + toInteger count)
-        pure (start, len)
+-- | Destroy the prepared metadata statement, the extraction statement, and
+-- every cached type. Release every item even if one destructor fails, and raise the first
+-- error after the last release. The state is empty afterwards, so a second call
+-- does nothing.
+destroyVariantState :: VariantState -> IO ()
+destroyVariantState VariantState{variantStatement, variantExtraction, variantTypes} = mask_ do
+  statement <- readIORef variantStatement
+  extraction <- readIORef variantExtraction
+  types <- readIORef variantTypes
+  writeIORef variantStatement Nothing
+  writeIORef variantExtraction Nothing
+  writeIORef variantTypes Map.empty
+  releaseItems
+    id
+    ( map (destroy c_duckdb_v2_prepared_statement_destroy) (maybe [] pure statement)
+        <> map (destroy c_duckdb_v2_sql_statement_destroy . snd) (maybe [] pure extraction)
+        <> map destroyLogicalType (Map.elems types)
+    )
 
--- | Decode one row while its flattened result chunk remains alive.
-decodeVariant :: DuckDBVector -> Int -> IO FieldValue
-decodeVariant vector row = prepareVariantDecoder vector >>= ($ row)
+-- | Copy a vector before returning its row reader. The connection of the state
+-- is a dedicated helper connection. It must remain exclusively borrowed until
+-- this function returns. The callbacks decode a value, or the first row of a
+-- borrowed vector, that contains no VARIANT. They use the factory they get and
+-- complete all native reads before returning. Each level batches type and key
+-- metadata. See Note [VARIANT decoding].
+prepareVariantDecoder
+  :: (DuckDBV2FactoryHandle -> DuckDBV2ValueHandle -> IO FieldValue)
+  -> (DuckDBV2FactoryHandle -> DuckDBV2VectorHandle -> IO FieldValue)
+  -> VariantState
+  -> DuckDBV2VectorHandle
+  -> IO (Int -> IO FieldValue)
+prepareVariantDecoder plain plainVector state vector = do
+  count <- output (c_duckdb_v2_vector_get_size vector)
+  bracket (acquireItems destroyValue [output (c_duckdb_v2_vector_get_value vector i) | i <- indices count]) (releaseItems destroyValue) \values -> do
+    decoded <- decodeValues plain plainVector state values
+    let rows = listArray (0, length decoded - 1) decoded
+    -- Give the element, not a thunk that keeps the array alive.
+    pure (evaluate . (rows !))
 
-{- | Check the format once and borrow buffers for a flattened result chunk.
-The returned reader must not outlive the chunk. The caller supplies row indices
-within that chunk. DuckDB result Fetch flattens nested vectors in 1.5.
-Each read copies its payload into Haskell memory, including referenced keys.
--}
-prepareVariantDecoder :: DuckDBVector -> IO (Int -> IO FieldValue)
-prepareVariantDecoder vector = do
-    checkVersion
-    checkPlatform
-    when (vector == nullPtr) (codecError "NULL vector")
-    bracket (nonNull "vector type" (c_duckdb_vector_get_column_type vector)) destroyLogicalType checkSchema
-    valid <- prepareValidity vector
-    keys <- child vector 0
-    children <- child vector 1
-    values <- child vector 2
-    blob <- child vector 3
-    keyBounds <- prepareListBounds keys
-    childBounds <- prepareListBounds children
-    valueBounds <- prepareListBounds values
-    keyVector <- nonNull "keys vector" (c_duckdb_list_vector_get_child keys)
-    childVector <- nonNull "children vector" (c_duckdb_list_vector_get_child children)
-    valueVector <- nonNull "values vector" (c_duckdb_list_vector_get_child values)
-    keyIndices <- child childVector 0
-    valueIndices <- child childVector 1
-    tags <- child valueVector 0
-    offsets <- child valueVector 1
-    readTag <- prepareElementReader tags
-    readOffset <- prepareElementReader offsets
-    hasKey <- prepareValidity keyIndices
-    readKey <- prepareElementReader keyIndices
-    readValue <- prepareElementReader valueIndices
-    readKeyBytes <- prepareBytesReader keyVector
-    readBlob <- prepareBytesReader blob
-    pure \row -> do
-        checkIndex 16 row
-        present <- valid row
-        if not present
-            then pure FieldNull
-            else do
-                (keyStart, keyCount) <- keyBounds row
-                (childStart, childCount) <- childBounds row
-                (valueStart, valueCount) <- valueBounds row
-                valueRows <- forM [valueStart .. valueStart + valueCount - 1] \index ->
-                    (,) <$> readTag index <*> readOffset index
-                childRows <- forM [childStart .. childStart + childCount - 1] \index -> do
-                    keyed <- hasKey index
-                    key <- if keyed then Just <$> readKey index else pure Nothing
-                    value <- readValue index
-                    when (toInteger value >= toInteger valueCount) (codecError "child value index out of bounds")
-                    case key of
-                        Just k | toInteger k >= toInteger keyCount -> codecError "child key index out of bounds"
-                        _ -> pure ()
-                    pure (key, value)
-                let usedKeys = Set.toList (Set.fromList [k | (Just k, _) <- childRows])
-                keyRows <- forM usedKeys \index -> do
-                    bytes <- readKeyBytes (keyStart + fromIntegral index)
-                    text <- checked (either (Left . show) Right (Text.decodeUtf8' bytes))
-                    pure (index, text)
-                bytes <- readBlob row
-                decodeVariantPayload valueRows childRows keyRows bytes
+-- | A decoded node owns the child values needed at the next nesting level.
+data VariantNode
+  = ScalarNode FieldValue
+  | ListNode [DuckDBV2ValueHandle]
+  | ObjectNode [(Text, DuckDBV2ValueHandle)]
+
+-- | Decode all siblings together before reconstructing their parent nodes.
+-- See Note [VARIANT decoding].
+decodeValues
+  :: (DuckDBV2FactoryHandle -> DuckDBV2ValueHandle -> IO FieldValue)
+  -> (DuckDBV2FactoryHandle -> DuckDBV2VectorHandle -> IO FieldValue)
+  -> VariantState
+  -> [DuckDBV2ValueHandle]
+  -> IO [FieldValue]
+decodeValues _ _ _ [] = pure []
+decodeValues plain plainVector state values = do
+  metadata <- queryMetadata plainVector state values
+  unless (length metadata == length values) (codecError "metadata query returned an unexpected number of nodes")
+  let indexed = zip3 [0 ..] metadata values
+      grouped key select = Map.toList (Map.fromListWith (++) [(key node, [(index, value)]) | (index, node@(tag, _), value) <- indexed, select tag])
+      nulls = [(index, ScalarNode FieldNull) | (index, (tag, _), _) <- indexed, isNull tag]
+      releaseIndexed = releaseNode . snd
+  scalars <- mapM (uncurry decodeScalars) (grouped fst (\tag -> not (isNull tag || isArray tag || isObject tag)))
+  bracket
+    (acquireItems releaseIndexed [(,) index <$> decodeArray value | (index, (tag, _), value) <- indexed, isArray tag])
+    (releaseItems releaseIndexed)
+    \arrays ->
+      bracket
+        (acquireItems (releaseItems releaseIndexed) [queryObjectGroup state keys rows | (keys, rows) <- grouped snd isObject])
+        (releaseItems (releaseItems releaseIndexed))
+        \objectGroups -> do
+          let indexedNodes = IntMap.fromList (nulls <> concat scalars <> arrays <> concat objectGroups)
+          nodes <- forM [0 .. length values - 1] \index ->
+            maybe (codecError "object extraction omitted a node") pure (IntMap.lookup index indexedNodes)
+          children <- decodeValues plain plainVector state (concatMap nodeChildren nodes)
+          assemble nodes children
   where
-    child parent index = nonNull "STRUCT vector child" (c_duckdb_struct_vector_get_child parent index)
+    casts = variantCasts state
+    isNull = (== "VARIANT_NULL")
+    isArray = Text.isPrefixOf "ARRAY("
+    isObject = Text.isPrefixOf "OBJECT("
+    decodeArray value =
+      withCast state value "VARIANT[]" \list -> do
+        count <- output (c_duckdb_v2_value_get_child_count list)
+        ListNode <$> acquireItems destroyValue [output (c_duckdb_v2_value_get_child list i) | i <- indices count]
+    -- Cast the scalars of one tag as one list. The cast keeps the exact type.
+    -- Cast a single scalar directly, because a list needs more native calls.
+    decodeScalars tag rows = do
+      target <- scalarType tag
+      case rows of
+        [(index, value)] -> withCast state value target \cast -> do
+          -- The cast fixes the type. Read these payloads without an owned vector.
+          decoded <- case tag of
+            "INT64" -> FieldInt64 <$> output (c_duckdb_v2_value_get_bigint cast)
+            "UINT64" -> FieldWord64 <$> output (c_duckdb_v2_value_get_ubigint cast)
+            _ -> plain casts cast
+          pure [(index, ScalarNode decoded)]
+        _ ->
+          withVariantList state (map snd rows) \list ->
+            withCast state list (target <> "[]") \cast ->
+              plain casts cast >>= \case
+                FieldList decoded | length decoded == length rows -> pure (zip (map fst rows) (map ScalarNode decoded))
+                _ -> codecError "scalar cast returned an unexpected value"
 
-{- | Decode copied 1.5 payload data for one non-NULL row.
-Values are (tag, byte offset). Children are (optional key index, value index).
-Keys pair an index with its text. Indices are relative to this row's LISTs.
-The root value has index zero. This helper checks all metadata before decoding.
-It raises an error for cycles. Shared values use a memo table.
--}
-decodeVariantPayload :: [(Word8, Word32)] -> [(Maybe Word32, Word32)] -> [(Word32, Text)] -> ByteString -> IO FieldValue
-decodeVariantPayload valueRows childRows keyRows bytes = do
-    when (finiteBitSize (0 :: Int) < 64) (codecError "the private codec requires a 64-bit host")
-    let values = listArray (0, length valueRows - 1) valueRows
-        children = listArray (0, length childRows - 1) childRows
-        keys = IntMap.fromList [(fromIntegral k, t) | (k, t) <- keyRows]
-        valueCount = length valueRows
-        childCount = length childRows
-    when (null valueRows) (codecError "missing root value")
-    unless (IntMap.size keys == length keyRows) (codecError "duplicate key dictionary index")
-    forM_ valueRows \(tag, offset) -> do
-        when (tag > 33) (codecError "unknown payload tag")
-        when (toInteger offset > toInteger (BS.length bytes)) (codecError "byte offset exceeds data size")
-    forM_ childRows \(key, value) -> do
-        when (toInteger value >= toInteger valueCount) (codecError "child value index out of bounds")
-        case key of
-            Just k -> unless (IntMap.member (fromIntegral k) keys) (codecError "missing child key")
-            Nothing -> pure ()
-    evalStateT (visit values children keys childCount IntSet.empty 0) IntMap.empty
+-- | Extract the children of objects with one key layout. One native cast or
+-- one extraction query extracts the children of all objects. Each object gets one
+-- child for each key, in key order. Check the object count and the child count of
+-- each object.
+queryObjectGroup :: VariantState -> [Text] -> [(Int, DuckDBV2ValueHandle)] -> IO [(Int, VariantNode)]
+queryObjectGroup _ [] rows = pure [(index, ObjectNode []) | (index, _) <- rows]
+queryObjectGroup state keys rows =
+  withVariantList state (map snd rows) \list ->
+    withObjectChildren state keys list \objects -> do
+      count <- output (c_duckdb_v2_value_get_child_count objects)
+      unless (toInteger count == toInteger (length rows)) (codecError "object extraction returned an unexpected row count")
+      acquireItems
+        (releaseNode . snd)
+        [ bracket (output (c_duckdb_v2_value_get_child objects i)) destroyValue \children -> do
+            childCount <- output (c_duckdb_v2_value_get_child_count children)
+            unless (toInteger childCount == toInteger (length keys)) (codecError "object extraction returned an unexpected child count")
+            owned <- acquireItems destroyValue [output (c_duckdb_v2_value_get_child children j) | j <- indices childCount]
+            pure (index, ObjectNode (zip keys owned))
+        | (i, (index, _)) <- zip [0 ..] rows
+        ]
+
+-- | Borrow one value for each object in a VARIANT list. Each value has one
+-- child for each key, in key order. If the keys are valid STRUCT field names, a
+-- native cast to a STRUCT list makes the values. Otherwise an extraction query
+-- makes them. The binder needs constant extraction keys. The query binds each
+-- key once and applies the extractions to all objects. The bound keys can be
+-- empty or contain NUL. The state keeps the parsed extraction statement of the
+-- last key count ('extractionStatement'). A group with another key count
+-- replaces it. V2 has no accessor for the children of a VARIANT value. The
+-- STRUCT cast is the fast path. The query is the only exact path for the other
+-- key lists. See Note [VARIANT decoding].
+withObjectChildren :: VariantState -> [Text] -> DuckDBV2ValueHandle -> (DuckDBV2ValueHandle -> IO a) -> IO a
+withObjectChildren state@VariantState{variantConnection = connection} keys list action
+  | validStructFields keys =
+      -- The cast is lenient. It matches a key and a field name without
+      -- regard to ASCII case. It gives NULL for a missing key. It ignores an
+      -- extra key. Thus a wrong field list does not cause an error. The
+      -- result is exact only because the fields are the keys of each object
+      -- and 'validStructFields' accepts them. Do not relax that predicate.
+      withConnectionFactory connection \factory ->
+        bracket (logicalTypeFromRep factory structList) destroyLogicalType \logical ->
+          bracket (output (c_duckdb_v2_value_cast (variantCasts state) list logical)) destroyValue action
+  | otherwise =
+      withConnectionFactory connection \factory ->
+        bracket
+          (acquireItems destroyValue [withText key (output . c_duckdb_v2_value_create_varchar factory) | key <- keys])
+          (releaseItems destroyValue)
+          \keyValues -> do
+            statement <- extractionStatement state (length keys)
+            withStatementValue connection statement (list : keyValues) action
   where
-    visit :: Array Int (Word8, Word32) -> Array Int (Maybe Word32, Word32) -> IntMap.IntMap Text -> Int -> IntSet.IntSet -> Int -> StateT (IntMap.IntMap FieldValue) IO FieldValue
-    visit values children keys childCount ancestors index = do
-        when (IntSet.member index ancestors) (lift (codecError "cyclic child reference"))
-        cached <- gets (IntMap.lookup index)
-        case cached of
-            Just result -> pure result
-            Nothing -> do
-                (tag, offset) <- lift (checked (arrayElement values index))
-                let payload = BS.drop (fromIntegral offset) bytes
-                result <- case tag of
-                    29 -> nested True payload
-                    30 -> nested False payload
-                    _ -> lift (decodeScalar tag payload)
-                modify' (IntMap.insert index result)
-                pure result
-      where
-        nested object payload = do
-            (count, rest) <- lift (checked (readVarint payload))
-            start <- if count == 0 then pure 0 else fst <$> lift (checked (readVarint rest))
-            unless (toInteger start + toInteger count <= toInteger childCount) $
-                lift (codecError "container child range out of bounds")
-            entries <- forM [fromIntegral start .. fromIntegral start + fromIntegral count - 1] \childIndex -> do
-                (key, childIndexValue) <- lift (checked (arrayElement children childIndex))
-                name <- case (object, key) of
-                    (True, Just k) -> case IntMap.lookup (fromIntegral k) keys of
-                        Just text -> pure text
-                        Nothing -> lift (codecError "missing object key")
-                    (False, Nothing) -> pure Text.empty
-                    _ -> lift (codecError "container key validity does not match its tag")
-                item <- visit values children keys childCount (IntSet.insert index ancestors) (fromIntegral childIndexValue)
-                pure (name, item)
-            if object
-                then do
-                    unless (Set.size (Set.fromList (map fst entries)) == length entries) $
-                        lift (codecError "duplicate object key")
-                    pure (variantObject entries)
-                else pure (FieldList (map snd entries))
+    structList =
+      LogicalTypeList
+        (LogicalTypeStruct (listArray (0, length keys - 1) [StructField key (LogicalTypeScalar LogicalTypeIdVariant) | key <- keys]))
 
--- | Read an array element after checking both bounds.
-arrayElement :: Array Int a -> Int -> Either String a
-arrayElement array index
-    | index < lower || index > upper = Left "value index out of bounds"
-    | otherwise = Right (array ! index)
+-- | Tell if the keys can be the field names of one STRUCT type. A name must
+-- not be empty and must not contain NUL. Two names must not be equal after ASCII
+-- case folding.
+validStructFields :: [Text] -> Bool
+validStructFields keys =
+  all (\key -> not (Text.null key || Text.any (== '\0') key)) keys
+    && Set.size (Set.fromList (map foldIdentifier keys)) == length keys
+
+-- | Rebuild a level from its copied children in their native order.
+assemble :: [VariantNode] -> [FieldValue] -> IO [FieldValue]
+assemble [] [] = pure []
+assemble [] _ = codecError "decoded child count exceeds its parent count"
+assemble (node : rest) children = do
+  let (count, build) = case node of
+        ScalarNode value -> (0, const value)
+        ListNode values -> (length values, FieldList)
+        ObjectNode entries -> (length entries, variantObject . zip (map fst entries))
+      (ownChildren, remaining) = splitAt count children
+  unless (length ownChildren == count) (codecError "decoded child count is smaller than its parent count")
+  -- Build the constructor of this node now. This reads no native value and
+  -- cannot fail.
+  value <- evaluate (build ownChildren)
+  (value :) <$> assemble rest remaining
+
+-- | Native types by type text, for casts and VARIANT lists. The map is small
+-- and bounded. It holds the types of the fixed scalar tags and their list forms,
+-- "VARIANT" and "VARIANT[]", and one DECIMAL type and its list form for each
+-- width and scale. It never holds a STRUCT type.
+type CastTypes = IORef (Map.Map Text DuckDBV2LogicalTypeHandle)
+
+-- | Borrow the native cast result while copying its payload. The cast uses the
+-- factory of the instance. See Note [User casts and the casts of the library]
+-- in "Database.DuckDB.Simple.Materialize".
+withCast :: VariantState -> DuckDBV2ValueHandle -> Text -> (DuckDBV2ValueHandle -> IO a) -> IO a
+withCast state value target action = do
+  logical <- castType state target
+  bracket (output (c_duckdb_v2_value_cast (variantCasts state) value logical)) destroyValue action
+
+-- | Borrow a type from the cache. Parse the type text on its first use.
+castType :: VariantState -> Text -> IO DuckDBV2LogicalTypeHandle
+castType VariantState{variantConnection = connection, variantTypes = castTypes} target =
+  Map.lookup target <$> readIORef castTypes >>= \case
+    Just cached -> pure cached
+    Nothing -> mask_ do
+      created <- withText target (\text -> factoryOutput connection (\factory -> c_duckdb_v2_factory_create_type_from_text factory text))
+      modifyIORef' castTypes (Map.insert target created)
+      pure created
+
+-- | Borrow the prepared metadata statement. Prepare it on first use and keep
+-- it in the state. An execution does not consume it. See Note [VARIANT decoding].
+metadataStatement :: VariantState -> IO DuckDBV2PreparedStatementHandle
+metadataStatement VariantState{variantConnection = connection, variantStatement} =
+  readIORef variantStatement >>= \case
+    Just statement -> pure statement
+    Nothing -> mask_ $ parseKept connection sql \parsed ->
+      bracket (pure parsed) (destroy c_duckdb_v2_sql_statement_destroy) \statement -> do
+        prepared <- output (c_duckdb_v2_prepared_statement_create connection statement 0)
+        writeIORef variantStatement (Just prepared)
+        pure prepared
   where
-    (lower, upper) = bounds array
+    -- See Note [SQL text of the library] in "Database.DuckDB.Simple.Native".
+    sql =
+      "SELECT system.main.list_transform(?::VARIANT[], lambda value: system.main.struct_pack(tag := system.main.variant_typeof(value), keys := system.main.variant_keys(value))) AS metadata"
 
--- | Read an unsigned base-128 uint32 without overflow or truncation.
-readVarint :: ByteString -> Either String (Word32, ByteString)
-readVarint = go 0 0
+-- | Borrow the extraction statement for a key count. The state keeps the
+-- statement of the last key count. A call with another key count parses a new
+-- statement and destroys the old statement. The statement is valid until the
+-- next call of this function or 'destroyVariantState'. See
+-- Note [VARIANT decoding].
+extractionStatement :: VariantState -> Int -> IO DuckDBV2SqlStatementHandle
+extractionStatement VariantState{variantConnection = connection, variantExtraction} count =
+  readIORef variantExtraction >>= \case
+    Just (kept, statement) | kept == count -> pure statement
+    previous ->
+      -- Store the new statement before the old statement is destroyed. If the
+      -- parse fails, the slot keeps the old statement. If the destroy of the
+      -- old statement fails, the error propagates. Then the slot holds the new
+      -- statement. Nothing destroys the old statement again, as in
+      -- 'destroyVariantState'.
+      mask_ $ parseKept connection sql \statement -> do
+        writeIORef variantExtraction (Just (count, statement))
+        mapM_ (destroy c_duckdb_v2_sql_statement_destroy . snd) previous
+        pure statement
   where
-    go shift value input = case BS.uncons input of
-        Nothing -> Left "truncated varint"
-        Just (byte, rest)
-            | shift == 28 && byte > 15 -> Left "varint exceeds uint32"
-            | otherwise ->
-                let result = value .|. (fromIntegral (byte .&. 127) `shiftL` shift)
-                 in if byte .&. 128 == 0 then Right (result, rest) else go (shift + 7) result rest
+    -- See Note [SQL text of the library] in "Database.DuckDB.Simple.Native".
+    sql =
+      "SELECT system.main.list_transform($1::VARIANT[], lambda value: system.main.list_value(" <> Text.intercalate "," extracts <> ")) AS payload"
+    extracts = ["system.main.variant_extract(value,$" <> Text.pack (show index) <> "::VARCHAR)" | index <- [2 .. count + 1]]
 
--- | Read a bounded fixed-size payload in little-endian order.
-readUnsigned :: Int -> ByteString -> Either String (Integer, ByteString)
-readUnsigned count bytes
-    | BS.length bytes < count = Left "truncated scalar payload"
-    | otherwise =
-        let (part, rest) = BS.splitAt count bytes
-         in Right (BS.foldr (\byte value -> value `shiftL` 8 .|. toInteger byte) 0 part, rest)
+-- | Parse trusted SQL and give its first statement to the action before the
+-- iterator closes. The action must keep or destroy the statement, also when
+-- the iterator destroy fails. Call this function under 'mask_'.
+parseKept :: DuckDBV2ConnectionHandle -> Text -> (DuckDBV2SqlStatementHandle -> IO a) -> IO a
+parseKept connection sql keep =
+  TextForeign.withCString sql \source ->
+    bracket (output (c_duckdb_v2_parse_sql connection (ConstPtr source))) (destroy c_duckdb_v2_statement_iterator_destroy) \iterator -> do
+      statement <- output (c_duckdb_v2_statement_iterator_next iterator)
+      keep statement
 
--- | Read a two's-complement integer with a checked payload length.
-readSigned :: Int -> ByteString -> Either String Integer
-readSigned count bytes = do
-    (value, _) <- readUnsigned count bytes
-    pure (if value >= 2 ^ (count * 8 - 1) then value - 2 ^ (count * 8) else value)
+-- | Read exact scalar tags and object keys without serializing payloads.
+queryMetadata
+  :: (DuckDBV2FactoryHandle -> DuckDBV2VectorHandle -> IO FieldValue)
+  -> VariantState
+  -> [DuckDBV2ValueHandle]
+  -> IO [(Text, [Text])]
+queryMetadata plainVector state values = withVariantList state values \list -> do
+  statement <- metadataStatement state
+  with list \items ->
+    withResultVector
+      (output (c_duckdb_v2_prepared_statement_execute statement (ConstPtr nullPtr) (ConstPtr items) 1))
+      \vector ->
+        plainVector (variantCasts state) vector >>= maybe (codecError "metadata query returned an unexpected value") pure . metadataNodes
 
--- | Read a length-prefixed string or blob.
-readString :: ByteString -> Either String ByteString
-readString bytes = do
-    (count, rest) <- readVarint bytes
-    if toInteger count > toInteger (BS.length rest)
-        then Left "string length exceeds payload size"
-        else Right (BS.take (fromIntegral count) rest)
+-- | Read the tag and the object keys of each metadata node. A NULL key list
+-- gives no keys. Return 'Nothing' for an unexpected shape.
+metadataNodes :: FieldValue -> Maybe [(Text, [Text])]
+metadataNodes = \case
+  FieldList nodes -> traverse node nodes
+  _ -> Nothing
+  where
+    node = \case
+      FieldStruct struct -> case elems (structValueFields struct) of
+        [StructField "tag" (FieldText tag), StructField "keys" keys] -> (,) tag <$> keyList keys
+        _ -> Nothing
+      _ -> Nothing
+    keyList = \case
+      FieldNull -> Just []
+      FieldList keys -> traverse keyText keys
+      _ -> Nothing
+    keyText = \case
+      FieldText key -> Just key
+      _ -> Nothing
 
--- | Decode the scalar tags from VariantLogicalType in DuckDB 1.5.
-decodeScalar :: Word8 -> ByteString -> IO FieldValue
-decodeScalar tag bytes = case tag of
-    0 -> pure FieldNull
-    1 -> pure (FieldBool True)
-    2 -> pure (FieldBool False)
-    15 -> checked do
-        (precision, rest) <- readVarint bytes
-        (scale, digits) <- readVarint rest
-        when (precision < 1 || precision > 38 || scale > precision) (Left "invalid decimal metadata")
-        let count = if precision <= 4 then 2 else if precision <= 9 then 4 else if precision <= 18 then 8 else 16
-        value <- readSigned count digits
-        when (abs value >= 10 ^ precision) (Left "unscaled decimal exceeds its precision")
-        pure (FieldDecimal (DecimalValue (fromIntegral precision) (fromIntegral scale) value))
-    16 -> checked do
-        string <- readString bytes
-        FieldText <$> either (Left . show) Right (Text.decodeUtf8' string)
-    17 -> FieldBlob <$> checked (readString bytes)
-    31 -> FieldBigNum . BigNum <$> checked (readString bytes >>= decodeBigNum)
-    32 -> checked do
-        bitBytes <- readString bytes
-        case BS.unpack (BS.take 2 bitBytes) of
-            [padding, first] -> do
-                when (padding > 7) (Left "BIT padding exceeds seven")
-                let maskBits = paddingMask padding
-                unless (first .&. maskBits == maskBits) (Left "invalid native BIT padding")
-                pure (FieldBit (bitStringFromBytes bitBytes))
-            _ -> Left "BIT requires a padding byte and nonempty data"
-    33 -> FieldGeometry . (`RawGeometry` Nothing) <$> checked (readString bytes)
-    _ -> case fixedWidthTag tag of
-        Just (dtype, size) -> decodeFixedWidth dtype size bytes
-        Nothing -> codecError "unknown scalar tag"
+-- | Borrow an owned VARIANT list that copies all supplied values.
+withVariantList :: VariantState -> [DuckDBV2ValueHandle] -> (DuckDBV2ValueHandle -> IO a) -> IO a
+withVariantList state values action = do
+  logical <- castType state "VARIANT"
+  withConnectionFactory (variantConnection state) \factory ->
+    withArray values \items ->
+      bracket (output (c_duckdb_v2_value_create_list factory logical (ConstPtr items) (fromIntegral (length values)))) destroyValue action
 
-{- | The type and the payload size of each fixed-width scalar tag. These
-payloads have the memory layout of one vector element of the type.
--}
-fixedWidthTag :: Word8 -> Maybe (DuckDBType, Int)
-fixedWidthTag = \case
-    3 -> Just (DuckDBTypeTinyInt, 1)
-    4 -> Just (DuckDBTypeSmallInt, 2)
-    5 -> Just (DuckDBTypeInteger, 4)
-    6 -> Just (DuckDBTypeBigInt, 8)
-    7 -> Just (DuckDBTypeHugeInt, 16)
-    8 -> Just (DuckDBTypeUTinyInt, 1)
-    9 -> Just (DuckDBTypeUSmallInt, 2)
-    10 -> Just (DuckDBTypeUInteger, 4)
-    11 -> Just (DuckDBTypeUBigInt, 8)
-    12 -> Just (DuckDBTypeUHugeInt, 16)
-    13 -> Just (DuckDBTypeFloat, 4)
-    14 -> Just (DuckDBTypeDouble, 8)
-    18 -> Just (DuckDBTypeUUID, 16)
-    19 -> Just (DuckDBTypeDate, 4)
-    20 -> Just (DuckDBTypeTime, 8)
-    21 -> Just (DuckDBTypeTimeNs, 8)
-    22 -> Just (DuckDBTypeTimestampS, 8)
-    23 -> Just (DuckDBTypeTimestampMs, 8)
-    24 -> Just (DuckDBTypeTimestamp, 8)
-    25 -> Just (DuckDBTypeTimestampNs, 8)
-    26 -> Just (DuckDBTypeTimeTz, 8)
-    27 -> Just (DuckDBTypeTimestampTz, 8)
-    28 -> Just (DuckDBTypeInterval, 16)
-    _ -> Nothing
+-- | Borrow the first result value while its statement result stays alive.
+withStatementValue
+  :: DuckDBV2ConnectionHandle -> DuckDBV2SqlStatementHandle -> [DuckDBV2ValueHandle] -> (DuckDBV2ValueHandle -> IO a) -> IO a
+withStatementValue connection statement parameters action =
+  withArray parameters \items ->
+    withResultVector
+      (output (c_duckdb_v2_statement_execute connection statement (ConstPtr nullPtr) (ConstPtr items) (fromIntegral (length parameters))))
+      \vector -> bracket (output (c_duckdb_v2_vector_get_value vector 0)) destroyValue action
 
--- | Copy a fixed-width payload to aligned memory and decode it as one element.
-decodeFixedWidth :: DuckDBType -> Int -> ByteString -> IO FieldValue
-decodeFixedWidth dtype size bytes = do
-    when (BS.length bytes < size) (codecError "truncated scalar payload")
-    allocaBytesAligned size 16 \buffer -> do
-        BS.useAsCStringLen bytes \(source, _) -> copyBytes buffer (castPtr source) size
-        decodeElement dtype (castPtr buffer) 0
+-- | Borrow the first result vector while its result and chunk stay alive.
+-- Complete native reads before the action returns.
+withResultVector :: IO DuckDBV2ResultHandle -> (DuckDBV2VectorHandle -> IO a) -> IO a
+withResultVector execute action =
+  bracket execute (destroy c_duckdb_v2_result_destroy) \result ->
+    bracket (output (c_duckdb_v2_result_fetch_chunk result)) (destroy c_duckdb_v2_data_chunk_destroy) \chunk -> do
+      unless (chunk /= nullHandle) (codecError "helper query returned no rows")
+      vector <- output (c_duckdb_v2_data_chunk_get_vector chunk 0)
+      action vector
 
--- | Get the high-bit mask used for native BIT padding.
-paddingMask :: Word8 -> Word8
-paddingMask padding = complement ((1 `shiftL` (8 - fromIntegral padding)) - 1)
+-- | Map every native VARIANT scalar tag to its exact cast target. The tags are
+-- the text of variant_typeof. The result is type text, because a DECIMAL tag
+-- holds its width and scale. 'castType' parses each text once for each state.
+-- See Note [VARIANT decoding].
+scalarType :: Text -> IO Text
+scalarType tag = case tag of
+  "BOOL_TRUE" -> pure "BOOLEAN"
+  "BOOL_FALSE" -> pure "BOOLEAN"
+  "INT8" -> pure "TINYINT"
+  "INT16" -> pure "SMALLINT"
+  "INT32" -> pure "INTEGER"
+  "INT64" -> pure "BIGINT"
+  "INT128" -> pure "HUGEINT"
+  "UINT8" -> pure "UTINYINT"
+  "UINT16" -> pure "USMALLINT"
+  "UINT32" -> pure "UINTEGER"
+  "UINT64" -> pure "UBIGINT"
+  "UINT128" -> pure "UHUGEINT"
+  "TIME_MICROS" -> pure "TIME"
+  "TIME_NANOS" -> pure "TIME_NS"
+  "TIME_MICROS_TZ" -> pure "TIMETZ"
+  "TIMESTAMP_SEC" -> pure "TIMESTAMP_S"
+  "TIMESTAMP_MILIS" -> pure "TIMESTAMP_MS"
+  "TIMESTAMP_MICROS" -> pure "TIMESTAMP"
+  "TIMESTAMP_NANOS" -> pure "TIMESTAMP_NS"
+  "TIMESTAMP_MICROS_TZ" -> pure "TIMESTAMPTZ"
+  "TIMESTAMP_NANOS_TZ" -> pure "TIMESTAMPTZ_NS"
+  "BITSTRING" -> pure "BIT"
+  _
+    | tag `elem` ["FLOAT", "DOUBLE", "VARCHAR", "BLOB", "UUID", "DATE", "INTERVAL", "BIGNUM", "GEOMETRY"] -> pure tag
+    | "DECIMAL(" `Text.isPrefixOf` tag && ")" `Text.isSuffixOf` tag -> pure tag
+    | otherwise -> codecError ("unsupported scalar tag " <> tag)
 
--- | Check BIGNUM's sign, three-byte length header, and magnitude, then decode it.
-decodeBigNum :: ByteString -> Either String Integer
-decodeBigNum bytes = do
-    when (BS.length bytes < 4) (Left "truncated BIGNUM header or magnitude")
-    let (header, raw) = BS.splitAt 3 bytes
-        encoded = BS.foldl' (\n byte -> n `shiftL` 8 .|. fromIntegral byte) (0 :: Word32) header
-        negative = encoded .&. 0x800000 == 0
-        decoded = if negative then complement encoded .&. 0xffffff else encoded
-        count = decoded .&. 0x7fffff
-        magnitude = if negative then BS.map complement raw else raw
-    unless (toInteger count == toInteger (BS.length magnitude)) (Left "BIGNUM header length mismatch")
-    case BS.uncons magnitude of
-        Just (0, rest) | not (BS.null rest) || negative -> Left "noncanonical BIGNUM magnitude"
-        _ -> Right ()
-    pure (fromBigNumBytes (BS.unpack bytes))
+-- | List a node's owned children in their native order.
+nodeChildren :: VariantNode -> [DuckDBV2ValueHandle]
+nodeChildren (ScalarNode _) = []
+nodeChildren (ListNode values) = values
+nodeChildren (ObjectNode entries) = map snd entries
+
+-- | Release the children owned by a decoded node.
+releaseNode :: VariantNode -> IO ()
+releaseNode = releaseItems destroyValue . nodeChildren
+
+-- | Report a metadata or payload mismatch before decoding a native value.
+codecError :: Text -> IO a
+codecError message = throwInternalError ("VARIANT: " <> message)
diff --git a/test-codec/Main.hs b/test-codec/Main.hs
deleted file mode 100644
--- a/test-codec/Main.hs
+++ /dev/null
@@ -1,88 +0,0 @@
-{-# LANGUAGE OverloadedStrings #-}
-{-# LANGUAGE ScopedTypeVariables #-}
-
--- | Check the private codec's validation without constructing invalid native vectors.
-module Main (main) where
-
-import Control.Exception (IOException, try)
-import Control.Monad (forM_)
-import Data.Bits (shiftR, (.&.), (.|.))
-import qualified Data.ByteString as BS
-import Data.Text (Text)
-import Data.Word (Word32, Word8)
-import Database.DuckDB.Simple.FromField (FieldValue (..))
-import Database.DuckDB.Simple.Variant (variantObject)
-import Database.DuckDB.Simple.VariantCodec (decodeVariantPayload)
-import Test.Tasty (TestTree, defaultMain, testGroup)
-import Test.Tasty.HUnit
-
--- | Run malformed payload checks and boundary cases for the native format.
-main :: IO ()
-main =
-    defaultMain $
-        testGroup
-            "VARIANT payload validation"
-            [ rejected "missing root" [] [] [] []
-            , rejected "unknown tag" [(34, 0)] [] [] []
-            , rejected "offset outside blob" [(1, 1)] [] [] []
-            , rejected "truncated BIGINT" [(6, 0)] [] [] (replicate 7 0)
-            , rejected "truncated varint" [(16, 0)] [] [] [128]
-            , rejected "varint overflows uint32" [(16, 0)] [] [] [255, 255, 255, 255, 16]
-            , rejected "unterminated varint" [(16, 0)] [] [] [255, 255, 255, 255, 255, 0]
-            , rejected "string outside blob" [(16, 0)] [] [] [3, 97, 98]
-            , rejected "invalid UTF-8" [(16, 0)] [] [] [1, 255]
-            , rejected "decimal scale exceeds precision" [(15, 0)] [] [] [2, 3, 1, 0]
-            , rejected "decimal value exceeds precision" [(15, 0)] [] [] [1, 0, 100, 0]
-            , rejected "BIGNUM header is truncated" [(31, 0)] [] [] [2, 128, 0]
-            , rejected "BIGNUM length mismatch" [(31, 0)] [] [] [4, 128, 0, 2, 1]
-            , rejected "BIT padding exceeds seven" [(32, 0)] [] [] [2, 8, 255]
-            , rejected "BIT padding bits are absent" [(32, 0)] [] [] [2, 3, 21]
-            , rejected "child value out of range" [(30, 0)] [(Nothing, 1)] [] [1, 0]
-            , rejected "container range out of bounds" [(30, 0)] [] [] [1, 0]
-            , rejected "object key is missing" [(29, 0), (1, 2)] [(Just 0, 1)] [] [1, 0]
-            , rejected "array child has a key" [(30, 0), (1, 2)] [(Just 0, 1)] [(0, "x")] [1, 0]
-            , rejected "object child has no key" [(29, 0), (1, 2)] [(Nothing, 1)] [] [1, 0]
-            , rejected "duplicate dictionary index" [(1, 0)] [] [(0, "x"), (0, "y")] []
-            , rejected "duplicate object key" [(29, 0), (1, 2)] [(Just 0, 1), (Just 1, 1)] [(0, "x"), (1, "x")] [2, 0]
-            , rejected "cyclic child reference" [(30, 0)] [(Nothing, 0)] [] [1, 0]
-            , testCase "empty values need no payload bytes" $
-                decodeVariantPayload [(30, 0)] [] [] (BS.singleton 0) >>= (@?= FieldList [])
-            , testCase "shared children decode without duplicate traversal" $
-                decodeVariantPayload [(30, 0), (3, 2)] [(Nothing, 1), (Nothing, 1)] [] (BS.pack [2, 0, 7])
-                    >>= (@?= FieldList [FieldInt8 7, FieldInt8 7])
-            , testCase "length-aware keys preserve embedded NUL" $
-                decodeVariantPayload [(29, 0), (1, 2)] [(Just 0, 1)] [(0, "a\0b")] (BS.pack [1, 0])
-                    >>= (@?= variantObject [("a\0b", FieldBool True)])
-            , testCase "deep acyclic containers are accepted" $
-                forM_ [128, 129, 257, 1025] $ \count ->
-                    let (values, children, bytes) = nested count
-                     in decodeVariantPayload values children [] bytes >>= (@?= foldr (const (FieldList . pure)) (FieldInt8 7) [1 .. count - 1])
-            ]
-
--- | Require a validation error for copied native payload data.
-rejected :: String -> [(Word8, Word32)] -> [(Maybe Word32, Word32)] -> [(Word32, Text)] -> [Word8] -> TestTree
-rejected label values children keys bytes =
-    testCase label $ assertRejected (decodeVariantPayload values children keys (BS.pack bytes))
-
--- | Require a codec error.
-assertRejected :: IO FieldValue -> Assertion
-assertRejected action = do
-    result <- try action
-    case result of
-        Left (_ :: IOException) -> pure ()
-        Right value -> assertFailure ("expected payload rejection, got " <> show value)
-
--- | Construct a chain of arrays with one scalar leaf.
-nested :: Int -> ([(Word8, Word32)], [(Maybe Word32, Word32)], BS.ByteString)
-nested count =
-    ( zip (replicate (count - 1) 30 <> [3]) offsets
-    , [(Nothing, fromIntegral (n + 1)) | n <- [0 .. count - 2]]
-    , BS.pack (concat payloads)
-    )
-  where
-    payloads = [1 : varint (fromIntegral n) | n <- [0 .. count - 2]] <> [[7]]
-    offsets = scanl (+) 0 (map (fromIntegral . length) payloads)
-    varint :: Word32 -> [Word8]
-    varint value
-        | value < 128 = [fromIntegral value]
-        | otherwise = fromIntegral (value .&. 127 .|. 128) : varint (value `shiftR` 7)
diff --git a/test-quack/Main.hs b/test-quack/Main.hs
new file mode 100644
--- /dev/null
+++ b/test-quack/Main.hs
@@ -0,0 +1,98 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+-- |
+-- Module      : Main
+-- Description : Check authenticated Quack connections with local extension artifacts.
+module Main (main) where
+
+import Control.Exception (finally, try)
+import Control.Monad (unless, void)
+import Data.Int (Int64)
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Data.Time (UTCTime)
+import Data.Time.Clock.POSIX (posixSecondsToUTCTime)
+import Database.DuckDB.Simple
+import qualified Database.DuckDB.Simple.Streaming as Streaming
+import System.Directory (canonicalizePath, doesFileExist)
+import System.Environment (lookupEnv)
+import Test.Tasty (defaultMain)
+import Test.Tasty.HUnit
+
+-- | Require the matching artifacts before starting the integration test.
+main :: IO ()
+main = do
+  httpfs <- extensionPath "DUCKDB_HTTPFS_EXTENSION"
+  quack <- extensionPath "DUCKDB_QUACK_EXTENSION"
+  defaultMain $
+    testCase "authenticated Quack CONNECT, ATTACH, parameters and streaming" $
+      withQuackConnection [httpfs, quack] \server -> do
+        void $ execute_ server "CREATE TABLE items(id BIGINT, label VARCHAR)"
+        void $ executeMany server "INSERT INTO items VALUES (?, ?)" [(1 :: Int64, "one" :: Text), (2, "two")]
+        void $ execute_ server "CREATE TABLE large AS SELECT i FROM range(5000) t(i)"
+        void $ execute_ server "CREATE TABLE instants(value TIMESTAMPTZ_NS)"
+        let precise = posixSecondsToUTCTime 0.123456789
+        void $ execute server "INSERT INTO instants VALUES (?)" (Only precise)
+        [(uri, _, _)] <-
+          query_ server "CALL quack_serve('quack:localhost:0', token='duckdb-haskell-loopback', disable_ssl=true)" :: IO [(Text, Text, Text)]
+        finally
+          ( do
+              withQuackConnection [httpfs, quack] \client -> do
+                void $ execute_ client (remoteConnection "CONNECT" uri "duckdb-haskell-loopback")
+                (query_ client "SELECT id, label FROM items ORDER BY id" :: IO [(Int64, Text)])
+                  >>= (@?= [(1, "one"), (2, "two")])
+                void $ execute_ client "DISCONNECT"
+                void $ execute_ client (remoteConnection "ATTACH" uri "duckdb-haskell-loopback")
+                void $ execute_ client "SET disabled_optimizers='remote_pushdown'"
+                (query client "SELECT id, label FROM remote.items WHERE id >= ? ORDER BY id" (Only (2 :: Int64)) :: IO [(Int64, Text)])
+                  >>= (@?= [(2, "two")])
+                (queryNamed client "SELECT label FROM remote.items WHERE id=$id" ["id" := (1 :: Int64)] :: IO [Only Text])
+                  >>= (@?= [Only "one"])
+                void $ execute client "INSERT INTO remote.items VALUES (?, ?)" (3 :: Int64, "bound 'λ'" :: Text)
+                (query_ server "SELECT label FROM items WHERE id=3" :: IO [Only Text])
+                  >>= (@?= [Only "bound 'λ'"])
+                streamed <- Streaming.fold client "SELECT i FROM remote.large WHERE i < ?" (Only (5000 :: Int64)) (0 :: Int, 0 :: Int64) \(count, total) (Only value) ->
+                  pure (count + 1, total + value)
+                streamed @?= (5000, 12497500)
+                (query_ client "SELECT value FROM remote.instants" :: IO [Only UTCTime])
+                  >>= (@?= [Only precise])
+              withQuackConnection [httpfs, quack] \rejected -> do
+                result <- try (execute_ rejected (remoteConnection "CONNECT" uri "wrong-token"))
+                case result of
+                  Left SQLError{sqlErrorMessage} ->
+                    assertBool "wrong credentials must fail authentication" ("Authentication failed" `Text.isInfixOf` sqlErrorMessage)
+                  Right _ -> assertFailure "expected Quack to reject the wrong token"
+                (query_ server "SELECT count(*) FROM items" :: IO [Only Int64]) >>= (@?= [Only 3])
+          )
+          (void (query server "CALL quack_stop(?)" (Only uri) :: IO [Only Text]))
+
+-- | Fail when an extension path is absent or does not name a local file.
+extensionPath :: String -> IO FilePath
+extensionPath name = do
+  configured <- lookupEnv name
+  path <- case configured of
+    Just value | not (null value) -> pure value
+    _ -> fail (name <> " must name a local DuckDB extension artifact")
+  exists <- doesFileExist path
+  unless exists $ fail (name <> " does not name an existing file: " <> path)
+  canonicalizePath path
+
+-- | Load the local extensions with the configuration required by this fixture.
+withQuackConnection :: [FilePath] -> (Connection -> IO a) -> IO a
+withQuackConnection extensions action =
+  withConnectionWithConfig ":memory:" [("allow_unsigned_extensions", "true"), ("threads", "2")] \connection -> do
+    mapM_ (\path -> void (execute_ connection (Query ("LOAD " <> sqlLiteral (Text.pack path))))) extensions
+    action connection
+
+-- | Build CONNECT or ATTACH SQL with quoted URI and token literals.
+remoteConnection :: Text -> Text -> Text -> Query
+remoteConnection command uri token =
+  Query (command <> " " <> sqlLiteral uri <> alias <> " (TOKEN " <> sqlLiteral token <> ")")
+  where
+    alias = if command == "ATTACH" then " AS remote" else ""
+
+-- | Quote a SQL string literal, including apostrophes in local paths.
+sqlLiteral :: Text -> Text
+sqlLiteral value = "'" <> Text.replace "'" "''" value <> "'"
diff --git a/test/ArrowTests.hs b/test/ArrowTests.hs
--- a/test/ArrowTests.hs
+++ b/test/ArrowTests.hs
@@ -1,183 +1,282 @@
 {-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE DuplicateRecordFields #-}
+{-# LANGUAGE LambdaCase #-}
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE ScopedTypeVariables #-}
-{-# OPTIONS_GHC -Wno-deprecations #-}
+{-# LANGUAGE TypeApplications #-}
 
--- | Integration tests for scoped Arrow batches and their native ownership.
+-- |
+-- Module      : ArrowTests
+-- Description : Integration tests for scoped Arrow batches and their native ownership.
 module ArrowTests (arrowTests) where
 
 import Control.Concurrent (forkIO, killThread, newEmptyMVar, putMVar, takeMVar)
 import Control.Exception (AsyncException (ThreadKilled), IOException, SomeException, bracket, bracket_, fromException, mask_, throwIO, try)
-import Control.Monad (forM, forM_, when)
+import Control.Monad (forM, forM_, void, when)
 import Data.Bits (testBit)
+import Data.Coerce (coerce)
 import Data.IORef (IORef, modifyIORef', newIORef, readIORef)
 import Data.Int (Int64)
+import Data.List (sort)
+import Data.Proxy (Proxy (..))
 import qualified Data.Text as Text
+import Data.Void (Void)
 import Data.Word (Word8)
-import Database.DuckDB.FFI
+import Database.DuckDB.FFI.V2
 import Database.DuckDB.Simple
+import Database.DuckDB.Simple.Arrow (releaseArrowArray, releaseArrowSchema)
 import qualified Database.DuckDB.Simple.Arrow as Arrow
-import qualified Database.DuckDB.Simple.Deprecated.Streaming as Streaming
+import Database.DuckDB.Simple.FromField (DecimalValue (..))
 import Database.DuckDB.Simple.Internal (peekUtf8CString)
+import qualified Database.DuckDB.Simple.Streaming as Streaming
+import Foreign.C.ConstPtr (ConstPtr (..))
 import Foreign.C.String (peekCString)
 import Foreign.Marshal.Alloc (alloca)
 import Foreign.Marshal.Utils (fillBytes)
-import Foreign.Ptr (Ptr, castPtr, freeHaskellFunPtr, nullFunPtr, nullPtr)
-import Foreign.Storable (peek, peekElemOff, poke, sizeOf)
+import Foreign.Ptr (Ptr, freeHaskellFunPtr, nullFunPtr, nullPtr)
+import Foreign.Storable (peek, peekElemOff, poke)
+import GHC.Records (getField)
+import HsBindgen.Runtime.HasCField (fromPtr)
+import HsBindgen.Runtime.Marshal (staticSizeOf)
+import HsBindgen.Runtime.Support.FunPtr (fromFunPtr, toFunPtr)
 import Test.Tasty (TestTree, testGroup)
 import Test.Tasty.HUnit
+import TestUtils (filteredQueries)
 
 -- | Exercise native results and count their Arrow release callbacks.
 arrowTests :: TestTree
 arrowTests =
-    testGroup "Arrow batches" [arrowModeTests False, arrowModeTests True]
+  testGroup "Arrow batches" [arrowModeTests False, arrowModeTests True]
 
 -- | Run the same ownership checks for both public Arrow interfaces.
 arrowModeTests :: Bool -> TestTree
 arrowModeTests streaming =
-    testGroup
-        (if streaming then "deprecated streaming" else "materialized")
-        [ testCase "parameters, Unicode names, NULLs and multiple batches" $
-            withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
-                (batches, chunks) <-
-                    foldArrow conn "SELECT CASE WHEN i % 3 = 0 THEN NULL ELSE i END AS \"íslenska_λ\" FROM range(?::BIGINT) t(i)" (Only (5000 :: Int64)) (0 :: Int, []) \(count, acc) schemaPtr arrayPtr -> do
-                        schema <- peek schemaPtr
-                        arrowSchemaChildCount schema @?= 1
-                        child <- peekElemOff (arrowSchemaChildren schema) 0 >>= peek
-                        peekUtf8CString (arrowSchemaName child) >>= (@?= "íslenska_λ")
-                        peekCString (arrowSchemaFormat child) >>= (@?= "l")
-                        values <- readInt64Batch arrayPtr
-                        pure (count + 1, values : acc)
-                assertBool "more than one native batch" (batches > 1)
-                concat (reverse chunks) @?= [if i `rem` 3 == 0 then Nothing else Just i | i <- [0 .. 4999]]
-        , testCase "empty results retain the initial accumulator" $
-            withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
-                result <- foldArrow_ conn "SELECT 1::BIGINT WHERE false" (17 :: Int) \_ _ _ -> assertFailure "unexpected batch" >> pure 0
-                result @?= 17
-        , testCase "result metadata follows bound parameter types" $
-            withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
-                values <- foldArrow conn "SELECT ? AS value" (Only (5000000000 :: Int64)) [] \acc _ array -> do
-                    batch <- readInt64Batch array
-                    pure (acc <> batch)
-                values @?= [Just 5000000000]
-        , testCase "success releases the schema and every batch" $
-            withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
-                withReleaseCounters \schemaReleases arrayReleases observe -> do
-                    batches <- foldArrow_ conn "SELECT i FROM range(5000) t(i)" (0 :: Int) \count schema array -> do
-                        observe schema array
-                        pure (count + 1)
-                    readIORef schemaReleases >>= (@?= batches)
-                    readIORef arrayReleases >>= (@?= batches)
-                    assertConnectionUsable conn
-        , testCase "consumers can release each schema and batch" $
-            withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
-                withReleaseCounters \schemaReleases arrayReleases observe -> do
-                    batches <- foldArrow_ conn "SELECT i FROM range(5000) t(i)" (0 :: Int) \count schema array -> do
-                        observe schema array
-                        releaseArrowArray array
-                        releaseArrowSchema schema
-                        pure (count + 1)
-                    assertBool "more than one native batch" (batches > 1)
-                    readIORef schemaReleases >>= (@?= batches)
-                    readIORef arrayReleases >>= (@?= batches)
-                    assertConnectionUsable conn
-        , testCase "moved objects survive query and connection close" $
-            withReleaseCounters \schemaReleases arrayReleases observe -> do
-                alloca \savedSchema -> alloca \savedArray ->
-                    bracket_
-                        ( do
-                            fillBytes savedSchema 0 (sizeOf (undefined :: ArrowSchema))
-                            fillBytes savedArray 0 (sizeOf (undefined :: ArrowArray))
-                        )
-                        (releaseArrowArray savedArray >> releaseArrowSchema savedSchema)
-                        do
-                            withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
-                                foldArrow_ conn "SELECT 42::BIGINT AS id" () \() schemaPtr arrayPtr -> mask_ do
-                                    observe schemaPtr arrayPtr
-                                    schema <- peek schemaPtr
-                                    array <- peek arrayPtr
-                                    poke savedSchema schema
-                                    poke schemaPtr schema{arrowSchemaRelease = nullFunPtr}
-                                    poke savedArray array
-                                    poke arrayPtr array{arrowArrayRelease = nullFunPtr}
-                            readIORef schemaReleases >>= (@?= 0)
-                            readIORef arrayReleases >>= (@?= 0)
-                            schema <- peek savedSchema
-                            child <- peekElemOff (arrowSchemaChildren schema) 0 >>= peek
-                            peekCString (arrowSchemaName child) >>= (@?= "id")
-                            readInt64Batch savedArray >>= (@?= [Just 42])
-                readIORef schemaReleases >>= (@?= 1)
-                readIORef arrayReleases >>= (@?= 1)
-        , testCase "exceptions during consumption release each object once" $
-            forM_ [False, True] \consumeSchema ->
+  testGroup
+    (if streaming then "native streaming" else "materialized")
+    [ testCase "parameters, Unicode names, NULLs and multiple batches" $
+        withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+          (batches, chunks) <-
+            foldArrow
+              conn
+              "SELECT CASE WHEN i % 3 = 0 THEN NULL ELSE i END AS \"íslenska_λ\" FROM range(?::BIGINT) t(i)"
+              (Only (5000 :: Int64))
+              (0 :: Int, [])
+              \(count, acc) schemaPtr arrayPtr -> do
+                schema <- peek schemaPtr
+                (getField @"n_children") schema @?= 1
+                child <- peekElemOff ((getField @"children") schema) 0 >>= peek
+                peekUtf8CString ((getField @"name") child) >>= (@?= "íslenska_λ")
+                (peekCString . coerce) ((getField @"format") child) >>= (@?= "l")
+                values <- readInt64Batch arrayPtr
+                pure (count + 1, values : acc)
+          assertBool "more than one native batch" (batches > 1)
+          concat (reverse chunks) @?= [if i `rem` 3 == 0 then Nothing else Just i | i <- [0 .. 4999]]
+    , testCase "the batch size option sets the rows of each batch" $ do
+        let run options count = withConnectionWithOptions ":memory:" options{connectionConfig = [("threads", "1")]} \conn ->
+              reverse <$> foldArrow conn "SELECT i::BIGINT AS i FROM range(?::BIGINT) t(i)" (Only (count :: Int64)) [] \acc _ arrayPtr -> do
+                values <- readInt64Batch arrayPtr
+                pure (values : acc)
+            -- Each array has at most the given number of rows. The arrays give
+            -- each row in order.
+            checkBatches size limit count = do
+              batches <- run defaultConnectionOptions{connectionArrowBatchSize = size} count
+              assertBool ("array lengths " <> show (map length batches)) (all ((<= limit) . length) batches)
+              concat batches @?= map Just [0 .. count - 1]
+        defaultRows <- run defaultConnectionOptions 5
+        singleRows <- run defaultConnectionOptions{connectionArrowBatchSize = 1} 5
+        concat defaultRows @?= map Just [0 .. 4]
+        concat singleRows @?= concat defaultRows
+        (length defaultRows, length singleRows) @?= (1, 5)
+        -- 131072 is the batch size of DuckDB.
+        checkBatches 131072 131072 300000
+        checkBatches 20000 20000 10000
+        checkBatches 3000 3000 10000
+        forM_ [-1, 0] \size ->
+          try (withConnectionWithOptions ":memory:" defaultConnectionOptions{connectionArrowBatchSize = size} (const (pure ()))) >>= \case
+            Left (err :: SQLError) -> do
+              sqlErrorType err @?= Just ErrorInputInvalid
+              assertBool ("unexpected message: " <> show err) ("connectionArrowBatchSize is not positive" `Text.isInfixOf` sqlErrorMessage err)
+            Right () -> assertFailure ("the batch size " <> show size <> " opened a connection")
+    , testCase "an error of the step keeps its own query, and a native error of the fold has the fold query" $
+        withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> withConnection ":memory:" \other -> do
+          let failingStep :: IO ()
+              failingStep = void (query other "SELECT ?" (Only (DecimalValue 2 1 100)) :: IO [Only Int64])
+              stepError :: String -> IO a -> IO ()
+              stepError label action =
+                try action >>= \case
+                  Left (err :: SQLError) -> do
+                    assertEqual label (Just ErrorTypeConversion) (sqlErrorType err)
+                    assertEqual label Nothing (sqlErrorQuery err)
+                  Right _ -> assertFailure (label <> ": expected the DECIMAL error")
+          stepError "Arrow.foldArrow" (Arrow.foldArrow conn "SELECT 1" () () \acc _ _ -> failingStep >> pure acc)
+          stepError "Streaming.foldArrow" (Streaming.foldArrow conn "SELECT 1" () () \acc _ _ -> failingStep >> pure acc)
+          stepError "fold" (fold conn "SELECT 1" () () \acc (Only (_ :: Int64)) -> failingStep >> pure acc)
+          stepError "Streaming.fold" (Streaming.fold conn "SELECT 1" () () \acc (Only (_ :: Int64)) -> failingStep >> pure acc)
+          forM_ [("Arrow.foldArrow", Arrow.foldArrow), ("Streaming.foldArrow", Streaming.foldArrow)] \(label, foldBatches) ->
+            try (foldBatches conn "SELECT error('boom')" () () \acc _ _ -> pure acc) >>= \case
+              Left (err :: SQLError) -> assertEqual label (Just "SELECT error('boom')") (sqlErrorQuery err)
+              Right () -> assertFailure (label <> ": expected the error of DuckDB")
+    , testCase "empty results retain the initial accumulator" $
+        withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+          result <- foldArrow_ conn "SELECT 1::BIGINT WHERE false" (17 :: Int) \_ _ _ -> assertFailure "unexpected batch" >> pure 0
+          result @?= 17
+    , testCase "result metadata follows bound parameter types" $
+        withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+          values <- foldArrow conn "SELECT ? AS value" (Only (5000000000 :: Int64)) [] \acc _ array -> do
+            batch <- readInt64Batch array
+            pure (acc <> batch)
+          values @?= [Just 5000000000]
+    , testCase "success releases the schema and every batch" $
+        withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
+          withReleaseCounters \schemaReleases arrayReleases observe -> do
+            batches <- foldArrow_ conn "SELECT i FROM range(5000) t(i)" (0 :: Int) \count schema array -> do
+              observe schema array
+              pure (count + 1)
+            readIORef schemaReleases >>= (@?= batches)
+            readIORef arrayReleases >>= (@?= batches)
+            assertConnectionUsable conn
+    , testCase "consumers can release each schema and batch" $
+        withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
+          withReleaseCounters \schemaReleases arrayReleases observe -> do
+            batches <- foldArrow_ conn "SELECT i FROM range(5000) t(i)" (0 :: Int) \count schema array -> do
+              observe schema array
+              releaseArrowArray array
+              releaseArrowSchema schema
+              pure (count + 1)
+            assertBool "more than one native batch" (batches > 1)
+            readIORef schemaReleases >>= (@?= batches)
+            readIORef arrayReleases >>= (@?= batches)
+            assertConnectionUsable conn
+    , testCase "moved objects survive query and connection close" $
+        withReleaseCounters \schemaReleases arrayReleases observe -> do
+          alloca \savedSchema -> alloca \savedArray ->
+            bracket_
+              ( do
+                  fillBytes savedSchema 0 (staticSizeOf (Proxy @ArrowSchema))
+                  fillBytes savedArray 0 (staticSizeOf (Proxy @ArrowArray))
+              )
+              (releaseArrowArray savedArray >> releaseArrowSchema savedSchema)
+              do
                 withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
-                    withReleaseCounters \schemaReleases arrayReleases observe -> do
-                        result <- try $ foldArrow_ conn "SELECT 42::BIGINT" () \() schema array -> do
-                            observe schema array
-                            releaseArrowArray array
-                            when consumeSchema (releaseArrowSchema schema)
-                            throwIO (userError "consumer failed after release")
-                        case result of
-                            Left (err :: IOException) -> assertBool "consumer exception" ("consumer failed" `Text.isInfixOf` Text.pack (show err))
-                            Right () -> assertFailure "expected consumer exception"
-                        readIORef schemaReleases >>= (@?= 1)
-                        readIORef arrayReleases >>= (@?= 1)
-                        assertConnectionUsable conn
-        , testCase "callback exceptions release the active batch and schema" $
-            withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
-                withReleaseCounters \schemaReleases arrayReleases observe -> do
-                    result <- try $ foldArrow_ conn "SELECT i FROM range(5000) t(i)" () \_ schema array -> do
-                        observe schema array
-                        throwIO (userError "Arrow callback failed")
-                    case result of
-                        Left (err :: IOException) -> assertBool "original error" ("Arrow callback failed" `Text.isInfixOf` Text.pack (show err))
-                        Right () -> assertFailure "expected callback exception"
-                    readIORef schemaReleases >>= (@?= 1)
-                    readIORef arrayReleases >>= (@?= 1)
-                    assertConnectionUsable conn
-        , testCase "cancellation releases the active batch and schema" $
-            withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
-                withReleaseCounters \schemaReleases arrayReleases observe -> do
-                    entered <- newEmptyMVar
-                    blocked <- newEmptyMVar
-                    finished <- newEmptyMVar
-                    worker <- forkIO do
-                        result <- try $ foldArrow_ conn "SELECT i FROM range(5000) t(i)" () \_ schema array -> do
-                            observe schema array
-                            putMVar entered ()
-                            takeMVar blocked
-                        putMVar finished (result :: Either SomeException ())
-                    takeMVar entered
-                    killThread worker
-                    result <- takeMVar finished
-                    case result of
-                        Left err -> fromException err @?= Just ThreadKilled
-                        Right () -> assertFailure "expected cancellation"
-                    readIORef schemaReleases >>= (@?= 1)
-                    readIORef arrayReleases >>= (@?= 1)
-                    assertConnectionUsable conn
-        , testCase "SQL errors leave the connection usable" $
-            withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
-                result <- try $ foldArrow_ conn "SELECT error('Arrow query failed')" () \_ _ _ -> assertFailure "unexpected batch"
-                case result of
-                    Left (err :: SQLError) -> assertBool "native error" ("Arrow query failed" `Text.isInfixOf` sqlErrorMessage err)
-                    Right () -> assertFailure "expected query error"
-                assertConnectionUsable conn
-        , testCase "closing the connection stops further batch callbacks" $
-            withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
-                withReleaseCounters \schemaReleases arrayReleases observe -> do
-                    callbacks <- newIORef (0 :: Int)
-                    result <- try $ foldArrow_ conn "SELECT i FROM range(5000) t(i)" () \_ schema array -> do
-                        observe schema array
-                        modifyIORef' callbacks (+ 1)
-                        close conn
-                    case result of
-                        Left (err :: SQLError) -> sqlErrorMessage err @?= "duckdb-simple: connection is closed"
-                        Right () -> assertFailure "expected closed connection error"
-                    readIORef callbacks >>= (@?= 1)
-                    readIORef schemaReleases >>= (@?= 1)
-                    readIORef arrayReleases >>= (@?= 1)
-        ]
+                  foldArrow_ conn "SELECT 42::BIGINT AS id" () \() schemaPtr arrayPtr -> mask_ do
+                    observe schemaPtr arrayPtr
+                    schema <- peek schemaPtr
+                    array <- peek arrayPtr
+                    poke savedSchema schema
+                    poke (fromPtr (Proxy @"release") (schemaPtr :: Ptr ArrowSchema)) (coerce (nullFunPtr @Void))
+                    poke savedArray array
+                    poke (fromPtr (Proxy @"release") (arrayPtr :: Ptr ArrowArray)) (coerce (nullFunPtr @Void))
+                readIORef schemaReleases >>= (@?= 0)
+                readIORef arrayReleases >>= (@?= 0)
+                schema <- peek savedSchema
+                child <- peekElemOff ((getField @"children") schema) 0 >>= peek
+                (peekCString . coerce) ((getField @"name") child) >>= (@?= "id")
+                readInt64Batch savedArray >>= (@?= [Just 42])
+          readIORef schemaReleases >>= (@?= 1)
+          readIORef arrayReleases >>= (@?= 1)
+    , testCase "exceptions during consumption release each object once" $
+        forM_ [False, True] \consumeSchema ->
+          withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
+            withReleaseCounters \schemaReleases arrayReleases observe -> do
+              result <- try $ foldArrow_ conn "SELECT 42::BIGINT" () \() schema array -> do
+                observe schema array
+                releaseArrowArray array
+                when consumeSchema (releaseArrowSchema schema)
+                throwIO (userError "consumer failed after release")
+              case result of
+                Left (err :: IOException) -> assertBool "consumer exception" ("consumer failed" `Text.isInfixOf` Text.pack (show err))
+                Right () -> assertFailure "expected consumer exception"
+              readIORef schemaReleases >>= (@?= 1)
+              readIORef arrayReleases >>= (@?= 1)
+              assertConnectionUsable conn
+    , testCase "callback exceptions release the active batch and schema" $
+        withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
+          withReleaseCounters \schemaReleases arrayReleases observe -> do
+            result <- try $ foldArrow_ conn "SELECT i FROM range(5000) t(i)" () \_ schema array -> do
+              observe schema array
+              throwIO (userError "Arrow callback failed")
+            case result of
+              Left (err :: IOException) -> assertBool "original error" ("Arrow callback failed" `Text.isInfixOf` Text.pack (show err))
+              Right () -> assertFailure "expected callback exception"
+            readIORef schemaReleases >>= (@?= 1)
+            readIORef arrayReleases >>= (@?= 1)
+            assertConnectionUsable conn
+    , testCase "cancellation releases the active batch and schema" $
+        withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
+          withReleaseCounters \schemaReleases arrayReleases observe -> do
+            entered <- newEmptyMVar
+            blocked <- newEmptyMVar
+            finished <- newEmptyMVar
+            worker <- forkIO do
+              result <- try $ foldArrow_ conn "SELECT i FROM range(5000) t(i)" () \_ schema array -> do
+                observe schema array
+                putMVar entered ()
+                takeMVar blocked
+              putMVar finished (result :: Either SomeException ())
+            takeMVar entered
+            killThread worker
+            result <- takeMVar finished
+            case result of
+              Left err -> fromException err @?= Just ThreadKilled
+              Right () -> assertFailure "expected cancellation"
+            readIORef schemaReleases >>= (@?= 1)
+            readIORef arrayReleases >>= (@?= 1)
+            assertConnectionUsable conn
+    , testCase "SQL errors leave the connection usable" $
+        withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+          result <- try $ foldArrow_ conn "SELECT error('Arrow query failed')" () \_ _ _ -> assertFailure "unexpected batch"
+          case result of
+            Left (err :: SQLError) -> assertBool "native error" ("Arrow query failed" `Text.isInfixOf` sqlErrorMessage err)
+            Right () -> assertFailure "expected query error"
+          assertConnectionUsable conn
+    , testCase "callback connection use follows the execution mode" $
+        withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+          count <- foldArrow_ conn "SELECT i FROM range(5000) t(i)" (0 :: Int) \acc _ _ -> do
+            if streaming
+              then do
+                outcome <- try (query_ conn "SELECT 42" :: IO [Only Int64])
+                case outcome of
+                  Left (err :: SQLError) -> sqlErrorType err @?= Just ErrorResourceInUse
+                  Right _ -> assertFailure "expected a busy streaming connection"
+              else query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+            pure (acc + 1)
+          assertBool "expected multiple callbacks" (count > 1)
+    , testCase "SQL errors report the query that failed" $
+        withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+          let outer = "SELECT error('Arrow query failed')"
+              inner = "SELECT error('callback query failed')"
+          failed <- try $ foldArrow_ conn outer () \_ _ _ -> assertFailure "unexpected batch"
+          case failed of
+            Left (err :: SQLError) -> sqlErrorQuery err @?= Just outer
+            Right () -> assertFailure "expected query error"
+          nested <- try $ foldArrow_ conn "SELECT 42" () \_ _ _ -> void (query_ conn inner :: IO [Only Int64])
+          case nested of
+            Left (err :: SQLError) -> sqlErrorQuery err @?= Just inner
+            Right () -> assertFailure "expected callback query error"
+          assertConnectionUsable conn
+    , testCase "closing the connection stops further batch callbacks" $
+        withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
+          withReleaseCounters \schemaReleases arrayReleases observe -> do
+            callbacks <- newIORef (0 :: Int)
+            result <- try $ foldArrow_ conn "SELECT i FROM range(5000) t(i)" () \_ schema array -> do
+              observe schema array
+              modifyIORef' callbacks (+ 1)
+              close conn
+            case result of
+              Left (err :: SQLError) -> sqlErrorMessage err @?= "duckdb-simple: connection is closed"
+              Right () -> assertFailure "expected closed connection error"
+            readIORef callbacks >>= (@?= 1)
+            readIORef schemaReleases >>= (@?= 1)
+            readIORef arrayReleases >>= (@?= 1)
+    , testCase "filtered results give each row in the batches" $
+        forM_ ["1", "4"] \threads -> withConnectionWithConfig ":memory:" [("threads", threads)] \conn ->
+          forM_ filteredQueries \(sql, expected) -> do
+            batches <- foldArrow_ conn sql [] \acc _ array -> (: acc) <$> readInt64Batch array
+            let rows = concat (reverse batches)
+            -- With more than one thread, DuckDB can give the rows in another order.
+            assertEqual (Text.unpack threads <> " threads: " <> show sql) (map Just expected) (if threads == "1" then rows else sort rows)
+    ]
   where
     foldArrow :: (ToRow q) => Connection -> Query -> q -> a -> (a -> Ptr ArrowSchema -> Ptr ArrowArray -> IO a) -> IO a
     foldArrow = if streaming then Streaming.foldArrow else Arrow.foldArrow
@@ -188,53 +287,53 @@
 -- | Copy a BIGINT Arrow column, including its validity bitmap.
 readInt64Batch :: Ptr ArrowArray -> IO [Maybe Int64]
 readInt64Batch arrayPtr = do
-    array <- peek arrayPtr
-    child <- peekElemOff (arrowArrayChildren array) 0 >>= peek
-    validity <- peekElemOff (arrowArrayBuffers child) 0
-    values <- peekElemOff (arrowArrayBuffers child) 1
-    forM [0 .. fromIntegral (arrowArrayLength array) - 1] \row -> do
-        let index = fromIntegral (arrowArrayOffset child) + row
-        valid <-
-            if validity == nullPtr
-                then pure True
-                else do
-                    byte <- peekElemOff (castPtr validity :: Ptr Word8) (index `div` 8)
-                    pure (testBit byte (index `rem` 8))
-        if valid then Just <$> peekElemOff (castPtr values) index else pure Nothing
+  array <- peek arrayPtr
+  child <- peekElemOff ((getField @"children") array) 0 >>= peek
+  validity <- peekElemOff ((getField @"buffers") child) 0
+  values <- peekElemOff ((getField @"buffers") child) 1
+  forM [0 .. fromIntegral ((getField @"length") array) - 1] \row -> do
+    let index = fromIntegral ((getField @"offset") child) + row
+    valid <-
+      if validity == (coerce (nullPtr @Void))
+        then pure True
+        else do
+          byte <- peekElemOff (coerce validity :: Ptr Word8) (index `div` 8)
+          pure (testBit byte (index `rem` 8))
+    if valid then Just <$> peekElemOff (coerce values) index else pure Nothing
 
 -- | Wrap real release callbacks to observe cleanup without changing ownership.
 withReleaseCounters :: (IORef Int -> IORef Int -> (Ptr ArrowSchema -> Ptr ArrowArray -> IO ()) -> IO a) -> IO a
 withReleaseCounters action = do
-    schemaReleases <- newIORef 0
-    arrayReleases <- newIORef 0
-    originalSchema <- newIORef Nothing
-    originalArray <- newIORef Nothing
-    bracket
-        ( wrapArrowSchemaRelease \ptr -> do
-            modifyIORef' schemaReleases (+ 1)
-            callback <- readIORef originalSchema
-            maybe (assertFailure "missing schema release") (\release -> mkArrowSchemaRelease release ptr) callback
+  schemaReleases <- newIORef 0
+  arrayReleases <- newIORef 0
+  originalSchema <- newIORef Nothing
+  originalArray <- newIORef Nothing
+  bracket
+    ( toFunPtr \ptr -> do
+        modifyIORef' schemaReleases (+ 1)
+        callback <- readIORef originalSchema
+        maybe (assertFailure "missing schema release") (\release -> fromFunPtr release ptr) callback
+    )
+    (freeHaskellFunPtr . coerce)
+    \schemaCallback ->
+      bracket
+        ( toFunPtr \ptr -> do
+            modifyIORef' arrayReleases (+ 1)
+            callback <- readIORef originalArray
+            maybe (assertFailure "missing array release") (\release -> fromFunPtr release ptr) callback
         )
-        freeHaskellFunPtr
-        \schemaCallback ->
-            bracket
-                ( wrapArrowArrayRelease \ptr -> do
-                    modifyIORef' arrayReleases (+ 1)
-                    callback <- readIORef originalArray
-                    maybe (assertFailure "missing array release") (\release -> mkArrowArrayRelease release ptr) callback
-                )
-                freeHaskellFunPtr
-                \arrayCallback -> do
-                    let observe schemaPtr arrayPtr = do
-                            schema <- peek schemaPtr
-                            assertBool "schema must not have been released" (arrowSchemaRelease schema /= nullFunPtr)
-                            when (arrowSchemaRelease schema /= schemaCallback) do
-                                modifyIORef' originalSchema (const (Just (arrowSchemaRelease schema)))
-                                poke schemaPtr schema{arrowSchemaRelease = schemaCallback}
-                            array <- peek arrayPtr
-                            modifyIORef' originalArray (const (Just (arrowArrayRelease array)))
-                            poke arrayPtr array{arrowArrayRelease = arrayCallback}
-                    action schemaReleases arrayReleases observe
+        (freeHaskellFunPtr . coerce)
+        \arrayCallback -> do
+          let observe schemaPtr arrayPtr = do
+                schema <- peek schemaPtr
+                assertBool "schema must not have been released" ((getField @"release") schema /= (coerce (nullFunPtr @Void)))
+                when ((getField @"release") schema /= schemaCallback) do
+                  modifyIORef' originalSchema (const (Just ((getField @"release") schema)))
+                  poke (fromPtr (Proxy @"release") (schemaPtr :: Ptr ArrowSchema)) schemaCallback
+                array <- peek arrayPtr
+                modifyIORef' originalArray (const (Just ((getField @"release") array)))
+                poke (fromPtr (Proxy @"release") (arrayPtr :: Ptr ArrowArray)) arrayCallback
+          action schemaReleases arrayReleases observe
 
 -- | Check that no failed Arrow operation leaves the connection busy.
 assertConnectionUsable :: Connection -> Assertion
diff --git a/test/CancellationTests.hs b/test/CancellationTests.hs
--- a/test/CancellationTests.hs
+++ b/test/CancellationTests.hs
@@ -2,166 +2,436 @@
 {-# LANGUAGE LambdaCase #-}
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE ScopedTypeVariables #-}
-{-# OPTIONS_GHC -Wno-deprecations #-}
 
--- | Cancellation during native execution must finish before handles are released.
-module CancellationTests (cancellationTests) where
+-- |
+-- Module      : CancellationTests
+-- Description : Cancellation during native execution must finish before handles are released, and a callback must not wait without a bound for its own connection.
+module CancellationTests (cancellationTests, callbackLockTests) where
 
-import Control.Concurrent (MVar, ThreadId, forkIOWithUnmask, newEmptyMVar, putMVar, readMVar, rtsSupportsBoundThreads, threadDelay, throwTo, tryPutMVar, tryReadMVar)
-import Control.Exception (AsyncException (..), SomeException, bracket, fromException, mask_, try)
-import Control.Monad (unless, void)
-import Data.IORef (atomicWriteIORef, newIORef, readIORef)
+import Control.Concurrent (
+  MVar,
+  ThreadId,
+  forkIOWithUnmask,
+  myThreadId,
+  newEmptyMVar,
+  putMVar,
+  readMVar,
+  rtsSupportsBoundThreads,
+  threadDelay,
+  throwTo,
+  tryPutMVar,
+  tryReadMVar,
+ )
+import Control.Exception (AsyncException (..), ErrorCall (..), SomeException, bracket, fromException, mask_, throwIO, try)
+import Control.Monad (unless, void, when)
+import Data.IORef (IORef, atomicModifyIORef', atomicWriteIORef, modifyIORef', newIORef, readIORef)
 import Data.Int (Int64)
-import Database.DuckDB.FFI (c_duckdb_interrupt, c_duckdb_query)
+import Data.Maybe (isNothing)
+import Data.Text (Text)
+import qualified Data.Text as Text
 import Database.DuckDB.Simple
 import Database.DuckDB.Simple.Arrow (foldArrow_)
-import qualified Database.DuckDB.Simple.Deprecated.Streaming as Streaming
-import Database.DuckDB.Simple.Internal (withConnectionHandle, withQueryCString, withResult)
+import Database.DuckDB.Simple.Internal (
+  c_duckdb_v2_connection_interrupt,
+  c_duckdb_v2_result_drain,
+  checked,
+  output,
+  runInterruptibleQuery,
+  withConnectionHandle,
+  withResult,
+  withResultWindow,
+ )
+import qualified Database.DuckDB.Simple.Streaming as Streaming
 import GHC.Conc (BlockReason (..), ThreadStatus (..), threadStatus)
 import System.Timeout (timeout)
 import Test.Tasty (TestTree, testGroup)
 import Test.Tasty.HUnit
+import TestUtils (assertReusable, raiseCapabilities)
 
 -- | Exercise each native execution entry point and two cancellation races.
 cancellationTests :: TestTree
 cancellationTests =
-    testGroup "native cancellation" $
-        [ testCase name $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
-            assertBool "cancellation requires the threaded runtime" rtsSupportsBoundThreads
-            entered <- newEmptyMVar
-            createFunction conn "query_started" (signal entered >> pure (1 :: Int64))
-            withCaller conn (pure ()) (run conn longQuery) \caller done -> do
-                await "native query did not start" (readMVar entered)
-                (_, sent) <- startCaller (throwTo caller UserInterrupt)
-                outcome <- await "native query did not cancel" (readMVar done)
-                assertAsync [UserInterrupt] outcome
-                await "interrupt sender did not finish" (readMVar sent) >>= assertSucceeded
-            assertReusable conn
-        | (name, run) <-
-            [ ("query_", \conn sql -> void (query_ conn sql :: IO [Only Double]))
-            , ("query with a prepared statement", \conn sql -> void (query conn sql () :: IO [Only Double]))
-            , ("execute_", \conn sql -> void (execute_ conn sql))
-            , ("execute with a prepared statement", \conn sql -> void (execute conn sql ()))
-            , ("statement cursor", \conn sql -> withStatement conn sql \stmt -> void (nextRow stmt :: IO (Maybe (Only Double))))
-            , ("fold_", \conn sql -> void (fold_ conn sql (0 :: Double) (\acc (Only value) -> pure (acc + value))))
-            , ("Arrow fold", \conn sql -> foldArrow_ conn sql () (\() _ _ -> pure ()))
-            ]
+  testGroup "native cancellation" $
+    [ testCase name $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+        assertBool "cancellation requires the threaded runtime" rtsSupportsBoundThreads
+        entered <- newEmptyMVar
+        createFunction conn "query_started" (signal entered >> pure (1 :: Int64))
+        withCaller conn (pure ()) (run conn longQuery) \caller done -> do
+          await "native query did not start" (readMVar entered)
+          (_, sent) <- startCaller (throwTo caller UserInterrupt)
+          outcome <- await "native query did not cancel" (readMVar done)
+          assertAsync [UserInterrupt] outcome
+          await "interrupt sender did not finish" (readMVar sent) >>= assertSucceeded
+        assertReusable conn
+    | (name, run) <-
+        [ ("query_", \conn sql -> void (query_ conn sql :: IO [Only Double]))
+        , ("query with a prepared statement", \conn sql -> void (query conn sql () :: IO [Only Double]))
+        , ("execute_", \conn sql -> void (execute_ conn sql))
+        , ("execute with a prepared statement", \conn sql -> void (execute conn sql ()))
+        , ("statement cursor", \conn sql -> withStatement conn sql \stmt -> void (nextRow stmt :: IO (Maybe (Only Double))))
+        , ("fold_", \conn sql -> void (fold_ conn sql (0 :: Double) (\acc (Only value) -> pure (acc + value))))
+        , ("Arrow fold", \conn sql -> foldArrow_ conn sql () (\() _ _ -> pure ()))
         ]
-            <> [ testCase name $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
-                    void (execute_ conn "SET streaming_buffer_size = '64KB'")
-                    filtering <- newIORef False
-                    entered <- newEmptyMVar
-                    createFunction conn "discard_remaining" \(_ :: Int64) -> do
-                        active <- readIORef filtering
-                        if active then signal entered >> pure True else pure False
-                    let sql = "SELECT i FROM range(1000000000000) t(i) WHERE NOT discard_remaining(i)"
-                    withCaller conn (pure ()) (run conn sql (atomicWriteIORef filtering True)) \caller done -> do
-                        await "fetch did not start after the first delivered batch" (readMVar entered)
-                        (_, sent) <- startCaller (throwTo caller UserInterrupt)
-                        await "streaming fetch did not cancel" (readMVar done) >>= assertAsync [UserInterrupt]
-                        await "interrupt sender did not finish" (readMVar sent) >>= assertSucceeded
-                    assertReusable conn
-               | (name, run) <-
-                    [ ("cancel a native row fetch", \conn sql delivered -> Streaming.fold_ conn sql () (\() (Only (_ :: Int64)) -> delivered))
-                    , ("cancel a native Arrow fetch", \conn sql delivered -> Streaming.foldArrow_ conn sql () (\() _ _ -> delivered))
-                    ,
-                        ( "mixed cursor entry points retain interruptible fetching"
-                        , \conn sql delivered -> withStatement conn sql \stmt -> do
-                            Streaming.nextRow stmt >>= (@?= Just (Only (0 :: Int64)))
-                            delivered
-                            let consume =
-                                    nextRow stmt >>= \case
-                                        Nothing -> pure ()
-                                        Just (Only (_ :: Int64)) -> consume
-                            consume
-                        )
-                    ]
-               ]
-            <> [ testCase "cancellation before native entry is not cleared by startup" $
-                    withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
-                        queued <- newEmptyMVar
-                        begin <- newEmptyMVar
-                        createFunction conn "query_started" (pure 1 :: IO Int64)
-                        let action = withConnectionHandle conn \handle ->
-                                withQueryCString longQuery \sql ->
-                                    withResult
-                                        conn
-                                        longQuery
-                                        (\result -> signal queued >> readMVar begin >> c_duckdb_query handle sql result)
-                                        (const (pure ()))
-                        withCaller conn (signal begin) action \caller done -> do
-                            await "query worker did not reach its entry gate" (readMVar queued)
-                            (_, sent) <- startCaller (throwTo caller UserInterrupt)
-                            await "first interrupt was not delivered" (readMVar sent) >>= assertSucceeded
-                            awaitCleanup caller
-                            signal begin
-                            await "startup cleared the cancellation" (readMVar done) >>= assertAsync [UserInterrupt]
-                        assertReusable conn
-               , testCase "a second cancellation waits for a blocked callback to return" $
-                    withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
-                        entered <- newEmptyMVar
-                        release <- newEmptyMVar
-                        createFunction conn "blocked_callback" (signal entered >> readMVar release >> pure (1 :: Int64))
-                        withCaller conn (signal release) (void (query_ conn "SELECT blocked_callback()" :: IO [Only Int64])) \caller done -> do
-                            await "callback did not start" (readMVar entered)
-                            (_, firstSent) <- startCaller (throwTo caller UserInterrupt)
-                            await "first interrupt was not delivered" (readMVar firstSent) >>= assertSucceeded
-                            secondAttempted <- newEmptyMVar
-                            (_, secondSent) <- startCaller (signal secondAttempted >> throwTo caller ThreadKilled)
-                            await "second interrupt sender did not start" (readMVar secondAttempted)
-                            premature <- timeout 50000 (readMVar secondSent)
-                            case premature of
-                                Nothing -> pure ()
-                                Just _ -> assertFailure "second interrupt escaped cleanup"
-                            tryReadMVar done >>= \case
-                                Nothing -> pure ()
-                                Just _ -> assertFailure "query returned while its callback was still running"
-                            signal release
-                            await "callback cancellation did not finish" (readMVar done) >>= assertAsync [UserInterrupt, ThreadKilled]
-                            await "second interrupt sender did not finish" (readMVar secondSent) >>= assertSucceeded
-                        assertReusable conn
-               ]
+    ]
+      <> [ testCase name $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+             void (execute_ conn "SET streaming_buffer_size = '64KB'")
+             filtering <- newIORef False
+             entered <- newEmptyMVar
+             createFunction conn "discard_remaining" \(_ :: Int64) -> do
+               active <- readIORef filtering
+               if active then signal entered >> pure True else pure False
+             let sql = "SELECT i FROM range(1000000000000) t(i) WHERE NOT discard_remaining(i)"
+             withCaller conn (pure ()) (run conn sql (atomicWriteIORef filtering True)) \caller done -> do
+               await "fetch did not start after the first delivered batch" (readMVar entered)
+               (_, sent) <- startCaller (throwTo caller UserInterrupt)
+               await "streaming fetch did not cancel" (readMVar done) >>= assertAsync [UserInterrupt]
+               await "interrupt sender did not finish" (readMVar sent) >>= assertSucceeded
+             assertReusable conn
+         | (name, run) <-
+             [ ("cancel a native row fetch", \conn sql delivered -> Streaming.fold_ conn sql () (\() (Only (_ :: Int64)) -> delivered))
+             , ("cancel a native Arrow fetch", \conn sql delivered -> Streaming.foldArrow_ conn sql () (\() _ _ -> delivered))
+             ,
+               ( "mixed cursor entry points retain interruptible fetching"
+               , \conn sql delivered -> withStatement conn sql \stmt -> do
+                   Streaming.nextRow stmt >>= (@?= Just (Only (0 :: Int64)))
+                   delivered
+                   let consume =
+                         nextRow stmt >>= \case
+                           Nothing -> pure ()
+                           Just (Only (_ :: Int64)) -> consume
+                   consume
+               )
+             ]
+         ]
+      <> [ testCase "cancellation before native entry is not cleared by startup" $
+             withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+               queued <- newEmptyMVar
+               begin <- newEmptyMVar
+               createFunction conn "query_started" (pure 1 :: IO Int64)
+               let action = withStatement conn longQuery \stmt ->
+                     withResult stmt \result -> runInterruptibleQuery conn do
+                       signal queued
+                       readMVar begin
+                       void (output (c_duckdb_v2_result_drain result))
+               withCaller conn (signal begin) action \caller done -> do
+                 await "query worker did not reach its entry gate" (readMVar queued)
+                 (_, sent) <- startCaller (throwTo caller UserInterrupt)
+                 await "first interrupt was not delivered" (readMVar sent) >>= assertSucceeded
+                 awaitCleanup caller
+                 signal begin
+                 await "startup cleared the cancellation" (readMVar done) >>= assertAsync [UserInterrupt]
+               assertReusable conn
+         , testCase "a second cancellation waits for a blocked callback to return" $
+             withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+               entered <- newEmptyMVar
+               release <- newEmptyMVar
+               createFunction conn "blocked_callback" (signal entered >> readMVar release >> pure (1 :: Int64))
+               withCaller conn (signal release) (void (query_ conn "SELECT blocked_callback()" :: IO [Only Int64])) \caller done -> do
+                 await "callback did not start" (readMVar entered)
+                 (_, firstSent) <- startCaller (throwTo caller UserInterrupt)
+                 await "first interrupt was not delivered" (readMVar firstSent) >>= assertSucceeded
+                 secondAttempted <- newEmptyMVar
+                 (_, secondSent) <- startCaller (signal secondAttempted >> throwTo caller ThreadKilled)
+                 await "second interrupt sender did not start" (readMVar secondAttempted)
+                 premature <- timeout 50000 (readMVar secondSent)
+                 case premature of
+                   Nothing -> pure ()
+                   Just _ -> assertFailure "second interrupt escaped cleanup"
+                 tryReadMVar done >>= \case
+                   Nothing -> pure ()
+                   Just _ -> assertFailure "query returned while its callback was still running"
+                 signal release
+                 await "callback cancellation did not finish" (readMVar done) >>= assertAsync [UserInterrupt, ThreadKilled]
+                 await "second interrupt sender did not finish" (readMVar secondSent) >>= assertSucceeded
+               assertReusable conn
+         , testCase "a cancellation in the result window releases the result that the window makes" $
+             withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+               queued <- newEmptyMVar
+               gate <- newEmptyMVar
+               released <- newIORef []
+               -- The helper thread of the window makes its result only after the
+               -- caller is cancelled. The caller does not return that result, so
+               -- the release action of the window must get it.
+               let action = withResultWindow conn (\result -> modifyIORef' released (result :)) do
+                     signal queued
+                     readMVar gate
+                     pure (7 :: Int)
+               withCaller conn (signal gate) (void action) \caller done -> do
+                 await "result window did not start" (readMVar queued)
+                 (_, sent) <- startCaller (throwTo caller UserInterrupt)
+                 await "interrupt was not delivered" (readMVar sent) >>= assertSucceeded
+                 awaitCleanup caller
+                 signal gate
+                 await "cancelled result window did not finish" (readMVar done) >>= assertAsync [UserInterrupt]
+               readIORef released >>= (@?= [7])
+               assertReusable conn
+         ]
 
+-- | A callback that runs a statement on the connection that runs the callback
+-- waits for the lock of that connection. Each case sets a bound of 0.2 s.
+callbackLockTests :: TestTree
+callbackLockTests =
+  testGroup
+    "a callback that waits for a connection lock"
+    [ testCase "a callback that runs a statement on its own connection in query_ fails at the bound" $
+        withBoundedConnections "1" testLockWait \conn _ -> do
+          (threads, errors) <- registerStatementCallback conn conn
+          outcome <- boundedOuterCall 30000000 threads (void (query_ conn "SELECT own_statement(i) FROM range(3) t(i)" :: IO [Only Int64]))
+          assertBoundError outcome
+          assertInnerErrors errors
+          assertReusable conn
+    , testCase "a callback that runs a statement on its own connection in a later stream fetch fails at the bound" $
+        withBoundedConnections "1" testLockWait \conn _ -> do
+          (threads, errors) <- registerStatementCallback conn conn
+          rows <- newIORef (0 :: Int)
+          void (execute_ conn "SET streaming_buffer_size = '16KB'")
+          outcome <- boundedOuterCall 30000000 threads $ withStatement conn laterFetchQuery \stmt -> do
+            let consume =
+                  Streaming.nextRow stmt >>= \case
+                    Nothing -> pure ()
+                    Just (Only (_ :: Int64)) -> modifyIORef' rows (+ 1) >> consume
+            consume
+          assertBoundError outcome
+          assertInnerErrors errors
+          readIORef rows >>= \count -> assertBool "the callback ran before the stream delivered a row" (count > 0)
+          assertReusable conn
+    , testCase "a callback that runs a statement on its own connection in a streaming fold fails at the bound" $
+        withBoundedConnections "1" testLockWait \conn _ -> do
+          (threads, errors) <- registerStatementCallback conn conn
+          rows <- newIORef (0 :: Int)
+          void (execute_ conn "SET streaming_buffer_size = '16KB'")
+          outcome <- boundedOuterCall 30000000 threads $ Streaming.fold_ conn laterFetchQuery () \() (Only (_ :: Int64)) -> modifyIORef' rows (+ 1)
+          assertBoundError outcome
+          assertInnerErrors errors
+          readIORef rows >>= \count -> assertBool "the callback ran before the fold received a row" (count > 0)
+          assertReusable conn
+    , testCase "a callback that runs a statement on its own connection in a later Arrow fetch fails at the bound" $
+        withBoundedConnections "1" testLockWait \conn _ -> do
+          (threads, errors) <- registerStatementCallback conn conn
+          batches <- newIORef (0 :: Int)
+          void (execute_ conn "SET streaming_buffer_size = '16KB'")
+          outcome <- boundedOuterCall 30000000 threads $ Streaming.foldArrow_ conn laterFetchQuery () \() _ _ -> modifyIORef' batches (+ 1)
+          assertBoundError outcome
+          assertInnerErrors errors
+          readIORef batches >>= \count -> assertBool "the callback ran before the fold received a batch" (count > 0)
+          assertReusable conn
+    , testCase "a callback that runs a statement on its own connection before the first Arrow batch fails at the bound" $
+        withBoundedConnections "1" testLockWait \conn _ -> do
+          (threads, errors) <- registerStatementCallback conn conn
+          batches <- newIORef (0 :: Int)
+          outcome <-
+            boundedOuterCall 30000000 threads $
+              Streaming.foldArrow_ conn "SELECT own_statement(i) FROM range(3) t(i)" () \() _ _ -> modifyIORef' batches (+ 1)
+          assertBoundError outcome
+          assertInnerErrors errors
+          readIORef batches >>= (@?= 0)
+          assertReusable conn
+    , testCase "a callback that prepares a statement on its own connection fails at the bound" $
+        withBoundedConnections "1" testLockWait \conn _ -> do
+          -- The preparation is the only step of the callback that takes the connection lock.
+          (threads, errors) <- registerOwnStatement conn (withStatement conn "SELECT ?::BIGINT" (\_ -> pure ()))
+          outcome <- boundedOuterCall 30000000 threads (void (query_ conn "SELECT own_statement(i) FROM range(3) t(i)" :: IO [Only Int64]))
+          assertBoundError outcome
+          assertInnerErrors errors
+          assertReusable conn
+    , testCase "a callback that reads the column count of a statement on its own connection fails at the bound" $
+        withBoundedConnections "1" testLockWait \conn _ ->
+          -- The statement has no schemas yet. Thus the column count binds the
+          -- metadata of the statement, and that bind takes the connection lock.
+          withStatement conn "SELECT 1 AS a, 2 AS b" \pending -> do
+            (threads, errors) <- registerOwnStatement conn (void (columnCount pending))
+            outcome <- boundedOuterCall 30000000 threads (void (query_ conn "SELECT own_statement(i) FROM range(3) t(i)" :: IO [Only Int64]))
+            assertBoundError outcome
+            assertInnerErrors errors
+            columnCount pending >>= (@?= 2)
+            assertReusable conn
+    , testCase "a callback statement that fails on a second connection leaves the lock of that connection free" $
+        withBoundedConnections "1" testLockWait \conn other -> do
+          createFunction conn "failing_other" \(i :: Int64) -> do
+            inner <- try (query_ other "SELECT error('inner')" :: IO [Only Int64])
+            case inner of
+              Left (_ :: SQLError) -> pure ()
+              Right _ -> assertFailure "expected the inner error"
+            -- The failed statement held the lock of the second connection.
+            -- The next statement of the callback must get that lock at once.
+            query_ other "SELECT 1" >>= (@?= [Only (1 :: Int64)])
+            pure i
+          query_ conn "SELECT failing_other(i) FROM range(3) t(i)" >>= (@?= map Only [0, 1, 2 :: Int64])
+          timeout 5000000 (query_ other "SELECT 42") >>= (@?= Just [Only (42 :: Int64)])
+    , testCase "callbacks on 4 DuckDB threads that run statements on their own connection each fail at the bound" $
+        withBoundedConnections "4" testLockWait \conn _ -> do
+          void (execute_ conn "CREATE TABLE callback_rows AS SELECT i FROM range(1000000) t(i)")
+          (threads, errors) <- registerStatementCallback conn conn
+          outcome <- boundedOuterCall 30000000 threads (void (query_ conn "SELECT sum(own_statement(i)) FROM callback_rows" :: IO [Only Integer]))
+          assertBoundError outcome
+          assertInnerErrors errors
+          assertReusable conn
+    , testCase "callbacks on 4 capabilities that are inside at the same time each fail at the bound" $
+        do
+          -- See Note [Capabilities of the tests] in "TestUtils".
+          raiseCapabilities 4
+          withBoundedConnections "4" testLockWait \conn _ -> do
+            void (execute_ conn "CREATE TABLE callback_rows AS SELECT i FROM range(1000000) t(i)")
+            inside <- newIORef (0 :: Int)
+            together <- newEmptyMVar
+            successes <- newIORef (0 :: Int)
+            -- The first two calls wait for each other before their statements.
+            -- Thus two callback threads have a mark at the same time, and the
+            -- mark of the second thread must keep the mark of the first thread.
+            let meet = do
+                  count <- atomicModifyIORef' inside (\known -> (known + 1, known + 1))
+                  when (count >= 2) (signal together)
+                  met <- timeout 10000000 (readMVar together)
+                  when (isNothing met) (throwIO (userError "no second callback was inside at the same time"))
+            (threads, errors) <- registerOwnStatement conn do
+              meet
+              void (query_ conn "SELECT 1" :: IO [Only Int64])
+              atomicModifyIORef' successes (\known -> (known + 1, ()))
+            outcome <- boundedOuterCall 30000000 threads (void (query_ conn "SELECT sum(own_statement(i)) FROM callback_rows" :: IO [Only Integer]))
+            assertBoundError outcome
+            assertInnerErrors errors
+            readIORef successes >>= (@?= 0)
+            readIORef inside >>= \count -> assertBool ("callbacks before the error: " <> show count) (count >= 2)
+            assertReusable conn
+    , testCase "callbacks on 4 DuckDB threads can share a second connection" $
+        withBoundedConnections "4" (Just defaultCallbackLockWait) \conn other -> do
+          void (execute_ conn "CREATE TABLE callback_rows AS SELECT i FROM range(1000000) t(i)")
+          threads <- newIORef []
+          createFunction conn "other_statement" \(i :: Int64) -> do
+            when (i `mod` 200 == 0) do
+              myThreadId >>= \self -> atomicModifyIORef' threads (\known -> (self : known, ()))
+              query_ other "SELECT 1" >>= (@?= [Only (1 :: Int64)])
+            pure (i `mod` 7)
+          result <- newIORef []
+          outcome <- boundedOuterCall 120000000 threads (query_ conn "SELECT sum(other_statement(i)) FROM callback_rows" >>= atomicWriteIORef result)
+          either (assertFailure . show) pure outcome
+          readIORef result >>= (@?= [Only (sum [i `mod` 7 | i <- [0 .. 999999 :: Integer]])])
+          assertReusable other
+    , testCase "the callback lock wait rejects a negative bound and accepts no bound" $ do
+        negative <- try (openWithOptions ":memory:" defaultConnectionOptions{connectionCallbackLockWait = Just (-1)})
+        case negative of
+          Left (err :: SQLError) -> do
+            sqlErrorType err @?= Just ErrorInputInvalid
+            assertBool ("unexpected message: " <> show err) ("connectionCallbackLockWait" `Text.isInfixOf` sqlErrorMessage err)
+          Right conn -> close conn >> assertFailure "a negative bound opened a connection"
+        withConnectionWithOptions ":memory:" defaultConnectionOptions{connectionCallbackLockWait = Nothing} assertReusable
+    ]
+
+-- | The bound of the cases in microseconds: 0.2 s.
+testLockWait :: Maybe Int
+testLockWait = Just 200000
+
+-- | Run an action with two connections of one instance, each with the bound.
+withBoundedConnections :: Text -> Maybe Int -> (Connection -> Connection -> IO a) -> IO a
+withBoundedConnections threads bound action =
+  withEnvironment \environment -> withInstance environment [("threads", threads)] \inst -> do
+    attachDatabase inst ":memory:" "callback_lock" []
+    setDefaultDatabase inst "callback_lock"
+    let options = defaultConnectionOptions{connectionCallbackLockWait = bound}
+    bracket (connectWithOptions inst options) close \conn ->
+      bracket (connectWithOptions inst options) close (action conn)
+
+-- | Register @own_statement@ on a connection. It runs a statement on the target
+-- connection, records its thread and the error of the statement, and raises the error.
+registerStatementCallback :: Connection -> Connection -> IO (IORef [ThreadId], IORef [SQLError])
+registerStatementCallback conn target = registerOwnStatement conn (void (query_ target "SELECT 1" :: IO [Only Int64]))
+
+-- | Register @own_statement@ on a connection. It runs an action, records its
+-- thread and each 'SQLError' of the action, and raises the error.
+registerOwnStatement :: Connection -> IO () -> IO (IORef [ThreadId], IORef [SQLError])
+registerOwnStatement conn statement = do
+  threads <- newIORef []
+  errors <- newIORef []
+  createFunction conn "own_statement" \(i :: Int64) -> do
+    myThreadId >>= \self -> atomicModifyIORef' threads (\known -> (self : known, ()))
+    try statement >>= \case
+      Left err -> atomicModifyIORef' errors (\known -> (err : known, ())) >> throwIO (err :: SQLError)
+      Right () -> pure i
+  pure (threads, errors)
+
+-- | The stream delivers 500000 rows before DuckDB computes a row that calls the
+-- callback. With a small stream buffer, a later fetch computes that row.
+laterFetchQuery :: Query
+laterFetchQuery = "SELECT CASE WHEN i >= 500000 AND i % 100000 = 0 THEN own_statement(i) ELSE i END FROM range(1000000) t(i)"
+
+-- | Run an outer call in its own thread, and wait for it at most the test
+-- bound. If the bound expires, send an exception to each callback thread.
+-- Cleanup can still wait for exception delivery or a native call. Use an
+-- external process timeout to limit the complete test run.
+boundedOuterCall :: Int -> IORef [ThreadId] -> IO () -> IO (Either SomeException ())
+boundedOuterCall micros threads action = do
+  (_, done) <- startCaller action
+  timeout micros (readMVar done) >>= \case
+    Just outcome -> pure outcome
+    Nothing -> do
+      readIORef threads >>= mapM_ (`throwTo` ErrorCall "test bound: release the callback")
+      _ <- await "the outer call did not return after the release of its callbacks" (readMVar done)
+      assertFailure "the outer call did not return within the test bound"
+
+-- | Require the error of a callback that waited for the bound. The outer
+-- statement has the text of the error of the callback and the type
+-- ErrorInputInvalid, because ErrorResourceInUse does not pass. See
+-- Note [Errors that leave a callback] in "Database.DuckDB.Simple.Callback".
+assertBoundError :: Either SomeException () -> Assertion
+assertBoundError = \case
+  Left err -> case fromException err of
+    Just (failure :: SQLError) -> do
+      let message = sqlErrorMessage failure
+      sqlErrorType failure @?= Just ErrorInputInvalid
+      assertBool
+        ("the rule is missing: " <> show failure)
+        ("A callback must not run a statement on the connection that runs the callback" `Text.isInfixOf` message)
+      assertBool ("the bound is missing: " <> show failure) ("waited 0.2 s" `Text.isInfixOf` message)
+    Nothing -> assertFailure ("expected an SQLError, got " <> show err)
+  Right () -> assertFailure "the outer call returned without the error of the bound"
+
+-- | Require that each statement of a callback failed with the busy error type.
+assertInnerErrors :: IORef [SQLError] -> Assertion
+assertInnerErrors errors = do
+  known <- readIORef errors
+  assertBool "no statement of a callback failed" (not (null known))
+  map sqlErrorType known @?= map (const (Just ErrorResourceInUse)) known
+
 -- | Run one volatile callback before a CPU query that cannot finish in the test window.
 longQuery :: Query
 longQuery =
-    "WITH started AS MATERIALIZED (SELECT query_started() AS seed) \
-    \SELECT sum(sin((a.i + b.j + started.seed)::DOUBLE)) \
-    \FROM started, range(1000000) a(i), range(1000000) b(j)"
+  "WITH started AS MATERIALIZED (SELECT query_started() AS seed) \
+  \SELECT sum(sin((a.i + b.j + started.seed)::DOUBLE)) \
+  \FROM started, range(1000000) a(i), range(1000000) b(j)"
 
 -- | Publish a thread's outcome while asynchronous exceptions are masked.
 startCaller :: IO () -> IO (ThreadId, MVar (Either SomeException ()))
 startCaller action = mask_ do
-    done <- newEmptyMVar
-    caller <- forkIOWithUnmask \unmask -> try (unmask action) >>= putMVar done
-    pure (caller, done)
+  done <- newEmptyMVar
+  caller <- forkIOWithUnmask \unmask -> try (unmask action) >>= putMVar done
+  pure (caller, done)
 
 -- | Release gates and interrupt unfinished SQL before the connection can close.
 withCaller :: Connection -> IO () -> IO () -> (ThreadId -> MVar (Either SomeException ()) -> IO a) -> IO a
 withCaller conn release action use =
-    bracket (startCaller action) cleanup (uncurry use)
+  bracket (startCaller action) cleanup (uncurry use)
   where
     cleanup (_, done) = do
-        release
-        await "emergency query cleanup did not finish" (stop done)
+      release
+      await "emergency query cleanup did not finish" (stop done)
     stop done = do
-        finished <- tryReadMVar done
-        case finished of
-            Just _ -> pure ()
-            Nothing -> do
-                withConnectionHandle conn c_duckdb_interrupt
-                threadDelay 10000
-                stop done
+      finished <- tryReadMVar done
+      case finished of
+        Just _ -> pure ()
+        Nothing -> do
+          withConnectionHandle conn (\raw -> checked (c_duckdb_v2_connection_interrupt raw))
+          threadDelay 10000
+          stop done
 
 -- | Wait until the cancelled caller has reached its interrupt-and-join loop.
 awaitCleanup :: ThreadId -> IO ()
 awaitCleanup caller = awaitCondition "caller did not enter cancellation cleanup" do
-    threadStatus caller >>= \case
-        ThreadBlocked BlockedOnForeignCall -> pure False
-        ThreadBlocked _ -> pure True
-        ThreadFinished -> assertFailure "caller finished before the native worker" >> pure False
-        ThreadDied -> assertFailure "caller died before publishing its result" >> pure False
-        ThreadRunning -> pure False
+  threadStatus caller >>= \case
+    ThreadBlocked BlockedOnForeignCall -> pure False
+    ThreadBlocked _ -> pure True
+    ThreadFinished -> assertFailure "caller finished before the native worker" >> pure False
+    ThreadDied -> assertFailure "caller died before publishing its result" >> pure False
+    ThreadRunning -> pure False
 
 -- | Bound waits in the test thread, independently of the cancelled caller.
 await :: String -> IO a -> IO a
@@ -172,8 +442,8 @@
 awaitCondition message condition = await message loop
   where
     loop = do
-        ready <- condition
-        unless ready (threadDelay 1000 >> loop)
+      ready <- condition
+      unless ready (threadDelay 1000 >> loop)
 
 -- | Open a test gate once; cleanup can safely call this again.
 signal :: MVar () -> IO ()
@@ -182,17 +452,11 @@
 -- | Require the requested asynchronous exception to reach the caller.
 assertAsync :: [AsyncException] -> Either SomeException () -> Assertion
 assertAsync expected = \case
-    Left err -> case fromException err of
-        Just actual -> assertBool ("unexpected asynchronous exception: " <> show actual) (actual `elem` expected)
-        Nothing -> assertFailure ("expected asynchronous cancellation, got " <> show err)
-    Right () -> assertFailure "query completed instead of reporting cancellation"
+  Left err -> case fromException err of
+    Just actual -> assertBool ("unexpected asynchronous exception: " <> show actual) (actual `elem` expected)
+    Nothing -> assertFailure ("expected asynchronous cancellation, got " <> show err)
+  Right () -> assertFailure "query completed instead of reporting cancellation"
 
 -- | Check that an interrupt sender completed normally.
 assertSucceeded :: Either SomeException () -> Assertion
 assertSucceeded = either (assertFailure . show) pure
-
--- | The interrupted native query must have released its connection state.
-assertReusable :: Connection -> Assertion
-assertReusable conn = do
-    rows <- query_ conn "SELECT 42" :: IO [Only Int64]
-    rows @?= [Only 42]
diff --git a/test/CopyTests.hs b/test/CopyTests.hs
new file mode 100644
--- /dev/null
+++ b/test/CopyTests.hs
@@ -0,0 +1,426 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+
+-- |
+-- Module      : CopyTests
+-- Description : Native integration checks for managed COPY and multi-file callbacks.
+module CopyTests (copyTests) where
+
+import Control.Exception (bracket, try)
+import Control.Monad (forM_, void)
+import Data.IORef
+import Data.Int (Int64)
+import Data.List (sort)
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Database.DuckDB.FFI.V2
+import Database.DuckDB.Simple hiding (bind)
+import qualified Database.DuckDB.Simple.Catalog as Catalog
+import qualified Database.DuckDB.Simple.Copy as Copy
+import Database.DuckDB.Simple.FromField (Field (..), FieldValue (..), LogicalTypeRep (..))
+import Database.DuckDB.Simple.LogicalRep (withoutAliases)
+import Database.DuckDB.Simple.Ok (Ok (..))
+import qualified Database.DuckDB.Simple.V2.Copy as V2Copy
+import qualified Database.DuckDB.Simple.V2.Registration as R
+import Database.DuckDB.Simple.Variant (variantObject)
+import Foreign.C.ConstPtr (ConstPtr (..))
+import Foreign.Ptr (nullPtr)
+import System.Directory (createDirectory, getTemporaryDirectory, removeFile, removePathForcibly)
+import System.FilePath ((</>))
+import System.IO (hClose, openTempFile)
+import System.Mem (performMajorGC)
+import Test.Tasty (TestTree, testGroup)
+import Test.Tasty.HUnit
+import TestUtils (writeIntegers)
+
+-- | Exercise the available COPY directions and multi-file wrapper.
+copyTests :: TestTree
+copyTests =
+  testGroup
+    "managed COPY"
+    [ testCase "COPY TO scans batches and reports statistics" testCopyTo
+    , testCase "row callbacks receive per-partition file paths" testPartitionedCopy
+    , testCase "row callbacks decode VARIANT after the registering connection closes" testVariantCopy
+    , testCase "COPY FROM runs bind global local and exec callbacks" testCopyFrom
+    , testCase "callback exceptions become SQL errors and permit reuse" testCopyFailure
+    , testCase "multi-file wrappers support lists globs filename and hive columns" testMultiFile
+    , testCase "COPY TO and table descriptions report the logical type id of each column type" testColumnTypeIds
+    , testCase "COPY TO snapshots survive but native metadata expires after the callback" testCopyFieldTypes
+    ]
+
+-- | Run every COPY TO callback and check the reported file statistics.
+testCopyTo :: Assertion
+testCopyTo = withDirectory \directory -> withConnection ":memory:" \connection -> do
+  seen <- newIORef ([] :: [Text])
+  total <- newIORef (0 :: DuckDBIdx)
+  let mark phase = atomicModifyIORef' seen (\phases -> (phase : phases, ()))
+      bind info _ = do
+        mark "bind"
+        R.output (c_duckdb_v2_copy_to_bind_get_column_count info) >>= (@?= 1)
+        R.setCallbackState (c_duckdb_v2_copy_to_bind_set_bind_data info) ()
+      batchSize info _ = mark "batch size" >> R.checked (c_duckdb_v2_copy_to_batch_size_set_target info 1024)
+      initialize info _ = do
+        mark "init"
+        path <- R.output (c_duckdb_v2_copy_to_init_get_file_path info) >>= R.readText
+        writeFile (Text.unpack path) ""
+        R.setCallbackState (c_duckdb_v2_copy_to_init_set_init_data info) total
+      batch info _ = do
+        mark "batch"
+        count <-
+          bracket
+            (R.output (c_duckdb_v2_copy_to_batch_take_input info))
+            (R.destroy c_duckdb_v2_column_data_collection_destroy)
+            (R.output . c_duckdb_v2_column_data_collection_row_count)
+        R.setCallbackState (c_duckdb_v2_copy_to_batch_set_batch_data info) count
+      flush info _ = do
+        mark "flush"
+        count <- R.getCallbackState (c_duckdb_v2_copy_to_flush_get_batch_data info) :: IO DuckDBIdx
+        state <- R.getCallbackState (c_duckdb_v2_copy_to_flush_get_init_data info) :: IO (IORef DuckDBIdx)
+        atomicModifyIORef' state (\n -> (n + count, ()))
+      finalize _ _ = mark "finalize"
+      statistics info _ = do
+        mark "statistics"
+        state <- R.getCallbackState (c_duckdb_v2_copy_to_statistics_get_init_data info) :: IO (IORef DuckDBIdx)
+        count <- readIORef state
+        R.checked (c_duckdb_v2_copy_to_statistics_set_row_count info count)
+        R.checked (c_duckdb_v2_copy_to_statistics_set_file_size info 17)
+      callbacks =
+        (V2Copy.copyToCallbacks batch flush)
+          { V2Copy.copyToBindCallback = Just bind
+          , V2Copy.copyToBatchSizeCallback = Just batchSize
+          , V2Copy.copyToInitCallback = Just initialize
+          , V2Copy.copyToFinalizeCallback = Just finalize
+          , V2Copy.copyToStatisticsCallback = Just statistics
+          }
+  V2Copy.registerCopyToCallbacks connection "managed_output" callbacks
+  rows <-
+    query
+      connection
+      "COPY (SELECT i FROM range(5000) t(i)) TO ? (FORMAT managed_output, RETURN_STATS)"
+      (Only (Text.pack (directory </> "stats")))
+      :: IO [[FieldValue]]
+  readIORef total >>= (@?= 5000)
+  phases <- readIORef seen
+  forM_ ["bind", "batch size", "init", "batch", "flush", "finalize", "statistics"] \phase -> assertBool (Text.unpack phase) (phase `elem` phases)
+  case rows of
+    [FieldText _ : count : size : _] -> do
+      number count @?= 5000
+      number size @?= 17
+    _ -> assertFailure (show rows)
+
+-- | Preserve the row-oriented API while native COPY creates partition files.
+testPartitionedCopy :: Assertion
+testPartitionedCopy = withDirectory \directory -> withConnection ":memory:" \connection -> do
+  files <- newIORef ([] :: [FilePath])
+  values <- newIORef ([] :: [Int64])
+  Copy.registerCopyToFunction
+    connection
+    "managed_partitions"
+    (\info -> Copy.copyBindColumnTypes info @?= [Copy.LogicalTypeIdBigInt])
+    ( \info -> do
+        let path = Copy.copyInitFilePath info
+        writeFile path ""
+        atomicModifyIORef' files (\paths -> (path : paths, ()))
+        pure path
+    )
+    ( \info rows -> do
+        let decoded = [value | [Field{fieldValue = FieldInt64 value}] <- rows]
+        atomicModifyIORef' values (\previous -> (decoded <> previous, ()))
+        appendFile (Copy.copySinkGlobalState info) (unlines (map show decoded))
+    )
+    (const (pure ()))
+  void
+    ( execute
+        connection
+        "COPY (SELECT i, i%2 AS part FROM range(12) t(i)) TO ? (FORMAT managed_partitions, PARTITION_BY(part))"
+        (Only (Text.pack (directory </> "partitioned")))
+    )
+  readIORef values >>= (@?= [0 .. 11]) . sort
+  paths <- readIORef files
+  length paths @?= 2
+  assertBool "partition paths" (all (Text.isInfixOf "part=" . Text.pack) paths)
+
+-- | COPY TO keeps pure type snapshots and expires escaped native actions.
+testCopyFieldTypes :: Assertion
+testCopyFieldTypes = withDirectory \directory -> withConnection ":memory:" \connection -> do
+  received <- newIORef ([] :: [Field])
+  snapshots <- newIORef ([] :: [LogicalTypeRep])
+  Copy.registerCopyToFunction
+    connection
+    "field_types"
+    (const (pure ()))
+    (\info -> writeFile (Copy.copyInitFilePath info) "")
+    ( \_ rows -> do
+        forM_ rows \fields -> case fields of
+          [decimal, json, _] -> do
+            runConversion (traverse fieldType [decimal, json]) >>= \case
+              Ok types -> atomicModifyIORef' snapshots (\previous -> (previous <> types, ()))
+              Errors errors -> assertFailure (show errors)
+          _ -> assertFailure "expected three COPY TO columns"
+        atomicModifyIORef' received (\previous -> (previous <> concat rows, ()))
+    )
+    (const (pure ()))
+  void
+    ( execute
+        connection
+        "COPY (SELECT 1.5::DECIMAL(4,1) AS d, '{}'::JSON AS j, 7::BIGINT AS unused) TO ? (FORMAT field_types)"
+        (Only (Text.pack (directory </> "types")))
+    )
+  performMajorGC
+  readIORef snapshots >>= (@?= [LogicalTypeDecimal 4 1, LogicalTypeAlias "JSON" (LogicalTypeScalar LogicalTypeIdVarchar)])
+  readIORef received >>= mapM_ \entry ->
+    try (runConversion (fieldType entry)) >>= \case
+      Left SQLError{sqlErrorMessage} -> sqlErrorMessage @?= "duckdb-simple: field type scope is closed"
+      Right _ -> assertFailure "COPY TO metadata survived its callback"
+
+-- | COPY registrations share the instance and copy nested VARIANT payloads.
+testVariantCopy :: Assertion
+testVariantCopy = withDirectory \directory -> withEnvironment \environment -> withInstance environment [] \instance' -> do
+  received <- newIORef ([] :: [FieldValue])
+  withConnectionOn instance' \connection ->
+    Copy.registerCopyToFunction
+      connection
+      "managed_variant"
+      (\info -> Copy.copyBindColumnTypes info @?= [Copy.LogicalTypeIdVariant])
+      (\info -> writeFile (Copy.copyInitFilePath info) "")
+      (\_ rows -> atomicModifyIORef' received (\previous -> (previous <> [fieldValue entry | [entry] <- rows], ())))
+      (const (pure ()))
+  withConnectionOn instance' \connection -> do
+    void
+      ( execute
+          connection
+          "COPY (SELECT {'n': i, 'values': [i, NULL]}::VARIANT FROM range(3) t(i)) TO ? (FORMAT managed_variant)"
+          (Only (Text.pack (directory </> "variant")))
+      )
+    readIORef received >>= (@?= [variantObject [("n", FieldInt64 i), ("values", FieldList [FieldInt64 i, FieldNull])] | i <- [0 .. 2]])
+
+-- | Create a column of each type that DuckDB permits. Check the id that the
+-- COPY TO bind info reports for each column. Check the id in the table
+-- description of each column that has a scalar type. Check that no column type
+-- in the table description has an alias, so the name of each id in
+-- logicalTypeIdName is the name that DuckDB gives.
+testColumnTypeIds :: Assertion
+testColumnTypeIds = withDirectory \directory -> withConnection ":memory:" \connection -> do
+  reported <- newIORef []
+  Copy.registerCopyToFunction
+    connection
+    "column_types"
+    (writeIORef reported . Copy.copyBindColumnTypes)
+    (\info -> writeFile (Copy.copyInitFilePath info) "")
+    (\_ _ -> pure ())
+    (const (pure ()))
+  let named = zip [Text.pack ("c" <> show index) | index <- [0 :: Int ..]] tableColumns
+  void (execute_ connection (Query ("CREATE TABLE typed (" <> Text.intercalate ", " [name <> " " <> sql | (name, (sql, _)) <- named] <> ")")))
+  -- A table cannot have a TYPE column. A query can.
+  void (execute connection "COPY (SELECT NULL::TYPE, * FROM typed) TO ? (FORMAT column_types)" (Only (Text.pack (directory </> "types"))))
+  readIORef reported >>= (@?= LogicalTypeIdType : map snd tableColumns)
+  sort (LogicalTypeIdType : map snd tableColumns) @?= filter (`notElem` unreachable) [minBound .. maxBound]
+  description <- Catalog.describeTable connection "typed"
+  [ (name, ident)
+    | Catalog.ColumnDescription{Catalog.columnDescriptionName = name, Catalog.columnDescriptionType = LogicalTypeScalar ident} <-
+        Catalog.tableDescriptionColumns description
+    ]
+    @?= [(name, ident) | (name, (_, ident)) <- named, ident `notElem` nested]
+  let types = map Catalog.columnDescriptionType (Catalog.tableDescriptionColumns description)
+  map withoutAliases types @?= types
+  where
+    -- DuckDB uses these ids for an unset type, an unresolved parameter, and a
+    -- function parameter of any type. SQL cannot declare a column of these types.
+    unreachable = [LogicalTypeIdInvalid, LogicalTypeIdUnknown, LogicalTypeIdAny]
+    -- LogicalTypeRep has a constructor with the type parameters for these ids.
+    nested =
+      [ LogicalTypeIdDecimal
+      , LogicalTypeIdGeometry
+      , LogicalTypeIdStruct
+      , LogicalTypeIdList
+      , LogicalTypeIdMap
+      , LogicalTypeIdEnum
+      , LogicalTypeIdUnion
+      , LogicalTypeIdArray
+      , LogicalTypeIdTuple
+      ]
+    tableColumns =
+      [ ("\"NULL\"", LogicalTypeIdSQLNull)
+      , ("BOOLEAN", LogicalTypeIdBoolean)
+      , ("TINYINT", LogicalTypeIdTinyInt)
+      , ("SMALLINT", LogicalTypeIdSmallInt)
+      , ("INTEGER", LogicalTypeIdInteger)
+      , ("BIGINT", LogicalTypeIdBigInt)
+      , ("DATE", LogicalTypeIdDate)
+      , ("TIME", LogicalTypeIdTime)
+      , ("TIMESTAMP_S", LogicalTypeIdTimestampSec)
+      , ("TIMESTAMP_MS", LogicalTypeIdTimestampMs)
+      , ("TIMESTAMP", LogicalTypeIdTimestamp)
+      , ("TIMESTAMP_NS", LogicalTypeIdTimestampNs)
+      , ("DECIMAL(10, 2)", LogicalTypeIdDecimal)
+      , ("FLOAT", LogicalTypeIdFloat)
+      , ("DOUBLE", LogicalTypeIdDouble)
+      , ("VARCHAR", LogicalTypeIdVarchar)
+      , ("BLOB", LogicalTypeIdBlob)
+      , ("INTERVAL", LogicalTypeIdInterval)
+      , ("UTINYINT", LogicalTypeIdUTinyInt)
+      , ("USMALLINT", LogicalTypeIdUSmallInt)
+      , ("UINTEGER", LogicalTypeIdUInteger)
+      , ("UBIGINT", LogicalTypeIdUBigInt)
+      , ("TIMESTAMPTZ", LogicalTypeIdTimestampTz)
+      , ("TIMESTAMPTZ_NS", LogicalTypeIdTimestampTzNs)
+      , ("TIMETZ", LogicalTypeIdTimeTz)
+      , ("TIME_NS", LogicalTypeIdTimeNs)
+      , ("BIT", LogicalTypeIdBit)
+      , ("BIGNUM", LogicalTypeIdBigNum)
+      , ("UHUGEINT", LogicalTypeIdUHugeInt)
+      , ("HUGEINT", LogicalTypeIdHugeInt)
+      , ("UUID", LogicalTypeIdUUID)
+      , ("GEOMETRY", LogicalTypeIdGeometry)
+      , ("STRUCT(a INTEGER)", LogicalTypeIdStruct)
+      , ("INTEGER[]", LogicalTypeIdList)
+      , ("MAP(INTEGER, VARCHAR)", LogicalTypeIdMap)
+      , ("ENUM('a', 'b')", LogicalTypeIdEnum)
+      , ("UNION(a INTEGER, b VARCHAR)", LogicalTypeIdUnion)
+      , ("INTEGER[2]", LogicalTypeIdArray)
+      , ("VARIANT", LogicalTypeIdVariant)
+      , ("TUPLE(INTEGER, VARCHAR)", LogicalTypeIdTuple)
+      ]
+
+-- | Fill one output vector from state created in each native COPY FROM phase.
+testCopyFrom :: Assertion
+testCopyFrom = withConnection ":memory:" \connection -> do
+  phases <- newIORef ([] :: [Text])
+  let mark phase = atomicModifyIORef' phases (\previous -> (phase : previous, ()))
+      bind info _ = do
+        mark "bind"
+        R.output (c_duckdb_v2_copy_from_bind_get_column_count info) >>= (@?= 1)
+        R.setCallbackState (c_duckdb_v2_copy_from_bind_set_bind_data info) (7 :: Int64)
+        R.checked (c_duckdb_v2_copy_from_bind_set_cardinality info 3 1)
+      initializeGlobal info _ = do
+        mark "global"
+        start <- R.getCallbackState (c_duckdb_v2_copy_from_init_global_get_bind_data info)
+        state <- newIORef (Just (start :: Int64))
+        R.setCallbackState (c_duckdb_v2_copy_from_init_global_set_global_state info) state
+        R.checked (c_duckdb_v2_copy_from_init_global_set_max_threads info 1)
+      initializeLocal info _ = do
+        mark "local"
+        R.setCallbackState (c_duckdb_v2_copy_from_init_local_set_local_state info) ()
+      executeRows info _ = do
+        mark "exec"
+        () <- R.getCallbackState (c_duckdb_v2_copy_from_exec_get_local_state info)
+        state <- R.getCallbackState (c_duckdb_v2_copy_from_exec_get_global_state info) :: IO (IORef (Maybe Int64))
+        start <- atomicModifyIORef' state (\value -> (Nothing, value))
+        chunk <- R.output (c_duckdb_v2_copy_from_exec_get_output_chunk info)
+        vector <- R.output (c_duckdb_v2_data_chunk_get_vector chunk 0)
+        writeIntegers vector (maybe [] (\first -> [first .. first + 2]) start)
+      -- DuckDB calls this only to display progress, so the test checks
+      -- registration and does not require a call.
+      progress info _ = R.checked (c_duckdb_v2_copy_from_progress_set_progress info 0.5)
+      callbacks =
+        (V2Copy.copyFromCallbacks bind executeRows)
+          { V2Copy.copyFromInitGlobalCallback = Just initializeGlobal
+          , V2Copy.copyFromInitLocalCallback = Just initializeLocal
+          , V2Copy.copyFromProgressCallback = Just progress
+          }
+  V2Copy.registerCopyFromCallbacks connection "managed_input" callbacks
+  void (execute_ connection "CREATE TABLE imported (value BIGINT)")
+  void (execute_ connection "COPY imported FROM 'unused' (FORMAT managed_input)")
+  query_ connection "SELECT value FROM imported ORDER BY value" >>= (@?= map Only ([7, 8, 9] :: [Int64]))
+  called <- readIORef phases
+  forM_ ["bind", "global", "local", "exec"] \phase -> assertBool (Text.unpack phase) (phase `elem` called)
+
+-- | Contain exceptions from native COPY callbacks.
+testCopyFailure :: Assertion
+testCopyFailure = withConnection ":memory:" \connection -> do
+  V2Copy.registerCopyFromCallbacks
+    connection
+    "managed_failure"
+    (V2Copy.copyFromCallbacks (\_ _ -> pure ()) (\_ _ -> ioError (userError "managed COPY failure")))
+  void (execute_ connection "CREATE TABLE failed_import (value BIGINT)")
+  result <- try (execute_ connection "COPY failed_import FROM 'unused' (FORMAT managed_failure)")
+  case result of
+    Left SQLError{sqlErrorMessage} -> assertBool "callback diagnostic" ("managed COPY failure" `Text.isInfixOf` sqlErrorMessage)
+    Right _ -> assertFailure "expected callback failure"
+  query_ connection "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+
+-- | Wrap a managed one-file table reader with native file discovery.
+testMultiFile :: Assertion
+testMultiFile = withDirectory \directory -> withConnection ":memory:" \connection -> do
+  let first = directory </> "first.mock"
+      second = directory </> "second.mock"
+  writeFile first "7"
+  writeFile second "11"
+  bindInfoCalls <- registerSingleFileReader connection
+  Copy.registerMultiFileFunction connection "managed_files" "managed_single" (Copy.MultiFileOptions (Just "managed fixture") (Just "mock"))
+  query connection "SELECT value FROM managed_files(?) ORDER BY value" (Only (Text.pack (directory </> "*.mock")))
+    >>= (@?= map Only ([7, 11] :: [Int64]))
+  let paths = [Text.pack first, Text.pack second]
+  query connection "SELECT value, filename FROM managed_files(?::VARCHAR[], filename=true) ORDER BY value" (Only paths)
+    >>= (@?= [(7 :: Int64, Text.pack first), (11, Text.pack second)])
+  forM_ [("left", 3), ("right", 5 :: Int)] \(part, value) -> do
+    let path = directory </> ("part=" <> part)
+    createDirectory path
+    writeFile (path </> "data.mock") (show value)
+  query
+    connection
+    "SELECT value,part FROM managed_files(?,hive_partitioning=true,union_by_name=true) ORDER BY value"
+    (Only (Text.pack (directory </> "part=*" </> "*.mock")))
+    >>= (@?= [(3 :: Int64, "left" :: Text), (5, "right")])
+  readIORef bindInfoCalls >>= assertBool "table get-bind-info callback" . (> 0)
+
+-- | Register a table function that returns the integer stored in one text file.
+registerSingleFileReader :: Connection -> IO (IORef Int)
+registerSingleFileReader connection = do
+  calls <- newIORef 0
+  R.registerTableFunction
+    connection
+    "managed_single"
+    [R.parameter "path" (R.TypeExpression "VARCHAR")]
+    (R.tableCallbacks bind executeRows){R.tableInitGlobalCallback = Just initialize, R.tableGetBindInfoCallback = Just (getBindInfo calls)}
+  pure calls
+  where
+    bind input result context = do
+      path <- bracket (R.output (c_duckdb_v2_function_bind_get_arg_value input 0)) (R.destroy c_duckdb_v2_value_destroy) \value -> R.output (c_duckdb_v2_value_get_varchar value) >>= R.readText
+      value <- read <$> readFile (Text.unpack path) :: IO Int64
+      R.setCallbackState (c_duckdb_v2_function_bind_set_bind_data input) value
+      bracket
+        ( R.output (c_duckdb_v2_context_get_factory context) >>= \factory -> R.withText "BIGINT" (R.output . c_duckdb_v2_factory_create_type_from_text factory)
+        )
+        (R.destroy c_duckdb_v2_logical_type_destroy)
+        \dtype ->
+          R.withIdentifier "value" \name -> R.checked (c_duckdb_v2_table_function_bind_add_result_column result name dtype)
+    getBindInfo calls info context = do
+      modifyIORef' calls (+ 1)
+      value <- R.getCallbackState (c_duckdb_v2_table_function_get_bind_info_get_bind_data info) :: IO Int64
+      factory <- R.output (c_duckdb_v2_context_get_factory context)
+      bracket (R.withText "value" (R.output . c_duckdb_v2_value_create_varchar factory)) (R.destroy c_duckdb_v2_value_destroy) $ \identifier ->
+        R.checked (c_duckdb_v2_table_function_get_bind_info_set_column_identifier info 0 (ConstPtr nullPtr) 0 identifier)
+      bracket (R.output (c_duckdb_v2_value_create_bigint factory value)) (R.destroy c_duckdb_v2_value_destroy) $ \native ->
+        R.withText "fixture_value" $ \(ConstPtr key) -> R.checked (c_duckdb_v2_table_function_get_bind_info_set_option info key native)
+    initialize info _ = do
+      value <- R.getCallbackState (c_duckdb_v2_table_function_init_global_get_bind_data info)
+      state <- newIORef (Just (value :: Int64))
+      R.setCallbackState (c_duckdb_v2_table_function_init_global_set_global_state info) state
+    executeRows info _ = do
+      state <- R.getCallbackState (c_duckdb_v2_table_function_exec_get_global_state info) :: IO (IORef (Maybe Int64))
+      value <- atomicModifyIORef' state (\previous -> (Nothing, previous))
+      chunk <- R.output (c_duckdb_v2_table_function_exec_get_output_chunk info)
+      vector <- R.output (c_duckdb_v2_data_chunk_get_vector chunk 0)
+      writeIntegers vector (maybe [] pure value)
+
+-- | Read a nonnegative integer from native statistics.
+number :: FieldValue -> Integer
+number (FieldWord64 value) = toInteger value
+number (FieldInt64 value) = toInteger value
+number value = error ("unexpected statistics value " <> show value)
+
+-- | Create and remove a unique directory for native file operations.
+withDirectory :: (FilePath -> IO a) -> IO a
+withDirectory action = bracket create removePathForcibly action
+  where
+    create = do
+      root <- getTemporaryDirectory
+      (path, handle) <- openTempFile root "duckdb-managed-copy"
+      hClose handle
+      removeFile path
+      createDirectory path
+      pure path
diff --git a/test/CoreRegressionTests.hs b/test/CoreRegressionTests.hs
--- a/test/CoreRegressionTests.hs
+++ b/test/CoreRegressionTests.hs
@@ -1,153 +1,1027 @@
-{-# LANGUAGE OverloadedStrings #-}
-{-# LANGUAGE ScopedTypeVariables #-}
-{-# OPTIONS_GHC -Wno-deprecations #-}
-
--- | Regression tests for result metadata, cursor state, and handle lifetime.
-module CoreRegressionTests (coreRegressionTests) where
-
-import Control.Exception (SomeException, throwIO, try)
-import Control.Monad (forM_, replicateM_, void)
-import Data.IORef (readIORef)
-import Data.Int (Int64)
-import Data.List (isInfixOf)
-import Data.Text (Text)
-import Database.DuckDB.FFI.Deprecated (c_duckdb_result_is_streaming)
-import Database.DuckDB.Simple
-import Database.DuckDB.Simple.FromField (FieldValue)
-import Database.DuckDB.Simple.Internal (Statement (statementStream), StatementStream (statementStreamResult), StatementStreamState (..))
-import System.Mem (performMajorGC)
-import Test.Tasty (TestTree, testGroup)
-import Test.Tasty.HUnit
-
--- | Exercise public operations against an in-memory database.
-coreRegressionTests :: TestTree
-coreRegressionTests =
-    testGroup
-        "core regressions"
-        [ testCase "stream metadata follows parameter types" $
-            withConnection ":memory:" $ \conn -> do
-                rows <- fold conn "SELECT ?" (Only (42 :: Int64)) [] collect
-                rows @?= [Only (42 :: Int64)]
-        , testCase "cursor uses the supported materialized execution API" $
-            withConnection ":memory:" $ \conn ->
-                withStatement conn "SELECT i FROM range(10000) t(i)" $ \stmt -> do
-                    void (nextRow stmt :: IO (Maybe (Only Int64)))
-                    state <- readIORef (statementStream stmt)
-                    case state of
-                        StatementStreamActive stream -> do
-                            streaming <- c_duckdb_result_is_streaming (statementStreamResult stream)
-                            assertBool "expected a materialized native result" (streaming == 0)
-                        _ -> assertFailure "expected an active cursor"
-        , testCase "stream metadata preserves 64-bit values" $
-            withConnection ":memory:" $ \conn -> do
-                rows <- fold conn "SELECT coalesce(?, 1) FROM range(3)" (Only (5000000000 :: Int64)) [] collect
-                rows @?= replicate 3 (Only (5000000000 :: Int64))
-        , testCase "stream numeric to Text conversion uses result metadata" $
-            withConnection ":memory:" $ \conn -> do
-                rows <- fold conn "SELECT coalesce(?, 'x')" (Only (100 :: Int64)) [] collect
-                rows @?= [Only ("100" :: Text)]
-        , testCase "stream metadata follows schema rebinding" $
-            withConnection ":memory:" $ \conn -> do
-                void $ execute_ conn "CREATE TABLE rebind_probe(x VARCHAR)"
-                withStatement conn "SELECT x FROM rebind_probe" $ \stmt -> do
-                    void $ execute_ conn "DROP TABLE rebind_probe"
-                    void $ execute_ conn "CREATE TABLE rebind_probe(x BIGINT)"
-                    void $ execute_ conn "INSERT INTO rebind_probe VALUES (5000000000)"
-                    nextRow stmt >>= (@?= Just (Only (5000000000 :: Int64)))
-        , testCase "EOF remains exhausted" $
-            withConnection ":memory:" $ \conn ->
-                withStatement conn "SELECT 42" $ \stmt -> do
-                    nextRow stmt >>= (@?= Just (Only (42 :: Int64)))
-                    replicateM_ 3 $ nextRow stmt >>= (@?= (Nothing :: Maybe (Only Int64)))
-        , testCase "DML cursor executes only once" $
-            withConnection ":memory:" $ \conn -> do
-                void $ execute_ conn "CREATE TABLE once_probe(x INTEGER)"
-                withStatement conn "INSERT INTO once_probe VALUES (1)" $ \stmt ->
-                    replicateM_ 3 $ void (nextRow stmt :: IO (Maybe (Only Int64)))
-                query_ conn "SELECT count(*) FROM once_probe" >>= (@?= [Only (1 :: Int64)])
-        , testCase "rebinding resets an exhausted cursor" $
-            withConnection ":memory:" $ \conn ->
-                withStatement conn "SELECT ?::BIGINT" $ \stmt -> do
-                    bind stmt [toField (1 :: Int64)]
-                    nextRow stmt >>= (@?= Just (Only (1 :: Int64)))
-                    nextRow stmt >>= (@?= (Nothing :: Maybe (Only Int64)))
-                    bind stmt [toField (2 :: Int64)]
-                    nextRow stmt >>= (@?= Just (Only (2 :: Int64)))
-        , testCase "clear bindings invalidates an active cursor" $
-            withConnection ":memory:" $ \conn ->
-                withStatement conn "SELECT ?::BIGINT FROM range(3)" $ \stmt -> do
-                    bind stmt [toField (7 :: Int64)]
-                    void (nextRow stmt :: IO (Maybe (Only Int64)))
-                    clearStatementBindings stmt
-                    assertThrows (nextRow stmt :: IO (Maybe (Only Int64)))
-        , testCase "fetch errors are not EOF" $
-            withConnectionWithConfig ":memory:" [("threads", "1")] $ \conn ->
-                assertThrows (fold_ conn "SELECT CASE WHEN i = 5000 THEN error('late failure') ELSE i END FROM range(10000) t(i)" (0 :: Int64) (\acc (Only n) -> pure (acc + n)))
-        , testCase "composite cursors preserve values after chunk cleanup" $
-            withConnectionWithConfig ":memory:" [("threads", "1")] $ \conn ->
-                forM_
-                    [ "SELECT {'n': i, 'text': 'λ' || i::VARCHAR} FROM range(5000) t(i)"
-                    , "SELECT CASE WHEN i % 2 = 0 THEN union_value(n := i)::UNION(n BIGINT, text VARCHAR) ELSE union_value(text := i::VARCHAR)::UNION(n BIGINT, text VARCHAR) END FROM range(5000) t(i)"
-                    , "SELECT CASE WHEN i % 3 = 0 THEN NULL ELSE {'n': i, 'list': [i, NULL], 'union': union_value(v := i)} END FROM range(5000) t(i)"
-                    ]
-                    $ \sql -> do
-                        eager <- query_ conn sql :: IO [Only FieldValue]
-                        streamed <- reverse <$> fold_ conn sql [] (\acc row -> pure (row : acc))
-                        streamed @?= eager
-        , testCase "composite cursor failures release the result" $
-            withConnectionWithConfig ":memory:" [("threads", "1")] $ \conn -> do
-                let sql = "SELECT {'n': i, 'values': [i, NULL]} FROM range(5000) t(i)"
-                assertThrows (fold_ conn sql () (\() (Only (_ :: Int64)) -> pure ()))
-                assertThrows $ fold_ conn sql (0 :: Int) $ \n (Only (_ :: FieldValue)) ->
-                    if n == 2050 then throwIO (userError "composite fold failure") else pure (n + 1)
-                query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
-        , testCase "closed connection rejects active cursor reads" $ do
-            conn <- open ":memory:"
-            stmt <- openStatement conn "SELECT i FROM range(3) t(i)"
-            void (nextRow stmt :: IO (Maybe (Only Int64)))
-            close conn
-            assertThrows (nextRow stmt :: IO (Maybe (Only Int64)))
-            closeStatement stmt
-        , testCase "NUL in SQL is rejected" $
-            withConnection ":memory:" $ \conn ->
-                assertThrows (query_ conn "SELECT 1\0 + 2" :: IO [Only Int64])
-        , testCase "NUL in database path is rejected" $
-            assertThrows (withConnection ":memory:\0suffix" (const (pure ())))
-        , testCase "NUL in configuration value is rejected" $
-            assertThrows (withConnectionWithConfig ":memory:" [("threads", "1\0suffix")] (const (pure ())))
-        , testCase "NUL in parameter name is rejected" $
-            withConnection ":memory:" $ \conn ->
-                withStatement conn "SELECT $value" $ \stmt ->
-                    assertThrows (namedParameterIndex stmt "value\0suffix")
-        , testCase "duplicate named bindings are rejected" $
-            withConnection ":memory:" $ \conn ->
-                withStatement conn "SELECT $a + $b" $ \stmt -> do
-                    result <- try (bindNamed stmt ["a" := (1 :: Int64), "$a" := (2 :: Int64)])
-                    case result of
-                        Left (_ :: FormatError) -> pure ()
-                        Right () -> assertFailure "expected duplicate binding error before execution"
-        , testCase "transaction preserves the original exception if rollback fails" $
-            withConnection ":memory:" $ \conn -> do
-                result <- try $ withTransaction conn $ do
-                    void $ execute_ conn "ROLLBACK"
-                    throwIO (userError "original transaction failure")
-                case result of
-                    Left (err :: IOError) -> assertBool "original exception" ("original transaction failure" `isInfixOf` show err)
-                    Right () -> assertFailure "expected transaction failure"
-        , testCase "GC during the last connection use keeps native owners alive" $ do
-            -- A bracket cleanup would retain conn and hide early finalization.
-            conn <- open ":memory:"
-            createFunction conn "gc_identity" (\(n :: Int64) -> performMajorGC >> pure n)
-            rows <- query_ conn "SELECT gc_identity(i) FROM range(10) t(i)"
-            rows @?= map Only ([0 .. 9] :: [Int64])
-        ]
-  where
-    collect acc row = pure (acc <> [row])
-
--- | Require an exception without constraining its concrete type.
-assertThrows :: IO a -> Assertion
-assertThrows action = do
-    result <- try (void action)
-    case result of
-        Left (_ :: SomeException) -> pure ()
-        Right () -> assertFailure "expected an exception"
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+
+-- |
+-- Module      : CoreRegressionTests
+-- Description : Regression tests for result metadata, cursor state, and handle lifetime.
+module CoreRegressionTests (coreRegressionTests) where
+
+import Control.Concurrent (forkFinally, killThread, newEmptyMVar, putMVar, readMVar, takeMVar, threadDelay)
+import Control.Exception (AsyncException (ThreadKilled), IOException, SomeException, bracket, finally, throw, throwIO, try)
+import Control.Monad (forM_, forever, replicateM, replicateM_, void, when)
+import Data.Either (partitionEithers)
+import Data.IORef (IORef, atomicModifyIORef', modifyIORef', newIORef, readIORef)
+import Data.Int (Int64)
+import Data.List (isInfixOf)
+import Data.Text (Text)
+import qualified Data.Text as Text
+import qualified Database.DuckDB.FFI.V2 as Raw
+import Database.DuckDB.Simple
+import qualified Database.DuckDB.Simple.Catalog as Catalog
+import qualified Database.DuckDB.Simple.Config as Config
+import qualified Database.DuckDB.Simple.Copy as Copy
+import Database.DuckDB.Simple.FromField (BitString (..), FieldValue)
+import Database.DuckDB.Simple.Internal (
+  DuckDBV2ResultHandle (..),
+  Statement (statementStream),
+  StatementStream (statementStreamResult),
+  StatementStreamState (..),
+  checked,
+  executePreparedResult,
+  nullHandle,
+  output,
+  withCollectionStatement,
+  withConnectionFactory,
+  withConnectionHandle,
+ )
+import qualified Database.DuckDB.Simple.Internal as Internal
+import qualified Database.DuckDB.Simple.Logging as Logging
+import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep (..))
+import Database.DuckDB.Simple.Pragma (PragmaCallback (..), registerPragmaFunction)
+import Database.DuckDB.Simple.Registration (
+  Replacement (..),
+  TypeDeclaration (..),
+  parameter,
+  registerInstanceReplacementScan,
+  registerReplacementScan,
+ )
+import qualified Database.DuckDB.Simple.Streaming as Streaming
+import Foreign.C.ConstPtr (ConstPtr (..))
+import Foreign.Marshal.Array (withArray)
+import System.Directory (canonicalizePath, createDirectory, getTemporaryDirectory, listDirectory, removeFile, removePathForcibly)
+import System.FilePath ((</>))
+import System.IO (hClose, openBinaryTempFile)
+import System.Mem (performMajorGC)
+import System.Timeout (timeout)
+import Test.Tasty (TestTree, testGroup)
+import Test.Tasty.HUnit
+import TestUtils (assertInputError, assertReusable, assertSqlErrorType, raiseCapabilities)
+
+-- | Exercise public operations against an in-memory database.
+coreRegressionTests :: TestTree
+coreRegressionTests =
+  testGroup
+    "core regressions"
+    [ testCase "stream metadata follows parameter types" $
+        withConnection ":memory:" $ \conn -> do
+          rows <- fold conn "SELECT ?" (Only (42 :: Int64)) [] collect
+          rows @?= [Only (42 :: Int64)]
+    , testCase "cursor uses the supported materialized execution API" $
+        withConnection ":memory:" $ \conn ->
+          withStatement conn "SELECT i FROM range(10000) t(i)" $ \stmt -> do
+            void (nextRow stmt :: IO (Maybe (Only Int64)))
+            state <- readIORef (statementStream stmt)
+            case state of
+              StatementStreamActive stream -> do
+                assertBool "expected a released execution cursor" (statementStreamResult stream == nullHandle)
+              _ -> assertFailure "expected an active cursor"
+    , testCase "stream metadata preserves 64-bit values" $
+        withConnection ":memory:" $ \conn -> do
+          rows <- fold conn "SELECT coalesce(?, 1) FROM range(3)" (Only (5000000000 :: Int64)) [] collect
+          rows @?= replicate 3 (Only (5000000000 :: Int64))
+    , testCase "stream numeric to Text conversion uses result metadata" $
+        withConnection ":memory:" $ \conn -> do
+          rows <- fold conn "SELECT coalesce(?, 'x')" (Only (100 :: Int64)) [] collect
+          rows @?= [Only ("100" :: Text)]
+    , testCase "stream metadata follows schema rebinding" $
+        withConnection ":memory:" $ \conn -> do
+          void $ execute_ conn "CREATE TABLE rebind_probe(x VARCHAR)"
+          withStatement conn "SELECT x FROM rebind_probe" $ \stmt -> do
+            void $ execute_ conn "DROP TABLE rebind_probe"
+            void $ execute_ conn "CREATE TABLE rebind_probe(x BIGINT)"
+            void $ execute_ conn "INSERT INTO rebind_probe VALUES (5000000000)"
+            nextRow stmt >>= (@?= Just (Only (5000000000 :: Int64)))
+    , testCase "reset metadata follows an altered result schema" $
+        withConnection ":memory:" $ \conn -> do
+          void $ execute_ conn "CREATE TABLE metadata_rebind(x BIGINT)"
+          withStatement conn "SELECT * FROM metadata_rebind" $ \stmt -> do
+            columnCount stmt >>= (@?= 1)
+            void $ execute_ conn "ALTER TABLE metadata_rebind ADD COLUMN y VARCHAR"
+            clearStatementBindings stmt
+            columnCount stmt >>= (@?= 2)
+            columnName stmt 1 >>= (@?= "y")
+    , testCase "EOF remains exhausted" $
+        withConnection ":memory:" $ \conn ->
+          withStatement conn "SELECT 42" $ \stmt -> do
+            nextRow stmt >>= (@?= Just (Only (42 :: Int64)))
+            replicateM_ 3 $ nextRow stmt >>= (@?= (Nothing :: Maybe (Only Int64)))
+    , testCase "DML cursor executes only once" $
+        withConnection ":memory:" $ \conn -> do
+          void $ execute_ conn "CREATE TABLE once_probe(x INTEGER)"
+          withStatement conn "INSERT INTO once_probe VALUES (1)" $ \stmt -> do
+            nextRow stmt >>= (@?= Just (Only (1 :: Int64)))
+            replicateM_ 3 $ nextRow stmt >>= (@?= (Nothing :: Maybe (Only Int64)))
+          query_ conn "SELECT count(*) FROM once_probe" >>= (@?= [Only (1 :: Int64)])
+    , testCase "queries and folds give the changed-row count of a DML statement" $
+        withConnection ":memory:" $ \conn -> do
+          void (execute_ conn "CREATE TABLE changed_rows(value BIGINT)")
+          (query_ conn "INSERT INTO changed_rows VALUES (1),(2)" :: IO [Only Int64]) >>= (@?= [Only 2])
+          (query conn "INSERT INTO changed_rows VALUES (?)" (Only (3 :: Int64)) :: IO [Only Int64]) >>= (@?= [Only 1])
+          (queryNamed conn "UPDATE changed_rows SET value=value+10 WHERE value<=$limit" ["limit" := (2 :: Int64)] :: IO [Only Int64])
+            >>= (@?= [Only 2])
+          (query_ conn "DELETE FROM changed_rows WHERE false" :: IO [Only Int64]) >>= (@?= [Only 0])
+          fold_ conn "INSERT INTO changed_rows VALUES (4)" [] collect >>= (@?= [Only (1 :: Int64)])
+          fold conn "INSERT INTO changed_rows VALUES (?)" (Only (5 :: Int64)) [] collect >>= (@?= [Only (1 :: Int64)])
+          foldNamed conn "UPDATE changed_rows SET value=value+10 WHERE value<=$limit" ["limit" := (4 :: Int64)] [] collect
+            >>= (@?= [Only (2 :: Int64)])
+          query_ conn "SELECT value FROM changed_rows ORDER BY value" >>= (@?= map Only [5, 11, 12, 13, 14 :: Int64])
+    , testCase "rebinding resets an exhausted cursor" $
+        withConnection ":memory:" $ \conn ->
+          withStatement conn "SELECT ?::BIGINT" $ \stmt -> do
+            bind stmt [toField (1 :: Int64)]
+            nextRow stmt >>= (@?= Just (Only (1 :: Int64)))
+            nextRow stmt >>= (@?= (Nothing :: Maybe (Only Int64)))
+            bind stmt [toField (2 :: Int64)]
+            nextRow stmt >>= (@?= Just (Only (2 :: Int64)))
+    , testCase "failed replacement retains complete bindings and resets the cursor" $
+        withConnection ":memory:" $ \conn ->
+          withStatement conn "SELECT ?::BIGINT, ?::BIGINT, ?::BIGINT FROM range(2)" $ \stmt -> do
+            let original = (1, 2, 3) :: (Int64, Int64, Int64)
+            bind stmt [toField (1 :: Int64), toField (2 :: Int64), toField (3 :: Int64)]
+            nextRow stmt >>= (@?= Just original)
+            assertInputError (bind stmt [toField (4 :: Int64), toField (BitString 8 "x"), toField (6 :: Int64)])
+            nextRow stmt >>= (@?= Just original)
+            interrupted <- try (bind stmt [toField (7 :: Int64), throw ThreadKilled, toField (9 :: Int64)]) :: IO (Either AsyncException ())
+            interrupted @?= Left ThreadKilled
+            nextRow stmt >>= (@?= Just original)
+            nextRow stmt >>= (@?= Just original)
+            nextRow stmt >>= (@?= (Nothing :: Maybe (Int64, Int64, Int64)))
+            bind stmt [toField (10 :: Int64), toField (11 :: Int64), toField (12 :: Int64)]
+            nextRow stmt >>= (@?= Just (10 :: Int64, 11 :: Int64, 12 :: Int64))
+    , testCase "clear bindings invalidates an active cursor" $
+        withConnection ":memory:" $ \conn ->
+          withStatement conn "SELECT ?::BIGINT FROM range(3)" $ \stmt -> do
+            bind stmt [toField (7 :: Int64)]
+            void (nextRow stmt :: IO (Maybe (Only Int64)))
+            clearStatementBindings stmt
+            assertSqlErrorType ErrorInputInvalid (nextRow stmt :: IO (Maybe (Only Int64)))
+    , testCase "fetch errors are not EOF" $
+        withConnectionWithConfig ":memory:" [("threads", "1")] $ \conn ->
+          assertSqlErrorType
+            ErrorInputInvalid
+            ( fold_
+                conn
+                "SELECT CASE WHEN i = 5000 THEN error('late failure') ELSE i END FROM range(10000) t(i)"
+                (0 :: Int64)
+                (\acc (Only n) -> pure (acc + n))
+            )
+    , testCase "composite cursors preserve values after chunk cleanup" $
+        withConnectionWithConfig ":memory:" [("threads", "1")] $ \conn ->
+          forM_
+            [ "SELECT {'n': i, 'text': 'λ' || i::VARCHAR} FROM range(5000) t(i)"
+            , "SELECT CASE WHEN i % 2 = 0 THEN union_value(n := i)::UNION(n BIGINT, text VARCHAR) ELSE union_value(text := i::VARCHAR)::UNION(n BIGINT, text VARCHAR) END FROM range(5000) t(i)"
+            , "SELECT CASE WHEN i % 3 = 0 THEN NULL ELSE {'n': i, 'list': [i, NULL], 'union': union_value(v := i)} END FROM range(5000) t(i)"
+            ]
+            $ \sql -> do
+              eager <- query_ conn sql :: IO [Only FieldValue]
+              streamed <- reverse <$> fold_ conn sql [] (\acc row -> pure (row : acc))
+              streamed @?= eager
+    , -- The case of the leak test for a statement that closes with a live cursor
+      -- checks the release of the chunks.
+      testCase "composite fold failures raise their error and leave the connection usable" $
+        withConnectionWithConfig ":memory:" [("threads", "1")] $ \conn -> do
+          let sql = "SELECT {'n': i, 'values': [i, NULL]} FROM range(5000) t(i)"
+          -- A STRUCT does not convert to Int64. The conversion error names the
+          -- Haskell type and the query.
+          conversion <- try (fold_ conn sql () (\() (Only (_ :: Int64)) -> pure ()))
+          case conversion of
+            Left err -> do
+              assertBool (Text.unpack (sqlErrorMessage err)) ("Int64" `Text.isInfixOf` sqlErrorMessage err)
+              sqlErrorQuery err @?= Just sql
+            Right () -> assertFailure "expected the conversion error"
+          stepFailure <- try $ fold_ conn sql (0 :: Int) $ \n (Only (_ :: FieldValue)) ->
+            if n == 2050 then throwIO (userError "composite fold failure") else pure (n + 1)
+          case stepFailure of
+            Left (err :: IOException) -> show err @?= "user error (composite fold failure)"
+            Right count -> assertFailure ("expected the step failure, got " <> show count)
+          query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+    , testCase "closed connection rejects active cursor reads" $ do
+        conn <- open ":memory:"
+        stmt <- openStatement conn "SELECT i FROM range(3) t(i)"
+        void (nextRow stmt :: IO (Maybe (Only Int64)))
+        close conn
+        assertThrows (nextRow stmt :: IO (Maybe (Only Int64)))
+        closeStatement stmt
+    , testCase "NUL in SQL is rejected" $
+        withConnection ":memory:" $ \conn ->
+          assertInputError (query_ conn "SELECT 1\0 + 2" :: IO [Only Int64])
+    , testCase "NUL in database path is rejected" $
+        assertInputError (withConnection ":memory:\0suffix" (const (pure ())))
+    , testCase "NUL in configuration value is rejected" $
+        assertInputError (withConnectionWithConfig ":memory:" [("threads", "1\0suffix")] (const (pure ())))
+    , testCase "a column index out of bounds raises the input error with the query" $
+        withConnection ":memory:" $ \conn ->
+          withStatement conn "SELECT 1 AS a" $ \stmt ->
+            forM_ [-1, 1] $ \index -> do
+              assertInputError (columnName stmt index)
+              result <- try (columnName stmt index)
+              case result of
+                Left (err :: SQLError) -> sqlErrorQuery err @?= Just "SELECT 1 AS a"
+                Right name -> assertFailure ("expected the column index error, got " <> show name)
+    , testCase "NUL in parameter name is rejected" $
+        withConnection ":memory:" $ \conn ->
+          withStatement conn "SELECT $value" $ \stmt ->
+            assertInputError (namedParameterIndex stmt "value\0suffix")
+    , testCase "duplicate named bindings are rejected" $
+        withConnection ":memory:" $ \conn ->
+          withStatement conn "SELECT $foo + $bar" $ \stmt ->
+            forM_ ["$foo", "FOO"] $ \duplicate -> do
+              result <- try (bindNamed stmt ["foo" := (1 :: Int64), duplicate := (2 :: Int64)])
+              case result of
+                Left (_ :: FormatError) -> pure ()
+                Right () -> assertFailure "expected duplicate binding error before execution"
+    , testCase "named bindings retain distinct Unicode names" $
+        withConnection ":memory:" $ \conn ->
+          (queryNamed conn "SELECT $Straße::BIGINT, $STRASSE::BIGINT" ["Straße" := (1 :: Int64), "STRASSE" := (2 :: Int64)] :: IO [(Int64, Int64)])
+            >>= (@?= [(1, 2)])
+    , testCase "numeric named bindings retain sparse and reordered parameter names" $
+        withConnection ":memory:" $ \conn -> do
+          (queryNamed conn "SELECT $3::BIGINT" ["3" := (33 :: Int64)] :: IO [Only Int64]) >>= (@?= [Only 33])
+          (queryNamed conn "SELECT $3::BIGINT, $1::BIGINT, $3::BIGINT" ["1" := (11 :: Int64), "3" := (33 :: Int64)] :: IO [(Int64, Int64, Int64)])
+            >>= (@?= [(33, 11, 33)])
+          (query conn "SELECT ?::BIGINT, ?::BIGINT" ((1 :: Int64), (2 :: Int64)) :: IO [(Int64, Int64)]) >>= (@?= [(1, 2)])
+          (query conn "SELECT $02::BIGINT, $01::BIGINT" ((11 :: Int64), (22 :: Int64)) :: IO [(Int64, Int64)]) >>= (@?= [(22, 11)])
+    , testCase "a quoted parameter can start with a binding prefix" $
+        withConnection ":memory:" $ \conn -> do
+          let sql = "SELECT $foo::BIGINT, $\"$foo\"::BIGINT, $\":foo\"::BIGINT, $\"@foo\"::BIGINT"
+              names = ["$FOO", "$$foo", "$:foo", "$@foo"]
+          withStatement conn sql $ \stmt -> do
+            mapM (namedParameterIndex stmt) names >>= (@?= map Just [1 .. 4])
+            bindNamed stmt [name := value | (name, value) <- zip names [1 .. 4 :: Int64]]
+            nextRow stmt >>= (@?= Just (1 :: Int64, 2 :: Int64, 3 :: Int64, 4 :: Int64))
+          withStatement conn "SELECT $\"$1\"::BIGINT" $ \stmt -> do
+            outcome <- try (bind stmt [toField (5 :: Int64)])
+            case outcome of
+              Left (_ :: FormatError) -> pure ()
+              Right () -> assertFailure "a literal dollar sign is part of the name"
+            bindNamed stmt ["$$1" := (5 :: Int64)]
+            nextRow stmt >>= (@?= Just (Only (5 :: Int64)))
+    , testCase "quoted numeric names remain named parameters" $
+        withConnection ":memory:" $ \conn ->
+          forM_
+            [ ("SELECT $foo::BIGINT, $\"2\"::BIGINT", "foo")
+            , ("SELECT $\"01\"::BIGINT, $\"2\"::BIGINT", "01")
+            , ("SELECT $`0`::BIGINT, $`2`::BIGINT", "0")
+            ]
+            $ \(sql, first) -> do
+              (queryNamed conn sql [first := (11 :: Int64), "2" := (22 :: Int64)] :: IO [(Int64, Int64)]) >>= (@?= [(11, 22)])
+              Internal.withParsedStatements conn sql $ \parsed -> case parsed of
+                [raw] -> bracket (Internal.createStatementFromParsed conn "SELECT ?, ?" raw) closeStatement $ \stmt -> do
+                  namedParameterIndex stmt first >>= (@?= Just 1)
+                  outcome <- try (bind stmt [toField (11 :: Int64), toField (22 :: Int64)])
+                  case outcome of
+                    Left (_ :: FormatError) -> pure ()
+                    Right () -> assertFailure "expected positional binding rejection for quoted names"
+                _ -> assertFailure "expected one parsed statement"
+    , testCase "statements bind several thousand parameters by position and by name" $
+        withConnection ":memory:" $ \conn -> do
+          let count = 3000 :: Int
+              values = [1 .. fromIntegral count] :: [Int64]
+              listSum items = Query ("SELECT list_sum([" <> Text.intercalate "," items <> "])")
+              name index = "p" <> Text.pack (show index)
+          (query conn (listSum (replicate count "?::BIGINT")) values :: IO [Only Int64]) >>= (@?= [Only (sum values)])
+          ( queryNamed
+              conn
+              (listSum ["$" <> name index <> "::BIGINT" | index <- [1 .. count]])
+              [name index := value | (index, value) <- zip [1 :: Int ..] values]
+              :: IO [Only Int64]
+            )
+            >>= (@?= [Only (sum values)])
+          -- Dense numbered parameters bind by position despite their SQL order.
+          (query conn "SELECT $2::BIGINT, $1::BIGINT, $3::BIGINT" (1 :: Int64, 2 :: Int64, 3 :: Int64) :: IO [(Int64, Int64, Int64)])
+            >>= (@?= [(2, 1, 3)])
+          (queryNamed conn "SELECT $1::BIGINT, $3::BIGINT" ["1" := (11 :: Int64), "3" := (33 :: Int64)] :: IO [(Int64, Int64)]) >>= (@?= [(11, 33)])
+          assertThrows (query conn "SELECT $1::BIGINT, $3::BIGINT" (11 :: Int64, 33 :: Int64) :: IO [(Int64, Int64)])
+    , testCase "transaction preserves the original exception if rollback fails" $
+        withConnection ":memory:" $ \conn -> do
+          result <- try $ withTransaction conn $ do
+            void $ execute_ conn "ROLLBACK"
+            throwIO (userError "original transaction failure")
+          case result of
+            Left (err :: IOError) -> assertBool "original exception" ("original transaction failure" `isInfixOf` show err)
+            Right () -> assertFailure "expected transaction failure"
+    , testCase "a callback exception of each kind fails its statement in a transaction and leaves no rows" $
+        mapM_ runFailingCallback failingCallbacks
+    , testCase "materialization reports a late error before the first callback" $
+        withConnectionWithConfig ":memory:" [("threads", "1")] $ \conn -> do
+          calls <- newIORef (0 :: Int)
+          assertSqlErrorType ErrorInputInvalid $ fold_ conn "SELECT CASE WHEN i = 5000 THEN error('late failure') ELSE i END FROM range(10000) t(i)" () $ \() (Only (_ :: Int64)) ->
+            modifyIORef' calls (+ 1)
+          readIORef calls >>= (@?= 0)
+    , testCase "a materialized callback can query the same connection" $
+        withConnection ":memory:" $ \conn -> do
+          count <- fold_ conn "SELECT i FROM range(3) t(i)" (0 :: Int) $ \acc (Only (_ :: Int64)) -> do
+            query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+            pure (acc + 1)
+          count @?= 3
+    , testCase "threads share a connection for default queries" $
+        do
+          -- See Note [Capabilities of the tests] in "TestUtils".
+          raiseCapabilities 4
+          withConnection ":memory:" $ \conn -> do
+            void (execute_ conn "CREATE TABLE shared_rows(worker BIGINT, i BIGINT)")
+            start <- newEmptyMVar
+            completed <- replicateM 8 newEmptyMVar
+            forM_ (zip [1 :: Int64 ..] completed) $ \(worker, result) ->
+              void $ flip forkFinally (putMVar result) $ do
+                readMVar start
+                forM_ [1 .. 50 :: Int64] $ \i -> do
+                  query conn "SELECT ? + ?" (worker, i) >>= (@?= [Only (worker + i)])
+                  execute conn "INSERT INTO shared_rows VALUES (?, ?)" (worker, i) >>= (@?= 1)
+                  query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+                  -- The threads share the VARIANT decoder state of the connection.
+                  query conn "SELECT ?::VARIANT, [?, ?]::VARIANT" (worker + i, worker, i) >>= (@?= [(worker + i, [worker, i])])
+                  fold_ conn "SELECT i FROM range(3) t(i)" (0 :: Int64) (\acc (Only n) -> pure (acc + n)) >>= (@?= 3)
+                  execute_ conn "UPDATE shared_rows SET i = i WHERE worker = 0" >>= (@?= 0)
+            putMVar start ()
+            outcomes <- mapM takeMVar completed
+            case partitionEithers outcomes of
+              ([], _) -> pure ()
+              (failure : _, _) -> throwIO failure
+            query_ conn "SELECT count(*) FROM shared_rows" >>= (@?= [Only (400 :: Int64)])
+    , testCase "ad hoc SQL executes statement-expanded groups" $
+        withConnection ":memory:" $ \conn -> do
+          void
+            ( execute_
+                conn
+                "CREATE TABLE pivot_probe(category VARCHAR, yr INTEGER, amount BIGINT); INSERT INTO pivot_probe VALUES ('a',2020,1),('a',2021,2)"
+            )
+          query_ conn "PIVOT pivot_probe ON yr USING sum(amount)" >>= (@?= [("a" :: Text, 1 :: Int64, 2 :: Int64)])
+          void (execute_ conn "ALTER TABLE pivot_probe ADD COLUMN extra DOUBLE DEFAULT random()")
+          query_ conn "SELECT count(*) FROM pivot_probe WHERE extra IS NOT NULL" >>= (@?= [Only (2 :: Int64)])
+    , testCase "a prepared PIVOT refreshes its result schema on each execution" $
+        withConnection ":memory:" $ \conn -> do
+          void
+            ( execute_
+                conn
+                "CREATE TABLE prepared_pivot(category VARCHAR, yr INTEGER, amount BIGINT); INSERT INTO prepared_pivot VALUES ('a',2020,1),('a',2021,2)"
+            )
+          withStatement conn "PIVOT prepared_pivot ON yr USING sum(amount)" $ \stmt -> do
+            nextRow stmt >>= (@?= Just ("a" :: Text, 1 :: Int64, 2 :: Int64))
+            nextRow stmt >>= (@?= (Nothing :: Maybe (Text, Int64, Int64)))
+            void (execute_ conn "INSERT INTO prepared_pivot VALUES ('a',2022,3)")
+            clearStatementBindings stmt
+            nextRow stmt >>= (@?= Just ("a" :: Text, 1 :: Int64, 2 :: Int64, 3 :: Int64))
+            nextRow stmt >>= (@?= (Nothing :: Maybe (Text, Int64, Int64, Int64)))
+    , testCase "a scoped collection statement retains named input and parameter metadata" $
+        withConnection ":memory:" $ \conn ->
+          withConnectionHandle conn $ \native -> withConnectionFactory native $ \factory ->
+            withStatement conn "SELECT 42::BIGINT" $ \source ->
+              bracket (executePreparedResult source) (Internal.destroy Raw.c_duckdb_v2_result_destroy) $ \result ->
+                bracket (output (Raw.c_duckdb_v2_result_fetch_chunk result)) (Internal.destroy Raw.c_duckdb_v2_data_chunk_destroy) $ \chunk -> do
+                  bracket (output (Raw.c_duckdb_v2_result_fetch_chunk result)) (Internal.destroy Raw.c_duckdb_v2_data_chunk_destroy) $ \end ->
+                    end @?= nullHandle
+                  vector <- output (Raw.c_duckdb_v2_data_chunk_get_vector chunk 0)
+                  bracket (output (Raw.c_duckdb_v2_vector_get_logical_type vector)) (Internal.destroy Raw.c_duckdb_v2_logical_type_destroy) $ \logical ->
+                    withArray [logical] $ \types ->
+                      bracket
+                        (output (Raw.c_duckdb_v2_column_data_collection_create factory (ConstPtr types) 1))
+                        (Internal.destroy Raw.c_duckdb_v2_column_data_collection_destroy)
+                        $ \collection -> do
+                          let checkRows :: Maybe (Only Int64) -> IO ()
+                              checkRows expected = withCollectionStatement conn "SELECT payload + ?::BIGINT FROM input_rows" [("input_rows", collection, ["payload"])] $ \stmt -> do
+                                bind stmt [toField (1 :: Int64)]
+                                nextRow stmt >>= (@?= expected)
+                                nextRow stmt >>= (@?= (Nothing :: Maybe (Only Int64)))
+                          checkRows Nothing
+                          bracket
+                            (output (Raw.c_duckdb_v2_column_data_collection_append_state_create collection))
+                            (Internal.destroy Raw.c_duckdb_v2_column_data_collection_append_state_destroy)
+                            $ \appendState ->
+                              checked (Raw.c_duckdb_v2_column_data_collection_append collection appendState chunk)
+                          checkRows (Just (Only (43 :: Int64)))
+    , testCase "connections share an explicit instance" $
+        withEnvironment $ \environment -> withInstance environment [] $ \instance_ -> do
+          attachDatabase instance_ ":memory:" "shared" []
+          setDefaultDatabase instance_ "shared"
+          withConnectionOn instance_ $ \first -> withConnectionOn instance_ $ \second -> do
+            void (execute_ first "CREATE TABLE shared_probe(x BIGINT); INSERT INTO shared_probe VALUES (42)")
+            query_ second "SELECT x FROM shared_probe" >>= (@?= [Only (42 :: Int64)])
+    , testCase "a detached database is not reachable" $
+        withEnvironment $ \environment -> withInstance environment [] $ \instance_ -> do
+          attachDatabase instance_ ":memory:" "shared" []
+          setDefaultDatabase instance_ "shared"
+          attachDatabase instance_ ":memory:" "side" []
+          withConnectionOn instance_ $ \conn -> do
+            void (execute_ conn "CREATE TABLE side.probe(x BIGINT); INSERT INTO side.probe VALUES (7)")
+            query_ conn "SELECT x FROM side.probe" >>= (@?= [Only (7 :: Int64)])
+          detachDatabase instance_ "side"
+          withConnectionOn instance_ $ \conn -> do
+            query_ conn "SELECT count(*) FROM duckdb_databases() WHERE database_name = 'side'" >>= (@?= [Only (0 :: Int64)])
+            assertSqlErrorType ErrorDatabaseCatalog (query_ conn "SELECT x FROM side.probe" :: IO [Only Int64])
+            query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+          -- The native detach call gives this type. The SQL statement DETACH gives
+          -- a Binder Error.
+          assertSqlErrorType ErrorInputInvalid (detachDatabase instance_ "side")
+    , testCase "NUL in attach options and aliases is rejected" $
+        withEnvironment $ \environment -> withInstance environment [] $ \instance_ -> do
+          attachDatabase instance_ ":memory:" "shared" []
+          setDefaultDatabase instance_ "shared"
+          forM_
+            [ attachDatabase instance_ ":memory:" "side" [("read_only\0suffix", "false")]
+            , attachDatabase instance_ ":memory:" "side" [("read_only", "false\0suffix")]
+            , detachDatabase instance_ "shared\0suffix"
+            , setDefaultDatabase instance_ "shared\0suffix"
+            ]
+            $ \action -> do
+              result <- try action
+              case result of
+                Left (err :: SQLError) -> do
+                  sqlErrorType err @?= Just ErrorInputInvalid
+                  assertBool "NUL diagnostic" ("contains NUL" `Text.isInfixOf` sqlErrorMessage err)
+                Right () -> assertFailure "expected a NUL error"
+          withConnectionOn instance_ $ \conn ->
+            query_ conn "SELECT current_database(), count(*) FILTER (WHERE database_name = 'side') FROM duckdb_databases()"
+              >>= (@?= [("shared" :: Text, 0 :: Int64)])
+    , testCase "parent close releases concurrently created children" $
+        do
+          -- See Note [Capabilities of the tests] in "TestUtils".
+          raiseCapabilities 2
+          withEnvironment $ \environment -> withInstance environment [("threads", "1"), ("async_threads", "1")] $ \instance_ ->
+            withConcurrentChildren 64 (connect instance_) close $ \connections -> do
+              closeInstance instance_
+              forM_ connections $ \connection -> do
+                state <- readIORef (Internal.connectionState connection)
+                case state of
+                  Internal.ConnectionClosed -> pure ()
+                  Internal.ConnectionOpen{} -> assertFailure "parent close missed a connection"
+                assertThrows (query_ connection "SELECT 42" :: IO [Only Int64])
+          withEnvironment $ \environment ->
+            withConcurrentChildren 16 (createInstance environment [("threads", "1"), ("async_threads", "1")]) closeInstance $ \instances -> do
+              closeEnvironment environment
+              forM_ instances $ \instance_ -> do
+                state <- readIORef (Internal.instanceState instance_)
+                case state of
+                  Internal.InstanceClosed -> pure ()
+                  Internal.InstanceOpen{} -> assertFailure "parent close missed an instance"
+                assertThrows (connect instance_)
+    , testCase "startup configuration sets the whitelist before disabling external access" $ do
+        path <- canonicalizePath "/tmp/duckdb-whitelist-probe"
+        withConnectionWithConfig ":memory:" [("enable_external_access", "false"), ("allowed_paths", "['/tmp/duckdb-whitelist-probe']")] $ \conn ->
+          query conn "SELECT current_setting('enable_external_access'), list_contains(current_setting('allowed_paths'), ?)" (Only path)
+            >>= (@?= [(False, True)])
+    , testCase "environment close ends the live cursors of its connections" $ do
+        environment <- createEnvironment
+        instance_ <- createInstance environment []
+        attachDatabase instance_ ":memory:" "shared" []
+        setDefaultDatabase instance_ "shared"
+        conn <- connect instance_
+        stmt <- openStatement conn "SELECT i FROM range(5000) t(i)"
+        nextRow stmt >>= (@?= Just (Only (0 :: Int64)))
+        replicateM_ 20 (void (openStatement conn "SELECT 42"))
+        performMajorGC
+        closeEnvironment environment
+        cursor <- readIORef (statementStream stmt)
+        case cursor of
+          StatementStreamActive _ -> assertFailure "the environment close left the cursor of the statement active"
+          _ -> pure ()
+        assertThrows (nextRow stmt :: IO (Maybe (Only Int64)))
+        assertThrows (query_ conn "SELECT 42" :: IO [Only Int64])
+        closeStatement stmt
+        close conn
+        closeInstance instance_
+        closeEnvironment environment
+    , testCase "a refused environment close keeps the environment open" $ do
+        environment <- createEnvironment
+        state <- readIORef (Internal.environmentState environment)
+        raw <- case state of
+          Internal.EnvironmentOpen raw _ -> pure raw
+          Internal.EnvironmentClosed -> assertFailure "a new environment is closed"
+        -- The library does not track this instance, so it does not close it.
+        untracked <- output (Raw.c_duckdb_v2_instance_create raw)
+        refused <- try (closeEnvironment environment)
+        case refused of
+          Left (err :: SQLError) -> sqlErrorType err @?= Just ErrorResourceInUse
+          Right () -> assertFailure "expected a refused close"
+        -- Keep this instance open. The second close must find it in the child registry.
+        instance_ <- createInstance environment []
+        withConnectionOn instance_ $ \conn -> query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+        Internal.destroy Raw.c_duckdb_v2_instance_destroy untracked
+        closeEnvironment environment
+        assertThrows (connect instance_)
+        closed <- try (createInstance environment [])
+        case closed of
+          Left (err :: SQLError) -> sqlErrorMessage err @?= "duckdb-simple: environment is closed"
+          Right _ -> assertFailure "expected a closed environment"
+    , testCase "GC releases an unclosed convenience connection" $ do
+        directory <- getTemporaryDirectory
+        (path, file) <- openBinaryTempFile directory "duckdb-v2-gc.duckdb"
+        hClose file
+        removeFile path
+        let allocate = do
+              conn <- openWithConfig path [("threads", "1")]
+              void (execute_ conn "CREATE TABLE gc_probe AS SELECT 42::BIGINT AS x")
+            wait = do
+              performMajorGC
+              reopened <- try $ withConnectionWithConfig path [("threads", "1")] $ \conn ->
+                query_ conn "SELECT x FROM gc_probe" >>= (@?= [Only (42 :: Int64)])
+              case reopened of
+                Right () -> pure ()
+                Left (_ :: SQLError) -> threadDelay 10000 >> wait
+        flip finally (removeFile path) $ do
+          allocate
+          released <- timeout 60000000 wait
+          released @?= Just ()
+    , testCase "GC during the last connection use keeps native owners alive" $ do
+        -- A bracket cleanup would retain conn and hide early finalization.
+        conn <- open ":memory:"
+        createFunction conn "gc_identity" (\(n :: Int64) -> performMajorGC >> pure n)
+        rows <- query_ conn "SELECT gc_identity(i) FROM range(10) t(i)"
+        rows @?= map Only ([0 .. 9] :: [Int64])
+    , testCase "GC during the last statement use keeps cached schemas alive" $
+        withConnectionWithConfig ":memory:" [("threads", "1")] $ \conn -> do
+          let name = Text.replicate 4096 "x"
+              sql = Query ("SELECT 1 AS \"" <> name <> "\"")
+              collectGarbage = forever (performMajorGC >> threadDelay 1000)
+          done <- newEmptyMVar
+          -- A bracket around each statement would keep it alive after the read.
+          bracket (forkFinally collectGarbage (putMVar done)) (\worker -> killThread worker >> void (readMVar done)) $ \_ ->
+            replicateM_ 100 $ do
+              (openStatement conn sql >>= columnCount) >>= (@?= 1)
+              (openStatement conn sql >>= \stmt -> columnName stmt 0) >>= (@?= name)
+              (openStatement conn "SELECT ?::BIGINT" >>= \stmt -> Internal.preparedParameterType stmt 1)
+                >>= (@?= Just (LogicalTypeScalar Internal.LogicalTypeIdBigInt))
+    , testCase "a prepare of no statement or of two statements raises its error" $ withConnection ":memory:" $ \conn ->
+        forM_
+          [ ("", "duckdb-simple: SQL query contains no statement")
+          , ("-- a comment only", "duckdb-simple: SQL query contains no statement")
+          , ("SELECT 1; SELECT 2", "duckdb-simple: prepared SQL contains more than one statement")
+          ]
+          $ \(sql, message) -> do
+            outcome <- try (openStatement conn (Query sql))
+            case outcome of
+              Left err -> do
+                sqlErrorMessage err @?= message
+                sqlErrorQuery err @?= Just (Query sql)
+              Right stmt -> closeStatement stmt >> assertFailure ("expected an error for " <> show sql)
+    , testCase "named and indexed statement access raises the errors of the library" $
+        withConnection ":memory:" $ \conn -> withStatement conn "SELECT $value AS v" $ \stmt -> do
+          nulName <- try (bindNamed stmt ["value\0x" := (1 :: Int64)])
+          case nulName of
+            Left err -> do
+              sqlErrorMessage err @?= "duckdb-simple: parameter name contains NUL"
+              sqlErrorQuery err @?= Just "SELECT $value AS v"
+            Right () -> assertFailure "expected the NUL error"
+          tooMany <- try (bindNamed stmt ["value" := (1 :: Int64), "other" := (2 :: Int64)])
+          case tooMany of
+            Left err -> formatErrorMessage err @?= "duckdb-simple: SQL query contains 1 named parameter(s), but 2 argument(s) were supplied"
+            Right () -> assertFailure "expected the count error"
+          negativeIndex <- try (columnName stmt (-1))
+          case negativeIndex of
+            Left err -> sqlErrorMessage err @?= "duckdb-simple: column index -1 out of bounds"
+            Right name -> assertFailure ("expected the index error, got " <> show name)
+          -- The statement still works after the errors.
+          bindNamed stmt ["value" := (7 :: Int64)]
+          nextRow stmt >>= (@?= Just (Only (7 :: Int64)))
+    , testCase "connection options with NUL raise an error before the connection opens" $
+        withEnvironment $ \environment -> withInstance environment [] $ \instance_ -> do
+          attachDatabase instance_ ":memory:" "shared" []
+          setDefaultDatabase instance_ "shared"
+          outcome <- try (connectWithOptions instance_ defaultConnectionOptions{connectionConfig = [("threads\0x", "1")]})
+          case outcome of
+            Left err -> sqlErrorMessage err @?= "duckdb-simple: configuration contains NUL"
+            Right conn -> close conn >> assertFailure "expected the NUL error"
+    , testCase "statements without a query result give no row through each read function" $ withConnection ":memory:" $ \conn -> do
+        let prepend rows (Only (value :: Int64)) = pure (value : rows)
+        (query_ conn "CREATE TABLE no_rows_a (x BIGINT)" :: IO [Only Int64]) >>= (@?= [])
+        fold_ conn "CREATE TABLE no_rows_b (x BIGINT)" [] prepend >>= (@?= [])
+        withStatement conn "CREATE TABLE no_rows_c (x BIGINT)" nextRow >>= (@?= (Nothing :: Maybe (Only Int64)))
+        Streaming.fold_ conn "CREATE TABLE no_rows_d (x BIGINT)" [] prepend >>= (@?= [])
+        withStatement conn "CREATE TABLE no_rows_e (x BIGINT)" Streaming.nextRow >>= (@?= (Nothing :: Maybe (Only Int64)))
+        -- DuckDB ran each statement one time.
+        query_ conn "SELECT table_name FROM duckdb_tables() WHERE table_name LIKE 'no_rows_%' ORDER BY table_name"
+          >>= (@?= map Only ["no_rows_a", "no_rows_b", "no_rows_c", "no_rows_d", "no_rows_e" :: Text])
+    , testCase "a rejected runtime option raises the error of DuckDB and leaves the environment closable" $ do
+        environment <- createEnvironment
+        outcome <- try (createInstance environment [("logging_level", "no_such_level")])
+        case outcome of
+          Left err ->
+            assertBool
+              (Text.unpack (sqlErrorMessage err))
+              ("unrecognized value \"no_such_level\" for enum \"LogLevel\"" `Text.isInfixOf` sqlErrorMessage err)
+          Right instance_ -> closeInstance instance_ >> assertFailure "expected the error of DuckDB for logging_level"
+        -- No instance remains, so DuckDB destroys the environment.
+        closeEnvironment environment
+    , testCase "a description of a missing table raises the catalog error of DuckDB" $ withConnection ":memory:" $ \conn -> do
+        outcome <- try (Catalog.describeTable conn "no_such_table")
+        case outcome of
+          Left err -> assertBool (Text.unpack (sqlErrorMessage err)) ("Table with name no_such_table does not exist" `Text.isInfixOf` sqlErrorMessage err)
+          Right description -> assertFailure ("expected the catalog error, got " <> show (Catalog.tableDescriptionName description))
+        query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+    , testCase "an attach in a missing directory raises the IO error of DuckDB" $
+        withEnvironment $ \environment -> withInstance environment [] $ \instance_ -> do
+          outcome <- try (attachDatabase instance_ "/nonexistent-duckdb-simple/attached.db" "missing" [])
+          case outcome of
+            Left err ->
+              assertBool
+                (Text.unpack (sqlErrorMessage err))
+                ("Cannot open file \"/nonexistent-duckdb-simple/attached.db\": No such file or directory" `Text.isInfixOf` sqlErrorMessage err)
+            Right () -> assertFailure "expected the attach error"
+          -- The instance attaches another database after the failure.
+          attachDatabase instance_ ":memory:" "present" []
+          setDefaultDatabase instance_ "present"
+          withConnectionOn instance_ $ \conn -> query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+    ]
+  where
+    collect acc row = pure (acc <> [row])
+
+-- | Join all creation workers and release every acquired child after the action.
+withConcurrentChildren :: Int -> IO a -> (a -> IO ()) -> ([a] -> IO ()) -> IO ()
+withConcurrentChildren count acquire release action =
+  bracket createChildren (mapM_ release) action
+  where
+    createChildren = do
+      start <- newEmptyMVar
+      completed <- replicateM count newEmptyMVar
+      forM_ completed $ \result ->
+        void $ forkFinally (readMVar start >> acquire) (putMVar result)
+      putMVar start ()
+      outcomes <- mapM takeMVar completed
+      case partitionEithers outcomes of
+        ([], children) -> pure children
+        (failure : _, children) -> mapM_ release children >> throwIO failure
+
+-- | Require an exception without constraining its concrete type.
+assertThrows :: IO a -> Assertion
+assertThrows action = do
+  result <- try (void action)
+  case result of
+    Left (_ :: SomeException) -> pure ()
+    Right () -> assertFailure "expected an exception"
+
+-- | A callback of one kind and phase that raises an exception while DuckDB runs
+-- a statement over more than one chunk, and that statement.
+data FailingCallback = FailingCallback
+  { failingKind :: String
+  , failingLabel :: String
+  , failingThreads :: Int
+  , failingSetup :: FailingContext -> IO ()
+  , failingStatement :: FailingContext -> IO ()
+  , failingError :: Maybe (ErrorType, Text.Text)
+  -- ^ The type and a text of the error of the statement, or 'Nothing' for a
+  --   statement that does not fail, because DuckDB ignores the error of a log
+  --   sink. The callback of such a row must count its calls in
+  --   'contextCalls'.
+  }
+
+-- | The connections and the directory of one row of 'failingCallbacks'.
+data FailingContext = FailingContext
+  { contextConnection :: Connection
+  , contextOther :: Connection
+  , contextInstance :: Instance
+  , contextDirectory :: FilePath
+  , contextCalls :: IORef Int
+  }
+
+-- | Run a statement on the connection of the row.
+runIn :: FailingContext -> Query -> IO ()
+runIn context sql = void (execute_ (contextConnection context) sql)
+
+-- | Raise the exception of a row.
+failWith :: String -> IO a
+failWith text = throwIO (userError text)
+
+-- | A sum whose step, combine, or result raises an exception.
+failingSum :: (Int64 -> Bool) -> Bool -> Bool -> String -> Aggregate Int64 (Only Int64) Int64
+failingSum failStep failCombine failResult text =
+  Aggregate
+    { aggregateInitial = 0
+    , aggregateStep = \total (Only value) -> if failStep value then failWith text else pure (total + value)
+    , aggregateCombine = \a b -> if failCombine then failWith text else pure (a + b)
+    , aggregateResult = \total -> if failResult then failWith text else pure total
+    }
+
+-- | A table function of the pairs (n, f) for n from 0 to the count, whose column
+-- f raises an exception at one row.
+failingPairs :: Connection -> Text.Text -> Int64 -> String -> IO ()
+failingPairs conn name row text =
+  createTableFunction conn name ["n", "f"] \(Only count) ->
+    pure [(n, if n == row then error text else n) | n <- [0 .. count - 1 :: Int64]]
+
+-- | Each callback kind and phase in which a function of the user can fail. The
+-- statements run over 5000 rows: two full chunks of 2048 rows come before row
+-- 3000. Each kind runs one time more at 4 threads.
+failingCallbacks :: [FailingCallback]
+failingCallbacks = rows <> [row{failingThreads = 4} | row <- firstOfEachKind rows, failingThreads row == 1]
+  where
+    firstOfEachKind = foldr (\row kept -> row : filter ((/= failingKind row) . failingKind) kept) []
+    insertRows sql context = runIn context ("INSERT INTO failing_rows " <> sql)
+    countCall context = atomicModifyIORef' (contextCalls context) \count -> (count + 1, ())
+    rows =
+      [ FailingCallback
+          "scalar"
+          "scalar function with an IO result"
+          1
+          ( \context ->
+              createFunction (contextConnection context) "failing_io" \(x :: Int64) ->
+                (when (x == 3000) (failWith "failing scalar io") >> pure x :: IO Int64)
+          )
+          (insertRows "SELECT failing_io(i) FROM range(5000) t(i)")
+          (Just (ErrorInputInvalid, "failing scalar io"))
+      , FailingCallback
+          "scalar"
+          "scalar function with a pure result"
+          1
+          (\context -> createFunction (contextConnection context) "failing_pure" \(x :: Int64) -> if x == 3000 then error "failing scalar pure" else x)
+          (insertRows "SELECT failing_pure(i) FROM range(5000) t(i)")
+          (Just (ErrorInputInvalid, "failing scalar pure"))
+      , FailingCallback
+          "stateful scalar"
+          "stateful scalar function call"
+          1
+          ( \context ->
+              createFunctionWithState (contextConnection context) "failing_call" (pure ()) \() (x :: Int64) ->
+                (when (x == 3000) (failWith "failing stateful call") >> pure x :: IO Int64)
+          )
+          (insertRows "SELECT failing_call(i) FROM range(5000) t(i)")
+          (Just (ErrorInputInvalid, "failing stateful call"))
+      , FailingCallback
+          "stateful scalar"
+          "stateful scalar function init"
+          1
+          (\context -> createFunctionWithState (contextConnection context) "failing_init" (failWith "failing stateful init") \() (x :: Int64) -> x)
+          (insertRows "SELECT failing_init(i) FROM range(5000) t(i)")
+          (Just (ErrorInputInvalid, "failing stateful init"))
+      , FailingCallback
+          "aggregate"
+          "aggregate update with DISTINCT"
+          1
+          (\context -> createAggregate (contextConnection context) "failing_distinct" (failingSum (== 3000) False False "failing distinct update"))
+          (insertRows "SELECT failing_distinct(DISTINCT i) FROM range(5000) t(i)")
+          (Just (ErrorInputInvalid, "failing distinct update"))
+      , FailingCallback
+          "aggregate"
+          "aggregate update with FILTER"
+          1
+          (\context -> createAggregate (contextConnection context) "failing_filter" (failingSum (== 3000) False False "failing filter update"))
+          (insertRows "SELECT failing_filter(i) FILTER (WHERE i >= 0) FROM range(5000) t(i)")
+          (Just (ErrorInputInvalid, "failing filter update"))
+      , FailingCallback
+          "aggregate"
+          "aggregate update as a WINDOW aggregate"
+          1
+          (\context -> createAggregate (contextConnection context) "failing_window" (failingSum (== 3000) False False "failing window update"))
+          (insertRows "SELECT failing_window(i) OVER (ORDER BY i ROWS BETWEEN 2 PRECEDING AND CURRENT ROW) FROM range(5000) t(i)")
+          (Just (ErrorInputInvalid, "failing window update"))
+      , FailingCallback
+          "aggregate"
+          "aggregate combine of a plain aggregate"
+          1
+          (\context -> createAggregate (contextConnection context) "failing_combine" (failingSum (const False) True False "failing plain combine"))
+          (insertRows "SELECT failing_combine(i) FROM range(5000) t(i)")
+          (Just (ErrorInputInvalid, "failing plain combine"))
+      , -- A grouped aggregate combines only the partial states of several
+        -- threads, and DuckDB scans one row group of 122880 rows with one
+        -- thread. Thus this row needs two row groups and 4 threads.
+        FailingCallback
+          "aggregate"
+          "aggregate combine of a grouped aggregate"
+          4
+          ( \context -> do
+              runIn context "CREATE TABLE failing_groups AS SELECT i FROM range(130000) t(i)"
+              createAggregate (contextConnection context) "failing_grouped" (failingSum (const False) True False "failing grouped combine")
+          )
+          (insertRows "SELECT failing_grouped(i) FROM failing_groups GROUP BY i % 1000")
+          (Just (ErrorInputInvalid, "failing grouped combine"))
+      , FailingCallback
+          "aggregate"
+          "aggregate finalize as a WINDOW aggregate"
+          1
+          (\context -> createAggregate (contextConnection context) "failing_result" (failingSum (const False) False True "failing window finalize"))
+          (insertRows "SELECT failing_result(i) OVER (ORDER BY i ROWS BETWEEN 2 PRECEDING AND CURRENT ROW) FROM range(5000) t(i)")
+          (Just (ErrorInputInvalid, "failing window finalize"))
+      , FailingCallback
+          "table function"
+          "table function scan after rows, failing column only"
+          1
+          (\context -> failingPairs (contextConnection context) "failing_later" 3000 "failing scan at row 3000")
+          (insertRows "SELECT f FROM failing_later(5000)")
+          (Just (ErrorInputInvalid, "failing scan at row 3000"))
+      , FailingCallback
+          "table function"
+          "table function scan after rows, all columns"
+          1
+          (\context -> failingPairs (contextConnection context) "failing_later" 3000 "failing scan at row 3000")
+          (\context -> runIn context "INSERT INTO failing_pairs SELECT * FROM failing_later(5000)")
+          (Just (ErrorInputInvalid, "failing scan at row 3000"))
+      , FailingCallback
+          "table function"
+          "table function scan at row 0, failing column only"
+          1
+          (\context -> failingPairs (contextConnection context) "failing_first" 0 "failing scan at row 0")
+          (insertRows "SELECT f FROM failing_first(5000)")
+          (Just (ErrorInputInvalid, "failing scan at row 0"))
+      , FailingCallback
+          "table function"
+          "table function scan at row 0, all columns"
+          1
+          (\context -> failingPairs (contextConnection context) "failing_first" 0 "failing scan at row 0")
+          (\context -> runIn context "INSERT INTO failing_pairs SELECT * FROM failing_first(5000)")
+          (Just (ErrorInputInvalid, "failing scan at row 0"))
+      , FailingCallback
+          "table function"
+          "table function init"
+          1
+          ( \context ->
+              createTableFunction (contextConnection context) "failing_start" ["v"] \(Only (_ :: Int64)) ->
+                failWith "failing table init" :: IO [Only Int64]
+          )
+          (insertRows "SELECT v FROM failing_start(5000)")
+          (Just (ErrorInputInvalid, "failing table init"))
+      , -- The bind callback runs no function of the user. A NULL for a
+        -- parameter that cannot hold NULL fails there.
+        FailingCallback
+          "table function"
+          "table function bind"
+          1
+          (\context -> createTableFunction (contextConnection context) "failing_bind" ["v"] \(Only (count :: Int64)) -> pure [Only count])
+          (insertRows "SELECT v FROM failing_bind(NULL::BIGINT)")
+          (Just (ErrorInputInvalid, "failing_bind: argument arg0 is NULL, but Int64 cannot hold NULL"))
+      , FailingCallback
+          "table function"
+          "table function init with a failing query on another connection"
+          1
+          ( \context ->
+              createTableFunction (contextConnection context) "failing_inner" ["v"] \(Only (_ :: Int64)) ->
+                query_ (contextOther context) "SELECT 'abc'::INTEGER" :: IO [Only Int64]
+          )
+          (insertRows "SELECT v FROM failing_inner(5000)")
+          (Just (ErrorTypeConversion, "Conversion Error: Could not convert string 'abc' to INT32"))
+      , FailingCallback
+          "pragma"
+          "pragma in the call form"
+          1
+          ( \context ->
+              registerPragmaFunction
+                (contextConnection context)
+                "failing_pragma"
+                [parameter "amount" (TypeExpression "BIGINT")]
+                (ExecPragma \(Only (_ :: Int64)) -> failWith "failing pragma call")
+          )
+          (\context -> runIn context "PRAGMA failing_pragma(1)")
+          (Just (ErrorInputInvalid, "failing pragma call"))
+      , FailingCallback
+          "custom option"
+          "custom option update"
+          1
+          ( \context ->
+              Config.registerCustomOption
+                (contextConnection context)
+                (Config.customOption "failing_option" (TypeExpression "BIGINT")){Config.customOptionUpdate = Just \_ -> failWith "failing option update"}
+          )
+          (\context -> runIn context "SET failing_option = 1")
+          (Just (ErrorInputInvalid, "failing option update"))
+      , FailingCallback
+          "replacement scan"
+          "replacement scan on a connection"
+          1
+          ( \context -> registerReplacementScan (contextConnection context) \parts ->
+              if parts == ["failing_missing"] then failWith "failing replacement scan" else pure Nothing
+          )
+          (insertRows "SELECT * FROM failing_missing")
+          (Just (ErrorInputInvalid, "failing replacement scan"))
+      , FailingCallback
+          "replacement scan"
+          "replacement scan on an instance"
+          1
+          ( \context -> registerInstanceReplacementScan (contextInstance context) \parts ->
+              if parts == ["failing_missing"] then failWith "failing instance replacement scan" else pure (Nothing :: Maybe Replacement)
+          )
+          (insertRows "SELECT * FROM failing_missing")
+          (Just (ErrorInputInvalid, "failing instance replacement scan"))
+      , FailingCallback
+          "COPY TO"
+          "COPY TO sink after rows"
+          1
+          ( \context -> do
+              written <- newIORef (0 :: Int)
+              Copy.registerCopyToFunction
+                (contextConnection context)
+                "failing_copy"
+                (\_ -> pure ())
+                (\info -> writeFile (Copy.copyInitFilePath info) "" >> pure (Copy.copyInitFilePath info))
+                ( \info chunk -> do
+                    appendFile (Copy.copySinkGlobalState info) (concatMap (const "row\n") chunk)
+                    total <- atomicModifyIORef' written \count -> (count + length chunk, count + length chunk)
+                    when (total > 3000) (failWith "failing COPY TO sink")
+                )
+                (\_ -> pure ())
+          )
+          ( \context ->
+              void
+                ( execute
+                    (contextConnection context)
+                    "COPY (SELECT i FROM range(5000) t(i)) TO ? (FORMAT failing_copy)"
+                    (Only (Text.pack (contextDirectory context </> "out.txt")))
+                )
+          )
+          (Just (ErrorInputInvalid, "failing COPY TO sink"))
+      , FailingCallback
+          "COPY FROM"
+          "COPY FROM after rows"
+          1
+          ( \context -> do
+              writeFile (contextDirectory context </> "in.txt") ""
+              Copy.registerCopyFromFunction (contextConnection context) "failing_from" \_ ->
+                pure [Only (if i == 3000 then error "failing COPY FROM row" else i) | i <- [0 .. 4999 :: Int64]]
+          )
+          ( \context ->
+              void
+                ( execute
+                    (contextConnection context)
+                    "COPY failing_rows FROM ? (FORMAT failing_from)"
+                    (Only (Text.pack (contextDirectory context </> "in.txt")))
+                )
+          )
+          (Just (ErrorInputInvalid, "failing COPY FROM row"))
+      , FailingCallback
+          "multi-file function"
+          "multi-file function at its second file"
+          1
+          ( \context -> do
+              forM_ [1 :: Int .. 3] \file -> writeFile (contextDirectory context </> ("part" <> show file <> ".txt")) ""
+              createTableFunction (contextConnection context) "failing_single" ["v"] \(Only (path :: Text.Text)) -> do
+                when ("part2.txt" `Text.isSuffixOf` path) (failWith "failing second file")
+                pure [Only i | i <- [0 .. 2999 :: Int64]]
+              Copy.registerMultiFileFunction (contextConnection context) "failing_files" "failing_single" Copy.defaultMultiFileOptions
+          )
+          ( \context ->
+              void
+                ( execute
+                    (contextConnection context)
+                    "INSERT INTO failing_rows SELECT v FROM failing_files(?)"
+                    (Only (Text.pack (contextDirectory context </> "part*.txt")))
+                )
+          )
+          (Just (ErrorInputInvalid, "failing second file"))
+      , FailingCallback
+          "log sink"
+          "log sink write"
+          1
+          ( \context -> Logging.registerLogSink (contextConnection context) "failing_log" (\_ -> countCall context >> failWith "failing log write") (pure ())
+          )
+          ( \context -> runIn context "CALL enable_logging(); SET logging_storage = 'failing_log'; SELECT write_log('failing'); SET logging_storage = 'memory'"
+          )
+          Nothing
+      , FailingCallback
+          "log sink"
+          "log sink flush"
+          1
+          ( \context -> Logging.registerLogSink (contextConnection context) "failing_log" (\_ -> pure ()) (countCall context >> failWith "failing log flush")
+          )
+          ( \context -> runIn context "CALL enable_logging(); SET logging_storage = 'failing_log'; SELECT write_log('failing'); SET logging_storage = 'memory'"
+          )
+          Nothing
+      ]
+
+-- | Run one row of 'failingCallbacks' in its own instance and directory, inside
+-- an explicit transaction that has written a marker row. Require the error type
+-- and the text of the callback, then COMMIT, then a usable connection and a
+-- usable new connection of the instance, no row of the statement, no marker
+-- row, and no new file. A log sink row requires no error and a call of the
+-- sink, and keeps the marker. A new connection runs a query before the COMMIT
+-- too. The same connection runs its query only after the COMMIT, because
+-- DuckDB refuses each other statement in a transaction after a failed
+-- statement.
+runFailingCallback :: FailingCallback -> Assertion
+runFailingCallback row = bracket createRowDirectory removePathForcibly \directory ->
+  withEnvironment \environment -> withInstance environment [("threads", Text.pack (show (failingThreads row)))] \instance' ->
+    withConnection ":memory:" \other -> do
+      attachDatabase instance' ":memory:" "failing" []
+      setDefaultDatabase instance' "failing"
+      withConnectionOn instance' \conn -> do
+        calls <- newIORef 0
+        let context = FailingContext conn other instance' directory calls
+            label = failingLabel row <> " at " <> show (failingThreads row) <> " threads"
+        mapM_
+          (void . execute_ conn)
+          ["CREATE TABLE failing_rows (v BIGINT)", "CREATE TABLE failing_pairs (n BIGINT, f BIGINT)", "CREATE TABLE failing_marker (m INTEGER)"]
+        failingSetup row context
+        before <- listDirectory directory
+        void (execute_ conn "BEGIN")
+        void (execute_ conn "INSERT INTO failing_marker VALUES (1)")
+        outcome <- try (failingStatement row context)
+        case (failingError row, outcome) of
+          (Just (errorType, text), Left err) -> do
+            assertEqual label (Just errorType) (sqlErrorType err)
+            assertBool (label <> ": " <> show (sqlErrorMessage err)) (text `Text.isInfixOf` sqlErrorMessage err)
+          (Just _, Right ()) -> assertFailure (label <> ": the statement did not fail")
+          (Nothing, Left err) -> assertFailure (label <> ": " <> show err)
+          (Nothing, Right ()) -> readIORef calls >>= assertBool (label <> ": the callback ran") . (> 0)
+        withConnectionOn instance' assertReusable
+        void (execute_ conn "COMMIT")
+        assertReusable conn
+        withConnectionOn instance' assertReusable
+        let marker = maybe 1 (const 0) (failingError row) :: Int64
+        query_ conn "SELECT (SELECT count(*) FROM failing_rows), (SELECT count(*) FROM failing_pairs), (SELECT count(*) FROM failing_marker)"
+          >>= assertEqual (label <> ": rows after COMMIT") [(0 :: Int64, 0 :: Int64, marker)]
+        listDirectory directory >>= assertEqual (label <> ": files after the statement") before
+  where
+    createRowDirectory = do
+      root <- getTemporaryDirectory
+      (path, handle) <- openBinaryTempFile root "duckdb-failing-callback"
+      hClose handle
+      removeFile path
+      createDirectory path
+      pure path
diff --git a/test/ExtensionRegressionTests.hs b/test/ExtensionRegressionTests.hs
--- a/test/ExtensionRegressionTests.hs
+++ b/test/ExtensionRegressionTests.hs
@@ -2,303 +2,1018 @@
 {-# LANGUAGE FlexibleInstances #-}
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE ScopedTypeVariables #-}
-
--- | Regression tests for extension callbacks and native handle ownership.
-module ExtensionRegressionTests (main, extensionRegressionTests) where
-
-import Control.Exception (AsyncException (ThreadKilled), ErrorCall, Exception (..), SomeException, bracket, throwIO, try)
-import Control.Monad (forM_, replicateM_, void)
-import qualified Data.ByteString as BS
-import Data.IORef (modifyIORef', newIORef, readIORef)
-import Data.Int (Int64)
-import Data.Proxy (Proxy (..))
-import qualified Data.Text as Text
-import Data.Word (Word64)
-import Database.DuckDB.FFI
-import Database.DuckDB.Simple
-import qualified Database.DuckDB.Simple.Catalog as Catalog
-import qualified Database.DuckDB.Simple.Config as Config
-import qualified Database.DuckDB.Simple.Copy as Copy
-import qualified Database.DuckDB.Simple.FileSystem as FileSystem
-import qualified Database.DuckDB.Simple.Logging as Logging
-import System.Directory (removeFile)
-import System.IO (hClose, openBinaryTempFile)
-import Test.Tasty (TestTree, defaultMain, testGroup)
-import Test.Tasty.HUnit (Assertion, assertBool, assertFailure, testCase, (@?=))
-
--- | Run the extension regression tests as a standalone executable.
-main :: IO ()
-main = defaultMain extensionRegressionTests
-
--- | Check callback failures, value conversion, and resource cleanup.
-extensionRegressionTests :: TestTree
-extensionRegressionTests =
-    testGroup
-        "extension regressions"
-        [ testCase "scalar closed connection cleanup" do
-            conn <- open ":memory:"
-            close conn
-            replicateM_ 32 $ assertSqlError $ createFunction conn "closed_scalar" (1 :: Int64)
-        , testCase "stateful closed connection cleanup" do
-            conn <- open ":memory:"
-            close conn
-            replicateM_ 32 $ assertSqlError $ createFunctionWithState conn "closed_state" (pure ()) (\() -> (1 :: Int64))
-        , testCase "COPY closed connection cleanup" do
-            conn <- open ":memory:"
-            close conn
-            replicateM_ 32 $ assertSqlError $ registerCopy conn "closed_copy" Nothing
-        , testCase "logging closed connection cleanup" do
-            conn <- open ":memory:"
-            close conn
-            replicateM_ 32 $ assertSqlError $ Logging.registerLogStorage conn "closed_log" (\_ -> pure ())
-        , testCase "scalar replacement registration cleanup" $
-            withConnection ":memory:" \conn -> do
-                createFunction conn "duplicate_scalar" (42 :: Int64)
-                replicateM_ 32 $ createFunction conn "duplicate_scalar" (7 :: Int64)
-                query_ conn "SELECT duplicate_scalar()" >>= (@?= [Only (7 :: Int64)])
-        , testCase "stateful replacement registration cleanup" $
-            withConnection ":memory:" \conn -> do
-                createFunctionWithState conn "duplicate_state" (pure ()) (\() -> (42 :: Int64))
-                replicateM_ 32 $ createFunctionWithState conn "duplicate_state" (pure ()) (\() -> (7 :: Int64))
-                query_ conn "SELECT duplicate_state()" >>= (@?= [Only (7 :: Int64)])
-        , testCase "scalar invalid signature registration cleanup" $
-            withConnection ":memory:" \conn ->
-                replicateM_ 32 $ assertSqlError $ createFunction conn "invalid_scalar" InvalidSignature
-        , testCase "stateful invalid signature registration cleanup" $
-            withConnection ":memory:" \conn ->
-                replicateM_ 32 $ assertSqlError $ createFunctionWithState conn "invalid_state" (pure ()) (\() -> InvalidSignature)
-        , testCase "logging duplicate registration cleanup" $
-            withConnection ":memory:" \conn -> do
-                Logging.registerLogStorage conn "duplicate_log" (\_ -> pure ())
-                replicateM_ 32 $ assertSqlError $ Logging.registerLogStorage conn "duplicate_log" (\_ -> pure ())
-                query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
-        , testCase "empty registration names fail safely" $
-            withConnection ":memory:" \conn -> replicateM_ 32 do
-                assertSqlError $ createFunction conn "" (1 :: Int64)
-                assertSqlError $ createFunctionWithState conn "" (pure ()) (\() -> (1 :: Int64))
-                assertSqlError $ registerCopy conn "" Nothing
-                assertSqlError $ Logging.registerLogStorage conn "" (\_ -> pure ())
-        , testCase "NUL registration names fail safely" $
-            withConnection ":memory:" \conn -> do
-                assertSqlError $ createFunction conn "nul\0scalar" (1 :: Int64)
-                assertSqlError $ createFunctionWithState conn "nul\0state" (pure ()) (\() -> (1 :: Int64))
-                assertSqlError $ registerCopy conn "nul\0copy" Nothing
-                assertSqlError $ Logging.registerLogStorage conn "nul\0log" (\_ -> pure ())
-        , testCase "partial scalar setup cleanup" $
-            withConnection ":memory:" \conn -> replicateM_ 32 do
-                outcome <- try (createFunction conn "broken_signature" BrokenSignature) :: IO (Either ErrorCall ())
-                case outcome of
-                    Left _ -> pure ()
-                    Right () -> assertFailure "expected signature exception"
-        , testCase "scalar exceptions become SQL errors" $
-            withConnection ":memory:" \conn -> do
-                createFunction conn "throw_scalar" (throwIO (userError "scalar callback failure") :: IO Int64)
-                assertSqlErrorContaining "scalar callback failure" (query_ conn "SELECT throw_scalar()" :: IO [Only Int64])
-                query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
-        , testCase "exception rendering cannot escape scalar callback" $
-            withConnection ":memory:" \conn -> do
-                createFunction conn "throw_bad_display" (throwIO BrokenDisplay :: IO Int64)
-                assertSqlErrorContaining "Haskell callback failed" (query_ conn "SELECT throw_bad_display()" :: IO [Only Int64])
-        , testCase "scalar async exceptions become SQL errors" $
-            withConnection ":memory:" \conn -> do
-                createFunction conn "throw_async_scalar" (throwIO ThreadKilled :: IO Int64)
-                assertSqlErrorContaining "thread killed" (query_ conn "SELECT throw_async_scalar()" :: IO [Only Int64])
-        , testCase "scalar initializer exceptions become SQL errors" $
-            withConnection ":memory:" \conn -> do
-                createFunctionWithState conn "throw_init" (throwIO (userError "state init failure") :: IO ()) (\() -> (1 :: Int64))
-                assertSqlErrorContaining "state init failure" (query_ conn "SELECT throw_init()" :: IO [Only Int64])
-        , testCase "scalar initializer async exceptions become SQL errors" $
-            withConnection ":memory:" \conn -> do
-                createFunctionWithState conn "throw_async_init" (throwIO ThreadKilled :: IO ()) (\() -> (1 :: Int64))
-                assertSqlErrorContaining "thread killed" (query_ conn "SELECT throw_async_init()" :: IO [Only Int64])
-        , testCase "stateful scalar exceptions become SQL errors" $
-            withConnection ":memory:" \conn -> do
-                createFunctionWithState conn "throw_state" (pure ()) (\() -> throwIO (userError "state execution failure") :: IO Int64)
-                assertSqlErrorContaining "state execution failure" (query_ conn "SELECT throw_state()" :: IO [Only Int64])
-        , testCase "Float scalar results preserve NaN infinity and negative zero" $
-            withConnection ":memory:" \conn ->
-                forM_
-                    [ (0 / 0, isNaN)
-                    , (1 / 0, \value -> isInfinite value && value > 0)
-                    , (-1 / 0, \value -> isInfinite value && value < 0)
-                    , (negate 0, isNegativeZero)
-                    ]
-                    \(value, matches) -> do
-                        createFunction conn "float_value" (value :: Float)
-                        createFunctionWithState conn "float_state" (pure ()) (\() -> value)
-                        [(plain, stateful)] <- query_ conn "SELECT float_value(), float_state()" :: IO [(Double, Double)]
-                        assertBool "plain callback preserves the floating-point value" (matches plain)
-                        assertBool "stateful callback preserves the floating-point value" (matches stateful)
-        , testCase "Word64 scalar preserves unsigned maximum" $
-            withConnection ":memory:" \conn -> do
-                createFunction conn "word64_identity" (id :: Word64 -> Word64)
-                query_ conn "SELECT word64_identity(18446744073709551615::UBIGINT)" >>= (@?= [Only (maxBound :: Word64)])
-                query_ conn "SELECT typeof(word64_identity(0::UBIGINT))" >>= (@?= [Only ("UBIGINT" :: Text.Text)])
-        , testCase "Word scalar preserves unsigned maximum" $
-            withConnection ":memory:" \conn -> do
-                createFunction conn "word_maximum" (maxBound :: Word)
-                query_ conn "SELECT word_maximum()" >>= (@?= [Only (maxBound :: Word)])
-        , testCase "signed scalar preserves limits" $
-            withConnection ":memory:" \conn -> do
-                createFunction conn "int64_identity" (id :: Int64 -> Int64)
-                query_ conn "SELECT int64_identity(x) FROM (VALUES ((-9223372036854775808)::BIGINT), (9223372036854775807::BIGINT)) t(x)"
-                    >>= (@?= [Only (minBound :: Int64), Only maxBound])
-        , testCase "scalar strings preserve UTF8 and embedded NUL" $
-            withConnection ":memory:" \conn -> do
-                let payload = "Matti \955\0 suffix" :: Text.Text
-                createFunction conn "text_payload" payload
-                createFunction conn "text_identity" (id :: Text.Text -> Text.Text)
-                query_ conn "SELECT text_identity(text_payload())" >>= (@?= [Only payload])
-        , testCase "scalar NULL arguments reach Maybe functions" $
-            withConnection ":memory:" \conn -> do
-                createFunction conn "null_default" (\(x :: Maybe Int64) -> maybe 42 id x)
-                query_ conn "SELECT null_default(NULL::BIGINT)" >>= (@?= [Only (42 :: Int64)])
-        , testCase "scalar nullable strings across chunks" $
-            withConnection ":memory:" \conn -> do
-                createFunction conn "optional_text" (\(x :: Int64) -> if even x then Just ("\955\0" <> Text.replicate 32 "x") else Nothing)
-                query_ conn "SELECT count(*), count(optional_text(i)), min(length(optional_text(i))) FROM range(5000) t(i)"
-                    >>= (@?= [(5000 :: Int64, 2500 :: Int64, Just (34 :: Int64))])
-        , testCase "scalar DECIMAL inputs use supported numeric casts" $
-            withConnection ":memory:" \conn -> do
-                createFunction conn "double_identity" (id :: Double -> Double)
-                query_ conn "SELECT double_identity(123.25::DECIMAL(10,2))" >>= (@?= [Only (123.25 :: Double)])
-        , testCase "COPY exceptions become SQL errors in every phase" $
-            withConnection ":memory:" \conn ->
-                mapM_
-                    ( \phase -> do
-                        let name = "copy_fail_" <> Text.pack (show phase)
-                        registerCopy conn name (Just phase)
-                        assertSqlErrorContaining (Text.pack ("copy phase " <> show phase)) $
-                            execute_ conn (Query ("COPY (SELECT 1) TO '/tmp/duckdb-simple-regression-copy' (FORMAT " <> name <> ")"))
-                    )
-                    [0 .. 3]
-        , testCase "COPY state is valid across repeated queries" $
-            withConnection ":memory:" \conn -> do
-                registerCopy conn "copy_repeat" Nothing
-                replicateM_ 32 $ void $ execute_ conn "COPY (SELECT * FROM range(5000)) TO '/tmp/duckdb-simple-regression-copy' (FORMAT copy_repeat)"
-        , testCase "logging exceptions stay inside callback" $
-            withConnection ":memory:" \conn -> do
-                calls <- newIORef (0 :: Int)
-                Logging.registerLogStorage conn "throwing_log" \_ -> do
-                    modifyIORef' calls (+ 1)
-                    throwIO (userError "log callback failure")
-                void $ execute_ conn "SET logging_storage = 'throwing_log'"
-                void $ execute_ conn "SET enable_logging = true"
-                void $ execute_ conn "SELECT write_log('callback regression', level := 'INFO', scope := 'connection')"
-                readIORef calls >>= \n -> assertBool "log callback ran" (n > 0)
-                query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
-        , testCase "logging messages preserve UTF8" $
-            withConnection ":memory:" \conn -> do
-                messages <- newIORef []
-                Logging.registerLogStorage conn "unicode_log" \entry ->
-                    modifyIORef' messages (Logging.logEntryMessage entry :)
-                void $ execute_ conn "SET logging_storage = 'unicode_log'"
-                void $ execute_ conn "SET enable_logging = true"
-                void $ execute_ conn "SELECT write_log('\955', level := 'INFO', scope := 'connection')"
-                readIORef messages >>= \entries -> assertBool "Unicode log message" ("\955" `elem` entries)
-        , testCase "filesystem action exceptions release handles" $
-            withTemporaryFile \path ->
-                withConnection ":memory:" \conn -> do
-                    outcome <- try $ FileSystem.withFileHandle conn path [DuckDBFileFlagWrite] \_ -> throwIO (userError "file action failure")
-                    case outcome :: Either SomeException () of
-                        Left _ -> pure ()
-                        Right () -> assertFailure "expected file action exception"
-                    FileSystem.withFileHandle conn path [DuckDBFileFlagWrite] \handle -> do
-                        FileSystem.writeFileHandleBytes handle (BS.pack [0, 255]) >>= (@?= 2)
-                        FileSystem.fileHandleSync handle
-                    FileSystem.withFileHandle conn path [DuckDBFileFlagRead] \handle -> do
-                        FileSystem.readFileHandleChunk handle 0 >>= (@?= BS.empty)
-                        FileSystem.readFileHandleChunk handle 8 >>= (@?= BS.pack [0, 255])
-        , testCase "filesystem errors remain controlled" $
-            withConnection ":memory:" \conn -> do
-                assertSqlError $ FileSystem.withFileHandle conn "/tmp/duckdb-review-missing-dir/no-file" [DuckDBFileFlagRead] (\_ -> pure ())
-                withTemporaryFile \path ->
-                    assertSqlError $ FileSystem.withFileHandle conn (path <> "\0suffix") [DuckDBFileFlagRead] (\_ -> pure ())
-        , testCase "catalog unsupported kinds fail safely" $
-            withConnection ":memory:" \conn ->
-                withTransaction conn $
-                    mapM_
-                        (\kind -> assertSqlError $ Catalog.lookupCatalogEntry conn "memory" "main" "probe" kind)
-                        [DuckDBCatalogEntryTypeInvalid, DuckDBCatalogEntryTypeSchema, DuckDBCatalogEntryTypePreparedStatement, DuckDBCatalogEntryTypeDatabase, DuckDBCatalogEntryType 99]
-        , testCase "catalog and config NUL names fail safely" $
-            withConnection ":memory:" \conn -> do
-                assertSqlError $ Config.getConfigOption conn "threads\0suffix"
-                withTransaction conn do
-                    assertSqlError $ Catalog.catalogTypeName conn "memory\0suffix"
-                    assertSqlError $ Catalog.lookupCatalogEntry conn "memory" "main\0suffix" "probe" DuckDBCatalogEntryTypeTable
-        , testCase "catalog names preserve UTF8" $
-            withConnection ":memory:" \conn -> do
-                void $ execute_ conn "CREATE TABLE \"\955\" (i INT)"
-                withTransaction conn do
-                    entry <- Catalog.lookupCatalogEntry conn "memory" "main" "\955" DuckDBCatalogEntryTypeTable
-                    fmap Catalog.catalogEntryName entry @?= Just "\955"
-        , testCase "catalog and config missing values remain safe" $
-            withConnection ":memory:" \conn -> do
-                Config.getConfigOption conn "no_such_config_option" >>= (@?= Nothing)
-                withTransaction conn do
-                    Catalog.catalogTypeName conn "no_such_catalog" >>= (@?= Nothing)
-                    Catalog.lookupCatalogEntry conn "memory" "main" "no_such_table" DuckDBCatalogEntryTypeTable >>= (@?= Nothing)
-        ]
-
--- | Raise a second exception when the callback error is rendered.
-data BrokenDisplay = BrokenDisplay
-    deriving (Show)
-
-instance Exception BrokenDisplay where
-    displayException _ = error "broken error rendering"
-
--- | Force a setup exception after scalar callbacks have been acquired.
-data BrokenSignature = BrokenSignature
-
-instance Function BrokenSignature where
-    argumentTypes _ = error "broken scalar signature"
-    returnType _ = error "unused return type"
-    isVolatile _ = False
-    applyFunction _ _ = error "unused function"
-
--- | Supply an argument type which DuckDB rejects at registration.
-data InvalidSignature = InvalidSignature
-
-instance Function InvalidSignature where
-    argumentTypes _ = [DuckDBTypeInvalid]
-    returnType _ = returnType (Proxy :: Proxy Int64)
-    isVolatile _ = False
-    applyFunction _ _ = error "unregistered function"
-
--- | Register a COPY callback and optionally fail one phase.
-registerCopy :: Connection -> Text.Text -> Maybe Int -> IO ()
-registerCopy conn name failingPhase =
-    Copy.registerCopyToFunction
-        conn
-        name
-        (\_ -> failPhase 0)
-        (\info -> (Copy.copyInitBindState info @?= ()) >> failPhase 1)
-        (\info _ -> (Copy.copySinkGlobalState info @?= ()) >> failPhase 2)
-        (\info -> (Copy.copyFinalizeGlobalState info @?= ()) >> failPhase 3)
-  where
-    failPhase phase =
-        if failingPhase == Just phase
-            then throwIO (userError ("copy phase " <> show phase))
-            else pure ()
-
--- | Require a controlled SQL exception.
-assertSqlError :: IO a -> Assertion
-assertSqlError = assertSqlErrorContaining Text.empty
-
--- | Require a SQL exception which includes the expected message.
-assertSqlErrorContaining :: Text.Text -> IO a -> Assertion
-assertSqlErrorContaining expected action = do
-    outcome <- try (void action)
-    case outcome of
-        Left (err :: SQLError) ->
-            assertBool ("expected SQL error containing " <> show expected <> ", got " <> show err) $
-                expected `Text.isInfixOf` sqlErrorMessage err
-        Right () -> assertFailure "expected SQL error"
-
--- | Remove a temporary file after the action.
-withTemporaryFile :: (FilePath -> IO a) -> IO a
-withTemporaryFile action =
-    bracket
-        (do (path, handle) <- openBinaryTempFile "/tmp" "duckdb-extension-regression"; hClose handle; pure path)
-        removeFile
-        action
+{-# LANGUAGE TypeApplications #-}
+-- The tests call deleteFunction on purpose, so its warning does not apply.
+{-# OPTIONS_GHC -Wno-deprecations #-}
+
+-- |
+-- Module      : ExtensionRegressionTests
+-- Description : Regression tests for extension callbacks and native handle ownership.
+module ExtensionRegressionTests (main, extensionRegressionTests) where
+
+import Control.Concurrent (forkIOWithUnmask, killThread, newEmptyMVar, putMVar, readMVar, takeMVar, threadDelay)
+import Control.Exception (
+  AsyncException (ThreadKilled),
+  ErrorCall,
+  Exception (..),
+  IOException,
+  SomeException,
+  bracket,
+  bracket_,
+  finally,
+  throwIO,
+  try,
+ )
+import Control.Monad (forM, forM_, forever, replicateM_, void, when)
+import qualified Data.ByteString as BS
+import Data.IORef (IORef, atomicModifyIORef', mkWeakIORef, newIORef, readIORef, writeIORef)
+import Data.Int (Int64)
+import Data.List (find, isInfixOf, nub, sort)
+import Data.Maybe (isJust)
+import Data.Proxy (Proxy (..))
+import qualified Data.Text as Text
+import qualified Data.Text.Encoding as Text
+import Data.Time.Clock (addUTCTime, getCurrentTime)
+import Data.Word (Word64)
+import Database.DuckDB.FFI.V2
+import Database.DuckDB.Simple
+import qualified Database.DuckDB.Simple.Catalog as Catalog
+import qualified Database.DuckDB.Simple.Config as Config
+import qualified Database.DuckDB.Simple.Copy as Copy
+import qualified Database.DuckDB.Simple.FileSystem as FileSystem
+import Database.DuckDB.Simple.FromField (FieldValue (..))
+import Database.DuckDB.Simple.Internal (
+  MacroFunctionType,
+  acquireItems,
+  errorTypeCodes,
+  errorTypeFromNative,
+  logLevelFromNative,
+  logLevelToNative,
+  logScopeFromNative,
+  macroFunctionTypeToNative,
+  settingScopeFromNative,
+  settingScopeToNative,
+  throwInternalError,
+  tokenTypeFromNative,
+ )
+import qualified Database.DuckDB.Simple.Logging as Logging
+import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep (..))
+import qualified Database.DuckDB.Simple.Tokenizer as Tokenizer
+import qualified Database.DuckDB.Simple.V2.Registration as Registration
+import Numeric.Natural (Natural)
+import System.Directory (doesFileExist, getHomeDirectory, getTemporaryDirectory, removeFile)
+import System.FilePath (takeDirectory)
+import System.IO (hClose, openBinaryTempFile)
+import System.Mem (performMajorGC)
+import System.Mem.Weak (deRefWeak)
+import System.Timeout (timeout)
+import Test.Tasty (TestTree, defaultMain, testGroup)
+import Test.Tasty.HUnit (Assertion, assertBool, assertEqual, assertFailure, testCase, (@?=))
+import TestUtils (assertInputErrorContaining, assertRangeError, assertReleasedAfter, assertSqlErrorContaining, assertSqlErrorType)
+
+-- | Run the extension regression tests as a standalone executable.
+main :: IO ()
+main = defaultMain extensionRegressionTests
+
+-- | Check callback failures, value conversion, and resource cleanup.
+extensionRegressionTests :: TestTree
+extensionRegressionTests =
+  testGroup
+    "extension regressions"
+    [ -- A registration on a closed connection raises the error before it
+      -- allocates a callback.
+      testCase "scalar registration on a closed connection raises the closed error" do
+        conn <- open ":memory:"
+        close conn
+        replicateM_ 32 $ assertSqlErrorContaining "connection is closed" $ createFunction conn "closed_scalar" (1 :: Int64)
+    , testCase "stateful registration on a closed connection raises the closed error" do
+        conn <- open ":memory:"
+        close conn
+        replicateM_ 32
+          $ assertSqlErrorContaining "connection is closed"
+          $ createFunctionWithState conn "closed_state" (pure ()) (\() -> (1 :: Int64))
+    , testCase "COPY registration on a closed connection raises the closed error" do
+        conn <- open ":memory:"
+        close conn
+        replicateM_ 32 $ assertSqlErrorContaining "connection is closed" $ registerCopy conn "closed_copy" Nothing
+    , testCase "logging registration on a closed connection raises the closed error" do
+        conn <- open ":memory:"
+        close conn
+        replicateM_ 32 $ assertSqlErrorContaining "connection is closed" $ Logging.registerLogStorage conn "closed_log" (\_ -> pure ())
+    , testCase "scalar replacement releases each replaced callback before the connection closes" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "duplicate_scalar" (42 :: Int64)
+          assertReleasedAfter "a replaced scalar function" \token -> do
+            replicateM_ 32 $ createFunction conn "duplicate_scalar" (readIORef token)
+            createFunction conn "duplicate_scalar" (7 :: Int64)
+          query_ conn "SELECT duplicate_scalar()" >>= (@?= [Only (7 :: Int64)])
+    , testCase "a scalar function of a rolled-back transaction is gone and releases its callback" $
+        withConnection ":memory:" \conn -> do
+          assertReleasedAfter "a rolled-back scalar function" \token -> do
+            _ <- execute_ conn "BEGIN TRANSACTION"
+            createFunction conn "rolled_scalar" (\(x :: Int64) -> (+ x) <$> readIORef token)
+            query_ conn "SELECT rolled_scalar(1)" >>= (@?= [Only (2 :: Int64)])
+            void (execute_ conn "ROLLBACK")
+          assertSqlErrorType ErrorDatabaseCatalog (query_ conn "SELECT rolled_scalar(1)" :: IO [Only Int64])
+          createFunction conn "rolled_scalar" (\(x :: Int64) -> x + 100)
+          query_ conn "SELECT rolled_scalar(1)" >>= (@?= [Only (101 :: Int64)])
+          -- A registration that stays keeps its callback.
+          kept <- do
+            token <- newIORef (1 :: Int64)
+            weak <- mkWeakIORef token (pure ())
+            createFunction conn "kept_scalar" (\(x :: Int64) -> (+ x) <$> readIORef token)
+            pure weak
+          performMajorGC
+          performMajorGC
+          deRefWeak kept >>= assertBool "a registration that stays keeps its callback" . isJust
+          query_ conn "SELECT kept_scalar(1)" >>= (@?= [Only (2 :: Int64)])
+    , testCase "scalar deletion refusal keeps function and connection usable" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "retained_scalar" (42 :: Int64)
+          assertSqlErrorContaining "Cannot drop internal catalog entry" $ deleteFunction conn "retained_scalar"
+          query_ conn "SELECT retained_scalar()" >>= (@?= [Only (42 :: Int64)])
+          query_ conn "SELECT 7" >>= (@?= [Only (7 :: Int64)])
+    , testCase "absent scalar deletion succeeds" $
+        withConnection ":memory:" \conn -> do
+          deleteFunction conn "absent_scalar"
+          query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+    , testCase "clearing bindings permits statement reuse after cancellation" $
+        withConnection ":memory:" \conn -> do
+          let parameters = replicate 32 (toField (Text.replicate 4096 "x"))
+              sql = Query ("SELECT length(concat(" <> Text.intercalate ", " (replicate 32 "?::VARCHAR") <> "))")
+          withStatement conn sql \stmt -> replicateM_ 16 do
+            started <- newEmptyMVar
+            done <- newEmptyMVar
+            -- Each worker alternates binding and clearing. The cancellation
+            -- can occur in either operation. The last query checks reuse.
+            -- Unmask the loop because bracket masks the creation of the worker.
+            bracket
+              ( forkIOWithUnmask \unmask ->
+                  try @SomeException (unmask (putMVar started () >> forever (bind stmt parameters >> clearStatementBindings stmt)))
+                    >>= putMVar done
+              )
+              ( \worker -> do
+                  stopped <- timeout (5 * 1000000) (killThread worker >> readMVar done)
+                  case stopped of
+                    Just _ -> pure ()
+                    Nothing -> assertFailure "the binding worker did not stop during cleanup"
+              )
+              \worker -> do
+                outcome <- timeout (5 * 1000000) do
+                  takeMVar started
+                  threadDelay 1000
+                  killThread worker
+                  readMVar done
+                case outcome of
+                  Just (Left failure) | fromException failure == Just ThreadKilled -> pure ()
+                  Just (Left failure) -> throwIO failure
+                  Just (Right ()) -> assertFailure "the binding worker returned before cancellation"
+                  Nothing -> assertFailure "the binding worker did not finish after cancellation"
+            clearStatementBindings stmt
+            bind stmt parameters
+            nextRow stmt >>= (@?= Just (Only (131072 :: Int64)))
+    , testCase "deleteFunction reads the name with the qualified-name rules of DuckDB" $
+        withConnection ":memory:" \conn -> do
+          let macroCount :: Text.Text -> Text.Text -> IO [Only Int64]
+              macroCount schema name = query conn "SELECT count(*) FROM duckdb_functions() WHERE schema_name = ? AND function_name = ?" (schema, name)
+          void $ execute_ conn "CREATE MACRO \"a.b\"(x) AS x + 1; CREATE SCHEMA s; CREATE MACRO s.f(x) AS x; CREATE MACRO s.g(x) AS x"
+          mapM (uncurry macroCount) [("main", "a.b"), ("s", "f"), ("s", "g")] >>= (@?= replicate 3 [Only 1])
+          deleteFunction conn "\"a.b\""
+          macroCount "main" "a.b" >>= (@?= [Only 0])
+          deleteFunction conn "s.f"
+          macroCount "s" "f" >>= (@?= [Only 0])
+          deleteFunction conn "memory.s.g"
+          macroCount "s" "g" >>= (@?= [Only 0])
+          -- The parser rejects a quote inside a part that has no quotes, so no
+          -- statement runs.
+          void $ execute_ conn "CREATE TABLE kept (i INTEGER)"
+          assertSqlErrorContaining "Unexpected quote" $ deleteFunction conn "x\"; DROP TABLE kept; --"
+          query_ conn "SELECT count(*) FROM duckdb_tables() WHERE table_name = 'kept'" >>= (@?= [Only (1 :: Int64)])
+          assertSqlErrorContaining "Unexpected quote" $ deleteFunction conn "a\"b"
+          assertSqlErrorContaining "between one and three parts" $ deleteFunction conn "a.b.c.d"
+    , testCase "stateful replacement releases each replaced callback before the connection closes" $
+        withConnection ":memory:" \conn -> do
+          createFunctionWithState conn "duplicate_state" (pure ()) (\() -> (42 :: Int64))
+          assertReleasedAfter "a replaced stateful function" \token -> do
+            replicateM_ 32 $ createFunctionWithState conn "duplicate_state" (readIORef token) (id :: Int64 -> Int64)
+            createFunctionWithState conn "duplicate_state" (pure ()) (\() -> (7 :: Int64))
+          query_ conn "SELECT duplicate_state()" >>= (@?= [Only (7 :: Int64)])
+    , -- DuckDB refuses the type of the argument after the registration
+      -- allocates its callbacks.
+      testCase "scalar registration with an invalid signature releases its callbacks at the failure" $
+        withConnection ":memory:" \conn ->
+          assertReleasedAfter "a scalar function with an invalid signature" \token ->
+            replicateM_ 32 $ assertSqlError $ createFunction conn "invalid_scalar" (InvalidSignature token)
+    , testCase "stateful registration with an invalid signature releases its callbacks at the failure" $
+        withConnection ":memory:" \conn ->
+          assertReleasedAfter "a stateful function with an invalid signature" \token ->
+            replicateM_ 32 $ assertSqlError $ createFunctionWithState conn "invalid_state" (readIORef token) (\_ -> InvalidSignature token)
+    , testCase "logging duplicate registration releases each rejected callback at the failure" $
+        withConnection ":memory:" \conn -> do
+          Logging.registerLogStorage conn "duplicate_log" (\_ -> pure ())
+          assertReleasedAfter "a rejected log storage" \token ->
+            replicateM_ 32 $ assertSqlError $ Logging.registerLogStorage conn "duplicate_log" (\_ -> void (readIORef token))
+          query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+    , testCase "empty registration names fail safely" $
+        withConnection ":memory:" \conn -> replicateM_ 32 do
+          assertSqlError $ createFunction conn "" (1 :: Int64)
+          assertSqlError $ createFunctionWithState conn "" (pure ()) (\() -> (1 :: Int64))
+          assertSqlError $ registerCopy conn "" Nothing
+          assertSqlError $ Logging.registerLogStorage conn "" (\_ -> pure ())
+    , testCase "NUL registration names fail safely" $
+        withConnection ":memory:" \conn -> do
+          assertSqlError $ createFunction conn "nul\0scalar" (1 :: Int64)
+          assertSqlError $ createFunctionWithState conn "nul\0state" (pure ()) (\() -> (1 :: Int64))
+          assertSqlError $ registerCopy conn "nul\0copy" Nothing
+          assertSqlError $ Logging.registerLogStorage conn "nul\0log" (\_ -> pure ())
+    , testCase "a scalar registration whose setup fails releases its callbacks at the failure" $
+        -- The registration forces the argument declaration after it acquires the callbacks.
+        -- If a change forces the declaration before the acquisition, this check cannot fail.
+        withConnection ":memory:" \conn ->
+          assertReleasedAfter "a scalar function whose setup fails" \token -> replicateM_ 32 do
+            outcome <- try (createFunction conn "broken_signature" (BrokenSignature token)) :: IO (Either ErrorCall ())
+            case outcome of
+              Left err -> assertBool (displayException err) ("broken scalar signature" `isInfixOf` displayException err)
+              Right () -> assertFailure "expected signature exception"
+    , testCase "a raw result of another type than the result vector is an SQL error" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "mismatched_result" MismatchedResult
+          assertSqlErrorContaining
+            "but the result value has the type BIGINT"
+            (query_ conn "SELECT mismatched_result()" :: IO [Only Text.Text])
+          query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+    , testCase "scalar exceptions become SQL errors" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "throw_scalar" (throwIO (userError "scalar callback failure") :: IO Int64)
+          assertSqlErrorContaining "scalar callback failure" (query_ conn "SELECT throw_scalar()" :: IO [Only Int64])
+          query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+    , testCase "a scalar callback failure gives an SQL error of the type ErrorInputInvalid" $
+        withConnection ":memory:" \conn -> do
+          -- An untyped callback failure gets the code DuckDBV2ErrorApi.
+          -- DuckDB 2.0.0 reports that code as an invalid input.
+          createFunction conn "throw_typed_scalar" (throwIO (userError "typed callback failure") :: IO Int64)
+          outcome <- try (query_ conn "SELECT throw_typed_scalar()" :: IO [Only Int64])
+          case outcome of
+            Left (err :: SQLError) -> do
+              sqlErrorType err @?= Just ErrorInputInvalid
+              assertBool (show err) ("typed callback failure" `Text.isInfixOf` sqlErrorMessage err)
+            Right _ -> assertFailure "expected SQL error"
+    , testCase "an internal error of the library in a callback leaves the database usable" $
+        withConnection ":memory:" \conn -> do
+          -- See Note [Internal errors in callbacks] in "Database.DuckDB.Simple.Native".
+          createFunction conn "throw_internal" (throwInternalError "internal callback failure" :: IO Int64)
+          createAggregate
+            conn
+            "internal_step"
+            Aggregate
+              { aggregateInitial = 0 :: Int64
+              , aggregateStep = \_ (Only (_ :: Int64)) -> throwInternalError "internal step failure"
+              , aggregateCombine = \a b -> pure (a + b)
+              , aggregateResult = pure
+              }
+          forM_
+            [ ("SELECT throw_internal()", "internal callback failure")
+            , ("SELECT internal_step(i) FROM range(3) t(i)", "internal step failure") :: (Text.Text, Text.Text)
+            ]
+            \(sql, text) -> do
+              result <- try (query_ conn (Query sql) :: IO [Only Int64])
+              case result of
+                Left err -> do
+                  assertBool (show err) (text `Text.isInfixOf` sqlErrorMessage err)
+                  -- runCallback holds back ErrorRuntimeInternal.
+                  sqlErrorType err @?= Just ErrorInputInvalid
+                Right rows -> assertFailure (Text.unpack sql <> ": expected the error of the callback, got " <> show rows)
+              query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+    , testCase "exception rendering cannot escape scalar callback" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "throw_bad_display" (throwIO BrokenDisplay :: IO Int64)
+          assertSqlErrorContaining "Haskell callback failed" (query_ conn "SELECT throw_bad_display()" :: IO [Only Int64])
+    , testCase "a failing exception category cannot turn a callback failure into success" $
+        withConnection ":memory:" \conn -> do
+          let failure = SQLError "bad category" (error "category failed") Nothing Nothing
+          createFunction conn "bad_category" (throwIO failure :: IO Int64)
+          result <- try (query_ conn "SELECT bad_category()" :: IO [Only Int64])
+          case result of
+            Left err -> do
+              sqlErrorType err @?= Just ErrorInputInvalid
+              assertBool (show err) ("Haskell callback failed" `Text.isInfixOf` sqlErrorMessage err)
+            Right rows -> assertFailure ("expected a callback failure, got " <> show rows)
+          query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+    , testCase "scalar async exceptions become SQL errors" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "throw_async_scalar" (throwIO ThreadKilled :: IO Int64)
+          assertSqlErrorContaining "thread killed" (query_ conn "SELECT throw_async_scalar()" :: IO [Only Int64])
+    , testCase "scalar initializer exceptions become SQL errors" $
+        withConnection ":memory:" \conn -> do
+          createFunctionWithState conn "throw_init" (throwIO (userError "state init failure") :: IO ()) (\() -> (1 :: Int64))
+          assertSqlErrorContaining "state init failure" (query_ conn "SELECT throw_init()" :: IO [Only Int64])
+    , testCase "scalar initializer async exceptions become SQL errors" $
+        withConnection ":memory:" \conn -> do
+          createFunctionWithState conn "throw_async_init" (throwIO ThreadKilled :: IO ()) (\() -> (1 :: Int64))
+          assertSqlErrorContaining "thread killed" (query_ conn "SELECT throw_async_init()" :: IO [Only Int64])
+    , testCase "stateful scalar exceptions become SQL errors" $
+        withConnection ":memory:" \conn -> do
+          createFunctionWithState conn "throw_state" (pure ()) (\() -> throwIO (userError "state execution failure") :: IO Int64)
+          assertSqlErrorContaining "state execution failure" (query_ conn "SELECT throw_state()" :: IO [Only Int64])
+    , testCase "Float scalar results preserve NaN infinity and negative zero" $
+        withConnection ":memory:" \conn ->
+          forM_
+            [ (0 / 0, isNaN)
+            , (1 / 0, \value -> isInfinite value && value > 0)
+            , (-1 / 0, \value -> isInfinite value && value < 0)
+            , (negate 0, isNegativeZero)
+            ]
+            \(value, matches) -> do
+              createFunction conn "float_value" (value :: Float)
+              createFunctionWithState conn "float_state" (pure ()) (\() -> value)
+              [(plain, stateful)] <- query_ conn "SELECT float_value(), float_state()" :: IO [(Double, Double)]
+              assertBool "plain callback preserves the floating-point value" (matches plain)
+              assertBool "stateful callback preserves the floating-point value" (matches stateful)
+    , testCase "Word64 scalar preserves unsigned maximum" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "word64_identity" (id :: Word64 -> Word64)
+          query_ conn "SELECT word64_identity(18446744073709551615::UBIGINT)" >>= (@?= [Only (maxBound :: Word64)])
+          query_ conn "SELECT typeof(word64_identity(0::UBIGINT))" >>= (@?= [Only ("UBIGINT" :: Text.Text)])
+    , testCase "Word scalar preserves unsigned maximum" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "word_maximum" (maxBound :: Word)
+          query_ conn "SELECT word_maximum()" >>= (@?= [Only (maxBound :: Word)])
+    , testCase "signed scalar preserves limits" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "int64_identity" (id :: Int64 -> Int64)
+          query_ conn "SELECT int64_identity(x) FROM (VALUES ((-9223372036854775808)::BIGINT), (9223372036854775807::BIGINT)) t(x)"
+            >>= (@?= [Only (minBound :: Int64), Only maxBound])
+    , testCase "scalar strings preserve UTF8 and embedded NUL" $
+        withConnection ":memory:" \conn -> do
+          let payload = "Matti \955\0 suffix" :: Text.Text
+          createFunction conn "text_payload" payload
+          createFunction conn "text_identity" (id :: Text.Text -> Text.Text)
+          query_ conn "SELECT text_identity(text_payload())" >>= (@?= [Only payload])
+    , testCase "a throwing String result tail fails the query and permits another call" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "broken_text" \(index :: Int64) ->
+            if index == 1
+              then replicate 64 'x' <> error "text result tail failed"
+              else replicate 64 'x'
+          assertSqlErrorContaining "text result tail failed" $
+            (query_ conn "SELECT broken_text(i) FROM range(3) t(i)" :: IO [Only String])
+          query_ conn "SELECT broken_text(0)" >>= (@?= [Only (replicate 64 'x')])
+    , testGroup
+        "native acquisition cleanup"
+        [ testCase label do
+            released <- newIORef []
+            outcome <- try (acquireItems (\item -> atomicModifyIORef' released (\items -> (items <> [item], ()))) actions)
+            case outcome of
+              Left (failure :: SomeException) ->
+                assertBool "the acquisition exception reaches the caller" ("acquisition failed" `isInfixOf` displayException failure)
+              Right _ -> assertFailure "the acquisition succeeded"
+            readIORef released >>= (@?= [2, 1 :: Int])
+        | (label, actions) <-
+            [ ("a failing list spine releases the acquired prefix in reverse order", pure 1 : pure 2 : error "acquisition failed")
+            , ("a failing acquisition action releases the acquired prefix in reverse order", [pure 1, pure 2, throwIO (userError "acquisition failed")])
+            ]
+        ]
+    , testCase "a failing lazy list parameter permits another query" $
+        withConnection ":memory:" \conn -> do
+          outcome <- try (query conn "SELECT ?::BIGINT[]" (Only (1 : error "parameter tail failed" :: [Int64])) :: IO [Only [Int64]])
+          case outcome of
+            Left (failure :: ErrorCall) ->
+              assertBool "the list exception reaches the caller" ("parameter tail failed" `isInfixOf` displayException failure)
+            Right _ -> assertFailure "the lazy list parameter succeeded"
+          query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+    , testCase "scalar NULL arguments reach Maybe functions" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "null_default" (\(x :: Maybe Int64) -> maybe 42 id x)
+          query_ conn "SELECT null_default(NULL::BIGINT)" >>= (@?= [Only (42 :: Int64)])
+    , testCase "scalar nullable strings across chunks" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "optional_text" (\(x :: Int64) -> if even x then Just ("\955\0" <> Text.replicate 32 "x") else Nothing)
+          query_ conn "SELECT count(*), count(optional_text(i)), min(length(optional_text(i))) FROM range(5000) t(i)"
+            >>= (@?= [(5000 :: Int64, 2500 :: Int64, Just (34 :: Int64))])
+    , testCase "scalar DECIMAL inputs use supported numeric casts" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "double_identity" (id :: Double -> Double)
+          query_ conn "SELECT double_identity(123.25::DECIMAL(10,2))" >>= (@?= [Only (123.25 :: Double)])
+    , testCase "COPY exceptions become SQL errors in every phase" $
+        withMissingFile \path -> withConnection ":memory:" \conn ->
+          mapM_
+            ( \phase -> do
+                let name = "copy_fail_" <> Text.pack (show phase)
+                registerCopy conn name (Just phase)
+                assertSqlErrorContaining (Text.pack ("copy phase " <> show phase)) $
+                  execute conn (Query ("COPY (SELECT 1) TO ? (FORMAT " <> name <> ")")) (Only (Text.pack path))
+            )
+            [0 .. 3]
+    , testCase "COPY state is valid across repeated queries" $
+        withMissingFile \path -> withConnection ":memory:" \conn -> do
+          registerCopy conn "copy_repeat" Nothing
+          replicateM_ 32 $ void $ execute conn "COPY (SELECT * FROM range(5000)) TO ? (FORMAT copy_repeat)" (Only (Text.pack path))
+    , testCase "log sink callback exceptions cannot fail a query" do
+        calls <- newIORef (0 :: Int)
+        withConnection ":memory:" \conn -> do
+          Logging.registerLogStorage conn "throwing_log" (\_ -> atomicModifyIORef' calls (\n -> (n + 1, ())) >> throwIO ThreadKilled)
+          void $ execute_ conn "CALL enable_logging(); SET logging_storage = 'throwing_log'; SELECT write_log('contained')"
+          query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+        readIORef calls >>= assertBool "the sink ran" . (> 0)
+    , testCase "log sinks copy entries and flush when released" do
+        entries <- newIORef []
+        flushes <- newIORef (0 :: Int)
+        start <- getCurrentTime
+        withConnection ":memory:" \conn -> do
+          Logging.registerLogSink
+            conn
+            "captured_log"
+            (\entry -> atomicModifyIORef' entries (\values -> (entry : values, ())))
+            (atomicModifyIORef' flushes (\count -> (count + 1, ())))
+          void $
+            execute_
+              conn
+              "CALL enable_logging(); SET logging_storage = 'captured_log'; SELECT write_log('Matti λ', level := 'warning', log_type := 'HaskellTest'); SET logging_storage = 'memory'"
+          -- DuckDB 2.0.0 flushes the sink five times for these statements.
+          readIORef flushes >>= (@?= 5)
+        end <- getCurrentTime
+        received <- filter ((== "HaskellTest") . Logging.logEntryType) <$> readIORef entries
+        map Logging.logEntryMessage received @?= ["Matti λ"]
+        map Logging.logEntrySeverity received @?= [Logging.LogLevelWarning]
+        map Logging.logEntryScope received @?= [Logging.LogScopeConnection]
+        assertBool "entry has a timestamp" (all ((/= Nothing) . Logging.logEntryTimestamp) received)
+        -- A timestamp in the wrong unit is far from the clock of the test.
+        let nearClock time = addUTCTime (-300) start <= time && time <= addUTCTime 300 end
+        assertBool
+          ("timestamps " <> show (map Logging.logEntryTimestamp received) <> " are within five minutes of " <> show (start, end))
+          (all (maybe False nearClock . Logging.logEntryTimestamp) received)
+        assertBool "entry has a connection id" (all ((/= Nothing) . Logging.logEntryConnectionId) received)
+        -- The release flushes the sink one more time.
+        readIORef flushes >>= (@?= 6)
+    , testCase "instance log sinks receive connection and instance messages" do
+        entries <- newIORef []
+        withEnvironment \environment -> withInstance environment [] \instance_ -> do
+          attachDatabase instance_ ":memory:" "shared" []
+          setDefaultDatabase instance_ "shared"
+          Logging.registerInstanceLogSink instance_ "instance_log" (\entry -> atomicModifyIORef' entries (\values -> (entry : values, ()))) (pure ())
+          withConnectionOn instance_ \conn -> do
+            void $ execute_ conn "CALL enable_logging(); SET logging_storage = 'instance_log'"
+            Logging.logConnectionMessage conn Logging.LogLevelWarning "HaskellConnection" "from a connection"
+            Logging.logInstanceMessage instance_ Logging.LogLevelWarning "HaskellInstance" "from an instance"
+            void $ execute_ conn "SET logging_storage = 'memory'"
+        received <- readIORef entries
+        let ofType kind = filter ((== kind) . Logging.logEntryType) received
+        map Logging.logEntryMessage (ofType "HaskellConnection") @?= ["from a connection"]
+        map Logging.logEntryScope (ofType "HaskellConnection") @?= [Logging.LogScopeConnection]
+        assertBool "connection entry has a connection id" (all ((/= Nothing) . Logging.logEntryConnectionId) (ofType "HaskellConnection"))
+        map Logging.logEntryMessage (ofType "HaskellInstance") @?= ["from an instance"]
+        map Logging.logEntryScope (ofType "HaskellInstance") @?= [Logging.LogScopeDatabase]
+        map Logging.logEntryConnectionId (ofType "HaskellInstance") @?= [Nothing]
+    , testCase "log entries carry the connection, transaction, and query ids of DuckDB" do
+        entries <- newIORef []
+        (connectionId, transactionId, queryId) <- withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+          Logging.registerLogSink conn "id_log" (\entry -> atomicModifyIORef' entries (\values -> (entry : values, ()))) (pure ())
+          void $ execute_ conn "CALL enable_logging(); SET logging_storage = 'id_log'"
+          -- In a transaction, the transaction id and the query id differ.
+          void $ execute_ conn "BEGIN"
+          _ <- query_ conn "SELECT 1" :: IO [Only Int64]
+          rows <-
+            query_
+              conn
+              "SELECT write_log('ids', level := 'warning', log_type := 'HaskellIds'), current_connection_id(), current_transaction_id(), current_query_id()"
+              :: IO [(FieldValue, Word64, Word64, Word64)]
+          void $ execute_ conn "COMMIT; SET logging_storage = 'memory'"
+          case rows of
+            [(_, connection, transaction, queryNumber)] -> pure (connection, transaction, queryNumber)
+            _ -> assertFailure ("expected one row, got " <> show rows)
+        assertEqual "the ids differ" 3 (length (nub [connectionId, transactionId, queryId]))
+        received <- filter ((== "HaskellIds") . Logging.logEntryType) <$> readIORef entries
+        map Logging.logEntryConnectionId received @?= [Just connectionId]
+        map Logging.logEntryTransactionId received @?= [Just transactionId]
+        map Logging.logEntryQueryId received @?= [Just queryId]
+        map Logging.logEntryThreadId received @?= [Nothing]
+    , testCase "filesystem action exceptions propagate and the file opens again" $
+        withTemporaryFile \path ->
+          withConnection ":memory:" \conn -> do
+            outcome <- try $ FileSystem.withFileHandle conn path [FileSystem.FileFlagWrite] \_ -> throwIO (userError "file action failure")
+            case outcome of
+              Left (err :: IOException) -> displayException err @?= "user error (file action failure)"
+              Right () -> assertFailure "expected file action exception"
+            FileSystem.withFileHandle conn path [FileSystem.FileFlagWrite] \handle -> do
+              FileSystem.writeFileHandleBytes handle (BS.pack [0, 255]) >>= (@?= 2)
+              FileSystem.fileHandleSync handle
+            FileSystem.withFileHandle conn path [FileSystem.FileFlagRead] \handle -> do
+              FileSystem.readFileHandleChunk handle 0 >>= (@?= BS.empty)
+              FileSystem.readFileHandleChunk handle 8 >>= (@?= BS.pack [0, 255])
+    , testCase "filesystem errors remain controlled" $
+        withConnection ":memory:" \conn -> do
+          assertSqlError $ FileSystem.withFileHandle conn "/tmp/duckdb-review-missing-dir/no-file" [FileSystem.FileFlagRead] (\_ -> pure ())
+          withTemporaryFile \path ->
+            assertInputErrorContaining "file path contains NUL" $
+              FileSystem.withFileHandle conn (path <> "\0suffix") [FileSystem.FileFlagRead] (\_ -> pure ())
+    , testCase "catalog and config NUL names fail safely" $
+        withConnection ":memory:" \conn -> do
+          -- The NUL check runs before the handler that gives Nothing for an unknown option.
+          nulName <- try (Config.getConfigOption conn "threads\0suffix")
+          case nulName of
+            Left (err :: SQLError) -> do
+              sqlErrorType err @?= Just ErrorInputInvalid
+              sqlErrorMessage err @?= "duckdb-simple: config option name contains NUL"
+            Right value -> assertFailure ("expected the NUL error, got " <> show (fmap Config.configValueText value))
+          -- DuckDB reads the name with its length, so it gets the NUL byte and
+          -- reports an unknown option. The library rejects the name before
+          -- the native call.
+          let rejectsNul = assertInputErrorContaining "config option name contains NUL"
+          rejectsNul $ Config.setConfigOption conn Config.SettingScopeSession "threads\0suffix" "1"
+          rejectsNul $ Config.setConfigValue conn Config.SettingScopeSession "threads\0suffix" (1 :: Int64)
+          rejectsNul $ Config.getConfigValue conn "threads\0suffix"
+          rejectsNul $ Config.getConfigDefaultValue conn "threads\0suffix"
+          withTransaction conn do
+            assertSqlError $ Catalog.catalogTypeName conn "memory\0suffix"
+            assertSqlError $ Catalog.lookupCatalogEntry conn "memory" "main\0suffix" "probe" Catalog.CatalogTable
+    , testCase "catalog names preserve UTF8" $
+        withConnection ":memory:" \conn -> do
+          void $ execute_ conn "CREATE TABLE \"\955\" (i INT)"
+          withTransaction conn do
+            entry <- Catalog.lookupCatalogEntry conn "memory" "main" "\955" Catalog.CatalogTable
+            fmap Catalog.catalogEntryName entry @?= Just "\955"
+    , testCase "catalog names use ASCII identifier comparison independently of collation" $
+        withConnection ":memory:" \conn -> do
+          void $ execute_ conn "CREATE TABLE MiXeD (i INT); CREATE TABLE \"Ä\" (i INT); CREATE TABLE \"ä\" (i INT)"
+          void $ execute_ conn "SET default_collation = 'nocase'"
+          Catalog.catalogTypeName conn "MEMORY" >>= (@?= Just "duckdb")
+          entry <- Catalog.lookupCatalogEntry conn "MEMORY" "MAIN" "mixed" Catalog.CatalogTable
+          fmap Catalog.catalogEntryName entry @?= Just "MiXeD"
+          forM_ ["Ä", "ä"] \name -> do
+            found <- Catalog.lookupCatalogEntry conn "memory" "main" name Catalog.CatalogTable
+            fmap Catalog.catalogEntryName found @?= Just name
+    , testCase "catalog lookup keeps nested and literal-dot schema names distinct" $
+        withConnection ":memory:" \conn -> do
+          void $ execute_ conn "CREATE SCHEMA parent; CREATE SCHEMA parent.child; CREATE TABLE parent.child.inside (i INT)"
+          Catalog.lookupCatalogEntry conn "memory" "child" "inside" Catalog.CatalogTable >>= (@?= Nothing)
+          void $ execute_ conn "CREATE SCHEMA \"parent.child\"; CREATE TABLE \"parent.child\".outside (i INT)"
+          found <- Catalog.lookupCatalogEntry conn "memory" "parent.child" "outside" Catalog.CatalogTable
+          fmap Catalog.catalogEntryName found @?= Just "outside"
+    , testCase "catalog and config missing values remain safe" $
+        withConnection ":memory:" \conn -> do
+          Config.getConfigOption conn "no_such_config_option" >>= (@?= Nothing)
+          withTransaction conn do
+            Catalog.catalogTypeName conn "no_such_catalog" >>= (@?= Nothing)
+            Catalog.lookupCatalogEntry conn "memory" "main" "no_such_table" Catalog.CatalogTable >>= (@?= Nothing)
+    , testCase "configuration descriptors remain usable after connection close" $
+        withConnection ":memory:" \conn -> do
+          Config.setConfigOption conn Config.SettingScopeGlobal "threads" "1"
+          options <- Config.listConfigOptions conn
+          fmap Config.configValueText <$> Config.getConfigOption conn "threads" >>= (@?= Just (Just "1"))
+          close conn
+          case find ((== "threads") . Config.configOptionName) options of
+            Nothing -> assertFailure "missing threads descriptor"
+            Just option -> do
+              Config.configOptionSetting option @?= Just "1"
+              Config.configOptionName option @?= "threads"
+              assertBool "description is retained" (not (Text.null (Config.configOptionDescription option)))
+    , testCase "listed options give the aliases of DuckDB" $
+        withConnection ":memory:" \conn -> do
+          void $ execute_ conn "SET progress_bar_time = 1234"
+          options <- Config.listConfigOptions conn
+          let option name = find ((== name) . Config.configOptionName) options
+          aliases <- query_ conn "SELECT name, aliases FROM duckdb_settings() WHERE len(aliases) > 0 ORDER BY name" :: IO [(Text.Text, [Text.Text])]
+          assertBool "DuckDB lists options with aliases" (not (null aliases))
+          forM_ aliases \(name, expected) ->
+            assertEqual (Text.unpack name) (Just (sort expected)) (sort . Config.configOptionAliases <$> option name)
+          Config.configOptionSetting <$> option "progress_bar_time" @?= Just (Just "1234")
+    , testCase "option descriptors give Nothing for a NULL value and a missing default" $
+        withConnection ":memory:" \conn -> do
+          Config.registerCustomOption
+            conn
+            (Config.customOption "haskell_described" (Registration.TypeExpression "BIGINT"))
+              { Config.customOptionDefault = Just (Registration.defaultValue (3 :: Int64))
+              }
+          void $ execute_ conn "RESET progress_bar_time"
+          options <- Config.listConfigOptions conn
+          let described get name = get <$> find ((== name) . Config.configOptionName) options
+          described Config.configOptionDefault "haskell_described" @?= Just (Just "3")
+          -- progress_bar_time has no static default. After RESET its value is 2000.
+          described Config.configOptionDefault "progress_bar_time" @?= Just Nothing
+          described Config.configOptionSetting "progress_bar_time" @?= Just (Just "2000")
+          -- enable_profiling has a NULL value until a write.
+          described Config.configOptionSetting "enable_profiling" @?= Just Nothing
+          -- getConfigOption shows the NULL value in the same way.
+          fmap Config.configValueText <$> Config.getConfigOption conn "enable_profiling" >>= (@?= Just Nothing)
+    , testCase "instance options list global values" $
+        withEnvironment \environment -> withInstance environment [("threads", "1")] \instance_ -> do
+          options <- Config.listInstanceOptions instance_
+          fmap Config.configOptionSetting (find ((== "threads") . Config.configOptionName) options) @?= Just (Just "1")
+    , testCase "connection options set a session option on one connection only" $
+        withEnvironment \environment -> withInstance environment [] \instance_ -> do
+          attachDatabase instance_ ":memory:" "shared" []
+          setDefaultDatabase instance_ "shared"
+          -- DuckDB gives progress_bar_time the session scope by default.
+          let options = defaultConnectionOptions{connectionConfig = [("progress_bar_time", "1234")]}
+          bracket (connectWithOptions instance_ options) close \configured ->
+            withConnectionOn instance_ \other -> do
+              query_ configured "SELECT current_setting('progress_bar_time')" >>= (@?= [Only (1234 :: Int64)])
+              query_ other "SELECT current_setting('progress_bar_time')" >>= (@?= [Only (2000 :: Int64)])
+    , testCase "configuration values resolve case-insensitive names and aliases" $
+        withConnection ":memory:" \conn -> do
+          Config.setConfigOption conn Config.SettingScopeGlobal "threads" "1"
+          forM_ ["threads", "THREADS", "worker_threads", "WORKER_THREADS"] \name ->
+            fmap Config.configValueText <$> Config.getConfigOption conn name >>= (@?= Just (Just "1"))
+          Config.getConfigOption conn "NO_SUCH_CONFIG_OPTION" >>= (@?= Nothing)
+          close conn
+          assertSqlError $ Config.getConfigOption conn "threads"
+    , testCase "typed reads copy the value of every listed option" $
+        withConnection ":memory:" \conn -> do
+          options <- Config.listConfigOptions conn
+          assertBool "options are listed" (not (null options))
+          failures <- forM options \option -> do
+            let name = Config.configOptionName option
+            outcome <- try (Config.getConfigValue conn name)
+            pure case outcome of
+              Left (err :: SomeException) -> [(name, displayException err)]
+              Right _ -> []
+          concat failures @?= []
+          assertSqlError $ Config.getConfigValue conn "NO_SUCH_CONFIG_OPTION"
+          assertSqlError $ Config.getConfigDefaultValue conn "NO_SUCH_CONFIG_OPTION"
+    , testCase "custom options retain typed defaults scopes and callback errors" $
+        withConnection ":memory:" \conn -> do
+          let option =
+                (Config.customOption "haskell_limit" (Registration.StructuredType (LogicalTypeScalar LogicalTypeIdBigInt)))
+                  { Config.customOptionDefault = Just (Registration.defaultValue (3 :: Int64))
+                  , Config.customOptionDescription = "A Haskell option"
+                  , Config.customOptionDefaultScope = Config.SettingScopeSession
+                  , Config.customOptionScopes = [Config.SettingScopeGlobal, Config.SettingScopeSession]
+                  , Config.customOptionUpdate = Just \value -> case value of
+                      FieldInt64 number | number < 0 -> throwIO (userError "limit must be nonnegative")
+                      _ -> pure ()
+                  }
+          Config.registerCustomOption conn option
+          Config.getConfigDefaultValue conn "haskell_limit" >>= (@?= FieldInt64 3)
+          Config.setConfigValue conn Config.SettingScopeSession "haskell_limit" (7 :: Int64)
+          Config.getConfigValue conn "haskell_limit" >>= (@?= (FieldInt64 7, Config.SettingScopeSession))
+          assertSqlErrorContaining "limit must be nonnegative" $ Config.setConfigValue conn Config.SettingScopeSession "haskell_limit" (-1 :: Int64)
+          void $ execute_ conn "RESET haskell_limit"
+          fmap Config.configValueText <$> Config.getConfigOption conn "haskell_limit" >>= (@?= Just (Just "3"))
+          assertSqlError $ Config.registerCustomOption conn option
+    , testCase "listConfigFlags lists a custom option of the connection" $
+        withConnection ":memory:" \conn -> do
+          Config.registerCustomOption conn (Config.customOption "haskell_listed" (Registration.TypeExpression "BIGINT"))
+          flags <- Config.listConfigFlags conn
+          options <- Config.listConfigOptions conn
+          assertBool "the custom option is listed" ("haskell_listed" `elem` map Config.configFlagName flags)
+          map Config.configFlagName flags @?= map Config.configOptionName options
+    , testCase "typed reads of a VARIANT custom option give the value that it holds" $
+        withConnection ":memory:" \conn -> do
+          let variantType = Registration.TypeExpression "VARIANT"
+          Config.registerCustomOption
+            conn
+            (Config.customOption "haskell_variant" variantType){Config.customOptionDefault = Just (Registration.defaultValue (5 :: Int64))}
+          Config.getConfigDefaultValue conn "haskell_variant" >>= (@?= FieldInt64 5)
+          Config.setConfigValue conn Config.SettingScopeGlobal "haskell_variant" (7 :: Int64)
+          Config.getConfigValue conn "haskell_variant" >>= (@?= (FieldInt64 7, Config.SettingScopeGlobal))
+          -- A nested value gives the value of the same VARIANT in a result.
+          void $ execute_ conn "SET haskell_variant = {'a': 1, 'b': [1, 2]}"
+          [Only expected] <- query_ conn "SELECT {'a': 1, 'b': [1, 2]}::VARIANT" :: IO [Only FieldValue]
+          fst <$> Config.getConfigValue conn "haskell_variant" >>= (@?= expected)
+    , testCase "VARIANT option updates decode GLOBAL and SESSION values and can reject a write" $
+        withConnection ":memory:" \conn -> do
+          seen <- newIORef Nothing
+          let update value = case value of
+                FieldText "reject" -> throwIO (userError "rejected VARIANT value")
+                _ -> writeIORef seen (Just value)
+          Config.registerCustomOption conn $
+            (Config.customOption "haskell_variant_update" (Registration.TypeExpression "VARIANT"))
+              { Config.customOptionScopes = [Config.SettingScopeGlobal, Config.SettingScopeSession]
+              , Config.customOptionUpdate = Just update
+              }
+          [Only expected] <- query_ conn "SELECT {'a': [1,2]}::VARIANT" :: IO [Only FieldValue]
+          void $ execute_ conn "SET GLOBAL haskell_variant_update = {'a': [1,2]}"
+          readIORef seen >>= (@?= Just expected)
+          Config.getConfigValue conn "haskell_variant_update" >>= (@?= (expected, Config.SettingScopeGlobal))
+          void $ execute_ conn "SET SESSION haskell_variant_update = 7::BIGINT"
+          readIORef seen >>= (@?= Just (FieldInt64 7))
+          assertSqlErrorContaining "rejected VARIANT value" $ execute_ conn "SET SESSION haskell_variant_update = 'reject'"
+          Config.getConfigValue conn "haskell_variant_update" >>= (@?= (FieldInt64 7, Config.SettingScopeSession))
+    , testCase "setConfigValue with an Integer or a Natural checks the range of an unsigned option" $
+        withConnection ":memory:" \conn -> do
+          -- DuckDB 2.0.0 gives asof_loop_join_threshold the type UBIGINT.
+          let option = "asof_loop_join_threshold"
+              current = fst <$> Config.getConfigValue conn option
+          Config.setConfigValue conn Config.SettingScopeSession option (9 :: Integer)
+          current >>= (@?= FieldWord64 9)
+          assertSqlErrorContaining "out of range for the destination type UINT64" $
+            Config.setConfigValue conn Config.SettingScopeSession option (-5 :: Integer)
+          current >>= (@?= FieldWord64 9)
+          Config.setConfigValue conn Config.SettingScopeSession option (11 :: Natural)
+          current >>= (@?= FieldWord64 11)
+    , testCase "setConfigValue with an Integer or a Natural outside the HUGEINT range raises an error" $
+        withConnection ":memory:" \conn -> do
+          -- toDuckValue gives no BIGNUM value for an Integer or a Natural. See
+          -- Note [Integer parameters] in "Database.DuckDB.Simple.ToField".
+          let option = "asof_loop_join_threshold"
+          assertRangeError $
+            Config.setConfigValue conn Config.SettingScopeSession option (2 ^ (128 :: Int) + 5 :: Integer)
+          -- A Natural from 2^127 is a UHUGEINT value. DuckDB checks its cast.
+          assertSqlErrorContaining "out of range for the destination type UINT64" $
+            Config.setConfigValue conn Config.SettingScopeSession option (2 ^ (127 :: Int) :: Natural)
+          assertRangeError $
+            Config.setConfigValue conn Config.SettingScopeSession option (2 ^ (128 :: Int) + 5 :: Natural)
+    , testCase "table descriptions resolve names and copy borrowed column types" $
+        withConnection ":memory:" \conn -> do
+          void $ execute_ conn "CREATE TABLE \"\955\" (id BIGINT DEFAULT 7, twice BIGINT GENERATED ALWAYS AS (id * 2))"
+          description <- Catalog.describeTable conn "\"\955\""
+          Catalog.tableDescriptionName description @?= ["memory", "main", "\955"]
+          Catalog.tableDescriptionReadonly description @?= False
+          map Catalog.columnDescriptionName (Catalog.tableDescriptionColumns description) @?= ["id", "twice"]
+          map Catalog.columnDescriptionHasDefault (Catalog.tableDescriptionColumns description) @?= [True, False]
+          map Catalog.columnDescriptionGenerated (Catalog.tableDescriptionColumns description) @?= [False, True]
+          query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+    , testCase "tokenization copies Unicode byte offsets and unterminated state" $
+        withConnection ":memory:" \conn -> do
+          let sql = "SELECT \"\955\", 'x'; -- comment\n"
+              bytes = Text.encodeUtf8 sql
+          parsed <- Tokenizer.tokenize conn sql
+          Tokenizer.tokenizationUnterminated parsed @?= False
+          forM_ (Tokenizer.tokenizationTokens parsed) \token ->
+            BS.take (BS.length (Tokenizer.tokenBytes token)) (BS.drop (Tokenizer.tokenOffset token) bytes) @?= Tokenizer.tokenBytes token
+          assertBool "comment token" (any ((== Tokenizer.TokenTypeComment) . Tokenizer.tokenType) (Tokenizer.tokenizationTokens parsed))
+          unfinished <- Tokenizer.tokenize conn "SELECT 'unclosed"
+          Tokenizer.tokenizationUnterminated unfinished @?= True
+    , testCase "tokenization reports the type of each token" $
+        withConnection ":memory:" \conn -> do
+          parsed <- Tokenizer.tokenize conn "SELECT amount, 'text', 42 + 1; -- note\n"
+          [(Tokenizer.tokenType token, Tokenizer.tokenBytes token) | token <- Tokenizer.tokenizationTokens parsed]
+            @?= [ (Tokenizer.TokenTypeKeyword, "SELECT")
+                , (Tokenizer.TokenTypeIdentifier, "amount")
+                , (Tokenizer.TokenTypeOperator, ",")
+                , (Tokenizer.TokenTypeStringLiteral, "'text'")
+                , (Tokenizer.TokenTypeOperator, ",")
+                , (Tokenizer.TokenTypeNumberLiteral, "42")
+                , (Tokenizer.TokenTypeOperator, "+")
+                , (Tokenizer.TokenTypeNumberLiteral, "1")
+                , (Tokenizer.TokenTypeTerminator, ";")
+                , (Tokenizer.TokenTypeComment, "-- note\n")
+                ]
+    , testCase "configuration writes and reads each setting scope" $
+        withConnection ":memory:" \conn -> do
+          let option name scope =
+                (Config.customOption name (Registration.StructuredType (LogicalTypeScalar LogicalTypeIdBigInt)))
+                  { Config.customOptionDefault = Just (Registration.defaultValue (0 :: Int64))
+                  , Config.customOptionDefaultScope = scope
+                  , Config.customOptionScopes = [Config.SettingScopeGlobal, Config.SettingScopeSession]
+                  }
+          Config.registerCustomOption conn (option "haskell_global_scope" Config.SettingScopeGlobal)
+          Config.registerCustomOption conn (option "haskell_session_scope" Config.SettingScopeSession)
+          Config.setConfigValue conn Config.SettingScopeDefault "haskell_global_scope" (1 :: Int64)
+          Config.getConfigValue conn "haskell_global_scope" >>= (@?= (FieldInt64 1, Config.SettingScopeGlobal))
+          Config.setConfigOption conn Config.SettingScopeDefault "haskell_session_scope" "2"
+          Config.getConfigValue conn "haskell_session_scope" >>= (@?= (FieldInt64 2, Config.SettingScopeSession))
+          Config.setConfigValue conn Config.SettingScopeGlobal "haskell_global_scope" (3 :: Int64)
+          Config.getConfigValue conn "haskell_global_scope" >>= (@?= (FieldInt64 3, Config.SettingScopeGlobal))
+          Config.setConfigOption conn Config.SettingScopeSession "haskell_global_scope" "4"
+          Config.getConfigValue conn "haskell_global_scope" >>= (@?= (FieldInt64 4, Config.SettingScopeSession))
+          fmap Config.configValueScope <$> Config.getConfigOption conn "haskell_global_scope" >>= (@?= Just Config.SettingScopeSession)
+          options <- Config.listConfigOptions conn
+          sort
+            [ (Config.configOptionName descriptor, Config.configOptionScope descriptor, Config.configOptionScopes descriptor)
+            | descriptor <- options
+            , "haskell_" `Text.isPrefixOf` Config.configOptionName descriptor
+            ]
+            @?= [ ("haskell_global_scope", Config.SettingScopeGlobal, [Config.SettingScopeGlobal, Config.SettingScopeSession])
+                , ("haskell_session_scope", Config.SettingScopeSession, [Config.SettingScopeGlobal, Config.SettingScopeSession])
+                ]
+    , testCase "log sinks receive each log level and its scope" do
+        entries <- newIORef []
+        withConnection ":memory:" \conn -> do
+          Logging.registerLogSink conn "level_log" (\entry -> atomicModifyIORef' entries (\values -> (entry : values, ()))) (pure ())
+          void $ execute_ conn "CALL enable_logging(level := 'trace'); SET logging_storage = 'level_log'"
+          forM_ [minBound .. maxBound] \level -> Logging.logConnectionMessage conn level "HaskellLevels" (Text.pack (show level))
+          void $ execute_ conn "SET logging_storage = 'memory'"
+        received <- filter ((== "HaskellLevels") . Logging.logEntryType) <$> readIORef entries
+        sort [(Logging.logEntrySeverity entry, Logging.logEntryLevel entry, Logging.logEntryMessage entry) | entry <- received]
+          @?= [ (level, name, Text.pack (show level))
+              | (level, name) <- zip [minBound .. maxBound] ["TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "FATAL"]
+              ]
+        map Logging.logEntryScope received @?= replicate 6 Logging.LogScopeConnection
+    , testCase "native errors report their error type" $
+        withConnection ":memory:" \conn ->
+          forM_
+            [ ("SELEC 1", ErrorQueryParser)
+            , ("SELECT * FROM no_such_table", ErrorDatabaseCatalog)
+            , ("SELECT no_such_column", ErrorQueryBinder)
+            , ("SELECT 'abc'::INTEGER", ErrorTypeConversion)
+            ]
+            \(sql, expected) -> do
+              outcome <- try (execute_ conn sql)
+              case outcome of
+                Left (err :: SQLError) -> sqlErrorType err @?= Just expected
+                Right _ -> assertFailure ("expected an error from " <> show sql)
+    , testCase "each enum value has the name of its native value" do
+        assertNativeRoundTrip settingScopeToNative settingScopeFromNative DuckDBV2SettingScopeMaxEnum
+        assertNativeRoundTrip logLevelToNative logLevelFromNative DuckDBV2LogLevelMaxEnum
+        -- The package converts these three types in one direction only.
+        assertFromNative logScopeFromNative [DuckDBV2LogScopeDatabase, DuckDBV2LogScopeConnection, DuckDBV2LogScopeThread] DuckDBV2LogScopeMaxEnum
+        assertFromNative
+          tokenTypeFromNative
+          [ DuckDBV2TokenTypeInvalid
+          , DuckDBV2TokenTypeKeyword
+          , DuckDBV2TokenTypeIdentifier
+          , DuckDBV2TokenTypeStringLiteral
+          , DuckDBV2TokenTypeNumberLiteral
+          , DuckDBV2TokenTypeOperator
+          , DuckDBV2TokenTypeComment
+          , DuckDBV2TokenTypeTerminator
+          , DuckDBV2TokenTypeEndOfInput
+          ]
+          DuckDBV2TokenTypeMaxEnum
+        let macroTypes = [minBound .. maxBound] :: [MacroFunctionType]
+        map (show . macroFunctionTypeToNative) macroTypes @?= map (("DuckDBV2" <>) . show) macroTypes
+        let errorTypes = [minBound .. maxBound] :: [ErrorType]
+        map (\errorType -> lookup errorType errorTypeCodes >>= errorTypeFromNative) errorTypes @?= map Just errorTypes
+        map (fmap show . (`lookup` errorTypeCodes)) errorTypes @?= map (Just . ("DuckDBV2" <>) . show) errorTypes
+        map errorTypeFromNative [DuckDBV2ErrorNone, DuckDBV2ErrorMaxEnum] @?= [Nothing, Nothing]
+    , testCase "positioned file operations preserve the sequential position" $
+        withTemporaryFile \path -> withConnection ":memory:" \conn ->
+          FileSystem.withFileHandle conn path [FileSystem.FileFlagRead, FileSystem.FileFlagWrite] \handle -> do
+            FileSystem.writeFileHandleBytes handle (BS.pack [1, 2, 3, 4]) >>= (@?= 4)
+            FileSystem.fileHandleSeek handle 1
+            FileSystem.readFileHandleAt handle 2 2 >>= (@?= BS.pack [3, 4])
+            FileSystem.fileHandleTell handle >>= (@?= 1)
+            FileSystem.writeFileHandleAt handle 0 (BS.pack [8, 9])
+            FileSystem.fileHandleTell handle >>= (@?= 1)
+            FileSystem.fileHandleSeek handle 0
+            FileSystem.readFileHandleChunk handle 8 >>= (@?= BS.pack [8, 9, 3, 4])
+    , testCase "file reads shorter than the file give the requested bytes" $
+        withTemporaryFile \path -> withConnection ":memory:" \conn -> do
+          let bytes = BS.pack [0 .. 15]
+          BS.writeFile path bytes
+          FileSystem.withFileHandle conn path [FileSystem.FileFlagRead] \handle -> do
+            FileSystem.readFileHandleChunk handle 4 >>= (@?= BS.take 4 bytes)
+            FileSystem.fileHandleTell handle >>= (@?= 4)
+            FileSystem.readFileHandleAt handle 8 4 >>= (@?= BS.take 4 (BS.drop 8 bytes))
+            -- A chunk read gives the bytes that remain after the position.
+            FileSystem.readFileHandleChunk handle 100 >>= (@?= BS.drop 4 bytes)
+    , testCase "a positioned read past the end gives the error of DuckDB" $
+        withTemporaryFile \path -> withConnection ":memory:" \conn -> do
+          BS.writeFile path (BS.pack [0 .. 15])
+          FileSystem.withFileHandle conn path [FileSystem.FileFlagRead] \handle -> do
+            outcome <- try (FileSystem.readFileHandleAt handle 14 4)
+            case outcome of
+              Left (err :: SQLError) -> do
+                sqlErrorType err @?= Just ErrorIOGeneral
+                assertBool "DuckDB read error" ("Could not read enough bytes" `Text.isInfixOf` sqlErrorMessage err)
+              Right bytes -> assertFailure ("expected an IO error, got " <> show bytes)
+            -- The library checks only that the end of the range fits in Int64.
+            assertInputErrorContaining "file read range exceeds Int64 range" $ FileSystem.readFileHandleAt handle maxBound 1
+            assertInputErrorContaining "file offset is negative" $ FileSystem.readFileHandleAt handle (-1) 1
+            assertInputErrorContaining "file read size is negative" $ FileSystem.readFileHandleAt handle 0 (-1)
+            assertInputErrorContaining "file offset is negative" $ FileSystem.fileHandleSeek handle (-1)
+            -- A size of 0 gives no bytes, also past the end, as in DuckDB.
+            FileSystem.readFileHandleAt handle 20 0 >>= (@?= BS.empty)
+            FileSystem.readFileHandleAt handle 12 4 >>= (@?= BS.pack [12 .. 15])
+    , testCase "a positioned write checks that its end fits in Int64" $
+        withTemporaryFile \path -> withConnection ":memory:" \conn ->
+          FileSystem.withFileHandle conn path [FileSystem.FileFlagWrite] \handle -> do
+            assertInputErrorContaining "file write range exceeds Int64 range" $ FileSystem.writeFileHandleAt handle (maxBound - 1) (BS.pack [1, 2])
+            assertInputErrorContaining "file offset is negative" $ FileSystem.writeFileHandleAt handle (-1) (BS.pack [1])
+            FileSystem.fileHandleSize handle >>= (@?= 0)
+    , testCase "file flags of the other file tests create read and write a file" $
+        withTemporaryFile \path -> withConnection ":memory:" \conn -> do
+          removeFile path
+          FileSystem.withFileHandle conn path [FileSystem.FileFlagCreate, FileSystem.FileFlagWrite] \handle ->
+            FileSystem.writeFileHandleBytes handle (BS.pack [1, 2, 3]) >>= (@?= 3)
+          FileSystem.withFileHandle conn path [FileSystem.FileFlagWrite] \handle ->
+            FileSystem.writeFileHandleBytes handle (BS.pack [4]) >>= (@?= 1)
+          FileSystem.withFileHandle conn path [FileSystem.FileFlagRead] \handle ->
+            FileSystem.readFileHandleChunk handle 8 >>= (@?= BS.pack [4, 2, 3])
+          FileSystem.withFileHandle conn path [FileSystem.FileFlagRead, FileSystem.FileFlagWrite] \handle -> do
+            FileSystem.readFileHandleChunk handle 8 >>= (@?= BS.pack [4, 2, 3])
+            FileSystem.writeFileHandleBytes handle (BS.pack [5]) >>= (@?= 1)
+            FileSystem.fileHandleSize handle >>= (@?= 4)
+    , testCase "file flags truncate a file and refuse to create an existing file" $
+        withTemporaryFile \path -> withConnection ":memory:" \conn -> do
+          BS.writeFile path (BS.pack [1, 2, 3])
+          FileSystem.withFileHandle conn path [FileSystem.FileFlagWrite, FileSystem.FileFlagCreateNew] FileSystem.fileHandleSize >>= (@?= 0)
+          let exclusive = [FileSystem.FileFlagWrite, FileSystem.FileFlagCreate, FileSystem.FileFlagExclusiveCreate]
+          assertSqlError $ FileSystem.withFileHandle conn path exclusive (\_ -> pure ())
+          removeFile path
+          FileSystem.withFileHandle conn path exclusive \handle ->
+            FileSystem.writeFileHandleBytes handle (BS.pack [7]) >>= (@?= 1)
+          FileSystem.withFileHandle conn path [FileSystem.FileFlagRead] \handle ->
+            FileSystem.readFileHandleChunk handle 8 >>= (@?= BS.pack [7])
+    , testCase "file paths support expansion glob movement and removal" $
+        withTemporaryFile \path -> withConnection ":memory:" \conn -> do
+          FileSystem.pathExists conn path >>= (@?= True)
+          -- A directory is not a file.
+          FileSystem.pathExists conn (takeDirectory path) >>= (@?= False)
+          home <- getHomeDirectory
+          FileSystem.expandPath conn "~/duckdb-simple-path" >>= (@?= home <> "/duckdb-simple-path")
+          FileSystem.globPaths conn (path <> "*") >>= (@?= [path])
+          FileSystem.pathIsRemote conn "https://example.com/data.parquet" >>= (@?= True)
+          FileSystem.pathIsRemote conn path >>= (@?= False)
+          let moved = path <> ".moved"
+          bracket_ (FileSystem.movePath conn path moved) (FileSystem.movePath conn moved path) do
+            FileSystem.pathExists conn path >>= (@?= False)
+            FileSystem.pathExists conn moved >>= (@?= True)
+          ( do
+              FileSystem.removePath conn path >>= (@?= True)
+              FileSystem.removePath conn path >>= (@?= False)
+            )
+            `finally` BS.writeFile path BS.empty
+          assertSqlError $ FileSystem.globPaths conn (path <> "\0suffix")
+    ]
+
+-- | Raise a second exception when the callback error is rendered.
+data BrokenDisplay = BrokenDisplay
+  deriving (Show)
+
+instance Exception BrokenDisplay where
+  displayException _ = error "broken error rendering"
+
+-- | Force a setup exception after scalar callbacks have been acquired. The
+-- registration reads the declaration of the argument in the setup. The token
+-- lets a case check the release of the value.
+newtype BrokenSignature = BrokenSignature (IORef Int64)
+
+instance Function BrokenSignature where
+  argumentTypes _ = [Right (error "broken scalar signature")]
+  returnType _ = returnType (Proxy @Int64)
+  isVolatile _ = False
+  applyFunction _ _ = error "unused function"
+
+-- | Declare a VARCHAR result, but give a BIGINT value.
+data MismatchedResult = MismatchedResult
+
+instance Function MismatchedResult where
+  argumentTypes _ = []
+  returnType _ = Right (Registration.TypeExpression "VARCHAR")
+  isVolatile _ = True
+  applyFunction fields _ = applyFunction fields (1 :: Int64)
+
+-- | Supply an argument type which DuckDB rejects at registration. The token
+-- lets a case check the release of the value.
+newtype InvalidSignature = InvalidSignature (IORef Int64)
+
+instance Function InvalidSignature where
+  argumentTypes _ = [Right (Registration.TypeExpression "no_such_type")]
+  returnType _ = returnType (Proxy @Int64)
+  isVolatile _ = False
+  applyFunction _ _ = error "unregistered function"
+
+-- | Register a COPY callback and optionally fail one phase. The bind state and
+-- the global state are the column count that DuckDB gives. Each query of this
+-- module has one column.
+registerCopy :: Connection -> Text.Text -> Maybe Int -> IO ()
+registerCopy conn name failingPhase =
+  Copy.registerCopyToFunction
+    conn
+    name
+    (\info -> failPhase 0 >> pure (length (Copy.copyBindColumnTypes info)))
+    (\info -> (Copy.copyInitBindState info @?= 1) >> failPhase 1 >> pure (Copy.copyInitBindState info))
+    (\info _ -> (Copy.copySinkGlobalState info @?= 1) >> failPhase 2)
+    (\info -> (Copy.copyFinalizeGlobalState info @?= 1) >> failPhase 3)
+  where
+    failPhase phase =
+      if failingPhase == Just phase
+        then throwIO (userError ("copy phase " <> show phase))
+        else pure ()
+
+-- | Require a controlled SQL exception.
+assertSqlError :: IO a -> Assertion
+assertSqlError = assertSqlErrorContaining Text.empty
+
+-- | Convert each value to its native value and back. The native value must have
+-- the pattern name of the value. The native sentinel must raise 'SQLError'.
+assertNativeRoundTrip :: (Bounded a, Enum a, Eq a, Show a, Show native) => (a -> native) -> (native -> IO a) -> native -> Assertion
+assertNativeRoundTrip toNative fromNative sentinel = do
+  let values = [minBound .. maxBound]
+  mapM (fromNative . toNative) values >>= (@?= values)
+  map (show . toNative) values @?= map (("DuckDBV2" <>) . show) values
+  assertSqlErrorContaining "unknown native" (fromNative sentinel)
+
+-- | Check that the native values convert to all constructors in order, and that
+-- each constructor has the pattern name of its native value. The native sentinel
+-- must raise 'SQLError'.
+assertFromNative :: (Bounded a, Enum a, Eq a, Show a, Show native) => (native -> IO a) -> [native] -> native -> Assertion
+assertFromNative fromNative natives sentinel = do
+  values <- mapM fromNative natives
+  values @?= [minBound .. maxBound]
+  map show natives @?= map (("DuckDBV2" <>) . show) values
+  assertSqlErrorContaining "unknown native" (fromNative sentinel)
+
+-- | Give the action a unique temporary path where no file exists. Remove the
+-- file after the action if the action created it. DuckDB writes a COPY TO
+-- target that exists through a second file, so the path has no file.
+withMissingFile :: (FilePath -> IO a) -> IO a
+withMissingFile = bracket acquire release
+  where
+    acquire = do
+      directory <- getTemporaryDirectory
+      (path, handle) <- openBinaryTempFile directory "duckdb-extension-regression"
+      hClose handle
+      removeFile path
+      pure path
+    release path = doesFileExist path >>= \exists -> when exists (removeFile path)
+
+-- | Remove a temporary file after the action.
+withTemporaryFile :: (FilePath -> IO a) -> IO a
+withTemporaryFile action =
+  bracket
+    (do (path, handle) <- openBinaryTempFile "/tmp" "duckdb-extension-regression"; hClose handle; pure path)
+    removeFile
+    action
diff --git a/test/GeometryRegressionTests.hs b/test/GeometryRegressionTests.hs
--- a/test/GeometryRegressionTests.hs
+++ b/test/GeometryRegressionTests.hs
@@ -1,404 +1,671 @@
 {-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE DataKinds #-}
 {-# LANGUAGE OverloadedStrings #-}
-{-# OPTIONS_GHC -Wno-deprecations #-}
 
+-- |
+-- Module      : GeometryRegressionTests
+-- Description : Regression tests for GEOMETRY construction, metadata, nesting, and streaming.
 module GeometryRegressionTests (tests) where
 
-import Control.Exception (SomeException, bracket, displayException, try)
-import Control.Monad (forM_)
-import Data.Array (Array, listArray)
+import Control.Exception (bracket, try)
+import Control.Monad (forM, forM_)
+import Data.Array (elems, listArray)
 import qualified Data.ByteString as BS
 import qualified Data.Geometry as G
 import qualified Data.Geometry.WKB as WKB
 import qualified Data.Geometry.WKT as WKT
 import Data.Int (Int64)
-import Data.List (isInfixOf)
 import qualified Data.Map.Strict as Map
 import Data.Text (Text)
 import qualified Data.Text as Text
 import qualified Data.Vector as V
 import qualified Data.Vector.Unboxed as U
 import Database.DuckDB.Simple
-import qualified Database.DuckDB.Simple.Deprecated.Streaming as Streaming
-import Database.DuckDB.Simple.FromField (FieldValue (..), StructValue (..), UnionValue)
+import Database.DuckDB.Simple.FromField (FieldValue (..), StructValue (..), UnionValue (..))
 import Database.DuckDB.Simple.Geometry (RawGeometry (..), fromRawGeometry, toRawGeometry)
-import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep (..), StructField (..), destroyLogicalType, logicalTypeFromRep, logicalTypeToRep)
+import Database.DuckDB.Simple.Internal (withConnectionFactory, withConnectionHandle)
+import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep (..), StructField (..), UnionMemberType (..))
+import qualified Database.DuckDB.Simple.Streaming as Streaming
+import Database.DuckDB.Simple.V2.LogicalRep (destroyLogicalType, logicalTypeFromRep, logicalTypeToRep)
+import Database.DuckDB.Simple.Variant (Variant (..))
 import GHC.Float (castWord64ToDouble)
 import System.Mem (performMajorGC)
 import Test.Tasty (TestTree, testGroup)
 import Test.Tasty.HUnit
-import TestUtils (assertFailureIO)
+import TestUtils (assertFailureIO, assertSqlErrorType, sized)
 
 -- | Check native construction, metadata, nesting, and streaming.
 tests :: TestTree
 tests =
-    testGroup
-        "geometry integration"
-        [ testCase "Haskell shapes bind directly in every coordinate layout" $
-            withConnection ":memory:" \conn -> do
-                shapeRoundTrips conn G.DimXY G.PointXY G.CoordinatesXY (G.XY 1 2) (G.XY 3 4)
-                shapeRoundTrips conn G.DimXYZ G.PointXYZ G.CoordinatesXYZ (G.XYZ 1 2 3) (G.XYZ 4 5 6)
-                shapeRoundTrips conn G.DimXYM G.PointXYM G.CoordinatesXYM (G.XYM 1 2 3) (G.XYM 4 5 6)
-                shapeRoundTrips conn G.DimXYZM G.PointXYZM G.CoordinatesXYZM (G.XYZM 1 2 3 4) (G.XYZM 5 6 7 8)
-        , testCase "large coordinate buffers survive native round trips" $
-            withConnection ":memory:" \conn -> do
-                let coordinates = U.generate 10000 (\i -> G.XY (fromIntegral i) (fromIntegral (i * 2)))
-                    points = U.imap (\i coordinate -> if i `mod` 17 == 0 then G.EmptyPoint G.DimXY else G.PointXY coordinate) coordinates
-                forM_ [G.LineString (G.CoordinatesXY coordinates), G.MultiPoint points] \shape -> do
-                    (query conn "SELECT ?" (Only shape)) >>= (@?= [Only shape])
-                    raw <- either assertFailure pure (toRawGeometry shape)
-                    (importRaw conn raw) >>= (@?= [Only raw])
-        , testCase "WKT binding preserves exact finite coordinate bits" $
-            withConnection ":memory:" \conn ->
-                forM_ [0, 0x8000000000000000, 1, 0x8000000000000001, 0x000fffffffffffff, 0x0010000000000000, 0x3fb999999999999b, 0x3ff0000000000001, 0x44b52d02c7e14af6, 0x7fefffffffffffff, 0xffefffffffffffff] \bits -> do
-                    let shape = G.PointGeometry (G.PointXY (G.XY (castWord64ToDouble bits) (-0.0)))
-                    expected <- either assertFailure pure (WKB.encodeWKB shape)
-                    [(actual, wkt)] <- query conn "SELECT ST_AsWKB(?), ST_AsText(?)" (shape, shape) :: IO [(BS.ByteString, Text)]
-                    actual @?= expected
-                    (WKT.decodeWKT wkt >>= WKB.encodeWKB) @?= Right expected
-                    (query conn "SELECT system.main.ST_AsWKB(system.main.ST_GeomFromWKB(?))" (Only expected) :: IO [Only BS.ByteString])
-                        >>= (@?= [Only expected])
-        , testCase "pure WKT decoding agrees with native geometry results" $
-            withConnection ":memory:" \conn ->
-                forM_ shapes \wkt -> do
-                    [(native, rendered)] <- query conn "SELECT ?::GEOMETRY, ST_AsText(?::GEOMETRY)" (wkt, wkt) :: IO [(G.Geometry, Text)]
-                    WKT.decodeWKT wkt @?= Right native
-                    WKT.decodeWKT rendered @?= Right native
-        , testCase "native bare multipoint EMPTY syntax parses as WKT" $
-            withConnection ":memory:" \conn -> do
-                [(native, bytes, rendered)] <-
-                    query_ conn "SELECT g, ST_AsWKB(g), ST_AsText(g) FROM (SELECT 'MULTIPOINT ((1 2), EMPTY, (3 4))'::GEOMETRY AS g)" :: IO [(G.Geometry, BS.ByteString, Text)]
-                native @?= G.MultiPoint (U.fromList [G.PointXY (G.XY 1 2), G.EmptyPoint G.DimXY, G.PointXY (G.XY 3 4)])
-                WKB.decodeWKB bytes @?= Right native
-                WKT.decodeWKT rendered @?= Right native
-                (WKT.encodeWKT native >>= WKT.decodeWKT) @?= Right native
-        , testCase "standalone WKT syntax binds through native geometry parameters" $
-            withConnection ":memory:" \conn ->
-                forM_ ["point(+.5 -1.e+2)", "MULTIPOINT (EMPTY, (1 2), (3 4))", "MULTIPOINT (EMPTY, 1 2, EMPTY, 3 4, EMPTY)"] \wkt -> do
-                    shape <- either assertFailure pure (WKT.decodeWKT wkt)
-                    (query conn "SELECT ?" (Only shape)) >>= (@?= [Only shape])
-        , testCase "native geometry depth limit produces a recoverable error" $
-            withConnection ":memory:" \conn -> do
-                let nested = iterate (G.GeometryCollection . V.singleton) (G.PointGeometry (G.PointXY (G.XY 1 2)))
-                    accepted = nested !! 15
-                    rejected = nested !! 16
-                (query conn "SELECT ?" (Only accepted)) >>= (@?= [Only accepted])
-                assertFailureIO (query conn "SELECT ?" (Only rejected) :: IO [Only G.Geometry])
-                (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
-        , testCase "decoded native shapes round trip through parameters and WKB" $
-            withConnection ":memory:" \conn ->
-                forM_ shapes \wkt -> do
-                    [Only geometry] <- query conn "SELECT ?::GEOMETRY" (Only wkt) :: IO [Only G.Geometry]
-                    (query conn "SELECT ?" (Only geometry) :: IO [Only G.Geometry]) >>= (@?= [Only geometry])
-                    raw <- either assertFailure pure (toRawGeometry geometry)
-                    fromRawGeometry raw @?= Right geometry
-        , testCase "decoded rows retain point and sequence layouts, including empties" $
-            withConnection ":memory:" \conn ->
-                forM_
-                    [ ("POINT Z EMPTY", G.PointGeometry (G.EmptyPoint G.DimXYZ))
-                    , ("LINESTRING M EMPTY", G.LineString (G.CoordinatesXYM U.empty))
-                    , ("POINT Z (1 2 3)", G.PointGeometry (G.PointXYZ (G.XYZ 1 2 3)))
-                    , ("POINT EMPTY", G.PointGeometry (G.EmptyPoint G.DimXY))
-                    ]
-                    \(wkt, expected) ->
-                        (query conn "SELECT ?::GEOMETRY" (Only (wkt :: Text)) :: IO [Only G.Geometry])
-                            >>= (@?= [Only expected])
-        , testCase "decoded arrays preserve shapes and NULL elements without CRS" $
-            withConnection ":memory:" \conn -> do
-                let geometry = G.PointGeometry (G.PointXYM (G.XYM 1 2 3))
-                    values = listArray (0, 2) [Nothing, Just geometry, Just (G.PointGeometry (G.EmptyPoint G.DimXYM))]
-                (query conn "SELECT ?, ST_CRS((?)[2])" (values, values) :: IO [(Array Int (Maybe G.Geometry), Maybe Text)])
-                    >>= (@?= [(values, Nothing)])
-        , testCase "only raw geometry retains CRS metadata" $
-            withConnection ":memory:" \conn -> do
-                [(raw, shape)] <- query_ conn "SELECT g, g FROM (SELECT 'POINT ZM (1 2 3 4)'::GEOMETRY('OGC:CRS84') AS g)" :: IO [(RawGeometry, G.Geometry)]
-                rawGeometryCRS raw @?= Just "OGC:CRS84"
-                shape @?= G.PointGeometry (G.PointXYZM (G.XYZM 1 2 3 4))
-                fromRawGeometry raw @?= Right shape
-                unannotated <- either assertFailure pure (toRawGeometry shape)
-                rawGeometryCRS unannotated @?= Nothing
-                rawGeometryWKB unannotated @?= rawGeometryWKB raw
-                (query conn "SELECT system.main.ST_CRS(system.main.ST_SetCRS(system.main.ST_GeomFromWKB(?), ?))" (rawParameters raw) :: IO [Only (Maybe Text)])
-                    >>= (@?= [Only (Just "OGC:CRS84")])
-                (query conn "SELECT ST_CRS(?), ?" (shape, shape) :: IO [(Maybe Text, G.Geometry)])
-                    >>= (@?= [(Nothing, shape)])
-        , testCase "decoded coordinates remain usable after closing their connection" $ do
-            geometry <- withConnection ":memory:" \conn -> do
-                [Only value] <- query_ conn "SELECT 'LINESTRING (1 2, 3 4, 5 6)'::GEOMETRY('OGC:CRS84')" :: IO [Only G.Geometry]
-                pure value
-            performMajorGC
-            case geometry of
-                G.LineString (G.CoordinatesXY coords) -> U.foldl' (\acc (G.XY x y) -> acc + x + y) 0 coords @?= 21
-                other -> assertFailure ("unexpected geometry: " <> show other)
-        , testCase "native WKB round trips through explicit binary import" $
-            withConnection ":memory:" \conn ->
-                forM_ shapes \wkt -> do
-                    [Only geometry] <- query conn "SELECT ?::GEOMETRY" (Only wkt)
-                    (query conn "SELECT typeof(system.main.ST_GeomFromWKB(?)), system.main.ST_GeomFromWKB(?)" (rawGeometryWKB geometry, rawGeometryWKB geometry) :: IO [(Text, RawGeometry)])
-                        >>= (@?= [("GEOMETRY", geometry)])
-        , testCase "raw empty containers retain layouts that decoded values do not store" $
-            withConnection ":memory:" \conn ->
-                forM_
-                    ( [ (family <> " " <> dimensions <> " EMPTY", family <> " EMPTY")
-                      | family <- ["MULTIPOINT", "MULTILINESTRING", "MULTIPOLYGON", "GEOMETRYCOLLECTION"]
-                      , dimensions <- ["Z", "M", "ZM"]
-                      ]
-                        ++ [("GEOMETRYCOLLECTION ZM (MULTIPOINT ZM EMPTY, GEOMETRYCOLLECTION ZM EMPTY)", "GEOMETRYCOLLECTION (MULTIPOINT EMPTY, GEOMETRYCOLLECTION EMPTY)")]
-                    )
-                    \(wkt, normalizedWKT) -> do
-                        [Only raw] <- query conn "SELECT ?::GEOMETRY('OGC:CRS84')" (Only (wkt :: Text)) :: IO [Only RawGeometry]
-                        (importRaw conn raw) >>= (@?= [Only raw])
-                        decoded <- either assertFailure pure (fromRawGeometry raw)
-                        WKT.encodeWKT decoded @?= Right normalizedWKT
-                        normalized <- either assertFailure pure (toRawGeometry decoded)
-                        rawGeometryCRS normalized @?= Nothing
-                        assertBool "decoded empty containers must not retain an unstored dimension tag" (rawGeometryWKB normalized /= rawGeometryWKB raw)
-        , testCase "mixed-layout collections use binary import without WKT normalization" $
-            withConnection ":memory:" \conn -> do
-                let geometry = G.GeometryCollection (V.fromList [G.PointGeometry (G.PointXY (G.XY 1 2)), G.PointGeometry (G.PointXYZ (G.XYZ 3 4 5))])
-                raw <- either assertFailure pure (toRawGeometry geometry)
-                assertFailureIO (query conn "SELECT ?" (Only geometry) :: IO [Only G.Geometry])
-                (importRaw conn raw) >>= (@?= [Only raw])
-                (query conn "SELECT ST_GeomFromWKB(?)" (Only (rawGeometryWKB raw)) :: IO [Only G.Geometry])
-                    >>= (@?= [Only geometry])
-                (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
-        , testCase "mixed multipoint layouts promote missing ordinates to NaN" $
-            withConnection ":memory:" \conn -> do
-                let geometry = G.MultiPoint (U.fromList [G.PointXY (G.XY 1 2), G.PointXYZ (G.XYZ 3 4 5)])
-                [Only actual] <- query conn "SELECT ?" (Only geometry) :: IO [Only G.Geometry]
-                case actual of
-                    G.MultiPoint points -> do
-                        U.length points @?= 2
-                        case points U.! 0 of
-                            G.PointXYZ (G.XYZ x y z) -> do
-                                (x, y) @?= (1, 2)
-                                assertBool "promoted Z must be NaN" (isNaN z)
-                            other -> assertFailure ("unexpected promoted point: " <> show other)
-                        points U.! 1 @?= G.PointXYZ (G.XYZ 3 4 5)
-                    other -> assertFailure ("unexpected geometry: " <> show other)
-        , testCase "raw NaN points retain ordinates that decoded emptiness normalizes" $
-            withConnection ":memory:" \conn -> do
-                [Only raw] <- query_ conn "SELECT 'POINT Z (NaN NaN 7)'::GEOMETRY" :: IO [Only RawGeometry]
-                (importRaw conn raw) >>= (@?= [Only raw])
-                decoded <- either assertFailure pure (fromRawGeometry raw)
-                decoded @?= G.PointGeometry (G.EmptyPoint G.DimXYZ)
-                normalized <- either assertFailure pure (toRawGeometry decoded)
-                assertBool "decoding an XY-NaN point normalizes its extra ordinates" (rawGeometryWKB normalized /= rawGeometryWKB raw)
-                (query conn "SELECT ?" (Only decoded) :: IO [Only G.Geometry]) >>= (@?= [Only decoded])
-        , testCase "binary import preserves distinct NaN payload bits" $
-            withConnection ":memory:" \conn -> do
-                let shape = G.PointGeometry (G.PointXYZ (G.XYZ (castWord64ToDouble 0x7ff8000000000001) (castWord64ToDouble 0x7ff8000000000002) 7))
-                raw <- either assertFailure pure (toRawGeometry shape)
-                (importRaw conn raw) >>= (@?= [Only raw])
-                fromRawGeometry raw @?= Right (G.PointGeometry (G.EmptyPoint G.DimXYZ))
-        , testCase "binary import preserves mixed empty and nonempty member layouts" $
-            withConnection ":memory:" \conn -> do
-                let shape = G.GeometryCollection (V.fromList [G.PointGeometry (G.EmptyPoint G.DimXY), G.PointGeometry (G.PointXYZ (G.XYZ 1 2 3))])
-                raw <- either assertFailure pure (toRawGeometry shape)
-                (query conn "SELECT system.main.ST_GeomFromWKB(?)" (Only (rawGeometryWKB raw)) :: IO [Only RawGeometry]) >>= (@?= [Only raw])
-                (query conn "SELECT system.main.ST_GeomFromWKB(?)" (Only (rawGeometryWKB raw)) :: IO [Only G.Geometry]) >>= (@?= [Only shape])
-        , testCase "decoded polygon writing normalizes all-empty rings" $
-            withConnection ":memory:" \conn -> do
-                let emptyRing = G.CoordinatesXYZ U.empty
-                    geometry = G.Polygon (G.PolygonRings emptyRing (V.singleton emptyRing))
-                    expected = G.Polygon (G.PolygonRings emptyRing V.empty)
-                (query conn "SELECT ?" (Only geometry) :: IO [Only G.Geometry]) >>= (@?= [Only expected])
-        , testCase "invalid decoded construction fails without poisoning the connection" $
-            withConnection ":memory:" \conn -> do
-                let closedRing = G.CoordinatesXY (U.fromList [G.XY 0 0, G.XY 1 0, G.XY 1 1, G.XY 0 0])
-                    openRing = G.CoordinatesXY (U.fromList [G.XY 0 0, G.XY 1 0, G.XY 1 1])
-                    emptyRing = G.CoordinatesXY U.empty
-                forM_
-                    [ G.LineString (G.CoordinatesXY (U.singleton (G.XY 1 2)))
-                    , G.Polygon (G.PolygonRings openRing V.empty)
-                    , G.Polygon (G.PolygonRings emptyRing (V.singleton closedRing))
-                    ]
-                    \shape ->
-                        assertFailureIO (query conn "SELECT ?" (Only shape) :: IO [Only G.Geometry])
-                [Only raw] <- query_ conn "SELECT 'LINESTRING (1 2)'::GEOMETRY" :: IO [Only RawGeometry]
-                assertBool "raw result bytes remain available" (not (BS.null (rawGeometryWKB raw)))
-                assertFailureIO (query_ conn "SELECT 'LINESTRING (1 2)'::GEOMETRY" :: IO [Only G.Geometry])
-                (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
-        , testCase "CRS survives explicit binary import and table insertion" $
-            withConnection ":memory:" \conn -> do
-                [Only geometry] <- query_ conn "SELECT 'POINT ZM (1 2 3 4)'::GEOMETRY('OGC:CRS84')"
-                rawGeometryCRS geometry @?= Just "OGC:CRS84"
-                (importRaw conn geometry)
-                    >>= (@?= [Only geometry])
-                _ <- execute_ conn "CREATE TABLE shapes (shape GEOMETRY('OGC:CRS84'))"
-                _ <- execute conn "INSERT INTO shapes VALUES (system.main.ST_SetCRS(system.main.ST_GeomFromWKB(?), ?))" (rawParameters geometry)
-                (query_ conn "SELECT shape FROM shapes" :: IO [Only RawGeometry]) >>= (@?= [Only geometry])
-        , testCase "CRS parameters preserve custom names and full definitions" $
-            withConnection ":memory:" \conn -> do
-                [Only geometry] <- query_ conn "SELECT 'POINT (1 2)'::GEOMETRY"
-                forM_
-                    [ "local' íslenska λ"
-                    , "ENGCRS[\"Local grid\",EDATUM[\"Local datum\"],CS[Cartesian,2],AXIS[\"x\",east,ORDER[1],LENGTHUNIT[\"metre\",1]],AXIS[\"y\",north,ORDER[2],LENGTHUNIT[\"metre\",1]]]"
-                    , "{\"type\":\"EngineeringCRS\",\"name\":\"Local grid\",\"datum\":{\"type\":\"EngineeringDatum\",\"name\":\"Local datum\"},\"coordinate_system\":{\"subtype\":\"Cartesian\",\"axis\":[{\"name\":\"x\",\"abbreviation\":\"x\",\"direction\":\"east\",\"unit\":\"metre\"},{\"name\":\"y\",\"abbreviation\":\"y\",\"direction\":\"north\",\"unit\":\"metre\"}]}}"
-                    ]
-                    \crs -> do
-                        let annotated = geometry{rawGeometryCRS = Just crs}
-                        (importRaw conn annotated) >>= (@?= [Only annotated])
-        , testCase "geometry construction ignores user macros with built-in names" $
-            withConnection ":memory:" \conn -> do
-                [Only raw] <- query_ conn "SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84')" :: IO [Only RawGeometry]
-                decoded <- either assertFailure pure (fromRawGeometry raw)
-                _ <- execute_ conn "CREATE MACRO ST_AsText(x) AS 42"
-                _ <- execute_ conn "CREATE MACRO ST_GeomFromWKB(x) AS 'POINT (9 9)'::GEOMETRY"
-                _ <- execute_ conn "CREATE MACRO ST_SetCRS(x, crs) AS 42"
-                (query conn "SELECT system.main.ST_SetCRS(system.main.ST_GeomFromWKB(?), ?), ?" (rawGeometryWKB raw, rawGeometryCRS raw, decoded) :: IO [(RawGeometry, G.Geometry)])
-                    >>= (@?= [(raw, decoded)])
-        , testCase "NULL and empty geometry stay distinct" $
-            withConnection ":memory:" \conn -> do
-                [Only empty] <- query_ conn "SELECT 'POINT EMPTY'::GEOMETRY" :: IO [Only RawGeometry]
-                (query conn "SELECT system.main.ST_GeomFromWKB(?), system.main.ST_GeomFromWKB(?)" (Nothing :: Maybe BS.ByteString, Just (rawGeometryWKB empty)) :: IO [(Maybe RawGeometry, Maybe RawGeometry)])
-                    >>= (@?= [(Nothing, Just empty)])
-        , testCase "binary import constructs arrays with a common CRS and NULL elements" $
-            withConnection ":memory:" \conn -> do
-                [Only geometry] <- query_ conn "SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84')" :: IO [Only RawGeometry]
-                let values = listArray (0, 2) [Nothing, Just geometry, Nothing]
-                (query conn "SELECT [NULL, system.main.ST_SetCRS(system.main.ST_GeomFromWKB(?), ?), NULL]::GEOMETRY('OGC:CRS84')[3]" (rawParameters geometry) :: IO [Only (Array Int (Maybe RawGeometry))]) >>= (@?= [Only values])
-        , testCase "nested LIST, ARRAY and MAP results preserve CRS and reject implicit raw binding" $
-            withConnection ":memory:" \conn -> do
-                [Only value] <-
-                    query_
-                        conn
-                        "SELECT {'xs': ['POINT (1 2)'::GEOMETRY('OGC:CRS84'), NULL], 'fixed': ['POINT EMPTY'::GEOMETRY('OGC:CRS84')]::GEOMETRY('OGC:CRS84')[1], 'map': MAP {'one': 'POINT (3 4)'::GEOMETRY('OGC:CRS84')}}" ::
-                        IO [Only (StructValue FieldValue)]
-                assertRawBindingFailure (query conn "SELECT ?" (Only value) :: IO [Only (StructValue FieldValue)])
-                (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
-        , testCase "UNION geometry results retain CRS and reject implicit raw binding" $
-            withConnection ":memory:" \conn -> do
-                [Only value] <- query_ conn "SELECT union_value(shape := 'POINT (1 2)'::GEOMETRY('OGC:CRS84'))" :: IO [Only (UnionValue FieldValue)]
-                assertRawBindingFailure (query conn "SELECT ?" (Only value) :: IO [Only (UnionValue FieldValue)])
-                [Only nullValue] <- query_ conn "SELECT union_value(shape := NULL::GEOMETRY('OGC:CRS84'))" :: IO [Only (UnionValue FieldValue)]
-                (query conn "SELECT ?" (Only nullValue) :: IO [Only (UnionValue FieldValue)]) >>= (@?= [Only nullValue])
-                (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
-        , testCase "inactive UNION geometry members keep the CRS of the type cache" $
-            withConnection ":memory:" \conn -> do
-                [Only value] <- query_ conn "SELECT union_value(number := 42::BIGINT)::UNION(number BIGINT, shape GEOMETRY('OGC:CRS84'))" :: IO [Only (UnionValue FieldValue)]
-                (query conn "SELECT typeof(?)" (Only value) :: IO [Only Text]) >>= (@?= [Only "UNION(number BIGINT, shape GEOMETRY('OGC:CRS84'))"])
-                (query conn "SELECT ?" (Only value) :: IO [Only (UnionValue FieldValue)]) >>= (@?= [Only value])
-        , testCase "NULL and empty nested geometry collections keep the CRS of the type cache" $
-            withConnection ":memory:" \conn -> do
-                _ <-
-                    execute_
-                        conn
-                        "CREATE TABLE nested AS SELECT {'null_list': NULL::GEOMETRY('OGC:CRS84')[], 'empty_list': []::GEOMETRY('OGC:CRS84')[], 'null_array': NULL::GEOMETRY('OGC:CRS84')[2], 'array': [NULL, NULL]::GEOMETRY('OGC:CRS84')[2], 'null_map': NULL::MAP(VARCHAR, GEOMETRY('OGC:CRS84')), 'empty_map': map([], [])::MAP(VARCHAR, GEOMETRY('OGC:CRS84')), 'map': map(['one'], [NULL::GEOMETRY('OGC:CRS84')])} AS v"
-                [Only value] <- query_ conn "SELECT v FROM nested" :: IO [Only (StructValue FieldValue)]
-                (query conn "SELECT ?" (Only value) :: IO [Only (StructValue FieldValue)]) >>= (@?= [Only value])
-                _ <- execute conn "INSERT INTO nested VALUES (?)" (Only value)
-                (query_ conn "SELECT v FROM nested" :: IO [Only (StructValue FieldValue)]) >>= (@?= [Only value, Only value])
-        , testCase "configured CRS definitions bind; other CRS definitions bind without a CRS" $ do
-            let crs = "local' íslenska λ"
-            withConnectionWithOptions ":memory:" defaultConnectionOptions{connectionGeometryCRS = [crs]} \conn -> do
-                [Only typed] <- query conn "SELECT typeof(?)" (Only (nullShape crs)) :: IO [Only Text]
-                assertBool (Text.unpack typed) ("íslenska λ" `Text.isInfixOf` typed)
-                (query conn "SELECT ?" (Only (nullShape crs)) :: IO [Only (StructValue FieldValue)]) >>= (@?= [Only (nullShape crs)])
-                (query conn "SELECT typeof(?)" (Only (nullShape "OGC:CRS84")) :: IO [Only Text]) >>= (@?= [Only "STRUCT(shape GEOMETRY)"])
-        , testCase "connection options validate CRS definitions and pass configuration flags" $ do
-            forM_ ["", "OGC:CRS84\0bad"] \crs ->
-                assertFailureIO (withConnectionWithOptions ":memory:" defaultConnectionOptions{connectionGeometryCRS = [crs]} (const (pure ())))
-            let options = defaultConnectionOptions{connectionConfig = [("threads", "1")], connectionGeometryCRS = ["local grid", "OGC:CRS84", "OGC:CRS84"]}
-            withConnectionWithOptions ":memory:" options \conn ->
-                (query_ conn "SELECT current_setting('threads')" :: IO [Only Int64]) >>= (@?= [Only 1])
-        , testCase "logical type construction drops CRS" $ do
-            let logical = LogicalTypeList (LogicalTypeGeometry (Just "OGC:CRS84"))
-            bracket (logicalTypeFromRep logical) destroyLogicalType logicalTypeToRep
-                >>= (@?= LogicalTypeList (LogicalTypeGeometry Nothing))
-        , testGroup
-            "folds cross chunk boundaries and preserve CRS"
-            [ testCase mode $
-                withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
-                    [Only expected] <- query_ conn "SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84')" :: IO [Only RawGeometry]
-                    count <- foldRows conn "SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84') FROM range(5000)" (0 :: Int64) \n (Only actual) -> do
-                        actual @?= expected
-                        pure (n + 1)
-                    count @?= 5000
-            | (mode, foldRows) <- [("materialized", fold_), ("deprecated streaming", Streaming.fold_)]
+  testGroup
+    "geometry integration"
+    [ testCase "Haskell shapes bind directly in every coordinate layout" $
+        withConnection ":memory:" \conn -> do
+          shapeRoundTrips conn G.DimXY G.PointXY G.CoordinatesXY (G.XY 1 2) (G.XY 3 4)
+          shapeRoundTrips conn G.DimXYZ G.PointXYZ G.CoordinatesXYZ (G.XYZ 1 2 3) (G.XYZ 4 5 6)
+          shapeRoundTrips conn G.DimXYM G.PointXYM G.CoordinatesXYM (G.XYM 1 2 3) (G.XYM 4 5 6)
+          shapeRoundTrips conn G.DimXYZM G.PointXYZM G.CoordinatesXYZM (G.XYZM 1 2 3 4) (G.XYZM 5 6 7 8)
+    , testCase "large coordinate buffers survive native round trips" $
+        withConnection ":memory:" \conn -> do
+          let coordinates = U.generate 10000 (\i -> G.XY (fromIntegral i) (fromIntegral (i * 2)))
+              points = U.imap (\i coordinate -> if i `mod` 17 == 0 then G.EmptyPoint G.DimXY else G.PointXY coordinate) coordinates
+          forM_ [G.LineString (G.CoordinatesXY coordinates), G.MultiPoint points] \shape -> do
+            (query conn "SELECT ?" (Only shape)) >>= (@?= [Only shape])
+            raw <- either assertFailure pure (toRawGeometry shape)
+            (importRaw conn raw) >>= (@?= [Only raw])
+    , testCase "WKT binding preserves exact finite coordinate bits" $
+        withConnection ":memory:" \conn ->
+          forM_
+            [ 0
+            , 0x8000000000000000
+            , 1
+            , 0x8000000000000001
+            , 0x000fffffffffffff
+            , 0x0010000000000000
+            , 0x3fb999999999999b
+            , 0x3ff0000000000001
+            , 0x44b52d02c7e14af6
+            , 0x7fefffffffffffff
+            , 0xffefffffffffffff
             ]
-        , testCase "invalid binary import leaves the connection usable" $
-            withConnection ":memory:" \conn -> do
-                assertFailureIO (query conn "SELECT system.main.ST_GeomFromWKB(?)" (Only (BS.pack [1, 1, 0, 0, 0])) :: IO [Only RawGeometry])
-                (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+            \bits -> do
+              let shape = G.PointGeometry (G.PointXY (G.XY (castWord64ToDouble bits) (-0.0)))
+              expected <- either assertFailure pure (WKB.encodeWKB shape)
+              [(actual, wkt)] <- query conn "SELECT ST_AsWKB(?), ST_AsText(?)" (shape, shape) :: IO [(BS.ByteString, Text)]
+              actual @?= expected
+              (WKT.decodeWKT wkt >>= WKB.encodeWKB) @?= Right expected
+              (query conn "SELECT system.main.ST_AsWKB(system.main.ST_GeomFromWKB(?))" (Only expected) :: IO [Only BS.ByteString])
+                >>= (@?= [Only expected])
+    , testCase "pure WKT decoding agrees with native geometry results" $
+        withConnection ":memory:" \conn ->
+          forM_ shapes \wkt -> do
+            [(native, rendered)] <- query conn "SELECT ?::GEOMETRY, ST_AsText(?::GEOMETRY)" (wkt, wkt) :: IO [(G.Geometry, Text)]
+            WKT.decodeWKT wkt @?= Right native
+            WKT.decodeWKT rendered @?= Right native
+    , testCase "native bare multipoint EMPTY syntax parses as WKT" $
+        withConnection ":memory:" \conn -> do
+          [(native, bytes, rendered)] <-
+            query_ conn "SELECT g, ST_AsWKB(g), ST_AsText(g) FROM (SELECT 'MULTIPOINT ((1 2), EMPTY, (3 4))'::GEOMETRY AS g)"
+              :: IO [(G.Geometry, BS.ByteString, Text)]
+          native @?= G.MultiPoint (U.fromList [G.PointXY (G.XY 1 2), G.EmptyPoint G.DimXY, G.PointXY (G.XY 3 4)])
+          WKB.decodeWKB bytes @?= Right native
+          WKT.decodeWKT rendered @?= Right native
+          (WKT.encodeWKT native >>= WKT.decodeWKT) @?= Right native
+    , testCase "standalone WKT syntax binds through native geometry parameters" $
+        withConnection ":memory:" \conn ->
+          forM_ ["point(+.5 -1.e+2)", "MULTIPOINT (EMPTY, (1 2), (3 4))", "MULTIPOINT (EMPTY, 1 2, EMPTY, 3 4, EMPTY)"] \wkt -> do
+            shape <- either assertFailure pure (WKT.decodeWKT wkt)
+            (query conn "SELECT ?" (Only shape)) >>= (@?= [Only shape])
+    , testCase "native geometry depth limit produces a recoverable error" $
+        withConnection ":memory:" \conn -> do
+          let nested = iterate (G.GeometryCollection . V.singleton) (G.PointGeometry (G.PointXY (G.XY 1 2)))
+              accepted = nested !! 15
+              rejected = nested !! 16
+          (query conn "SELECT ?" (Only accepted)) >>= (@?= [Only accepted])
+          assertSqlErrorType ErrorInputInvalid (query conn "SELECT ?" (Only rejected) :: IO [Only G.Geometry])
+          (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+    , testCase "decoded native shapes round trip through parameters and WKB" $
+        withConnection ":memory:" \conn ->
+          forM_ shapes \wkt -> do
+            [Only geometry] <- query conn "SELECT ?::GEOMETRY" (Only wkt) :: IO [Only G.Geometry]
+            (query conn "SELECT ?" (Only geometry) :: IO [Only G.Geometry]) >>= (@?= [Only geometry])
+            raw <- either assertFailure pure (toRawGeometry geometry)
+            fromRawGeometry raw @?= Right geometry
+    , testCase "decoded rows retain point and sequence layouts, including empties" $
+        withConnection ":memory:" \conn ->
+          forM_
+            [ ("POINT Z EMPTY", G.PointGeometry (G.EmptyPoint G.DimXYZ))
+            , ("LINESTRING M EMPTY", G.LineString (G.CoordinatesXYM U.empty))
+            , ("POINT Z (1 2 3)", G.PointGeometry (G.PointXYZ (G.XYZ 1 2 3)))
+            , ("POINT EMPTY", G.PointGeometry (G.EmptyPoint G.DimXY))
+            ]
+            \(wkt, expected) ->
+              (query conn "SELECT ?::GEOMETRY" (Only (wkt :: Text)) :: IO [Only G.Geometry])
+                >>= (@?= [Only expected])
+    , testCase "decoded arrays preserve shapes and NULL elements without CRS" $
+        withConnection ":memory:" \conn -> do
+          let geometry = G.PointGeometry (G.PointXYM (G.XYM 1 2 3))
+              values = sized [Nothing, Just geometry, Just (G.PointGeometry (G.EmptyPoint G.DimXYM))] :: SizedArray 3 (Maybe G.Geometry)
+          (query conn "SELECT ?, ST_CRS((?)[2])" (values, values) :: IO [(SizedArray 3 (Maybe G.Geometry), Maybe Text)])
+            >>= (@?= [(values, Nothing)])
+    , testCase "only raw geometry retains CRS metadata" $
+        withConnection ":memory:" \conn -> do
+          [(raw, shape)] <- query_ conn "SELECT g, g FROM (SELECT 'POINT ZM (1 2 3 4)'::GEOMETRY('OGC:CRS84') AS g)" :: IO [(RawGeometry, G.Geometry)]
+          rawGeometryCRS raw @?= Just "OGC:CRS84"
+          shape @?= G.PointGeometry (G.PointXYZM (G.XYZM 1 2 3 4))
+          fromRawGeometry raw @?= Right shape
+          unannotated <- either assertFailure pure (toRawGeometry shape)
+          rawGeometryCRS unannotated @?= Nothing
+          rawGeometryWKB unannotated @?= rawGeometryWKB raw
+          ( query conn "SELECT system.main.ST_CRS(system.main.ST_SetCRS(system.main.ST_GeomFromWKB(?), ?))" (rawParameters raw)
+              :: IO [Only (Maybe Text)]
+            )
+            >>= (@?= [Only (Just "OGC:CRS84")])
+          (query conn "SELECT ST_CRS(?), ?" (shape, shape) :: IO [(Maybe Text, G.Geometry)])
+            >>= (@?= [(Nothing, shape)])
+    , testCase "decoded coordinates remain usable after closing their connection" $ do
+        geometry <- withConnection ":memory:" \conn -> do
+          [Only value] <- query_ conn "SELECT 'LINESTRING (1 2, 3 4, 5 6)'::GEOMETRY('OGC:CRS84')" :: IO [Only G.Geometry]
+          pure value
+        performMajorGC
+        case geometry of
+          G.LineString (G.CoordinatesXY coords) -> U.foldl' (\acc (G.XY x y) -> acc + x + y) 0 coords @?= 21
+          other -> assertFailure ("unexpected geometry: " <> show other)
+    , testCase "native WKB round trips through explicit binary import" $
+        withConnection ":memory:" \conn ->
+          forM_ shapes \wkt -> do
+            [Only geometry] <- query conn "SELECT ?::GEOMETRY" (Only wkt)
+            ( query conn "SELECT typeof(system.main.ST_GeomFromWKB(?)), system.main.ST_GeomFromWKB(?)" (rawGeometryWKB geometry, rawGeometryWKB geometry)
+                :: IO [(Text, RawGeometry)]
+              )
+              >>= (@?= [("GEOMETRY", geometry)])
+    , testCase "raw empty containers retain layouts that decoded values do not store" $
+        withConnection ":memory:" \conn ->
+          forM_
+            ( [ (family <> " " <> dimensions <> " EMPTY", family <> " EMPTY")
+              | family <- ["MULTIPOINT", "MULTILINESTRING", "MULTIPOLYGON", "GEOMETRYCOLLECTION"]
+              , dimensions <- ["Z", "M", "ZM"]
+              ]
+                ++ [
+                     ( "GEOMETRYCOLLECTION ZM (MULTIPOINT ZM EMPTY, GEOMETRYCOLLECTION ZM EMPTY)"
+                     , "GEOMETRYCOLLECTION (MULTIPOINT EMPTY, GEOMETRYCOLLECTION EMPTY)"
+                     )
+                   ]
+            )
+            \(wkt, normalizedWKT) -> do
+              [Only raw] <- query conn "SELECT ?::GEOMETRY('OGC:CRS84')" (Only (wkt :: Text)) :: IO [Only RawGeometry]
+              (importRaw conn raw) >>= (@?= [Only raw])
+              decoded <- either assertFailure pure (fromRawGeometry raw)
+              WKT.encodeWKT decoded @?= Right normalizedWKT
+              normalized <- either assertFailure pure (toRawGeometry decoded)
+              rawGeometryCRS normalized @?= Nothing
+              assertBool "decoded empty containers must not retain an unstored dimension tag" (rawGeometryWKB normalized /= rawGeometryWKB raw)
+    , testCase "mixed-layout collections retain WKB but native import rejects them" $
+        withConnection ":memory:" \conn -> do
+          let geometry = G.GeometryCollection (V.fromList [G.PointGeometry (G.PointXY (G.XY 1 2)), G.PointGeometry (G.PointXYZ (G.XYZ 3 4 5))])
+          raw <- either assertFailure pure (toRawGeometry geometry)
+          fromRawGeometry raw @?= Right geometry
+          (fromRawGeometry raw >>= toRawGeometry) @?= Right raw
+          assertSqlErrorType ErrorInputInvalid (query conn "SELECT ?" (Only geometry) :: IO [Only G.Geometry])
+          assertMixedLayoutFailure ErrorInputInvalid (importRaw conn raw)
+          assertMixedLayoutFailure
+            ErrorInputInvalid
+            (query conn "SELECT system.main.ST_GeomFromWKB(?)" (Only (rawGeometryWKB raw)) :: IO [Only G.Geometry])
+          assertMixedLayoutFailure ErrorTypeConversion (query conn "SELECT ?::GEOMETRY" (Only (rawGeometryWKB raw)) :: IO [Only RawGeometry])
+          (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+    , testCase "mixed multipoint layouts promote missing ordinates to NaN" $
+        withConnection ":memory:" \conn -> do
+          let geometry = G.MultiPoint (U.fromList [G.PointXY (G.XY 1 2), G.PointXYZ (G.XYZ 3 4 5)])
+          [Only actual] <- query conn "SELECT ?" (Only geometry) :: IO [Only G.Geometry]
+          case actual of
+            G.MultiPoint points -> do
+              U.length points @?= 2
+              case points U.! 0 of
+                G.PointXYZ (G.XYZ x y z) -> do
+                  (x, y) @?= (1, 2)
+                  assertBool "promoted Z must be NaN" (isNaN z)
+                other -> assertFailure ("unexpected promoted point: " <> show other)
+              points U.! 1 @?= G.PointXYZ (G.XYZ 3 4 5)
+            other -> assertFailure ("unexpected geometry: " <> show other)
+    , testCase "raw NaN points retain ordinates that decoded emptiness normalizes" $
+        withConnection ":memory:" \conn -> do
+          [Only raw] <- query_ conn "SELECT 'POINT Z (NaN NaN 7)'::GEOMETRY" :: IO [Only RawGeometry]
+          (importRaw conn raw) >>= (@?= [Only raw])
+          decoded <- either assertFailure pure (fromRawGeometry raw)
+          decoded @?= G.PointGeometry (G.EmptyPoint G.DimXYZ)
+          normalized <- either assertFailure pure (toRawGeometry decoded)
+          assertBool "decoding an XY-NaN point normalizes its extra ordinates" (rawGeometryWKB normalized /= rawGeometryWKB raw)
+          (query conn "SELECT ?" (Only decoded) :: IO [Only G.Geometry]) >>= (@?= [Only decoded])
+    , testCase "binary import preserves distinct NaN payload bits" $
+        withConnection ":memory:" \conn -> do
+          let shape = G.PointGeometry (G.PointXYZ (G.XYZ (castWord64ToDouble 0x7ff8000000000001) (castWord64ToDouble 0x7ff8000000000002) 7))
+          raw <- either assertFailure pure (toRawGeometry shape)
+          (importRaw conn raw) >>= (@?= [Only raw])
+          fromRawGeometry raw @?= Right (G.PointGeometry (G.EmptyPoint G.DimXYZ))
+    , testCase "mixed empty and nonempty layouts retain WKB but native import rejects them" $
+        withConnection ":memory:" \conn -> do
+          let shape = G.GeometryCollection (V.fromList [G.PointGeometry (G.EmptyPoint G.DimXY), G.PointGeometry (G.PointXYZ (G.XYZ 1 2 3))])
+          raw <- either assertFailure pure (toRawGeometry shape)
+          fromRawGeometry raw @?= Right shape
+          (fromRawGeometry raw >>= toRawGeometry) @?= Right raw
+          assertMixedLayoutFailure ErrorInputInvalid (importRaw conn raw)
+          assertMixedLayoutFailure
+            ErrorInputInvalid
+            (query conn "SELECT system.main.ST_GeomFromWKB(?)" (Only (rawGeometryWKB raw)) :: IO [Only G.Geometry])
+          (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+    , testCase "decoded polygon writing normalizes all-empty rings" $
+        withConnection ":memory:" \conn -> do
+          let emptyRing = G.CoordinatesXYZ U.empty
+              geometry = G.Polygon (G.PolygonRings emptyRing (V.singleton emptyRing))
+              expected = G.Polygon (G.PolygonRings emptyRing V.empty)
+          (query conn "SELECT ?" (Only geometry) :: IO [Only G.Geometry]) >>= (@?= [Only expected])
+    , testCase "invalid decoded construction fails without poisoning the connection" $
+        withConnection ":memory:" \conn -> do
+          let closedRing = G.CoordinatesXY (U.fromList [G.XY 0 0, G.XY 1 0, G.XY 1 1, G.XY 0 0])
+              openRing = G.CoordinatesXY (U.fromList [G.XY 0 0, G.XY 1 0, G.XY 1 1])
+              emptyRing = G.CoordinatesXY U.empty
+          forM_
+            [ G.LineString (G.CoordinatesXY (U.singleton (G.XY 1 2)))
+            , G.Polygon (G.PolygonRings openRing V.empty)
+            , G.Polygon (G.PolygonRings emptyRing (V.singleton closedRing))
+            ]
+            \shape ->
+              assertFailureIO (query conn "SELECT ?" (Only shape) :: IO [Only G.Geometry])
+          [Only raw] <- query_ conn "SELECT 'LINESTRING (1 2)'::GEOMETRY" :: IO [Only RawGeometry]
+          assertBool "raw result bytes remain available" (not (BS.null (rawGeometryWKB raw)))
+          assertFailureIO (query_ conn "SELECT 'LINESTRING (1 2)'::GEOMETRY" :: IO [Only G.Geometry])
+          (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+    , testCase "CRS survives explicit binary import and table insertion" $
+        withConnection ":memory:" \conn -> do
+          [Only geometry] <- query_ conn "SELECT 'POINT ZM (1 2 3 4)'::GEOMETRY('OGC:CRS84')"
+          rawGeometryCRS geometry @?= Just "OGC:CRS84"
+          (importRaw conn geometry)
+            >>= (@?= [Only geometry])
+          _ <- execute_ conn "CREATE TABLE shapes (shape GEOMETRY('OGC:CRS84'))"
+          _ <- execute conn "INSERT INTO shapes VALUES (system.main.ST_SetCRS(system.main.ST_GeomFromWKB(?), ?))" (rawParameters geometry)
+          (query_ conn "SELECT shape FROM shapes" :: IO [Only RawGeometry]) >>= (@?= [Only geometry])
+    , testCase "CRS parameters preserve custom names and full definitions" $
+        withConnection ":memory:" \conn -> do
+          [Only geometry] <- query_ conn "SELECT 'POINT (1 2)'::GEOMETRY"
+          forM_
+            [ "local' íslenska λ"
+            , "ENGCRS[\"Local grid\",EDATUM[\"Local datum\"],CS[Cartesian,2],AXIS[\"x\",east,ORDER[1],LENGTHUNIT[\"metre\",1]],AXIS[\"y\",north,ORDER[2],LENGTHUNIT[\"metre\",1]]]"
+            , "{\"type\":\"EngineeringCRS\",\"name\":\"Local grid\",\"datum\":{\"type\":\"EngineeringDatum\",\"name\":\"Local datum\"},\"coordinate_system\":{\"subtype\":\"Cartesian\",\"axis\":[{\"name\":\"x\",\"abbreviation\":\"x\",\"direction\":\"east\",\"unit\":\"metre\"},{\"name\":\"y\",\"abbreviation\":\"y\",\"direction\":\"north\",\"unit\":\"metre\"}]}}"
+            ]
+            \crs -> do
+              let annotated = geometry{rawGeometryCRS = Just crs}
+              (importRaw conn annotated) >>= (@?= [Only annotated])
+    , testCase "geometry construction ignores user macros with built-in names" $
+        withConnection ":memory:" \conn -> do
+          [Only raw] <- query_ conn "SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84')" :: IO [Only RawGeometry]
+          decoded <- either assertFailure pure (fromRawGeometry raw)
+          _ <- execute_ conn "CREATE MACRO ST_AsText(x) AS 42"
+          _ <- execute_ conn "CREATE MACRO ST_GeomFromWKB(x) AS 'POINT (9 9)'::GEOMETRY"
+          _ <- execute_ conn "CREATE MACRO ST_SetCRS(x, crs) AS 42"
+          ( query conn "SELECT system.main.ST_SetCRS(system.main.ST_GeomFromWKB(?), ?), ?" (rawGeometryWKB raw, rawGeometryCRS raw, decoded)
+              :: IO [(RawGeometry, G.Geometry)]
+            )
+            >>= (@?= [(raw, decoded)])
+    , testCase "NULL and empty geometry stay distinct" $
+        withConnection ":memory:" \conn -> do
+          [Only empty] <- query_ conn "SELECT 'POINT EMPTY'::GEOMETRY" :: IO [Only RawGeometry]
+          ( query
+              conn
+              "SELECT system.main.ST_GeomFromWKB(?), system.main.ST_GeomFromWKB(?)"
+              (Nothing :: Maybe BS.ByteString, Just (rawGeometryWKB empty))
+              :: IO [(Maybe RawGeometry, Maybe RawGeometry)]
+            )
+            >>= (@?= [(Nothing, Just empty)])
+    , testCase "binary import constructs arrays with a common CRS and NULL elements" $
+        withConnection ":memory:" \conn -> do
+          [Only geometry] <- query_ conn "SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84')" :: IO [Only RawGeometry]
+          let values = sized [Nothing, Just geometry, Nothing] :: SizedArray 3 (Maybe RawGeometry)
+          ( query conn "SELECT [NULL, system.main.ST_SetCRS(system.main.ST_GeomFromWKB(?), ?), NULL]::GEOMETRY('OGC:CRS84')[3]" (rawParameters geometry)
+              :: IO [Only (SizedArray 3 (Maybe RawGeometry))]
+            )
+            >>= (@?= [Only values])
+    , testCase "nested STRUCT, LIST, ARRAY and MAP results bind again with their bytes and CRS" $
+        withConnection ":memory:" \conn -> do
+          wkbs <- shapeBytes conn
+          forM_ [("GEOMETRY", Nothing), ("GEOMETRY('OGC:CRS84')", Just "OGC:CRS84")] \(geometryType, crs) ->
+            forM_ wkbs \wkb -> do
+              [(value, valueType)] <-
+                query
+                  conn
+                  ( Query
+                      ( "SELECT v, typeof(v) FROM (SELECT {'shape': g, 'xs': [g, NULL], 'fixed': [g]::"
+                          <> geometryType
+                          <> "[1], 'map': MAP {'one': g}} AS v FROM (SELECT system.main.ST_GeomFromWKB(?)::"
+                          <> geometryType
+                          <> " AS g))"
+                      )
+                  )
+                  (Only wkb)
+                  :: IO [(StructValue FieldValue, Text)]
+              take 1 (elems (structValueFields value)) @?= [StructField "shape" (FieldGeometry (RawGeometry wkb crs))]
+              (query conn "SELECT ?, typeof(?)" (value, value)) >>= (@?= [(value, valueType)])
+    , testCase "UNION geometry results retain CRS and bind again" $
+        withConnection ":memory:" \conn -> do
+          [(value, valueType)] <-
+            query_ conn "SELECT u, typeof(u) FROM (SELECT union_value(shape := 'POINT (1 2)'::GEOMETRY('OGC:CRS84')) AS u)"
+              :: IO [(UnionValue FieldValue, Text)]
+          (query conn "SELECT ?, typeof(?)" (value, value)) >>= (@?= [(value, valueType)])
+          [Only nullValue] <- query_ conn "SELECT union_value(shape := NULL::GEOMETRY('OGC:CRS84'))" :: IO [Only (UnionValue FieldValue)]
+          (query conn "SELECT ?" (Only nullValue) :: IO [Only (UnionValue FieldValue)]) >>= (@?= [Only nullValue])
+          (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+    , testCase "a raw geometry binds only as a GEOMETRY with the same CRS" $
+        withConnection ":memory:" \conn -> do
+          [Only raw] <- query_ conn "SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84')" :: IO [Only RawGeometry]
+          let plain = raw{rawGeometryCRS = Nothing}
+              fromCRS = "duckdb-simple: a GEOMETRY value with the CRS 'OGC:CRS84' cannot bind as a GEOMETRY with no CRS"
+              toCRS = "duckdb-simple: a GEOMETRY value with no CRS cannot bind as a GEOMETRY with the CRS 'OGC:CRS84'"
+          forM_
+            [ ("GEOMETRY", LogicalTypeGeometry Nothing, raw, fromCRS)
+            , ("GEOMETRY", LogicalTypeScalar LogicalTypeIdGeometry, raw, fromCRS)
+            , ("GEOMETRY('OGC:CRS84')", LogicalTypeGeometry (Just "OGC:CRS84"), plain, toCRS)
+            ]
+            \(columnType, declared, value, message) -> do
+              _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE stored (v STRUCT(shape " <> columnType <> "))"))
+              result <- try (execute conn "INSERT INTO stored VALUES (?)" (Only (geometryStruct declared (FieldGeometry value))))
+              case result of
+                Left err -> do
+                  sqlErrorMessage err @?= message
+                  sqlErrorType err @?= Just ErrorInputInvalid
+                Right _ -> assertFailure "expected a CRS mismatch error"
+              (query_ conn "SELECT count(*) FROM stored" :: IO [Only Int64]) >>= (@?= [Only 0])
+          (query conn "SELECT ?" (Only (geometryStruct (LogicalTypeScalar LogicalTypeIdGeometry) (FieldGeometry plain))))
+            >>= (@?= [Only (geometryStruct (LogicalTypeGeometry Nothing) (FieldGeometry plain))])
+    , testCase "a raw geometry binds as a top-level parameter with its bytes and CRS" $
+        withConnection ":memory:" \conn -> do
+          wkbs <- shapeBytes conn
+          forM_ [("GEOMETRY", Nothing), ("GEOMETRY('OGC:CRS84')", Just "OGC:CRS84")] \(geometryType, crs) -> do
+            let values = [RawGeometry wkb crs | wkb <- wkbs]
+            forM_ values \value ->
+              (query conn "SELECT ?, typeof(?)" (value, value) :: IO [(RawGeometry, Text)]) >>= (@?= [(value, geometryType)])
+            _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE stored (i BIGINT, v " <> geometryType <> ")"))
+            _ <- executeMany conn "INSERT INTO stored VALUES (?, ?)" (zip [0 :: Int64 ..] values)
+            (query_ conn "SELECT v FROM stored ORDER BY i" :: IO [Only RawGeometry]) >>= (@?= map Only values)
+    , testCase "a top-level raw geometry follows the CRS casts of DuckDB" $
+        withConnection ":memory:" \conn -> do
+          [Only raw] <- query_ conn "SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84')" :: IO [Only RawGeometry]
+          let plain = raw{rawGeometryCRS = Nothing}
+              other = raw{rawGeometryCRS = Just "OGC:CRS83"}
+              mismatch = "Binder Error: Cannot cast GEOMETRY with CRS 'OGC:CRS83' to GEOMETRY with different CRS 'OGC:CRS84'"
+              store column value = do
+                _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE stored (v " <> column <> ")"))
+                _ <- execute conn "INSERT INTO stored VALUES (?)" (Only value)
+                query_ conn "SELECT v FROM stored" :: IO [Only RawGeometry]
+          -- A value without a CRS takes the CRS of its column.
+          store "GEOMETRY('OGC:CRS84')" plain >>= (@?= [Only raw])
+          -- A column without a CRS removes the CRS of the value.
+          store "GEOMETRY" raw >>= (@?= [Only plain])
+          store "GEOMETRY" other >>= (@?= [Only plain])
+          -- DuckDB does not cast a GEOMETRY to a GEOMETRY with another CRS.
+          _ <- execute_ conn "CREATE OR REPLACE TABLE stored (v GEOMETRY('OGC:CRS84'))"
+          inserted <- try (execute conn "INSERT INTO stored VALUES (?)" (Only other))
+          case inserted of
+            Left err -> do
+              sqlErrorMessage err @?= mismatch
+              sqlErrorType err @?= Just ErrorQueryBinder
+            Right _ -> assertFailure "expected the CRS cast error of DuckDB"
+          (query_ conn "SELECT count(*) FROM stored" :: IO [Only Int64]) >>= (@?= [Only 0])
+          -- A comparison follows the same casts.
+          _ <- execute conn "INSERT INTO stored VALUES (?)" (Only raw)
+          (query conn "SELECT count(*) FROM stored WHERE v = ?" (Only plain) :: IO [Only Int64]) >>= (@?= [Only 1])
+          compared <- try (query conn "SELECT count(*) FROM stored WHERE v = ?" (Only other) :: IO [Only Int64])
+          case compared of
+            Left err -> do
+              sqlErrorMessage err @?= mismatch
+              sqlErrorType err @?= Just ErrorQueryBinder
+            Right rows -> assertFailure ("expected the CRS cast error of DuckDB, got " <> show rows)
+    , testCase "a Maybe RawGeometry parameter binds NULL and a value" $
+        withConnection ":memory:" \conn -> do
+          [Only raw] <- query_ conn "SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84')" :: IO [Only RawGeometry]
+          _ <- execute_ conn "CREATE TABLE stored (i BIGINT, v GEOMETRY('OGC:CRS84'))"
+          _ <- executeMany conn "INSERT INTO stored VALUES (?, ?)" [(0 :: Int64, Just raw), (1, Nothing)]
+          (query_ conn "SELECT v FROM stored ORDER BY i" :: IO [Only (Maybe RawGeometry)]) >>= (@?= [Only (Just raw), Only Nothing])
+          (query conn "SELECT ? IS NULL" (Only (Nothing :: Maybe RawGeometry)) :: IO [Only Bool]) >>= (@?= [Only True])
+    , testCase "inactive UNION geometry members keep the CRS of their declared type" $
+        withConnection ":memory:" \conn -> do
+          [Only value] <-
+            query_ conn "SELECT union_value(number := 42::BIGINT)::UNION(number BIGINT, shape GEOMETRY('OGC:CRS84'))"
+              :: IO [Only (UnionValue FieldValue)]
+          (query conn "SELECT typeof(?)" (Only value) :: IO [Only Text]) >>= (@?= [Only "UNION(number BIGINT, shape GEOMETRY('OGC:CRS84'))"])
+          (query conn "SELECT ?" (Only value) :: IO [Only (UnionValue FieldValue)]) >>= (@?= [Only value])
+    , testCase "NULL and empty nested geometry collections keep the CRS of their declared type" $
+        withConnection ":memory:" \conn -> do
+          _ <-
+            execute_
+              conn
+              "CREATE TABLE nested AS SELECT {'null_list': NULL::GEOMETRY('OGC:CRS84')[], 'empty_list': []::GEOMETRY('OGC:CRS84')[], 'null_array': NULL::GEOMETRY('OGC:CRS84')[2], 'array': [NULL, NULL]::GEOMETRY('OGC:CRS84')[2], 'null_map': NULL::MAP(VARCHAR, GEOMETRY('OGC:CRS84')), 'empty_map': map([], [])::MAP(VARCHAR, GEOMETRY('OGC:CRS84')), 'map': map(['one'], [NULL::GEOMETRY('OGC:CRS84')])} AS v"
+          [Only value] <- query_ conn "SELECT v FROM nested" :: IO [Only (StructValue FieldValue)]
+          (query conn "SELECT ?" (Only value) :: IO [Only (StructValue FieldValue)]) >>= (@?= [Only value])
+          _ <- execute conn "INSERT INTO nested VALUES (?)" (Only value)
+          (query_ conn "SELECT v FROM nested" :: IO [Only (StructValue FieldValue)]) >>= (@?= [Only value, Only value])
+    , testCase "custom CRS and recognized definitions retain metadata with extension autoload disabled" $ do
+        let crs = "local' íslenska λ"
+        withConnectionWithConfig ":memory:" [("autoload_known_extensions", "false")] \conn -> do
+          [Only point] <- query_ conn "SELECT 'POINT (1 2)'::GEOMETRY" :: IO [Only RawGeometry]
+          let annotated = point{rawGeometryCRS = Just crs}
+          (query conn "SELECT ?" (Only annotated)) >>= (@?= [Only annotated])
+          [Only typed] <- query conn "SELECT typeof(?)" (Only (nullShape crs)) :: IO [Only Text]
+          assertBool (Text.unpack typed) ("íslenska λ" `Text.isInfixOf` typed)
+          (query conn "SELECT ?" (Only (nullShape crs))) >>= (@?= [Only (nullShape crs)])
+          (query conn "SELECT typeof(?)" (Only (nullShape "OGC:CRS84")) :: IO [Only Text]) >>= (@?= [Only "STRUCT(shape GEOMETRY('OGC:CRS84'))"])
+          (query conn "SELECT ?" (Only (nullShape "OGC:CRS84"))) >>= (@?= [Only (nullShape "OGC:CRS84")])
+    , testCase "custom CRS survives nested parameter types and prepared rebinding" $ do
+        let crs = "local' íslenska λ"
+            value = nestedNullShapes crs
+            array = sized [value] :: SizedArray 1 (StructValue FieldValue)
+        withConnection ":memory:" \conn -> do
+          (query conn "SELECT ?" (Only value)) >>= (@?= [Only value])
+          (queryNamed conn "SELECT $shape" ["shape" := value]) >>= (@?= [Only value])
+          (query conn "SELECT ?" (Only array)) >>= (@?= [Only array])
+          withStatement conn "SELECT ?" \stmt -> do
+            bind stmt [toField value]
+            nextRow stmt >>= (@?= Just (Only value))
+            bind stmt [toField value]
+            nextRow stmt >>= (@?= Just (Only value))
+    , testCase "a custom CRS bind leaves an active caller stream usable" $ do
+        let crs = "local' íslenska λ"
+        withConnection ":memory:" \conn ->
+          withStatement conn "SELECT ?" \parameter -> do
+            withStatement conn "SELECT i::BIGINT FROM range(3) t(i)" \stmt -> do
+              Streaming.nextRow stmt >>= (@?= Just (Only (0 :: Int64)))
+              bind parameter [toField (nullShape crs)]
+              performMajorGC
+              Streaming.nextRow stmt >>= (@?= Just (Only (1 :: Int64)))
+            nextRow parameter >>= (@?= Just (Only (nullShape crs)))
+    , testCase "ignore_unknown_crs cannot silently drop parameter metadata" $
+        withConnectionWithConfig ":memory:" [("ignore_unknown_crs", "true")] \conn -> do
+          let value = nullShape "local grid"
+          (query conn "SELECT ?" (Only value)) >>= (@?= [Only value])
+    , testCase "invalid CRS definitions fail during binding" $
+        withConnection ":memory:" \conn ->
+          forM_ ["", "OGC:CRS84\0bad", " "] \crs -> do
+            result <- try (query conn "SELECT ?" (Only (nullShape crs))) :: IO (Either SQLError [Only (StructValue FieldValue)])
+            case result of
+              Left err -> do
+                sqlErrorType err @?= Just ErrorInputInvalid
+                sqlErrorMessage err @?= "duckdb-simple: a GEOMETRY CRS must be nonblank and must not contain NUL"
+                sqlErrorBody err @?= Nothing
+              Right _ -> assertFailure ("expected binding to reject " <> show crs)
+            (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+    , testCase "connection options pass configuration flags" $
+        withConnectionWithOptions ":memory:" defaultConnectionOptions{connectionConfig = [("threads", "1")]} \conn ->
+          (query_ conn "SELECT current_setting('threads')" :: IO [Only Int64]) >>= (@?= [Only 1])
+    , testCase "logical type construction preserves CRS" $
+        withConnection ":memory:" \conn -> withConnectionHandle conn \native -> withConnectionFactory native \factory -> do
+          let logical = LogicalTypeList (LogicalTypeGeometry (Just "OGC:CRS84"))
+          bracket (logicalTypeFromRep factory logical) destroyLogicalType (logicalTypeToRep factory) >>= (@?= logical)
+    , testGroup
+        "folds cross chunk boundaries and preserve CRS"
+        [ testCase mode $
+            withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+              [Only expected] <- query_ conn "SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84')" :: IO [Only RawGeometry]
+              count <- foldRows conn "SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84') FROM range(5000)" (0 :: Int64) \n (Only actual) -> do
+                actual @?= expected
+                pure (n + 1)
+              count @?= 5000
+        | (mode, foldRows) <- [("materialized", fold_), ("native streaming", Streaming.fold_)]
         ]
+    , testCase "invalid binary import leaves the connection usable" $
+        withConnection ":memory:" \conn -> do
+          assertSqlErrorType
+            ErrorInputInvalid
+            (query conn "SELECT system.main.ST_GeomFromWKB(?)" (Only (BS.pack [1, 1, 0, 0, 0])) :: IO [Only RawGeometry])
+          (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+    , testCase "recognized, custom, and complete CRS names bind with their CRS" $ do
+        let names = ["OGC:CRS84", "local' íslenska λ", localGridWKT2]
+        withConnection ":memory:" \conn ->
+          forM_ names \crs -> (query conn "SELECT ?" (Only (nullShape crs))) >>= (@?= [Only (nullShape crs)])
+    , testCase "a default connection runs no CRS query, also for a VARIANT read" $
+        withLoggedInstance \inst countQueries -> withConnectionOn inst \conn -> do
+          countQueries crsQuery >>= (@?= 0)
+          countQueries "variant_typeof" >>= (@?= 0)
+          (query conn "SELECT ?" (Only (nullShape "OGC:CRS84"))) >>= (@?= [Only (nullShape "OGC:CRS84")])
+          (query_ conn "SELECT 42::VARIANT" :: IO [Only Variant]) >>= (@?= [Only (Variant (FieldInt32 42))])
+          countQueries crsQuery >>= (@?= 0)
+          -- The log records metadata preparation and execution on the helper connection.
+          countQueries "variant_typeof" >>= (@?= 2)
+    , testCase "a custom CRS resolves at bind time and a VARIANT read runs no CRS query" $
+        withLoggedInstance \inst countQueries -> withConnectionOn inst \conn -> do
+          countQueries crsQuery >>= (@?= 0)
+          let value = nullShape "local grid"
+          (query conn "SELECT ?" (Only value)) >>= (@?= [Only value])
+          resolved <- countQueries crsQuery
+          assertBool "the custom CRS uses the fallback query" (resolved > 0)
+          (query_ conn "SELECT 42::VARIANT" :: IO [Only Variant]) >>= (@?= [Only (Variant (FieldInt32 42))])
+          countQueries crsQuery >>= (@?= resolved)
+    , testCase "a recognized CRS binds in either spelling" $
+        withConnection ":memory:" \conn ->
+          forM_ ["ogc:crs84", "OGC:CRS84"] \crs -> (query conn "SELECT ?" (Only (nullShape crs))) >>= (@?= [Only (nullShape "OGC:CRS84")])
+    ]
+  where
+    crsQuery = "system.main.ST_SetCRS("
 
+-- | Run an action on an instance that logs each query. The second argument
+-- counts the logged queries whose text contains a part. The count query binds
+-- the part as a value, so its own text does not match.
+withLoggedInstance :: (Instance -> (Text -> IO Int64) -> IO a) -> IO a
+withLoggedInstance action = withEnvironment \env -> withInstance env [] \inst -> withConnectionOn inst \logger -> do
+  _ <- execute_ logger "CALL enable_logging(level := 'info')"
+  let countQueries part = do
+        rows <- query logger "SELECT count(*) FROM duckdb_logs() WHERE type = 'QueryLog' AND contains(message, ?)" (Only part)
+        case rows of
+          [Only count] -> pure count
+          _ -> assertFailure "expected one count"
+  action inst countQueries
+
+-- | A complete WKT2 definition that no DuckDB catalog entry identifies.
+localGridWKT2 :: Text
+localGridWKT2 =
+  "ENGCRS[\"Local grid\",EDATUM[\"Local datum\"],CS[Cartesian,2],AXIS[\"x\",east,ORDER[1],LENGTHUNIT[\"metre\",1]],AXIS[\"y\",north,ORDER[2],LENGTHUNIT[\"metre\",1]]]"
+
 -- | A one-field STRUCT with a NULL GEOMETRY of the given CRS.
 nullShape :: Text -> StructValue FieldValue
-nullShape crs =
-    StructValue
-        { structValueFields = listArray (0, 0) [StructField "shape" FieldNull]
-        , structValueTypes = listArray (0, 0) [StructField "shape" (LogicalTypeGeometry (Just crs))]
-        , structValueIndex = Map.singleton "shape" 0
-        }
+nullShape crs = geometryStruct (LogicalTypeGeometry (Just crs)) FieldNull
 
+-- | A one-field STRUCT with a value of the given declared GEOMETRY type.
+geometryStruct :: LogicalTypeRep -> FieldValue -> StructValue FieldValue
+geometryStruct logical value =
+  StructValue
+    { structValueFields = listArray (0, 0) [StructField "shape" value]
+    , structValueTypes = listArray (0, 0) [StructField "shape" logical]
+    , structValueIndex = Map.singleton "shape" 0
+    }
+
+-- | Retain custom CRS metadata in NULL, empty, and inactive nested values.
+nestedNullShapes :: Text -> StructValue FieldValue
+nestedNullShapes crs =
+  StructValue
+    { structValueFields = listArray (0, length fields - 1) [StructField name value | (name, value, _) <- fields]
+    , structValueTypes = listArray (0, length fields - 1) [StructField name logical | (name, _, logical) <- fields]
+    , structValueIndex = Map.fromList (zip [name | (name, _, _) <- fields] [0 ..])
+    }
+  where
+    geometry = LogicalTypeGeometry (Just crs)
+    list = LogicalTypeList geometry
+    array = LogicalTypeArray geometry 2
+    mapping = LogicalTypeMap (LogicalTypeScalar LogicalTypeIdVarchar) geometry
+    members = listArray (0, 1) [UnionMemberType "number" (LogicalTypeScalar LogicalTypeIdBigInt), UnionMemberType "shape" geometry]
+    inactive = UnionValue 0 "number" (FieldInt64 42) members
+    shape = nullShape crs
+    fields =
+      [ ("null_list", FieldNull, list)
+      , ("empty_list", FieldList [], list)
+      , ("null_array", FieldNull, array)
+      , ("array", FieldArray (listArray (0, 1) [FieldNull, FieldNull]), array)
+      , ("null_map", FieldNull, mapping)
+      , ("empty_map", FieldMap [], mapping)
+      , ("map", FieldMap [(FieldText "one", FieldNull)], mapping)
+      , ("inactive", FieldUnion inactive, LogicalTypeUnion members)
+      , ("nested", FieldStruct shape, LogicalTypeStruct (structValueTypes shape))
+      ]
+
 -- | Exercise all coordinate layouts with explicit point and sequence constructors.
-shapeRoundTrips :: (G.Coordinate coord) => Connection -> G.Dimensions -> (coord -> G.Point) -> (U.Vector coord -> G.Coordinates) -> coord -> coord -> Assertion
+shapeRoundTrips
+  :: (G.Coordinate coord) => Connection -> G.Dimensions -> (coord -> G.Point) -> (U.Vector coord -> G.Coordinates) -> coord -> coord -> Assertion
 shapeRoundTrips conn dimensions point coordinates first second = do
-    let line = coordinates (U.fromList [first, second])
-        ring = coordinates (U.fromList [first, second, first, first])
-        emptyLine = coordinates U.empty
-        emptyPoint = G.EmptyPoint dimensions
-        polygon = G.PolygonRings ring V.empty
-        emptyPolygon = G.PolygonRings emptyLine V.empty
-        values =
-            [ G.PointGeometry (point first)
-            , G.PointGeometry emptyPoint
-            , G.LineString line
-            , G.LineString emptyLine
-            , G.Polygon polygon
-            , G.Polygon emptyPolygon
-            , G.MultiPoint (U.fromList [point first, emptyPoint, point second])
-            , G.MultiPoint U.empty
-            , G.MultiLineString (V.fromList [line, emptyLine])
-            , G.MultiPolygon (V.fromList [polygon, emptyPolygon])
-            , G.GeometryCollection (V.fromList [G.PointGeometry emptyPoint, G.LineString line, G.GeometryCollection V.empty])
-            ]
-    forM_ values \shape -> do
-        rows <- query conn "SELECT ?, ST_CRS(?)" (shape, shape)
-        rows @?= [(shape, Nothing :: Maybe Text)]
-        raw <- either assertFailure pure (toRawGeometry shape)
-        fromRawGeometry raw @?= Right shape
-        let annotated = raw{rawGeometryCRS = Just "local' íslenska λ"}
-        (importRaw conn annotated)
-            >>= (@?= [Only annotated])
+  let line = coordinates (U.fromList [first, second])
+      ring = coordinates (U.fromList [first, second, first, first])
+      emptyLine = coordinates U.empty
+      emptyPoint = G.EmptyPoint dimensions
+      polygon = G.PolygonRings ring V.empty
+      emptyPolygon = G.PolygonRings emptyLine V.empty
+      values =
+        [ G.PointGeometry (point first)
+        , G.PointGeometry emptyPoint
+        , G.LineString line
+        , G.LineString emptyLine
+        , G.Polygon polygon
+        , G.Polygon emptyPolygon
+        , G.MultiPoint (U.fromList [point first, emptyPoint, point second])
+        , G.MultiPoint U.empty
+        , G.MultiLineString (V.fromList [line, emptyLine])
+        , G.MultiPolygon (V.fromList [polygon, emptyPolygon])
+        , G.GeometryCollection (V.fromList [G.PointGeometry emptyPoint, G.LineString line, G.GeometryCollection V.empty])
+        ]
+  forM_ values \shape -> do
+    rows <- query conn "SELECT ?, ST_CRS(?)" (shape, shape)
+    rows @?= [(shape, Nothing :: Maybe Text)]
+    raw <- either assertFailure pure (toRawGeometry shape)
+    fromRawGeometry raw @?= Right shape
+    let annotated = raw{rawGeometryCRS = Just "local' íslenska λ"}
+    (importRaw conn annotated)
+      >>= (@?= [Only annotated])
 
 -- | Import WKB without converting a missing CRS to SQL NULL.
 importRaw :: Connection -> RawGeometry -> IO [Only RawGeometry]
 importRaw conn raw = case rawGeometryCRS raw of
-    Nothing -> query conn "SELECT system.main.ST_GeomFromWKB(?)" (Only (rawGeometryWKB raw))
-    Just crs -> query conn "SELECT system.main.ST_SetCRS(system.main.ST_GeomFromWKB(?), ?)" (rawGeometryWKB raw, crs)
+  Nothing -> query conn "SELECT system.main.ST_GeomFromWKB(?)" (Only (rawGeometryWKB raw))
+  Just crs -> query conn "SELECT system.main.ST_SetCRS(system.main.ST_GeomFromWKB(?), ?)" (rawGeometryWKB raw, crs)
 
 -- | Bind raw bytes and CRS as separate SQL parameters.
 rawParameters :: RawGeometry -> (BS.ByteString, Maybe Text)
 rawParameters raw = (rawGeometryWKB raw, rawGeometryCRS raw)
 
--- | Check that generic values cannot silently normalize raw geometry.
-assertRawBindingFailure :: IO a -> Assertion
-assertRawBindingFailure action = do
-    result <- try (action >> pure ()) :: IO (Either SomeException ())
-    case result of
-        Left err -> assertBool (displayException err) ("raw GEOMETRY binding requires explicit" `isInfixOf` displayException err)
-        Right () -> assertFailure "expected raw geometry binding rejection"
+-- | Check the native rejection without accepting unrelated failures.
+assertMixedLayoutFailure :: ErrorType -> IO a -> Assertion
+assertMixedLayoutFailure expectedCode action = do
+  result <- try (action >> pure ()) :: IO (Either SQLError ())
+  case result of
+    Left err -> do
+      sqlErrorType err @?= Just expectedCode
+      assertBool (show err) ("inconsistent Z/M dimensions" `Text.isInfixOf` sqlErrorMessage err)
+    Right () -> assertFailure "expected native mixed-layout geometry rejection"
 
+-- | The WKB bytes of each native shape and of a point with NaN payload bits.
+shapeBytes :: Connection -> IO [BS.ByteString]
+shapeBytes conn = do
+  native <- forM shapes \wkt -> do
+    [Only raw] <- query conn "SELECT ?::GEOMETRY" (Only wkt) :: IO [Only RawGeometry]
+    pure (rawGeometryWKB raw)
+  nanPoint <-
+    either
+      assertFailure
+      pure
+      (WKB.encodeWKB (G.PointGeometry (G.PointXYZ (G.XYZ (castWord64ToDouble 0x7ff8000000000001) (castWord64ToDouble 0x7ff8000000000002) 7))))
+  pure (native <> [nanPoint])
+
 -- | Native shapes cover all families, dimensions, empty children, and exact doubles.
 shapes :: [Text]
 shapes =
-    [ "POINT (0.10000000000000002 -0.0)"
-    , "POINT Z (1 2 3)"
-    , "POINT M (1 2 3)"
-    , "POINT ZM (1 2 3 4)"
-    , "POINT EMPTY"
-    , "LINESTRING EMPTY"
-    , "LINESTRING (1 2, 3 4)"
-    , "POLYGON ((0 0, 1 0, 1 1, 0 0))"
-    , "POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0), (2 2, 2 4, 4 4, 4 2, 2 2))"
-    , "MULTIPOINT ((1 2), EMPTY, (3 4))"
-    , "MULTILINESTRING ((1 2, 3 4), EMPTY)"
-    , "MULTIPOLYGON (((0 0, 1 0, 1 1, 0 0)), EMPTY)"
-    , "GEOMETRYCOLLECTION (POINT (1 2), LINESTRING (0 0, 1 1))"
-    , "GEOMETRYCOLLECTION ZM (POINT ZM (1 2 3 4), POINT ZM EMPTY)"
-    , "POINT Z EMPTY"
-    , "LINESTRING M EMPTY"
-    , "GEOMETRYCOLLECTION ZM EMPTY"
-    ]
+  [ "POINT (0.10000000000000002 -0.0)"
+  , "POINT Z (1 2 3)"
+  , "POINT M (1 2 3)"
+  , "POINT ZM (1 2 3 4)"
+  , "POINT EMPTY"
+  , "LINESTRING EMPTY"
+  , "LINESTRING (1 2, 3 4)"
+  , "POLYGON ((0 0, 1 0, 1 1, 0 0))"
+  , "POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0), (2 2, 2 4, 4 4, 4 2, 2 2))"
+  , "MULTIPOINT ((1 2), EMPTY, (3 4))"
+  , "MULTILINESTRING ((1 2, 3 4), EMPTY)"
+  , "MULTIPOLYGON (((0 0, 1 0, 1 1, 0 0)), EMPTY)"
+  , "GEOMETRYCOLLECTION (POINT (1 2), LINESTRING (0 0, 1 1))"
+  , "GEOMETRYCOLLECTION ZM (POINT ZM (1 2 3 4), POINT ZM EMPTY)"
+  , "POINT Z EMPTY"
+  , "LINESTRING M EMPTY"
+  , "GEOMETRYCOLLECTION ZM EMPTY"
+  ]
diff --git a/test/Properties.hs b/test/Properties.hs
--- a/test/Properties.hs
+++ b/test/Properties.hs
@@ -1,185 +1,219 @@
 {-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE DataKinds #-}
 {-# LANGUAGE ExistentialQuantification #-}
 {-# LANGUAGE LambdaCase #-}
 {-# LANGUAGE NamedFieldPuns #-}
 {-# LANGUAGE OverloadedStrings #-}
-{-# LANGUAGE PatternSynonyms #-}
 {-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications #-}
 
+-- |
+-- Module      : Properties
+-- Description : Round-trip properties for parameters and results of each column type.
 module Properties (roundTripTests) where
 
 import Control.Monad (forM)
-import Data.Array (Array, elems, listArray)
+import Data.Array (elems, listArray)
+import Data.Bits (clearBit)
 import qualified Data.ByteString as BS
 import Data.Fixed (Fixed (MkFixed))
 import Data.Int (Int16, Int32, Int64, Int8)
 import qualified Data.Map.Strict as Map
 import Data.Proxy (Proxy (..))
+import Data.Ratio ((%))
 import qualified Data.Text as Text
-import Data.Time.Calendar (Day (..))
+import Data.Time.Calendar (Day (..), addDays, fromGregorian)
 import Data.Time.Clock (UTCTime (..), diffTimeToPicoseconds, picosecondsToDiffTime)
-import Data.Time.LocalTime (LocalTime (..), TimeOfDay (..), timeOfDayToTime)
+import Data.Time.Clock.POSIX (posixSecondsToUTCTime)
+import Data.Time.LocalTime (LocalTime (..), TimeOfDay (..), timeOfDayToTime, utc, utcToLocalTime)
 import Data.UUID (UUID)
 import qualified Data.UUID as UUID
 import Data.Word (Word16, Word32, Word64, Word8)
-import Database.DuckDB.FFI (
-    pattern DuckDBTypeBlob,
-    pattern DuckDBTypeBoolean,
-    pattern DuckDBTypeDouble,
-    pattern DuckDBTypeInteger,
-    pattern DuckDBTypeVarchar,
- )
-import Database.DuckDB.Simple (Connection, close, open, query)
+import Database.DuckDB.Simple (Connection, SizedArray, close, open, query)
 import Database.DuckDB.Simple.FromField (
-    BigNum (..),
-    BitString (..),
-    FieldValue (..),
-    FromField,
-    LogicalTypeRep (..),
-    StructField (..),
-    StructValue (..),
-    UnionMemberType (..),
-    UnionValue (..),
+  BigNum (..),
+  BitString (..),
+  FieldValue (..),
+  FromField,
+  LogicalTypeId (..),
+  LogicalTypeRep (..),
+  StructField (..),
+  StructValue (..),
+  UnionMemberType (..),
+  UnionValue (..),
  )
 import Database.DuckDB.Simple.ToField (ToField)
 import Database.DuckDB.Simple.Types (Null (..), Only (..))
+import GHC.Float (castWord32ToFloat, castWord64ToDouble)
 import Numeric.Natural (Natural)
 import Test.QuickCheck (
-    Gen,
-    Property,
-    arbitrary,
-    arbitrarySizedNatural,
-    chooseInt,
-    chooseInteger,
-    counterexample,
-    elements,
-    forAllShrink,
-    frequency,
-    ioProperty,
-    scale,
-    shrink,
-    shrinkIntegral,
-    sized,
-    suchThat,
-    vectorOf,
-    (===),
+  Gen,
+  Property,
+  arbitrary,
+  chooseInt,
+  chooseInteger,
+  counterexample,
+  elements,
+  forAllShrink,
+  frequency,
+  ioProperty,
+  shrink,
+  shrinkIntegral,
+  suchThat,
+  vectorOf,
+  (===),
  )
 import Test.Tasty (TestTree, testGroup, withResource)
 import Test.Tasty.QuickCheck (testProperty)
+import TestUtils (sized)
 
 data SomeRoundTrip
-    = forall a.
-        (Eq a, Show a, ToField a, FromField a) =>
-      SomeRoundTrip String (Proxy a) (Gen a) (a -> [a])
+  = forall a.
+    (Eq a, Show a, ToField a, FromField a) =>
+    SomeRoundTrip String (Proxy a) (Gen a) (a -> [a])
 
 roundTripTests :: TestTree
 roundTripTests =
-    withResource
-        (open ":memory:")
-        close
-        \getConn ->
-            testGroup
-                "round-trip properties"
-                (fmap (mkRoundTripTest getConn) specs)
+  testGroup
+    "round-trip properties"
+    (fmap mkRoundTripTest specs)
 
-mkRoundTripTest :: IO Connection -> SomeRoundTrip -> TestTree
-mkRoundTripTest getConn (SomeRoundTrip label proxy gen shrinker) =
-    testProperty label $
+mkRoundTripTest :: SomeRoundTrip -> TestTree
+mkRoundTripTest (SomeRoundTrip label proxy gen shrinker) =
+  withResource
+    (open ":memory:")
+    close
+    \getConn ->
+      testProperty label $
         forAllShrink gen shrinker (roundTripProperty getConn proxy)
 
-roundTripProperty ::
-    forall a.
-    (Eq a, Show a, ToField a, FromField a) =>
-    IO Connection ->
-    Proxy a ->
-    a ->
-    Property
+roundTripProperty
+  :: forall a
+   . (Eq a, Show a, ToField a, FromField a)
+  => IO Connection
+  -> Proxy a
+  -> a
+  -> Property
 roundTripProperty getConn _ value =
-    ioProperty do
-        conn <- getConn
-        rows <- query conn "SELECT ?" (Only value)
-        case rows of
-            [Only out] ->
-                pure $
-                    counterexample
-                        ("expected " ++ show value ++ ", got " ++ show out)
-                        (out === value)
-            other ->
-                fail $
-                    "unexpected row count during round-trip: "
-                        ++ show (length other)
+  ioProperty do
+    conn <- getConn
+    rows <- query conn "SELECT ?" (Only value)
+    case rows of
+      [Only out] ->
+        pure $
+          counterexample
+            ("expected " ++ show value ++ ", got " ++ show out)
+            (out === value)
+      other ->
+        fail $
+          "unexpected row count during round-trip: "
+            ++ show (length other)
 
 specs :: [SomeRoundTrip]
 specs =
-    [ SomeRoundTrip "Null" (Proxy :: Proxy Null) (pure Null) shrinkNone
-    , SomeRoundTrip "Bool" (Proxy :: Proxy Bool) (arbitrary :: Gen Bool) shrink
-    , SomeRoundTrip "Int" (Proxy :: Proxy Int) (arbitrary :: Gen Int) shrink
-    , SomeRoundTrip "Int8" (Proxy :: Proxy Int8) (arbitrary :: Gen Int8) shrink
-    , SomeRoundTrip "Int16" (Proxy :: Proxy Int16) (arbitrary :: Gen Int16) shrink
-    , SomeRoundTrip "Int32" (Proxy :: Proxy Int32) (arbitrary :: Gen Int32) shrink
-    , SomeRoundTrip "Int64" (Proxy :: Proxy Int64) (arbitrary :: Gen Int64) shrink
-    , SomeRoundTrip "Integer" (Proxy :: Proxy Integer) (arbitrary :: Gen Integer) shrink
-    , SomeRoundTrip "BigNum" (Proxy :: Proxy BigNum) genBigNum shrinkBigNum
-    , SomeRoundTrip "Natural" (Proxy :: Proxy Natural) genNatural shrinkNatural
-    , SomeRoundTrip "Word" (Proxy :: Proxy Word) (arbitrary :: Gen Word) shrink
-    , SomeRoundTrip "Word8" (Proxy :: Proxy Word8) (arbitrary :: Gen Word8) shrink
-    , SomeRoundTrip "Word16" (Proxy :: Proxy Word16) (arbitrary :: Gen Word16) shrink
-    , SomeRoundTrip "Word32" (Proxy :: Proxy Word32) (arbitrary :: Gen Word32) shrink
-    , SomeRoundTrip "Word64" (Proxy :: Proxy Word64) (arbitrary :: Gen Word64) shrink
-    , SomeRoundTrip "Float" (Proxy :: Proxy Float) genFiniteFloat shrink
-    , SomeRoundTrip "Double" (Proxy :: Proxy Double) genFiniteDouble shrink
-    , SomeRoundTrip "String" (Proxy :: Proxy String) genString shrinkString
-    , SomeRoundTrip "Text" (Proxy :: Proxy Text.Text) genText shrinkText
-    , SomeRoundTrip "ByteString" (Proxy :: Proxy BS.ByteString) genByteString shrinkByteString
-    , SomeRoundTrip "BitString" (Proxy :: Proxy BitString) genBitString shrinkBitString
-    , SomeRoundTrip "UUID" (Proxy :: Proxy UUID) genUUID shrinkNone
-    , SomeRoundTrip "Day" (Proxy :: Proxy Day) genDay shrinkDay
-    , SomeRoundTrip "TimeOfDay" (Proxy :: Proxy TimeOfDay) genTimeOfDay shrinkTimeOfDay
-    , SomeRoundTrip "LocalTime" (Proxy :: Proxy LocalTime) genLocalTime shrinkLocalTime
-    , SomeRoundTrip "UTCTime" (Proxy :: Proxy UTCTime) genUTCTime shrinkUTCTime
-    , SomeRoundTrip "Maybe Int" (Proxy :: Proxy (Maybe Int)) genMaybeInt shrinkMaybeInt
-    , SomeRoundTrip "Array Int Int" (Proxy :: Proxy (Array Int Int)) genIntArray shrinkIntArray
-    , SomeRoundTrip "StructValue FieldValue" (Proxy :: Proxy (StructValue FieldValue)) genStructValue shrinkStructValue
-    , SomeRoundTrip "UnionValue FieldValue" (Proxy :: Proxy (UnionValue FieldValue)) genUnionValue shrinkNone
-    ]
+  [ SomeRoundTrip "Null" (Proxy @Null) (pure Null) shrinkNone
+  , SomeRoundTrip "Bool" (Proxy @Bool) (arbitrary :: Gen Bool) shrink
+  , SomeRoundTrip "Int" (Proxy @Int) genBounded shrink
+  , SomeRoundTrip "Int8" (Proxy @Int8) genBounded shrink
+  , SomeRoundTrip "Int16" (Proxy @Int16) genBounded shrink
+  , SomeRoundTrip "Int32" (Proxy @Int32) genBounded shrink
+  , SomeRoundTrip "Int64" (Proxy @Int64) genBounded shrink
+  , SomeRoundTrip "Integer" (Proxy @Integer) genInteger shrink
+  , SomeRoundTrip "BigNum" (Proxy @BigNum) genBigNum shrinkBigNum
+  , SomeRoundTrip "Natural" (Proxy @Natural) genNatural shrinkNatural
+  , SomeRoundTrip "Word" (Proxy @Word) genBounded shrink
+  , SomeRoundTrip "Word8" (Proxy @Word8) genBounded shrink
+  , SomeRoundTrip "Word16" (Proxy @Word16) genBounded shrink
+  , SomeRoundTrip "Word32" (Proxy @Word32) genBounded shrink
+  , SomeRoundTrip "Word64" (Proxy @Word64) genBounded shrink
+  , SomeRoundTrip "Float" (Proxy @Float) genFiniteFloat shrink
+  , SomeRoundTrip "Double" (Proxy @Double) genFiniteDouble shrink
+  , SomeRoundTrip "String" (Proxy @String) genString shrinkString
+  , SomeRoundTrip "Text" (Proxy @Text.Text) genText shrinkText
+  , SomeRoundTrip "ByteString" (Proxy @BS.ByteString) genByteString shrinkByteString
+  , SomeRoundTrip "BitString" (Proxy @BitString) genBitString shrinkBitString
+  , SomeRoundTrip "UUID" (Proxy @UUID) genUUID shrinkNone
+  , SomeRoundTrip "Day" (Proxy @Day) genDay shrinkDay
+  , SomeRoundTrip "TimeOfDay" (Proxy @TimeOfDay) genTimeOfDay shrinkTimeOfDay
+  , SomeRoundTrip "LocalTime" (Proxy @LocalTime) genLocalTime shrinkLocalTime
+  , SomeRoundTrip "UTCTime" (Proxy @UTCTime) genUTCTime shrinkUTCTime
+  , SomeRoundTrip "Maybe Int" (Proxy @(Maybe Int)) genMaybeInt shrinkMaybeInt
+  , SomeRoundTrip "SizedArray 4 Int" (Proxy @(SizedArray 4 Int)) genIntArray shrinkNone
+  , SomeRoundTrip "StructValue FieldValue" (Proxy @(StructValue FieldValue)) genStructValue shrinkStructValue
+  , SomeRoundTrip "UnionValue FieldValue" (Proxy @(UnionValue FieldValue)) genUnionValue shrinkNone
+  ]
 
 shrinkNone :: a -> [a]
 shrinkNone _ = []
 
+-- | Choose a value from the whole range of a bounded integral type. One value
+-- in four is a boundary of the type: the minimum, the maximum, -1, 0, or 1.
+genBounded :: forall a. (Bounded a, Integral a) => Gen a
+genBounded =
+  frequency
+    [ (1, elements [minBound, maxBound, fromInteger (max (-1) (toInteger (minBound :: a))), 0, 1])
+    , (3, fromInteger <$> chooseInteger (toInteger (minBound :: a), toInteger (maxBound :: a)))
+    ]
+
+-- | Choose an integer of at most 200 bits. The boundaries are those of the
+-- 64-bit and 128-bit integer types, where the binding changes its native type.
+genInteger :: Gen Integer
+genInteger =
+  frequency
+    [ (1, elements integerBoundaries)
+    , (1, chooseInteger (-1000, 1000))
+    , (2, chooseInteger (negate (2 ^ (200 :: Int)), 2 ^ (200 :: Int)))
+    ]
+  where
+    integerBoundaries =
+      concat [[value, negate value] | bits <- [63, 64, 127, 128 :: Int], value <- [2 ^ bits - 1, 2 ^ bits, 2 ^ bits + 1]] <> [0, 1, -1]
+
 genNatural :: Gen Natural
-genNatural = fromInteger <$> arbitrarySizedNatural
+genNatural = fromInteger . abs <$> genInteger
 
 shrinkNatural :: Natural -> [Natural]
 shrinkNatural n = fromInteger <$> shrinkIntegral (toInteger n)
 
 genBigNum :: Gen BigNum
-genBigNum = BigNum <$> scale (\s -> s * 8) (arbitrary :: Gen Integer)
+genBigNum = BigNum <$> genInteger
 
 shrinkBigNum :: BigNum -> [BigNum]
 shrinkBigNum (BigNum n) = BigNum <$> shrinkIntegral n
 
+-- | Choose a finite Float from each bit pattern. The boundaries are the zeros,
+-- the largest finite values, the smallest normal value, and the smallest
+-- subnormal values.
 genFiniteFloat :: Gen Float
 genFiniteFloat =
-    (arbitrary :: Gen Float)
-        `suchThat` \x -> not (isNaN x || isInfinite x)
+  frequency
+    [ (1, elements [0, -0, 1, -1, 3.4028235e38, -3.4028235e38, 1.1754944e-38, 1.0e-45, -1.0e-45])
+    , (3, (castWord32ToFloat <$> arbitrary) `suchThat` \x -> not (isNaN x || isInfinite x))
+    ]
 
+-- | Choose a finite Double from each bit pattern, with the boundaries of the
+-- same kinds as for 'genFiniteFloat'.
 genFiniteDouble :: Gen Double
 genFiniteDouble =
-    (arbitrary :: Gen Double)
-        `suchThat` \x -> not (isNaN x || isInfinite x)
+  frequency
+    [ (1, elements [0, -0, 1, -1, 1.7976931348623157e308, -1.7976931348623157e308, 2.2250738585072014e-308, 5.0e-324, -5.0e-324])
+    , (3, (castWord64ToDouble <$> arbitrary) `suchThat` \x -> not (isNaN x || isInfinite x))
+    ]
 
+-- | Choose a string of at most 300 characters. The boundaries have 0, 1, 11, 12,
+-- and 13 ASCII characters, around the 12 bytes that DuckDB stores inline.
 genString :: Gen String
 genString =
-    sized \n -> do
-        len <- chooseInt (0, max 0 (min n 32))
-        vectorOf len genChar
+  frequency
+    [ (1, elements [replicate count 'x' | count <- [0, 1, 11, 12, 13]])
+    , (3, chooseInt (0, 300) >>= \len -> vectorOf len genChar)
+    ]
 
 shrinkString :: String -> [String]
 shrinkString = shrink
 
 genChar :: Gen Char
 genChar =
-    frequency [(1, pure '\0'), (9, arbitrary)]
+  frequency [(1, pure '\0'), (9, arbitrary)]
 
 genText :: Gen Text.Text
 genText = Text.pack <$> genString
@@ -187,221 +221,246 @@
 shrinkText :: Text.Text -> [Text.Text]
 shrinkText txt = Text.pack <$> shrinkString (Text.unpack txt)
 
+-- | Choose a byte string of at most 300 bytes. The boundaries have 0, 12, and
+-- 13 bytes, around the 12 bytes that DuckDB stores inline.
 genByteString :: Gen BS.ByteString
 genByteString =
-    sized \n -> do
-        len <- chooseInt (0, max 0 (min n 64))
-        BS.pack <$> vectorOf len (arbitrary :: Gen Word8)
+  frequency
+    [ (1, elements [BS.replicate count byte | count <- [0, 12, 13], byte <- [0, 255]])
+    , (3, chooseInt (0, 300) >>= \len -> BS.pack <$> vectorOf len (arbitrary :: Gen Word8))
+    ]
 
 shrinkByteString :: BS.ByteString -> [BS.ByteString]
 shrinkByteString bs =
-    [ BS.pack xs
-    | xs <- shrink (BS.unpack bs)
-    , length xs <= 64
-    ]
+  [ BS.pack xs
+  | xs <- shrink (BS.unpack bs)
+  , length xs <= 300
+  ]
 
+-- | Choose a BIT value of 1 to 64 bytes with 0 to 7 bits of padding. The
+-- padding bits of the first byte are 0, as the decoder gives them.
 genBitString :: Gen BitString
-genBitString =
-    sized \n -> do
-        len <- chooseInt (1, max 1 (min 64 (n * 2)))
-        bytes <- vectorOf len (arbitrary :: Gen Word8)
-        pure (BitString 0 (BS.pack bytes))
+genBitString = do
+  len <- chooseInt (1, 64)
+  padding <- chooseInt (0, 7)
+  first <- arbitrary :: Gen Word8
+  rest <- vectorOf (len - 1) (arbitrary :: Gen Word8)
+  pure (BitString (fromIntegral padding) (BS.pack (foldl clearBit first [8 - padding .. 7] : rest)))
 
 shrinkBitString :: BitString -> [BitString]
 shrinkBitString (BitString _ raw) =
-    [ BitString 0 (BS.pack xs)
-    | xs <- shrink (BS.unpack raw)
-    , length xs <= 64
-    , not (null xs)
-    ]
+  [ BitString 0 (BS.pack xs)
+  | xs <- shrink (BS.unpack raw)
+  , length xs <= 64
+  , not (null xs)
+  ]
 
+-- | Choose a UUID from each bit pattern. The boundaries are the nil UUID and
+-- the UUID with each bit set.
 genUUID :: Gen UUID
 genUUID =
-    UUID.fromWords
-        <$> (arbitrary :: Gen Word32)
-        <*> (arbitrary :: Gen Word32)
-        <*> (arbitrary :: Gen Word32)
-        <*> (arbitrary :: Gen Word32)
+  frequency
+    [ (1, elements [UUID.nil, UUID.fromWords maxBound maxBound maxBound maxBound])
+    , (3, UUID.fromWords <$> arbitrary <*> arbitrary <*> arbitrary <*> arbitrary)
+    ]
 
 genMaybeInt :: Gen (Maybe Int)
 genMaybeInt =
-    sized \n ->
-        let bound = max 1 (min 1000 (n * 10))
-         in frequency
-                [ (1, pure Nothing)
-                , (3, Just <$> chooseInt (-bound, bound))
-                ]
+  frequency
+    [ (1, pure Nothing)
+    , (3, Just <$> genBounded)
+    ]
 
 shrinkMaybeInt :: Maybe Int -> [Maybe Int]
 shrinkMaybeInt Nothing = []
 shrinkMaybeInt (Just x) = Nothing : [Just y | y <- shrink x]
 
+-- | Choose a day in the range of DATE that DuckDB accepts: from 5877642-06-25
+-- (BC), which is day -2147483646 from the Unix epoch, to 5881580-07-10, which
+-- is day 2147483646. The library raises an error for a smaller day. See
+-- Note [Time ranges] in "Database.DuckDB.Simple.ToField". The boundaries are
+-- the ends of the range and the days next to the epoch.
 genDay :: Gen Day
-genDay = ModifiedJulianDay <$> (arbitrary :: Gen Integer)
+genDay =
+  (`addDays` fromGregorian 1970 1 1)
+    <$> frequency
+      [ (1, elements [smallest, -1, 0, 1, largest])
+      , (3, chooseInteger (smallest, largest))
+      ]
+  where
+    smallest = -2147483646
+    largest = 2147483646
 
+-- | Choose a count of microseconds from the Unix epoch in the range of TIMESTAMP
+-- that DuckDB states: from 290309-12-22 (BC) 00:00:00, which is
+-- -9223372022400000000, to 294247-01-10 04:00:54.775806, which is maxBound - 1.
+-- DuckDB gives a conversion error for a smaller count.
+genTimestampMicros :: Gen Integer
+genTimestampMicros =
+  frequency
+    [ (1, elements [smallest, -1, 0, 1, largest])
+    , (3, chooseInteger (smallest, largest))
+    ]
+  where
+    smallest = -9223372022400000000
+    largest = toInteger (maxBound :: Int64) - 1
+
 shrinkDay :: Day -> [Day]
 shrinkDay (ModifiedJulianDay d) = ModifiedJulianDay <$> shrink d
 
+-- | Choose a time of day in microseconds. The boundaries are midnight, the last
+-- microsecond of the day, and 24:00:00, which DuckDB also accepts. A parameter
+-- with no known type keeps only microseconds.
 genTimeOfDay :: Gen TimeOfDay
-genTimeOfDay = do
-    micros <- chooseInteger (0, 86400 * 1000000 - 1)
-    pure (microsecondsToTimeOfDay micros)
+genTimeOfDay =
+  microsecondsToTimeOfDay
+    <$> frequency
+      [ (1, elements [0, 86400 * 1000000 - 1, 86400 * 1000000])
+      , (3, chooseInteger (0, 86400 * 1000000 - 1))
+      ]
 
 shrinkTimeOfDay :: TimeOfDay -> [TimeOfDay]
 shrinkTimeOfDay tod =
-    [ microsecondsToTimeOfDay us
-    | us <- shrinkIntegral (timeOfDayToMicroseconds tod)
-    , us >= 0
-    ]
+  [ microsecondsToTimeOfDay us
+  | us <- shrinkIntegral (timeOfDayToMicroseconds tod)
+  , us >= 0
+  ]
 
+-- | Choose a local time from the range of TIMESTAMP, with the boundaries of
+-- 'genTimestampMicros'.
 genLocalTime :: Gen LocalTime
-genLocalTime = LocalTime <$> genDay <*> genTimeOfDay
+genLocalTime = utcToLocalTime utc <$> genUTCTime
 
 shrinkLocalTime :: LocalTime -> [LocalTime]
 shrinkLocalTime LocalTime{localDay, localTimeOfDay} =
-    [ LocalTime day' localTimeOfDay
-    | day' <- shrinkDay localDay
-    ]
-        ++ [ LocalTime localDay time'
-           | time' <- shrinkTimeOfDay localTimeOfDay
-           ]
+  [ LocalTime day' localTimeOfDay
+  | day' <- shrinkDay localDay
+  ]
+    ++ [ LocalTime localDay time'
+       | time' <- shrinkTimeOfDay localTimeOfDay
+       ]
 
+-- | Choose a UTC time from the range of TIMESTAMPTZ, with the boundaries of
+-- 'genTimestampMicros'.
 genUTCTime :: Gen UTCTime
 genUTCTime = do
-    day <- genDay
-    micros <- chooseInteger (0, 86400 * 1000000 - 1)
-    pure (UTCTime day (picosecondsToDiffTime (micros * 1000000)))
+  micros <- genTimestampMicros
+  pure (posixSecondsToUTCTime (fromRational (micros % 1000000)))
 
 shrinkUTCTime :: UTCTime -> [UTCTime]
 shrinkUTCTime (UTCTime day diff) =
-    [UTCTime day' diff | day' <- shrinkDay day]
-        ++ [UTCTime day diff' | diff' <- shrinkDiff diff]
+  [UTCTime day' diff | day' <- shrinkDay day]
+    ++ [UTCTime day diff' | diff' <- shrinkDiff diff]
   where
     shrinkDiff dt =
-        [ picosecondsToDiffTime ps
-        | ps <- shrinkIntegral (diffTimeToPicoseconds dt)
-        , ps >= 0
-        , ps `mod` 1000000 == 0
-        ]
-
-genIntArray :: Gen (Array Int Int)
-genIntArray =
-    sized \n -> do
-        size <- chooseInt (0, max 0 (min n 8))
-        values <- vectorOf size (arbitrary :: Gen Int)
-        pure $
-            if size == 0
-                then listArray (1, 0) []
-                else listArray (0, size - 1) values
+      [ picosecondsToDiffTime ps
+      | ps <- shrinkIntegral (diffTimeToPicoseconds dt)
+      , ps >= 0
+      , ps `mod` 1000000 == 0
+      ]
 
-shrinkIntArray :: Array Int Int -> [Array Int Int]
-shrinkIntArray arr =
-    let values = elems arr
-     in [ listArray (0, length xs - 1) xs
-        | xs <- shrink values
-        , not (null xs)
-        ]
-            ++ if null values then [] else [listArray (1, 0) []]
+genIntArray :: Gen (SizedArray 4 Int)
+genIntArray = sized <$> vectorOf 4 genBounded
 
 genStructValue :: Gen (StructValue FieldValue)
 genStructValue = do
-    count <- chooseInt (0, 3)
-    if count == 0
-        then pure emptyStruct
-        else do
-            types <- vectorOf count genSimpleType
-            values <- forM types simpleTypeValue
-            let names = [Text.pack ("field" ++ show i) | i <- [0 .. count - 1]]
-                fieldArr =
-                    listArray
-                        (0, count - 1)
-                        [ StructField{structFieldName = name, structFieldValue = val}
-                        | (name, val) <- zip names values
-                        ]
-                typeArr =
-                    listArray
-                        (0, count - 1)
-                        [ StructField{structFieldName = name, structFieldValue = simpleTypeRep ty}
-                        | (name, ty) <- zip names types
-                        ]
-                indexMap = Map.fromList (zip names [0 ..])
-            pure
-                StructValue
-                    { structValueFields = fieldArr
-                    , structValueTypes = typeArr
-                    , structValueIndex = indexMap
-                    }
+  count <- chooseInt (0, 3)
+  if count == 0
+    then pure emptyStruct
+    else do
+      types <- vectorOf count genSimpleType
+      values <- forM types simpleTypeValue
+      let names = [Text.pack ("field" ++ show i) | i <- [0 .. count - 1]]
+          fieldArr =
+            listArray
+              (0, count - 1)
+              [ StructField{structFieldName = name, structFieldValue = val}
+              | (name, val) <- zip names values
+              ]
+          typeArr =
+            listArray
+              (0, count - 1)
+              [ StructField{structFieldName = name, structFieldValue = simpleTypeRep ty}
+              | (name, ty) <- zip names types
+              ]
+          indexMap = Map.fromList (zip names [0 ..])
+      pure
+        StructValue
+          { structValueFields = fieldArr
+          , structValueTypes = typeArr
+          , structValueIndex = indexMap
+          }
 
 shrinkStructValue :: StructValue FieldValue -> [StructValue FieldValue]
 shrinkStructValue StructValue{structValueFields}
-    | null (elems structValueFields) = []
-    | otherwise = [emptyStruct]
+  | null (elems structValueFields) = []
+  | otherwise = [emptyStruct]
 
 genUnionValue :: Gen (UnionValue FieldValue)
 genUnionValue = do
-    memberCount <- chooseInt (1, 4)
-    types <- vectorOf memberCount genSimpleType
-    let names = [Text.pack ("alt" ++ show i) | i <- [0 .. memberCount - 1]]
-        members =
-            listArray
-                (0, memberCount - 1)
-                [ UnionMemberType{unionMemberName = name, unionMemberType = simpleTypeRep ty}
-                | (name, ty) <- zip names types
-                ]
-    tag <- chooseInt (0, memberCount - 1)
-    payload <- simpleTypeValue (types !! tag)
-    pure
-        UnionValue
-            { unionValueIndex = fromIntegral tag
-            , unionValueLabel = names !! tag
-            , unionValuePayload = payload
-            , unionValueMembers = members
-            }
+  memberCount <- chooseInt (1, 4)
+  types <- vectorOf memberCount genSimpleType
+  let names = [Text.pack ("alt" ++ show i) | i <- [0 .. memberCount - 1]]
+      members =
+        listArray
+          (0, memberCount - 1)
+          [ UnionMemberType{unionMemberName = name, unionMemberType = simpleTypeRep ty}
+          | (name, ty) <- zip names types
+          ]
+  tag <- chooseInt (0, memberCount - 1)
+  payload <- simpleTypeValue (types !! tag)
+  pure
+    UnionValue
+      { unionValueIndex = fromIntegral tag
+      , unionValueLabel = names !! tag
+      , unionValuePayload = payload
+      , unionValueMembers = members
+      }
 
 emptyStruct :: StructValue FieldValue
 emptyStruct =
-    StructValue
-        { structValueFields = listArray (1, 0) []
-        , structValueTypes = listArray (1, 0) []
-        , structValueIndex = Map.empty
-        }
+  StructValue
+    { structValueFields = listArray (1, 0) []
+    , structValueTypes = listArray (1, 0) []
+    , structValueIndex = Map.empty
+    }
 
 data SimpleType
-    = SimpleBool
-    | SimpleInt32
-    | SimpleDouble
-    | SimpleText
-    | SimpleBlob
-    deriving (Eq, Show)
+  = SimpleBool
+  | SimpleInt32
+  | SimpleDouble
+  | SimpleText
+  | SimpleBlob
+  deriving (Eq, Show)
 
 genSimpleType :: Gen SimpleType
 genSimpleType =
-    elements [SimpleBool, SimpleInt32, SimpleDouble, SimpleText, SimpleBlob]
+  elements [SimpleBool, SimpleInt32, SimpleDouble, SimpleText, SimpleBlob]
 
 simpleTypeRep :: SimpleType -> LogicalTypeRep
 simpleTypeRep = \case
-    SimpleBool -> LogicalTypeScalar DuckDBTypeBoolean
-    SimpleInt32 -> LogicalTypeScalar DuckDBTypeInteger
-    SimpleDouble -> LogicalTypeScalar DuckDBTypeDouble
-    SimpleText -> LogicalTypeScalar DuckDBTypeVarchar
-    SimpleBlob -> LogicalTypeScalar DuckDBTypeBlob
+  SimpleBool -> LogicalTypeScalar LogicalTypeIdBoolean
+  SimpleInt32 -> LogicalTypeScalar LogicalTypeIdInteger
+  SimpleDouble -> LogicalTypeScalar LogicalTypeIdDouble
+  SimpleText -> LogicalTypeScalar LogicalTypeIdVarchar
+  SimpleBlob -> LogicalTypeScalar LogicalTypeIdBlob
 
 simpleTypeValue :: SimpleType -> Gen FieldValue
 simpleTypeValue = \case
-    SimpleBool -> FieldBool <$> (arbitrary :: Gen Bool)
-    SimpleInt32 -> FieldInt32 <$> (arbitrary :: Gen Int32)
-    SimpleDouble -> FieldDouble <$> genFiniteDouble
-    SimpleText -> FieldText <$> genText
-    SimpleBlob -> FieldBlob <$> genByteString
+  SimpleBool -> FieldBool <$> (arbitrary :: Gen Bool)
+  SimpleInt32 -> FieldInt32 <$> genBounded
+  SimpleDouble -> FieldDouble <$> genFiniteDouble
+  SimpleText -> FieldText <$> genText
+  SimpleBlob -> FieldBlob <$> genByteString
 
 timeOfDayToMicroseconds :: TimeOfDay -> Integer
 timeOfDayToMicroseconds tod =
-    diffTimeToPicoseconds (timeOfDayToTime tod) `div` 1000000
+  diffTimeToPicoseconds (timeOfDayToTime tod) `div` 1000000
 
 microsecondsToTimeOfDay :: Integer -> TimeOfDay
 microsecondsToTimeOfDay micros =
-    let (hours, remHour) = micros `divMod` (3600 * 1000000)
-        (minutes, remMinute) = remHour `divMod` (60 * 1000000)
-        (seconds, fracMicros) = remMinute `divMod` 1000000
-        pico = seconds * 1000000000000 + fracMicros * 1000000
-     in TimeOfDay (fromInteger hours) (fromInteger minutes) (MkFixed pico)
+  let (hours, remHour) = micros `divMod` (3600 * 1000000)
+      (minutes, remMinute) = remHour `divMod` (60 * 1000000)
+      (seconds, fracMicros) = remMinute `divMod` 1000000
+      pico = seconds * 1000000000000 + fracMicros * 1000000
+  in  TimeOfDay (fromInteger hours) (fromInteger minutes) (MkFixed pico)
diff --git a/test/RegistrationTests.hs b/test/RegistrationTests.hs
new file mode 100644
--- /dev/null
+++ b/test/RegistrationTests.hs
@@ -0,0 +1,705 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE DeriveGeneric #-}
+{-# LANGUAGE DerivingVia #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications #-}
+
+-- |
+-- Module      : RegistrationTests
+-- Description : Native integration checks for managed V2 registration.
+module RegistrationTests (registrationTests) where
+
+import Control.Exception (IOException, bracket, evaluate, throwIO, try)
+import Control.Monad (forM, forM_, void, when)
+import Data.IORef (IORef, atomicModifyIORef', mkWeakIORef, modifyIORef', newIORef, readIORef, writeIORef)
+import Data.Int (Int64)
+import Data.Maybe (isNothing)
+import Data.Proxy (Proxy (..))
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Database.DuckDB.FFI.V2
+import Database.DuckDB.Simple hiding (bind, execute)
+import Database.DuckDB.Simple.FromField (FieldValue (..))
+import Database.DuckDB.Simple.Generic (DuckValue (..), ViaDuckDB (..))
+import Database.DuckDB.Simple.Internal (withBytes, withConnectionFactory, withConnectionHandle)
+import qualified Database.DuckDB.Simple.Logging as Logging
+import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep (..), StructValue, UnionValue)
+import qualified Database.DuckDB.Simple.QueryMetrics as Metrics
+import qualified Database.DuckDB.Simple.V2.FunctionDocs as Docs
+import qualified Database.DuckDB.Simple.V2.Logging as V2Logging
+import qualified Database.DuckDB.Simple.V2.Pragma as Pragma
+import qualified Database.DuckDB.Simple.V2.Registration as R
+import Foreign.C.ConstPtr (ConstPtr (..))
+import Foreign.Marshal.Array (advancePtr, allocaArray, peekArray)
+import Foreign.Ptr (castPtr, freeHaskellFunPtr, nullPtr)
+import Foreign.Storable (peek, peekElemOff, poke, pokeElemOff)
+import GHC.Generics (Generic)
+import HsBindgen.Runtime.Marshal (staticSizeOf)
+import HsBindgen.Runtime.Support.FunPtr (toFunPtr)
+import System.Mem (performMajorGC)
+import System.Mem.Weak (Weak, deRefWeak)
+import Test.Tasty (TestTree, testGroup)
+import Test.Tasty.HUnit (Assertion, assertBool, assertEqual, assertFailure, testCase, (@?=))
+import TestUtils (assertSqlErrorContaining, writeIntegers, writeNullRows)
+
+-- | Check registration, callback errors, typed signatures, and resource release.
+registrationTests :: TestTree
+registrationTests =
+  testGroup
+    "V2 registration"
+    [ testCase "scalar named defaults and all parameter kinds" testScalar
+    , testCase "scalar type resolution bind state and documentation" testScalarResolution
+    , testCase "pragma query execution errors and documentation" testPragma
+    , testCase "pragma names must be nonempty and must not contain NUL" testPragmaNames
+    , testCase "query metric snapshots copy values and survive later queries" testMetrics
+    , testCase "aggregate grouped and window execution" testAggregate
+    , testCase "aggregate registration cleanup follows callback ownership" testAggregateCleanup
+    , testCase "table state and typed default parameter" testTable
+    , testCase "custom type and normal and try cast" testCast
+    , testCase "a composite value with a member of a custom type binds with no registered cast" testCastAliasMembers
+    , testCase "a second cast for the same pair of types has no effect" testCastSecond
+    , testGroup "a failed cast gives a Mismatch Type error and keeps the database usable" $
+        [testCase (castPairName castPair) (testCastFailureCode castPair) | castPair <- castFailurePairs]
+          <> [ testCase "a query on another connection fails in the callback" testCastFailureQuery
+             , testCase "an SQLError of the type Conversion, Invalid Input, or Out of Range in the callback" testCastTypedErrors
+             ]
+    , testCase "a COMMIT after a failed cast stores no row" testCastFailureCommit
+    , testCase "connection scans precede instance scans" testReplacement
+    , testCase "callback contexts write log entries" testContextLog
+    , testCase "callback failures become SQL errors" testErrors
+    , testCase "a native error text that is not valid UTF-8 gives a readable SQL error" testInvalidErrorText
+    , testCase "callback closures and query states are released" testRelease
+    ]
+
+bigint :: R.TypeDeclaration
+bigint = R.StructuredType (LogicalTypeScalar LogicalTypeIdBigInt)
+
+scalarSignature :: [R.FunctionParameter] -> R.FunctionSignature
+scalarSignature parameters = R.FunctionSignature parameters (Just bigint)
+
+scalarSum :: R.ContextCallback DuckDBV2ScalarFunctionExecInfoHandle
+scalarSum info _ = do
+  count <- R.output (c_duckdb_v2_scalar_function_exec_get_row_count info)
+  arguments <- allocaArray 4 \counts -> do
+    R.checked (c_duckdb_v2_scalar_function_exec_get_arg_count info counts (advancePtr counts 1) (advancePtr counts 2) (advancePtr counts 3))
+    fromIntegral . sum <$> peekArray 4 counts
+  columns <- forM [0 .. arguments - 1 :: Int] \index ->
+    R.output (c_duckdb_v2_scalar_function_exec_get_arg info (fromIntegral index)) >>= readIntegers (fromIntegral count)
+  vector <- R.output (c_duckdb_v2_scalar_function_exec_get_result info)
+  writeIntegers vector [sum [column !! row | column <- columns] | row <- [0 .. fromIntegral count - 1]]
+
+testScalar :: Assertion
+testScalar = withConnection ":memory:" \connection -> do
+  let left = (R.parameter "left" bigint){R.parameterDefault = Just (R.defaultValue (7 :: Int64))}
+      right =
+        (R.parameter "right" bigint)
+          { R.parameterDefault = Just (R.DefaultValue (\factory -> R.output (c_duckdb_v2_value_create_bigint factory 35)))
+          , R.parameterKind = DuckDBV2FunctionParameterKindNamedOnly
+          }
+  R.registerScalarFunction connection "managed_default" (scalarSignature [left, right]) [] (R.scalarCallbacks scalarSum)
+  query_ connection "SELECT managed_default()" >>= (@?= [Only (42 :: Int64)])
+  query_ connection "SELECT managed_default(right := 5, left := 3)" >>= (@?= [Only (8 :: Int64)])
+  let target = R.ConnectionTarget connection
+  R.withRegistrationFactory target \factory ->
+    R.registerScalarFunctionWith
+      target
+      ( \function -> do
+          R.withIdentifier "managed_target_default" (R.checked . c_duckdb_v2_scalar_function_set_name function)
+          R.output (c_duckdb_v2_scalar_function_get_signature function) >>= R.configureFunctionSignature factory (scalarSignature [left])
+      )
+      (R.scalarCallbacks scalarSum)
+  query_ connection "SELECT managed_target_default()" >>= (@?= [Only (7 :: Int64)])
+  let positional = (R.parameter "first" bigint){R.parameterKind = DuckDBV2FunctionParameterKindPositionalOnly}
+      standard = R.parameter "second" bigint
+      rest = (R.parameter "rest" bigint){R.parameterKind = DuckDBV2FunctionParameterKindPositionalVariadic}
+      named = (R.parameter "named" bigint){R.parameterKind = DuckDBV2FunctionParameterKindNamedOnly}
+      kwargs = (R.parameter "kwargs" bigint){R.parameterKind = DuckDBV2FunctionParameterKindNamedVariadic}
+  R.registerScalarFunction
+    connection
+    "managed_variadic"
+    (scalarSignature [positional, standard, rest, named, kwargs])
+    []
+    (R.scalarCallbacks scalarSum)
+  query_ connection "SELECT managed_variadic(1, 2, 3, 4, named := 5, extra := 6)" >>= (@?= [Only (21 :: Int64)])
+
+testScalarResolution :: Assertion
+testScalarResolution = withConnection ":memory:" \connection -> do
+  phases <- newIORef ([] :: [Text.Text])
+  let mark phase = modifyIORef' phases (phase :)
+      resolve input result _ = do
+        mark "resolve"
+        bracket (R.output (c_duckdb_v2_function_bind_get_arg_type input 0)) (R.destroy c_duckdb_v2_logical_type_destroy) $ \dtype ->
+          R.checked (c_duckdb_v2_scalar_function_resolve_types_set_return_type result dtype)
+      bindState _ result _ = do
+        mark "bind"
+        R.setCallbackState (c_duckdb_v2_scalar_function_bind_set_bind_data result) (42 :: Int)
+      executeRows info _ = do
+        state <- R.getCallbackState (c_duckdb_v2_scalar_function_exec_get_bind_data info)
+        (state :: Int) @?= 42
+        mismatch <- try (R.getCallbackState (c_duckdb_v2_scalar_function_exec_get_bind_data info) :: IO Bool)
+        either (\(_ :: SQLError) -> pure ()) (\_ -> assertFailure "state read with another type") mismatch
+        count <- R.output (c_duckdb_v2_scalar_function_exec_get_row_count info)
+        argument <- R.output (c_duckdb_v2_scalar_function_exec_get_arg info 0)
+        result <- R.output (c_duckdb_v2_scalar_function_exec_get_result info)
+        R.checked (c_duckdb_v2_vector_set_size result count)
+        forM_ (takeWhile (< count) [0 ..]) $ \index ->
+          bracket (R.output (c_duckdb_v2_vector_get_value argument index)) (R.destroy c_duckdb_v2_value_destroy) $ \value ->
+            R.checked (c_duckdb_v2_vector_set_value result index value)
+      anyType = R.StructuredType (LogicalTypeScalar LogicalTypeIdAny)
+      signature = R.FunctionSignature [R.parameter "value" anyType] (Just anyType)
+      target = R.ConnectionTarget connection
+  R.withRegistrationFactory target $ \factory ->
+    R.registerScalarFunctionWith
+      target
+      ( \function -> do
+          R.withIdentifier "managed_resolved" (R.checked . c_duckdb_v2_scalar_function_set_name function)
+          R.output (c_duckdb_v2_scalar_function_get_signature function) >>= R.configureFunctionSignature factory signature
+          docs <- R.output (c_duckdb_v2_scalar_function_get_docs function)
+          Docs.setFunctionDocs docs (Docs.FunctionDocs (Just "Preserve the input type.") [("Example", "SELECT managed_resolved(42)")] ["test"])
+      )
+      (R.scalarCallbacks executeRows){R.scalarResolveTypesCallback = Just resolve, R.scalarBindCallback = Just bindState}
+  query_ connection "SELECT typeof(managed_resolved(i::SMALLINT)), managed_resolved(i::SMALLINT) FROM range(2) t(i) ORDER BY i"
+    >>= (@?= [("SMALLINT" :: Text.Text, 0 :: Int64), ("SMALLINT", 1)])
+  seen <- readIORef phases
+  assertBool "resolve-types callback" ("resolve" `elem` seen)
+  assertBool "bind callback" ("bind" `elem` seen)
+  query_ connection "SELECT description FROM duckdb_functions() WHERE function_name='managed_resolved'"
+    >>= (@?= [Only ("Preserve the input type." :: Text.Text)])
+
+testPragma :: Assertion
+testPragma = withConnection ":memory:" \connection -> do
+  let amount = (R.parameter "amount" bigint){R.parameterDefault = Just (R.defaultValue (42 :: Int64))}
+  Pragma.registerPragmaFunctionOn (R.ConnectionTarget connection) "managed_query" [amount] $ Pragma.QueryPragma $ \info _ -> do
+    value <-
+      bracket
+        (R.output (c_duckdb_v2_function_bind_get_arg_value info 0))
+        (R.destroy c_duckdb_v2_value_destroy)
+        (R.output . c_duckdb_v2_value_get_bigint)
+    pure ("SELECT " <> Text.pack (show value) <> "::BIGINT")
+  query_ connection "PRAGMA managed_query" >>= (@?= [Only (42 :: Int64)])
+  query_ connection "PRAGMA managed_query(7)" >>= (@?= [Only (7 :: Int64)])
+  calls <- newIORef (0 :: Int)
+  Pragma.registerPragmaFunctionWith
+    (R.ConnectionTarget connection)
+    ( \function -> do
+        R.withIdentifier "managed_exec" (R.checked . c_duckdb_v2_pragma_function_set_name function)
+        docs <- R.output (c_duckdb_v2_pragma_function_get_docs function)
+        Docs.setFunctionDocs docs Docs.defaultFunctionDocs{Docs.functionDescription = Just "Count calls."}
+    )
+    (Pragma.ExecPragma (\_ _ -> modifyIORef' calls (+ 1)))
+  void (execute_ connection "PRAGMA managed_exec")
+  readIORef calls >>= (@?= 1)
+  Pragma.registerPragmaFunctionOn
+    (R.ConnectionTarget connection)
+    "managed_pragma_error"
+    []
+    (Pragma.QueryPragma (\_ _ -> throwIO (userError "managed callback failure")))
+  assertSqlError (query_ connection "PRAGMA managed_pragma_error" :: IO [Only Int64])
+  query_ connection "SELECT 1::BIGINT" >>= (@?= [Only (1 :: Int64)])
+
+testPragmaNames :: Assertion
+testPragmaNames = withConnection ":memory:" \connection -> do
+  forM_ ["", "managed\0pragma"] \name -> do
+    outcome <- try (Pragma.registerPragmaFunctionOn (R.ConnectionTarget connection) name [] (Pragma.ExecPragma (\_ _ -> pure ())))
+    case outcome of
+      Left (err :: SQLError) -> assertBool "name diagnostic" ("pragma function name" `Text.isInfixOf` sqlErrorMessage err)
+      Right () -> assertFailure "expected SQL error"
+  query_ connection "SELECT 1::BIGINT" >>= (@?= [Only (1 :: Int64)])
+
+testMetrics :: Assertion
+testMetrics = withConnection ":memory:" \connection -> do
+  Metrics.enableProfiling connection True
+  query_ connection "SELECT sum(i)::BIGINT FROM range(10) t(i)" >>= (@?= [Only (45 :: Int64)])
+  snapshot <- Metrics.queryMetrics connection
+  Metrics.metricsNodeName snapshot @?= "QUERY"
+  assertBool "root metrics" (not (null (Metrics.metricsValues snapshot)))
+  assertBool "operator metrics" (not (null (Metrics.metricsChildren snapshot)))
+  let scanRows =
+        [ value
+        | node <- metricNodes snapshot
+        , Metrics.metricsNodeName node == "TABLE_SCAN"
+        , Just value <- [lookup "operator.intermediate_rows" (Metrics.metricsValues node)]
+        ]
+  scanRows @?= [FieldWord64 10]
+  Metrics.enableProfiling connection False
+  query_ connection "SELECT 2::BIGINT" >>= (@?= [Only (2 :: Int64)])
+  empty <- Metrics.queryMetrics connection
+  Metrics.metricsValues empty @?= []
+  Metrics.metricsChildren empty @?= []
+  where
+    metricNodes node = node : concatMap metricNodes (Metrics.metricsChildren node)
+
+sumCallbacks :: R.AggregateCallbacks
+sumCallbacks = R.aggregateCallbacks stateSize initialize update combine finalize
+  where
+    stateSize info = R.checked (c_duckdb_v2_aggregate_function_size_set_state_size info (fromIntegral (staticSizeOf (Proxy @Int64))))
+    initialize info = do
+      count <- R.output (c_duckdb_v2_aggregate_function_init_get_state_count info)
+      states <- R.output (c_duckdb_v2_aggregate_function_init_get_states info)
+      forM_ [0 .. fromIntegral count - 1] \index -> peekElemOff states index >>= \state -> poke (castPtr state) (0 :: Int64)
+    update info = do
+      count <- R.output (c_duckdb_v2_aggregate_function_update_get_row_count info)
+      states <- R.output (c_duckdb_v2_aggregate_function_update_get_states info)
+      values <- R.output (c_duckdb_v2_aggregate_function_update_get_arg info 0) >>= readIntegers (fromIntegral count)
+      forM_ (zip [0 ..] values) \(index, value) -> do
+        state <- castPtr <$> peekElemOff states index
+        total <- peek state
+        poke state (total + value :: Int64)
+    combine info = do
+      count <- R.output (c_duckdb_v2_aggregate_function_combine_get_state_count info)
+      sources <- R.output (c_duckdb_v2_aggregate_function_combine_get_sources info)
+      targets <- R.output (c_duckdb_v2_aggregate_function_combine_get_targets info)
+      forM_ [0 .. fromIntegral count - 1] \index -> do
+        source <- peekElemOff sources index >>= peek . castPtr
+        target <- castPtr <$> peekElemOff targets index
+        total <- peek target
+        poke target (total + source :: Int64)
+    finalize info = do
+      count <- R.output (c_duckdb_v2_aggregate_function_finalize_get_state_count info)
+      states <- R.output (c_duckdb_v2_aggregate_function_finalize_get_states info)
+      offset <- R.output (c_duckdb_v2_aggregate_function_finalize_get_result_offset info)
+      result <- R.output (c_duckdb_v2_aggregate_function_finalize_get_result info)
+      raw <- R.output (c_duckdb_v2_vector_get_data_mutable result)
+      forM_ [0 .. fromIntegral count - 1] \index -> do
+        total <- peekElemOff states index >>= peek . castPtr
+        pokeElemOff (castPtr raw) (fromIntegral offset + index) (total :: Int64)
+
+testAggregate :: Assertion
+testAggregate = withConnection ":memory:" \connection -> do
+  destroyed <- newIORef (0 :: Int)
+  let callbacks = sumCallbacks{R.aggregateDestroyCallback = Just (\_ -> modifyIORef' destroyed (+ 1))}
+  R.registerAggregateFunction connection "managed_sum" (scalarSignature [R.parameter "value" bigint]) [] callbacks
+  query_ connection "SELECT managed_sum(i::BIGINT) FROM range(12) t(i) GROUP BY i % 3 ORDER BY i % 3"
+    >>= (@?= map Only ([18, 22, 26] :: [Int64]))
+  query_ connection "SELECT managed_sum(i::BIGINT) OVER () FROM range(4096) t(i) LIMIT 1" >>= (@?= [Only (8386560 :: Int64)])
+  readIORef destroyed >>= assertBool "aggregate state destruction ran" . (> 0)
+
+-- | Keep registration resources across queries and prepared statements. Release
+-- them once when the database closes, or when configuration fails.
+testAggregateCleanup :: Assertion
+testAggregateCleanup = do
+  released <- newIORef ([] :: [Text])
+  let release name = atomicModifyIORef' released \names -> (name : names, ())
+  withConnection ":memory:" \connection -> do
+    let target = R.ConnectionTarget connection
+    R.withRegistrationFactory target \factory -> do
+      let configure name function = do
+            R.withIdentifier name (R.checked . c_duckdb_v2_aggregate_function_set_name function)
+            signature <- R.output (c_duckdb_v2_aggregate_function_get_signature function)
+            R.configureFunctionSignature factory (scalarSignature [R.parameter "value" bigint]) signature
+      R.registerAggregateFunctionWithCleanup target (release "used") (configure "managed_owned_sum") sumCallbacks
+      R.registerAggregateFunctionWithCleanup target (release "unused") (configure "managed_unused_sum") sumCallbacks
+      failed <-
+        try
+          ( R.registerAggregateFunctionWithCleanup
+              target
+              (release "failed")
+              (\_ -> throwIO (userError "aggregate configuration failed"))
+              sumCallbacks
+          )
+      case failed of
+        Left (_ :: IOException) -> pure ()
+        Right () -> assertFailure "aggregate configuration must fail"
+    readIORef released >>= (@?= ["failed"])
+    forM_ [1 .. 3 :: Int] \_ ->
+      query_ connection "SELECT managed_owned_sum(i) FROM range(10) t(i)" >>= (@?= [Only (45 :: Int64)])
+    withStatement connection "SELECT managed_owned_sum(i) FROM range(10) t(i)" \statement -> do
+      nextRow statement >>= (@?= Just (Only (45 :: Int64)))
+      void (executeStatement statement)
+      nextRow statement >>= (@?= Just (Only (45 :: Int64)))
+    readIORef released >>= (@?= ["failed"])
+  names <- readIORef released
+  forM_ ["used", "unused", "failed"] \name ->
+    assertEqual ("cleanup count for " <> Text.unpack name) 1 (length (filter (== name) names))
+
+tableDefinition :: R.TableCallbacks
+tableDefinition = (R.tableCallbacks bind execute){R.tableInitGlobalCallback = Just initialize}
+  where
+    bind input result context = do
+      amount <- bracket (R.output (c_duckdb_v2_function_bind_get_arg_value input 0)) (R.destroy c_duckdb_v2_value_destroy) \value ->
+        R.output (c_duckdb_v2_value_get_bigint value)
+      R.setCallbackState (c_duckdb_v2_function_bind_set_bind_data input) (amount :: Int64)
+      bracket
+        ( R.output (c_duckdb_v2_context_get_factory context) >>= \factory -> R.output (c_duckdb_v2_factory_create_type_from_id factory DuckDBV2LogicalTypeIdBigInt (ConstPtr nullPtr) (ConstPtr nullPtr) 0)
+        )
+        (R.destroy c_duckdb_v2_logical_type_destroy)
+        \dtype -> R.withIdentifier "amount" \name -> R.checked (c_duckdb_v2_table_function_bind_add_result_column result name dtype)
+    initialize info _ = do
+      amount <- R.getCallbackState (c_duckdb_v2_table_function_init_global_get_bind_data info)
+      state <- newIORef (Just (amount :: Int64))
+      R.setCallbackState (c_duckdb_v2_table_function_init_global_set_global_state info) state
+    execute info _ = do
+      state <- R.getCallbackState (c_duckdb_v2_table_function_exec_get_global_state info) :: IO (IORef (Maybe Int64))
+      amount <- atomicModifyIORef' state (\value -> (Nothing, value))
+      chunk <- R.output (c_duckdb_v2_table_function_exec_get_output_chunk info)
+      vector <- R.output (c_duckdb_v2_data_chunk_get_vector chunk 0)
+      writeIntegers vector (maybe [] (\count -> [42 .. 41 + count]) amount)
+
+testTable :: Assertion
+testTable = withConnection ":memory:" \connection -> do
+  let count = (R.parameter "count" bigint){R.parameterDefault = Just (R.defaultValue (3 :: Int64))}
+  R.registerTableFunction connection "managed_scan" [count] tableDefinition
+  query_ connection "SELECT amount FROM managed_scan()" >>= (@?= map Only ([42, 43, 44] :: [Int64]))
+  query_ connection "SELECT amount FROM managed_scan(count := 1)" >>= (@?= [Only (42 :: Int64)])
+
+testCast :: Assertion
+testCast = withConnection ":memory:" \connection -> do
+  R.registerCustomType connection "managed_shifted" bigint
+  modes <- newIORef []
+  R.registerCast connection bigint (R.TypeExpression "managed_shifted") Nothing \info _ -> do
+    mode <- R.output (c_duckdb_v2_cast_function_exec_get_mode info)
+    modifyIORef' modes (mode :)
+    count <- R.output (c_duckdb_v2_cast_function_exec_get_row_count info)
+    values <- R.output (c_duckdb_v2_cast_function_exec_get_input info) >>= readIntegers (fromIntegral count)
+    result <- R.output (c_duckdb_v2_cast_function_exec_get_output info)
+    writeIntegers result (map (+ 100) values)
+  query_ connection "SELECT CAST(i::BIGINT AS managed_shifted)::BIGINT FROM range(3) t(i)" >>= (@?= map Only ([100, 101, 102] :: [Int64]))
+  query_ connection "SELECT TRY_CAST(7::BIGINT AS managed_shifted)::BIGINT" >>= (@?= [Only (107 :: Int64)])
+  seen <- readIORef modes
+  assertBool "normal cast" (DuckDBV2CastModeNormal `elem` seen)
+  assertBool "try cast" (DuckDBV2CastModeTry `elem` seen)
+
+-- | A BIGINT of the custom type member_shifted, as a record field.
+newtype Shifted = Shifted Int64
+
+instance DuckValue Shifted where
+  duckToField (Shifted value) = FieldInt64 value
+  duckFromField = fmap Shifted . duckFromField
+  duckLogicalType _ = LogicalTypeAlias "member_shifted" (LogicalTypeScalar LogicalTypeIdBigInt)
+
+-- | A record with a field of the custom type member_shifted.
+newtype Holder = Holder {held :: Shifted}
+  deriving (Generic)
+  deriving (ToField) via (ViaDuckDB Holder)
+
+-- | A STRUCT value and a UNION value with a member of a registered custom type
+-- bind again with no run of the registered cast from the base type, and so
+-- does a record whose field declares that type. The library writes these
+-- values with the default cast of DuckDB. See
+-- Note [User casts and the casts of the library] in
+-- "Database.DuckDB.Simple.Materialize".
+testCastAliasMembers :: Assertion
+testCastAliasMembers = withConnection ":memory:" \connection -> do
+  R.registerCustomType connection "member_shifted" bigint
+  calls <- newIORef (0 :: Int)
+  R.registerCast connection bigint (R.TypeExpression "member_shifted") Nothing \info _ -> do
+    modifyIORef' calls (+ 1)
+    count <- R.output (c_duckdb_v2_cast_function_exec_get_row_count info)
+    values <- R.output (c_duckdb_v2_cast_function_exec_get_input info) >>= readIntegers (fromIntegral count)
+    result <- R.output (c_duckdb_v2_cast_function_exec_get_output info)
+    writeIntegers result (map (+ 100) values)
+  [(struct, union)] <-
+    query_ connection "SELECT {'v': 7::BIGINT::member_shifted}, union_value(v := 7::BIGINT::member_shifted)"
+      :: IO [(StructValue FieldValue, UnionValue FieldValue)]
+  readIORef calls >>= assertBool "the query runs the registered cast" . (> 0)
+  writeIORef calls 0
+  query connection "SELECT (?).v::BIGINT, union_extract(?, 'v')::BIGINT, (?).held::BIGINT" (struct, union, Holder (Shifted 7))
+    >>= (@?= [(107 :: Int64, 107 :: Int64, 7 :: Int64)])
+  query connection "SELECT typeof(?), typeof(?), typeof(?)" (struct, union, Holder (Shifted 7))
+    >>= (@?= [("STRUCT(v member_shifted)" :: Text, "UNION(v member_shifted)" :: Text, "STRUCT(held member_shifted)" :: Text)])
+  readIORef calls >>= (@?= 0)
+
+-- | A pair of types for 'testCastFailureCode': the setup, the source type, the
+-- target type, a constant of the source type, and a column of the source type
+-- over @i@. DuckDB plans a cast of the first two pairs as a cast that cannot
+-- fail.
+data CastPair = CastPair
+  { castPairName :: String
+  , castPairSetup :: Connection -> IO ()
+  , castPairSource :: R.TypeDeclaration
+  , castPairTarget :: Text
+  , castPairConstant :: Text
+  , castPairColumn :: Text
+  }
+
+-- | The pairs of 'testCastFailureCode' and 'testCastFailureCommit'.
+castFailurePairs :: [CastPair]
+castFailurePairs =
+  [ CastPair "BIGINT to VARCHAR" (\_ -> pure ()) bigint "VARCHAR" "1::BIGINT" "i::BIGINT"
+  , CastPair "INTEGER to BIGINT" (\_ -> pure ()) (R.TypeExpression "INTEGER") "BIGINT" "1::INTEGER" "i::INTEGER"
+  , CastPair "BIGINT to a custom type" (\conn -> R.registerCustomType conn "cast_target" bigint) bigint "cast_target" "1::BIGINT" "i::BIGINT"
+  ]
+
+-- | Register a cast of the pair that writes NULL to each row and then raises
+-- an exception with the text 'castFailure'.
+registerFailingCast :: Connection -> CastPair -> IO ()
+registerFailingCast conn castPair =
+  R.registerCast conn (castPairSource castPair) (R.TypeExpression (castPairTarget castPair)) Nothing \info _ ->
+    writeNullRows info >> throwIO (userError castFailure)
+
+-- | The text of the exception of 'registerFailingCast'.
+castFailure :: String
+castFailure = "the cast refused the value"
+
+-- | Fail a cast of a pair in a constant, in a column of 3000 rows, in an INSERT
+-- with the assignment cast, and in an INSERT with CAST. Each failure gives
+-- 'ErrorTypeMismatch' with the text of the exception. Each connection of the
+-- database runs a query after the failure. TRY_CAST gives the NULL that the
+-- callback wrote, and TRY(CAST) raises the error. See
+-- Note [The error code of a failed cast] in "Database.DuckDB.Simple.V2.Registration".
+testCastFailureCode :: CastPair -> Assertion
+testCastFailureCode castPair = withEnvironment \environment ->
+  forM_ ["constant", "column", "INSERT", "INSERT with CAST"] \form -> withCastDatabase environment castPair \instance' conn -> do
+    let target = castPairTarget castPair
+        constant = castPairConstant castPair
+        label = castPairName castPair <> ", " <> form
+        statement = case form of
+          "constant" -> "SELECT CAST(" <> constant <> " AS " <> target <> ")"
+          "column" -> "SELECT CAST(c AS " <> target <> ") FROM src"
+          "INSERT" -> "INSERT INTO dst SELECT c FROM src"
+          _ -> "INSERT INTO dst SELECT CAST(c AS " <> target <> ") FROM src"
+    assertMismatch label (Text.pack castFailure) (void (query_ conn (Query statement) :: IO [Only FieldValue]))
+    query_ conn "SELECT 42" >>= assertEqual label [Only (42 :: Int64)]
+    withConnectionOn instance' \other -> query_ other "SELECT 42" >>= assertEqual label [Only (42 :: Int64)]
+    when (form == "constant") do
+      query_ conn (Query ("SELECT TRY_CAST(" <> constant <> " AS " <> target <> ") IS NULL")) >>= assertEqual label [Only True]
+      assertMismatch
+        label
+        (Text.pack castFailure)
+        (void (query_ conn (Query ("SELECT TRY(CAST(" <> constant <> " AS " <> target <> "))")) :: IO [Only FieldValue]))
+
+-- | A query on another connection fails in the callback of a cast with the
+-- type Conversion. The cast error has the type of each cast error.
+testCastFailureQuery :: Assertion
+testCastFailureQuery = withEnvironment \environment ->
+  withCastInstance environment \instance' -> withConnectionOn instance' \conn -> withConnectionOn instance' \other -> do
+    R.registerCast conn bigint (R.TypeExpression "VARCHAR") Nothing \_ _ ->
+      void (query_ other "SELECT 'abc'::INTEGER" :: IO [Only Int64])
+    assertMismatch
+      "query"
+      "Could not convert string 'abc' to INT32"
+      (void (query_ conn "SELECT CAST(i AS VARCHAR) FROM range(10) t(i)" :: IO [Only Text]))
+    query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+    query_ other "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+
+-- | An 'SQLError' of the type Conversion, Invalid Input, or Out of Range from
+-- the callback of a cast from BIGINT to VARCHAR gives 'ErrorTypeMismatch', and
+-- the database stays usable. DuckDB plans this cast as a cast that cannot fail.
+-- With the code of the type of the error, DuckDB would raise an INTERNAL error
+-- and invalidate the database. See Note [The error code of a failed cast] in
+-- "Database.DuckDB.Simple.V2.Registration".
+testCastTypedErrors :: Assertion
+testCastTypedErrors = withEnvironment \environment -> forM_ [ErrorTypeConversion, ErrorInputInvalid, ErrorInputOutOfRange] \errorType ->
+  withCastInstance environment \instance' -> withConnectionOn instance' \conn -> do
+    let label = show errorType
+        text = "the cast raised " <> Text.pack label
+    void (execute_ conn "CREATE TABLE src AS SELECT i::BIGINT AS c FROM range(3000) t(i)")
+    R.registerCast conn bigint (R.TypeExpression "VARCHAR") Nothing \_ _ ->
+      throwIO SQLError{sqlErrorMessage = text, sqlErrorType = Just errorType, sqlErrorQuery = Nothing, sqlErrorBody = Just text}
+    assertMismatch label text (void (query_ conn "SELECT CAST(c AS VARCHAR) FROM src" :: IO [Only Text]))
+    query_ conn "SELECT 42" >>= assertEqual label [Only (42 :: Int64)]
+    withConnectionOn instance' \other -> query_ other "SELECT 42" >>= assertEqual label [Only (42 :: Int64)]
+
+-- | A COMMIT after a failed cast in an explicit transaction stores no row,
+-- under each transaction invalidation policy. The last cast fails only in its
+-- fifth call, the last chunk of 10000 rows, so that the INSERT writes rows
+-- before the failure.
+testCastFailureCommit :: Assertion
+testCastFailureCommit = withEnvironment \environment -> forM_ [Nothing, Just "SYNTACTIC_ERRORS_DO_NOT_INVALIDATE"] \policy -> do
+  let commitAfter label instance' conn failing = do
+        forM_ (policy :: Maybe Text) \name -> forM_ ["default", "current"] \scope ->
+          execute_ conn (Query ("SET " <> scope <> "_transaction_invalidation_policy = '" <> name <> "'"))
+        void (execute_ conn "CREATE TABLE marker (m INTEGER)")
+        void (execute_ conn "BEGIN TRANSACTION")
+        void (execute_ conn "INSERT INTO marker VALUES (1)")
+        assertMismatch label (Text.pack castFailure) (void (execute_ conn failing))
+        void (try (execute_ conn "COMMIT") :: IO (Either SQLError Int))
+        withConnectionOn instance' \other ->
+          query_ other "SELECT (SELECT count(*) FROM marker) + (SELECT count(*) FROM dst)"
+            >>= assertEqual (label <> ", " <> show policy) [Only (0 :: Int64)]
+  forM_ castFailurePairs \castPair -> withCastDatabase environment castPair \instance' conn ->
+    commitAfter (castPairName castPair) instance' conn (Query ("INSERT INTO dst SELECT CAST(c AS " <> castPairTarget castPair <> ") FROM src"))
+  withCastInstance environment \instance' -> withConnectionOn instance' \conn -> do
+    void (execute_ conn "CREATE TABLE src AS SELECT i::BIGINT AS c FROM range(10000) t(i)")
+    void (execute_ conn "CREATE TABLE dst (x VARCHAR)")
+    calls <- newIORef (0 :: Int)
+    R.registerCast conn bigint (R.TypeExpression "VARCHAR") Nothing \info _ -> do
+      writeNullRows info
+      call <- atomicModifyIORef' calls \count -> (count + 1, count + 1)
+      when (call >= 5) (throwIO (userError castFailure))
+    commitAfter "BIGINT to VARCHAR over 10000 rows" instance' conn "INSERT INTO dst SELECT CAST(c AS VARCHAR) FROM src"
+
+-- | Require an 'SQLError' of the type 'ErrorTypeMismatch' whose message
+-- contains the text.
+assertMismatch :: String -> Text -> IO () -> Assertion
+assertMismatch label text action =
+  try action >>= \case
+    Left (err :: SQLError) -> do
+      assertEqual label (Just ErrorTypeMismatch) (sqlErrorType err)
+      assertBool (label <> ": " <> Text.unpack (sqlErrorMessage err)) (text `Text.isInfixOf` sqlErrorMessage err)
+    Right () -> assertFailure (label <> ": expected an SQL error")
+
+-- | Run an action with a new instance that has an in-memory database.
+withCastInstance :: Environment -> (Instance -> IO a) -> IO a
+withCastInstance environment action = withInstance environment [] \instance' -> do
+  attachDatabase instance' ":memory:" "cast_failure" []
+  setDefaultDatabase instance' "cast_failure"
+  action instance'
+
+-- | Run an action with a new instance, the tables src and dst of a pair, and
+-- the failing cast of the pair.
+withCastDatabase :: Environment -> CastPair -> (Instance -> Connection -> IO a) -> IO a
+withCastDatabase environment castPair action = withCastInstance environment \instance' -> withConnectionOn instance' \conn -> do
+  castPairSetup castPair conn
+  void (execute_ conn (Query ("CREATE TABLE src AS SELECT " <> castPairColumn castPair <> " AS c FROM range(3000) t(i)")))
+  void (execute_ conn (Query ("CREATE TABLE dst (x " <> castPairTarget castPair <> ")")))
+  registerFailingCast conn castPair
+  action instance' conn
+
+-- | A second registration of a cast for the same pair of types returns with no
+-- error, and CAST still runs the callback of the first registration. DuckDB
+-- 2.0.0 keeps the first cast for a pair.
+testCastSecond :: Assertion
+testCastSecond = withConnection ":memory:" \connection -> do
+  R.registerCustomType connection "managed_kept" bigint
+  let shift amount info _ = do
+        count <- R.output (c_duckdb_v2_cast_function_exec_get_row_count info)
+        values <- R.output (c_duckdb_v2_cast_function_exec_get_input info) >>= readIntegers (fromIntegral count)
+        result <- R.output (c_duckdb_v2_cast_function_exec_get_output info)
+        writeIntegers result (map (+ amount) values)
+  R.registerCast connection bigint (R.TypeExpression "managed_kept") Nothing (shift 100)
+  R.registerCast connection bigint (R.TypeExpression "managed_kept") Nothing (shift 200)
+  query_ connection "SELECT CAST(i::BIGINT AS managed_kept)::BIGINT FROM range(3) t(i)" >>= (@?= map Only ([100, 101, 102] :: [Int64]))
+
+replacement :: Int64 -> R.ContextCallback DuckDBV2ReplacementScanInfoHandle
+replacement number info _ =
+  bracket (R.output (c_duckdb_v2_replacement_scan_get_name info)) (R.destroy c_duckdb_v2_qname_destroy) \name -> do
+    count <- R.output (c_duckdb_v2_qname_get_part_count name)
+    when (count == 1) do
+      part <- R.output (c_duckdb_v2_qname_get_part name 0) >>= R.readIdentifier
+      when (part == "managed_missing")
+        $ R.withText ("SELECT " <> Text.pack (show number) <> "::BIGINT AS amount")
+        $ R.checked . c_duckdb_v2_replacement_scan_set_subquery info
+
+testReplacement :: Assertion
+testReplacement = withEnvironment \environment -> withInstance environment [] \instance' -> do
+  R.registerInstanceReplacementScan instance' (replacement 7)
+  withConnectionOn instance' \first -> withConnectionOn instance' \second -> do
+    R.registerReplacementScan first (replacement 42)
+    query_ first "SELECT amount FROM managed_missing" >>= (@?= [Only (42 :: Int64)])
+    query_ second "SELECT amount FROM managed_missing" >>= (@?= [Only (7 :: Int64)])
+
+testContextLog :: Assertion
+testContextLog = do
+  entries <- newIORef []
+  withConnection ":memory:" \connection -> do
+    Logging.registerLogSink connection "context_log" (\entry -> atomicModifyIORef' entries (\values -> (entry : values, ()))) (pure ())
+    let logged info context = do
+          V2Logging.logMessage context Logging.LogLevelWarning "HaskellContext" "from a callback"
+          count <- R.output (c_duckdb_v2_scalar_function_exec_get_row_count info)
+          vector <- R.output (c_duckdb_v2_scalar_function_exec_get_result info)
+          writeIntegers vector (replicate (fromIntegral count) 1)
+    R.registerScalarFunction connection "managed_log" (scalarSignature []) [] (R.scalarCallbacks logged)
+    void $ execute_ connection "CALL enable_logging(); SET logging_storage = 'context_log'"
+    query_ connection "SELECT managed_log()" >>= (@?= [Only (1 :: Int64)])
+    void $ execute_ connection "SET logging_storage = 'memory'"
+  received <- filter ((== "HaskellContext") . Logging.logEntryType) <$> readIORef entries
+  map Logging.logEntryMessage received @?= ["from a callback"]
+  map Logging.logEntryScope received @?= [Logging.LogScopeConnection]
+
+testErrors :: Assertion
+testErrors = withConnection ":memory:" \connection -> do
+  let failure = throwIO (userError "managed callback failure")
+  R.registerScalarFunction connection "managed_error" (scalarSignature []) [] (R.scalarCallbacks (\_ _ -> failure))
+  assertSqlError (query_ connection "SELECT managed_error()" :: IO [Only Int64])
+  R.registerAggregateFunction
+    connection
+    "managed_error_sum"
+    (scalarSignature [R.parameter "value" bigint])
+    []
+    sumCallbacks{R.aggregateUpdateCallback = \_ -> failure}
+  assertSqlError (query_ connection "SELECT managed_error_sum(i::BIGINT) FROM range(3) t(i)" :: IO [Only Int64])
+  R.registerTableFunction connection "managed_error_table" [] (R.tableCallbacks (\_ _ _ -> failure) (\_ _ -> pure ()))
+  assertSqlError (query_ connection "SELECT * FROM managed_error_table()" :: IO [Only Int64])
+  R.registerReplacementScan connection (\_ _ -> failure)
+  assertSqlError (query_ connection "SELECT * FROM managed_unknown" :: IO [Only Int64])
+
+-- | A raw exec callback writes an error text with the byte 0xff, which is not
+-- valid UTF-8. The query must fail with an SQL error that can be shown.
+testInvalidErrorText :: Assertion
+testInvalidErrorText =
+  bracket (toFunPtr (DuckDBV2ScalarFunctionExecCallbackFn_Aux invalidText)) freeHaskellFunPtr \exec ->
+    withConnection ":memory:" \connection -> do
+      withConnectionHandle connection \native -> withConnectionFactory native \factory ->
+        bracket (R.output (c_duckdb_v2_scalar_function_create factory)) (R.destroy c_duckdb_v2_scalar_function_destroy) \function -> do
+          R.withIdentifier "invalid_error_text" (R.checked . c_duckdb_v2_scalar_function_set_name function)
+          R.output (c_duckdb_v2_scalar_function_get_signature function) >>= R.configureFunctionSignature factory (scalarSignature [])
+          R.checked (c_duckdb_v2_scalar_function_set_exec_callback function (DuckDBV2ScalarFunctionExecCallbackFn exec))
+          R.checked (c_duckdb_v2_connection_register_scalar_function native function)
+      outcome <- try (query_ connection "SELECT invalid_error_text()" :: IO [Only Int64])
+      case outcome of
+        Left (err :: SQLError) -> do
+          assertBool "replacement character" ("bad \xFFFD message" `Text.isInfixOf` sqlErrorMessage err)
+          sqlErrorQuery err @?= Just "SELECT invalid_error_text()"
+          void (evaluate (length (show err)))
+        Right _ -> assertFailure "expected SQL error"
+  where
+    invalidText _ _ err = do
+      info <- peek err
+      void (c_duckdb_v2_error_info_set_code info DuckDBV2ErrorInputInvalid)
+      withBytes "bad \xff message" (void . c_duckdb_v2_error_info_set_text info)
+
+testRelease :: Assertion
+testRelease = do
+  references <- withConnection ":memory:" \connection -> do
+    closure <- newIORef (42 :: Int64)
+    closureWeak <- mkWeakIORef closure (pure ())
+    states <- newIORef []
+    let initialize info _ = do
+          state <- newIORef (1 :: Int64)
+          weak <- mkWeakIORef state (pure ())
+          modifyIORef' states (weak :)
+          R.setCallbackState (c_duckdb_v2_scalar_function_init_set_init_data info) state
+        execute info _ = do
+          state <- R.getCallbackState (c_duckdb_v2_scalar_function_exec_get_init_data info) :: IO (IORef Int64)
+          increment <- readIORef state
+          value <- (+ increment) <$> readIORef closure
+          result <- R.output (c_duckdb_v2_scalar_function_exec_get_result info)
+          writeIntegers result [value]
+    R.registerScalarFunction
+      connection
+      "managed_release"
+      (scalarSignature [])
+      []
+      (R.scalarCallbacks execute){R.scalarInitCallback = Just initialize}
+    query_ connection "SELECT managed_release()" >>= (@?= [Only (43 :: Int64)])
+    stateRefs <- readIORef states
+    assertBool "state initialized" (not (null stateRefs))
+    pragmaClosure <- newIORef (7 :: Int64)
+    pragmaWeak <- mkWeakIORef pragmaClosure (pure ())
+    Pragma.registerPragmaFunctionOn
+      (R.ConnectionTarget connection)
+      "managed_pragma_release"
+      []
+      (Pragma.ExecPragma (\_ _ -> void (readIORef pragmaClosure)))
+    void (execute_ connection "PRAGMA managed_pragma_release")
+    failed <- failedRegistration connection
+    pure (closureWeak : pragmaWeak : failed : stateRefs)
+  performMajorGC
+  performMajorGC
+  forM_ references \reference -> deRefWeak reference >>= assertBool "native callback state or closure remains live" . isNothing
+
+failedRegistration :: Connection -> IO (Weak (IORef Int64))
+failedRegistration connection = do
+  retained <- newIORef (1 :: Int64)
+  reference <- mkWeakIORef retained (pure ())
+  let execute _ _ = void (readIORef retained)
+      duplicate = R.parameter "duplicate" bigint
+  result <-
+    try (R.registerScalarFunction connection "managed_invalid" (scalarSignature [duplicate, duplicate]) [] (R.scalarCallbacks execute))
+  case result of
+    Left (_ :: SQLError) -> pure ()
+    Right () -> assertFailure "duplicate parameter names must fail"
+  pure reference
+
+-- | Require an 'SQLError' with the message of a failed managed callback.
+assertSqlError :: IO a -> Assertion
+assertSqlError = assertSqlErrorContaining "managed callback failure"
+
+readIntegers :: Int -> DuckDBV2VectorHandle -> IO [Int64]
+readIntegers count vector = do
+  R.checked (c_duckdb_v2_vector_flatten vector)
+  raw <- R.output (c_duckdb_v2_vector_get_data_mutable vector)
+  mapM (peekElemOff (castPtr raw)) [0 .. count - 1]
diff --git a/test/SizedArrayTests.hs b/test/SizedArrayTests.hs
new file mode 100644
--- /dev/null
+++ b/test/SizedArrayTests.hs
@@ -0,0 +1,209 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE DeriveGeneric #-}
+{-# LANGUAGE DerivingVia #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications #-}
+
+-- | Cases of the sized ARRAY type 'SizedArray'. See Note [Sized arrays] in
+-- "Database.DuckDB.Simple.ToField".
+module SizedArrayTests (sizedArrayTests) where
+
+import Control.Exception (try)
+import Control.Monad (forM_)
+import Data.Array (bounds, elems, listArray, (!))
+import Data.Foldable (toList)
+import Data.Int (Int32, Int64, Int8)
+import qualified Data.Map.Strict as Map
+import Data.Maybe (fromJust, isNothing)
+import Data.Proxy (Proxy (..))
+import qualified Data.Text as Text
+import Database.DuckDB.Simple
+import Database.DuckDB.Simple.FromField (FieldValue (..))
+import Database.DuckDB.Simple.Generic (DuckValue (..), ViaDuckDB (..))
+import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep (..), TypeDeclaration (..))
+import Database.DuckDB.Simple.Ok (Ok (..))
+import Database.DuckDB.Simple.ToField (ToDuckValue)
+import qualified Database.DuckDB.Simple.V2.Registration as R
+import GHC.Generics (Generic)
+import Test.Tasty (TestTree, testGroup)
+import Test.Tasty.HUnit (assertBool, assertFailure, testCase, (@?=))
+import TestUtils (assertInputErrorContaining, assertReusable, assertSqlErrorContaining, assertSqlErrorType)
+
+-- | A record with a field of a sized ARRAY type.
+newtype Sized = Sized {sizedValues :: SizedArray 3 Int64}
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToField, ToDuckValue, FromField) via (ViaDuckDB Sized)
+
+-- | A typed NULL must not allow an unsupported ARRAY size in a generic field.
+newtype Above = Above {aboveValues :: Maybe (SizedArray 100001 Int64)}
+  deriving stock (Show, Generic)
+  deriving (DuckDBColumnType, ToField, ToDuckValue, FromField) via (ViaDuckDB Above)
+
+-- | This size would wrap to one element if narrowed directly to Word64.
+newtype Overflow = Overflow {overflowValues :: Maybe (SizedArray 18446744073709551617 Int64)}
+  deriving stock (Show, Generic)
+  deriving (DuckDBColumnType, ToField, ToDuckValue, FromField) via (ViaDuckDB Overflow)
+
+-- | The generic declaration must check ARRAY sizes below each container.
+newtype NestedAbove = NestedAbove {nestedValues :: [Map.Map Text.Text (Maybe (SizedArray 100001 Int64))]}
+  deriving stock (Show, Generic)
+  deriving (DuckDBColumnType, ToField, ToDuckValue, FromField) via (ViaDuckDB NestedAbove)
+
+-- | The cases of 'SizedArray' as a parameter, a column, and a function argument.
+sizedArrayTests :: TestTree
+sizedArrayTests =
+  testGroup
+    "sized arrays"
+    [ testCase "a SizedArray rejects a longer list without forcing its tail or elements" $ do
+        assertBool "an infinite list is too long" (isNothing (sizedArrayFromList @3 ([1 ..] :: [Int64])))
+        assertBool
+          "a fourth element is enough to reject the list"
+          (isNothing (sizedArrayFromList @3 ([undefined, undefined, undefined, undefined] ++ undefined :: [Int64])))
+    , testCase "a SizedArray binds as an ARRAY of its size and reads back from a parameter and a column" $ withConnection ":memory:" \conn -> do
+        let values = fromJust (sizedArrayFromList @3 [1, 2, 3 :: Int64])
+        toList values @?= [1, 2, 3]
+        sizedArrayFromList @3 [1, 2 :: Int64] @?= Nothing
+        -- An Array with any bounds gives the bounds (0, n - 1) and the same
+        -- elements. An Array of another count gives Nothing.
+        let shifted = listArray (5, 7) [1, 2, 3 :: Int64]
+            fromShifted = fromJust (sizedArray @3 shifted)
+        bounds (sizedArrayToArray fromShifted) @?= (0, 2)
+        elems (sizedArrayToArray fromShifted) @?= elems shifted
+        fromShifted @?= values
+        show values @?= "SizedArray (array (0,2) [(0,1),(1,2),(2,3)])"
+        -- The count is checked before the Array is built, for an Array and a
+        -- list of fewer and of more values.
+        sizedArray @3 (listArray (0, 1) [1, 2 :: Int64]) @?= Nothing
+        sizedArray @3 (listArray (0, 3) [1, 2, 3, 4 :: Int64]) @?= Nothing
+        sizedArrayFromList @3 [1, 2, 3, 4 :: Int64] @?= Nothing
+        -- Size 0 has the bounds (0, -1). A size above the range of Int gives
+        -- Nothing, and no size wraps into the count of the values.
+        bounds (sizedArrayToArray (fromJust (sizedArrayFromList @0 ([] :: [Int64])))) @?= (0, -1)
+        sizedArrayFromList @9223372036854775808 (error "the list spine must not be read" :: [Int64]) @?= Nothing
+        sizedArrayFromList @18446744073709551619 [1, 2, 3 :: Int64] @?= Nothing
+        sizedArray @18446744073709551619 (listArray (0, 2) [1, 2, 3 :: Int64]) @?= Nothing
+        query conn "SELECT typeof(?), ?" (values, values) >>= (@?= [("BIGINT[3]" :: Text.Text, values)])
+        _ <- execute_ conn "CREATE TABLE stored (v BIGINT[3])"
+        _ <- execute conn "INSERT INTO stored VALUES (?)" (Only values)
+        [Only stored] <- query_ conn "SELECT v FROM stored"
+        stored @?= values
+        -- A value that is read has the bounds (0, n - 1).
+        bounds (sizedArrayToArray stored) @?= (0, 2)
+        sizedArrayToArray stored ! 1 @?= (2 :: Int64)
+        -- A LIST of three elements reads, as the cast to BIGINT[3] does.
+        query_ conn "SELECT [1, 2, 3]::BIGINT[]" >>= (@?= [Only values])
+    , testCase "a SizedArray raises an error for an ARRAY or a LIST of another length" $ withConnection ":memory:" \conn -> do
+        let refused expression sqlName count =
+              try (query_ conn (Query ("SELECT " <> expression <> " AS v")) :: IO [Only (SizedArray 3 Int64)]) >>= \case
+                Left SQLError{sqlErrorMessage} ->
+                  sqlErrorMessage
+                    @?= "duckdb-simple: column v has type " <> sqlName <> " but expected SizedArray 3 Int64: the value has " <> count <> " elements"
+                Right rows -> assertFailure ("expected Incompatible for " <> Text.unpack expression <> ", got " <> show rows)
+        refused "[1, 2]::BIGINT[2]" "BIGINT[2]" "2"
+        refused "[1, 2, 3, 4]::BIGINT[4]" "BIGINT[4]" "4"
+        refused "[1, 2]::BIGINT[]" "BIGINT[]" "2"
+    , testCase "a nested SizedArray and a SizedArray of Maybe elements round-trip" $ withConnection ":memory:" \conn -> do
+        let row = fromJust . sizedArrayFromList @3
+            nested = fromJust (sizedArrayFromList @2 [row [1, 2, 3 :: Int32], row [4, 5, 6]])
+        query conn "SELECT typeof(?), ?" (nested, nested) >>= (@?= [("INTEGER[3][2]" :: Text.Text, nested)])
+        let optional = fromJust (sizedArrayFromList @3 [Just 1, Nothing, Just (3 :: Int64)])
+        query conn "SELECT typeof(?), ?" (optional, optional) >>= (@?= [("BIGINT[3]" :: Text.Text, optional)])
+    , testCase "a SizedArray of size 0 raises an error at the bind, declaration, and read" $ withConnection ":memory:" \conn -> do
+        let empty = fromJust (sizedArrayFromList @0 ([] :: [Int64]))
+        assertInputErrorContaining "an empty ARRAY parameter is not possible" (query conn "SELECT ?" (Only empty) :: IO [Only (SizedArray 0 Int64)])
+        assertInputErrorContaining "a SizedArray of size 0 has no ARRAY type" $
+          createFunction conn "sized_empty" \(_ :: SizedArray 0 Int64) -> (1 :: Int64)
+        assertSqlErrorContaining "a DuckDB ARRAY has at least one element" $
+          (query_ conn "SELECT []::BIGINT[]" :: IO [Only (SizedArray 0 Int64)])
+        assertSqlErrorContaining "a DuckDB ARRAY has at least one element" $
+          (query_ conn "SELECT [1]::BIGINT[1]" :: IO [Only (SizedArray 0 Int64)])
+        assertSqlErrorType ErrorQueryBinder $
+          (query_ conn "SELECT []::BIGINT[0]" :: IO [Only Int64])
+        runConversion
+          (duckFromTypedField (LogicalTypeList (LogicalTypeScalar LogicalTypeIdBigInt)) (FieldList []) :: Conversion (SizedArray 0 Int64))
+          >>= \case
+            Errors errors -> assertBool (show errors) ("a DuckDB ARRAY has at least one element" `Text.isInfixOf` Text.pack (show errors))
+            Ok _ -> assertFailure "expected the generic size error"
+        (query_ conn "SELECT NULL::BIGINT[]" :: IO [Only (Maybe (SizedArray 0 Int64))]) >>= (@?= [Only Nothing])
+        assertReusable conn
+    , testCase "the largest ARRAY size binds and declares, and a larger size fails at the bind, declaration, and read" $ withConnection ":memory:" \conn -> do
+        let largest = fromJust (sizedArrayFromList @100000 (replicate 100000 (1 :: Int8)))
+            above = fromJust (sizedArrayFromList @100001 (replicate 100001 (1 :: Int8)))
+        query conn "SELECT typeof(?), len(?)" (largest, largest) >>= (@?= [("TINYINT[100000]" :: Text.Text, 100000 :: Int64)])
+        createFunction conn "sized_largest" \(v :: SizedArray 100000 Int8) -> length v
+        query conn "SELECT sized_largest(?)" (Only largest) >>= (@?= [Only (100000 :: Int)])
+        -- The value API of DuckDB would bind the larger value, but its SQL has no such type.
+        assertInputErrorContaining
+          "an ARRAY parameter of 100001 elements is not possible, because a DuckDB ARRAY has at most 100000 elements"
+          (query conn "SELECT len(?)" (Only above) :: IO [Only Int64])
+        assertInputErrorContaining "a SizedArray of size 100001 has no ARRAY type, because a DuckDB ARRAY has at most 100000 elements" $
+          createFunction conn "sized_above" \(v :: SizedArray 100001 Int8) -> length v
+        assertSqlErrorContaining "a DuckDB ARRAY has at most 100000 elements" $
+          (query_ conn "SELECT range(100001)::BIGINT[]" :: IO [Only (SizedArray 100001 Int64)])
+        assertSqlErrorType ErrorQueryBinder $
+          (query_ conn "SELECT range(100001)::BIGINT[100001]" :: IO [Only Int64])
+        assertSqlErrorContaining "a DuckDB ARRAY has at most 100000 elements" $
+          (query_ conn "SELECT {'aboveValues': range(100001)::BIGINT[]}" :: IO [Only Above])
+        assertSqlErrorContaining "a DuckDB ARRAY has at most 100000 elements" $
+          (query_ conn "SELECT {'aboveValues': [1]::BIGINT[1]}" :: IO [Only Above])
+        [Only (Above optional)] <- query_ conn "SELECT {'aboveValues': NULL::BIGINT[]}"
+        optional @?= Nothing
+        assertReusable conn
+    , testCase "generic ARRAY bounds are checked for NULL, nested containers, and a Nat above Word64" $ withConnection ":memory:" \conn -> do
+        assertInputErrorContaining "a DuckDB ARRAY has at most 100000 elements" (query conn "SELECT ?" (Only (Above Nothing)) :: IO [Only Above])
+        assertInputErrorContaining
+          "a DuckDB ARRAY has at most 100000 elements"
+          (query conn "SELECT ?" (Only (Overflow Nothing)) :: IO [Only Overflow])
+        let above = Above (Just (fromJust (sizedArrayFromList @100001 (replicate 100001 (1 :: Int64)))))
+        assertInputErrorContaining "an ARRAY parameter of 100001 elements is not possible" (query conn "SELECT ?" (Only above) :: IO [Only Above])
+        assertInputErrorContaining "a DuckDB ARRAY must have 1 to 100000 elements" $
+          createFunction conn "generic_above" \(_ :: Above) -> (1 :: Int64)
+        assertInputErrorContaining "a DuckDB ARRAY must have 1 to 100000 elements" $
+          createFunction conn "generic_overflow" \(_ :: Overflow) -> (1 :: Int64)
+        assertInputErrorContaining "a DuckDB ARRAY must have 1 to 100000 elements" $
+          createFunction conn "generic_nested_above" \(_ :: NestedAbove) -> (1 :: Int64)
+        assertInputErrorContaining "a DuckDB ARRAY has at most 100000 elements" $
+          R.registerCustomType
+            conn
+            "invalid_array"
+            (StructuredType (LogicalTypeAlias "invalid_array_base" (LogicalTypeArray (LogicalTypeScalar LogicalTypeIdBigInt) 100001)))
+        case duckLogicalType (Proxy @(SizedArray 18446744073709551617 Int64)) of
+          LogicalTypeArray _ size -> size @?= maxBound
+          logical -> assertFailure ("expected an invalid ARRAY size sentinel, got " <> show logical)
+    , testCase "a list goes into an ARRAY column of its length and reads an ARRAY of each size" $ withConnection ":memory:" \conn -> do
+        _ <- execute_ conn "CREATE TABLE fixed (v BIGINT[3])"
+        _ <- execute conn "INSERT INTO fixed VALUES (?)" (Only [1, 2, 3 :: Int64])
+        query conn "SELECT count(*) FROM fixed WHERE v = ?" (Only [1, 2, 3 :: Int64]) >>= (@?= [Only (1 :: Int64)])
+        -- DuckDB casts a list of another length to the column with an error.
+        try (execute conn "INSERT INTO fixed VALUES (?)" (Only [1, 2 :: Int64])) >>= \case
+          Left SQLError{sqlErrorType, sqlErrorMessage} -> do
+            sqlErrorType @?= Just ErrorTypeConversion
+            assertBool (Text.unpack sqlErrorMessage) ("Cannot cast list with length 2 to array with length 3" `Text.isInfixOf` sqlErrorMessage)
+          Right count -> assertFailure ("expected the cast error of DuckDB, got " <> show count)
+        query_ conn "SELECT [1, 2]::BIGINT[2], [1, 2, 3]::BIGINT[3]" >>= (@?= [([1, 2], [1, 2, 3]) :: ([Int64], [Int64])])
+    , testCase "a FieldArray binds an ARRAY of a size that the program gives at run time" $ withConnection ":memory:" \conn ->
+        forM_ [1, 4, 7] \count -> do
+          let value = FieldArray (listArray (0, count - 1) (map FieldInt64 [1 .. fromIntegral count]))
+          query conn "SELECT typeof(?), len(?)" (value, value) >>= (@?= [(Text.pack ("BIGINT[" <> show count <> "]"), count)])
+    , testCase "a SizedArray field of a record declares and reads the ARRAY of its size" $ withConnection ":memory:" \conn -> do
+        let row = Sized (fromJust (sizedArrayFromList @3 [1, 2, 3]))
+        query conn "SELECT typeof(?), ?" (row, row) >>= (@?= [("STRUCT(sizedValues BIGINT[3])" :: Text.Text, row)])
+        createFunction conn "sized_field" \(Sized sized) -> sum sized
+        query conn "SELECT typeof(sized_field(?)), sized_field(?)" (row, row) >>= (@?= [("BIGINT" :: Text.Text, 6 :: Int64)])
+        try (query_ conn "SELECT {'sizedValues': [1, 2]::BIGINT[2]}" :: IO [Only Sized]) >>= \case
+          Left SQLError{sqlErrorMessage} ->
+            assertBool
+              (Text.unpack sqlErrorMessage)
+              ("has type BIGINT[2] but expected SizedArray 3: the value has 2 elements" `Text.isInfixOf` sqlErrorMessage)
+          Right rows -> assertFailure ("expected the size error, got " <> show rows)
+        try (query_ conn "SELECT {'sizedValues': ['x', 'y']::VARCHAR[]}" :: IO [Only Sized]) >>= \case
+          Left SQLError{sqlErrorMessage} ->
+            assertBool
+              (Text.unpack sqlErrorMessage)
+              ("has type VARCHAR[] but expected SizedArray 3: the value has 2 elements" `Text.isInfixOf` sqlErrorMessage)
+          Right rows -> assertFailure ("expected the size error before an element error, got " <> show rows)
+    ]
diff --git a/test/Spec.hs b/test/Spec.hs
--- a/test/Spec.hs
+++ b/test/Spec.hs
@@ -1,1258 +1,1733 @@
 {-# LANGUAGE BlockArguments #-}
-{-# LANGUAGE DeriveAnyClass #-}
-{-# LANGUAGE DeriveGeneric #-}
-{-# LANGUAGE DerivingVia #-}
-{-# LANGUAGE LambdaCase #-}
-{-# LANGUAGE NamedFieldPuns #-}
-{-# LANGUAGE OverloadedStrings #-}
-{-# LANGUAGE PatternSynonyms #-}
-{-# LANGUAGE ScopedTypeVariables #-}
-{-# LANGUAGE TypeOperators #-}
-
--- | Tasty-based test suite for duckdb-simple.
-module Main (main) where
-
-import ArrowTests (arrowTests)
-import CancellationTests (cancellationTests)
-import Control.Applicative ((<|>))
-import Control.Exception (ErrorCall, Exception, SomeException, displayException, fromException, try)
-import Control.Monad (forM_, replicateM_, when)
-import CoreRegressionTests (coreRegressionTests)
-import Data.Array (Array, elems, listArray)
-import qualified Data.ByteString as BS
-import Data.IORef (atomicModifyIORef', newIORef, readIORef)
-import Data.Int (Int16, Int32, Int64, Int8)
-import Data.List (sortOn)
-import qualified Data.Map.Strict as Map
-import Data.Maybe (fromJust)
-import Data.Proxy (Proxy (..))
-import Data.Ratio ((%))
-import Data.String (fromString)
-import qualified Data.Text as Text
-import Data.Time.Calendar (fromGregorian)
-import Data.Time.Clock (UTCTime (..), secondsToDiffTime)
-import Data.Time.LocalTime (
-    LocalTime (..),
-    TimeOfDay (..),
-    localTimeToUTC,
-    minutesToTimeZone,
-    timeOfDayToTime,
-    utc,
- )
-import qualified Data.UUID as UUID
-import Data.Word (Word16, Word32, Word64, Word8)
-import Database.DuckDB.FFI (
-    pattern DuckDBCatalogEntryTypeTable,
-    pattern DuckDBFileFlagCreate,
-    pattern DuckDBFileFlagRead,
-    pattern DuckDBFileFlagWrite,
- )
-import Database.DuckDB.Simple
-import qualified Database.DuckDB.Simple.Catalog as Catalog
-import qualified Database.DuckDB.Simple.Config as Config
-import qualified Database.DuckDB.Simple.Copy as Copy
-import qualified Database.DuckDB.Simple.FileSystem as FileSystem
-import Database.DuckDB.Simple.FromField (
-    BigNum (..),
-    BitString (..),
-    DecimalValue (..),
-    Field (..),
-    FieldValue (..),
-    IntervalValue (..),
-    TimeWithZone (..),
-    bsFromBool,
-    fromBigNumBytes,
-    returnError,
-    toBigNumBytes,
- )
-import Database.DuckDB.Simple.Generic (
-    ViaDuckDB (..),
-    genericFromFieldValue,
-    genericToFieldValue,
-    genericToStructValue,
- )
-import qualified Database.DuckDB.Simple.Logging as Logging
-import Database.DuckDB.Simple.LogicalRep (
-    StructField (..),
-    StructValue (..),
-    UnionMemberType (..),
-    UnionValue (..),
- )
-import Database.DuckDB.Simple.Ok (Ok (..))
-import Database.DuckDB.Simple.Time (Unbounded (..))
-import ExtensionRegressionTests (extensionRegressionTests)
-import GHC.Generics (Generic)
-import qualified GeometryRegressionTests
-import Numeric.Natural (Natural)
-import Properties (roundTripTests)
-import StreamingTests (nativeStreamingTests)
-import System.Directory (doesFileExist, removeFile)
-import Test.Tasty (TestTree, defaultMain, testGroup)
-import Test.Tasty.ExpectedFailure (expectFailBecause)
-import Test.Tasty.HUnit
-import Test.Tasty.QuickCheck (testProperty, (===))
-import TimeTests (timeTests)
-import ValueRegressionTests (valueRegressionTests)
-import qualified VariantRegressionTests
-
-data Person = Person
-    { personId :: Int
-    , personName :: Text.Text
-    }
-    deriving stock (Eq, Show, Generic)
-    deriving anyclass (FromRow)
-
-data WithRemaining = WithRemaining Int Int
-    deriving (Eq, Show)
-
-data GenericRecord = GenericRecord
-    { grId :: Int
-    , grName :: Text.Text
-    }
-    deriving stock (Eq, Show, Generic)
-
-data GenericSum
-    = SumInt Int
-    | SumBool Bool
-    | SumPair Int Text.Text
-    deriving stock (Eq, Show, Generic)
-
-data GenericEnum
-    = EnumRed
-    | EnumBlue
-    deriving stock (Eq, Show, Generic)
-
-data ViaUser = ViaUser
-    { vuId :: Int64
-    , vuName :: Text.Text
-    }
-    deriving stock (Eq, Show, Generic)
-    deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB ViaUser)
-
-data ViaShape
-    = ViaCircle Double
-    | ViaSquare Double
-    deriving stock (Eq, Show, Generic)
-    deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB ViaShape)
-
--- Edge case test types
-data TwoFieldStruct = TwoFieldStruct Int Text.Text
-    deriving stock (Eq, Show, Generic)
-
-data LargeSumType
-    = LargeC1 Int
-    | LargeC2 Int
-    | LargeC3 Int
-    | LargeC4 Int
-    | LargeC5 Int
-    deriving stock (Eq, Show, Generic)
-    deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB LargeSumType)
-
-data EmptyStruct = EmptyStruct
-    deriving stock (Eq, Show, Generic)
-    deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB EmptyStruct)
-
-data OptionalFields = OptionalFields
-    { ofInt :: Maybe Int
-    , ofText :: Maybe Text.Text
-    }
-    deriving stock (Eq, Show, Generic)
-    deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB OptionalFields)
-
-instance FromRow WithRemaining where
-    fromRow = do
-        firstVal <- field
-        remaining <- numFieldsRemaining
-        replicateM_ remaining (fieldWith (const (Ok ())))
-        pure (WithRemaining firstVal remaining)
-
-newtype YesNo = YesNo Bool
-    deriving (Eq, Show)
-
-instance FromRow YesNo where
-    fromRow = parseYes <|> parseNo
-      where
-        parseYes = YesNo True <$ fieldWith (match (Text.pack "yes"))
-        parseNo = YesNo False <$ fieldWith (match (Text.pack "no"))
-
-        match expected fld@Field{} =
-            case fromField fld :: Ok Text.Text of
-                Errors err -> Errors err
-                Ok txt ->
-                    let normalized = Text.toLower txt
-                     in if normalized == expected
-                            then Ok ()
-                            else returnError ConversionFailed fld "failed to match exact string"
-
-newtype NonEmptyText = NonEmptyText Text.Text
-    deriving (Eq, Show)
-
-nonEmptyTextParser :: FieldParser NonEmptyText
-nonEmptyTextParser f@Field{} =
-    case fromField f of
-        Errors err -> Errors err
-        Ok txt
-            | Text.null txt ->
-                returnError ConversionFailed f "NonEmptyText requires a non-empty string"
-            | otherwise -> Ok (NonEmptyText txt)
-
-instance FromField NonEmptyText where
-    fromField = nonEmptyTextParser
-main :: IO ()
-main = defaultMain tests
-
-tests :: TestTree
-tests =
-    testGroup
-        "duckdb-simple"
-        [ connectionTests
-        , coreRegressionTests
-        , arrowTests
-        , cancellationTests
-        , nativeStreamingTests
-        , extensionRegressionTests
-        , GeometryRegressionTests.tests
-        , VariantRegressionTests.tests
-        , valueRegressionTests
-        , timeTests
-        , withConnectionTests
-        , statementTests
-        , roundTripTests
-        , typeTests
-        , streamingTests
-        , functionsTests
-        , v15Tests
-        , transactionTests
-        ]
-
-connectionTests :: TestTree
-connectionTests =
-    testGroup
-        "open/close"
-        [ testCase "opens and closes an in-memory database" $ do
-            conn <- open ":memory:"
-            close conn
-        , testCase "allows closing the same connection twice" $ do
-            conn <- open ":memory:"
-            close conn
-            close conn
-        , testCase "opens with startup config" $ do
-            conn <- openWithConfig ":memory:" [("threads", "1")]
-            mValue <- Config.getConfigOption conn "threads"
-            close conn
-            case mValue of
-                Nothing -> assertFailure "expected threads config value"
-                Just value -> Config.configValueText value @?= "1"
-        ]
-
-v15Tests :: TestTree
-v15Tests =
-    testGroup
-        "DuckDB 1.5 wrappers"
-        [ testCase "lists config flags" $ do
-            flags <- Config.listConfigFlags
-            assertBool "expected at least one config flag" (not (null flags))
-            assertBool "expected threads flag" (any ((== "threads") . Config.configFlagName) flags)
-        , testCase "catalog lookup works inside a transaction" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE catalog_probe(id INTEGER)"
-                withTransaction conn $ do
-                    mType <- Catalog.catalogTypeName conn "memory"
-                    assertBool "expected catalog type name" (mType /= Nothing)
-                    mEntry <- Catalog.lookupCatalogEntry conn "memory" "main" "catalog_probe" DuckDBCatalogEntryTypeTable
-                    case mEntry of
-                        Nothing -> assertFailure "expected catalog entry"
-                        Just entry -> Catalog.catalogEntryName entry @?= "catalog_probe"
-        , testCase "file system wrappers round-trip bytes" $ do
-            let path = "/tmp/duckdb-simple-filesystem.bin"
-                payload = BS.pack [0, 1, 2, 3, 255]
-            exists <- doesFileExist path
-            when exists (removeFile path)
-            withConnection ":memory:" \conn -> do
-                FileSystem.withFileHandle conn path [DuckDBFileFlagCreate, DuckDBFileFlagWrite] \handle -> do
-                    written <- FileSystem.writeFileHandleBytes handle payload
-                    written @?= fromIntegral (BS.length payload)
-                    FileSystem.fileHandleSync handle
-                FileSystem.withFileHandle conn path [DuckDBFileFlagRead] \handle -> do
-                    size <- FileSystem.fileHandleSize handle
-                    size @?= fromIntegral (BS.length payload)
-                    bytes <- FileSystem.readFileHandleChunk handle 32
-                    bytes @?= payload
-            removeFile path
-        , testCase "copy wrappers receive COPY TO rows" $
-            withConnection ":memory:" \conn -> do
-                capturedRef <- newIORef ([] :: [Int])
-                pathRef <- newIORef Nothing
-                Copy.registerCopyToFunction
-                    conn
-                    "hs_capture"
-                    (\bindInfo -> pure (length (Copy.copyBindColumnTypes bindInfo)))
-                    ( \initInfo -> do
-                        atomicModifyIORef' pathRef \_ -> (Just (Copy.copyInitFilePath initInfo), ())
-                        pure (Copy.copyInitBindState initInfo)
-                    )
-                    ( \sinkInfo rows -> do
-                        Copy.copySinkBindState sinkInfo @?= 1
-                        Copy.copySinkGlobalState sinkInfo @?= 1
-                        values <- mapM fieldInt rows
-                        atomicModifyIORef' capturedRef \existing -> (existing <> values, ())
-                    )
-                    ( \finalizeInfo -> do
-                        Copy.copyFinalizeBindState finalizeInfo @?= 1
-                        Copy.copyFinalizeGlobalState finalizeInfo @?= 1
-                    )
-                _ <- execute_ conn "COPY (SELECT * FROM (VALUES (1), (2), (3)) AS t(x)) TO '/tmp/duckdb-simple-copy.out' (FORMAT hs_capture)"
-                captured <- readIORef capturedRef
-                filePath <- readIORef pathRef
-                captured @?= [1, 2, 3]
-                filePath @?= Just "/tmp/duckdb-simple-copy.out"
-        , testCase "logging wrapper registers a log sink" $
-            withConnection ":memory:" \conn -> do
-                entriesRef <- newIORef ([] :: [Logging.LogEntry])
-                Logging.registerLogStorage conn "hs_log_capture" \entry ->
-                    atomicModifyIORef' entriesRef \entries -> (entry : entries, ())
-                _ <- execute_ conn "SELECT write_log('duckdb-simple logging wrapper', level := 'INFO', scope := 'connection')"
-                _ <- readIORef entriesRef
-                pure ()
-        ]
-
-fieldInt :: [Field] -> IO Int
-fieldInt [fld] =
-    case fromField fld of
-        Errors err -> assertFailure (show err) >> pure 0
-        Ok value -> pure value
-fieldInt fields = assertFailure ("expected one field, got " <> show (length fields)) >> pure 0
-
-withConnectionTests :: TestTree
-withConnectionTests =
-    testGroup
-        "withConnection"
-        [ testCase "returns the action result" $ do
-            result <- withConnection ":memory:" \_ -> pure (21 :: Int)
-            assertEqual "action result" 21 result
-        , testCase "propagates exceptions from the action"
-            $ assertThrowsErrorCall
-            $ withConnection ":memory:" (\_ -> error "boom" :: IO ())
-        ]
-
-statementTests :: TestTree
-statementTests =
-    testGroup
-        "statements"
-        [ testCase "prepares and closes a simple statement" $
-            withConnection ":memory:" \conn -> do
-                stmt <- openStatement conn "SELECT 42"
-                closeStatement stmt
-        , testCase "allows closing a statement twice" $
-            withConnection ":memory:" \conn -> do
-                stmt <- openStatement conn "SELECT 1"
-                closeStatement stmt
-                closeStatement stmt
-        , testCase "rejects preparing statements on a closed connection" $ do
-            conn <- open ":memory:"
-            close conn
-            assertThrowsSQLError $
-                openStatement conn "SELECT 1"
-        , testCase "throws SQLError for invalid SQL" $
-            withConnection ":memory:" \conn ->
-                assertThrowsSQLError $
-                    openStatement conn "THIS IS NOT VALID SQL"
-        , testCase "withStatement closes the statement automatically" $
-            withConnection ":memory:" \conn -> do
-                result <- withStatement conn "SELECT 1" \_ -> pure ("done" :: String)
-                assertEqual "withStatement result" "done" result
-        , testCase "withStatement closes statements even when the action fails" $
-            withConnection ":memory:" \conn -> do
-                assertThrowsErrorCall $
-                    withStatement conn "SELECT 1" (\_ -> error "boom" :: IO ())
-                stmt <- openStatement conn "SELECT 1"
-                closeStatement stmt
-        , testCase "execute returns affected row count" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE test_exec (x INTEGER)"
-                count <- execute conn "INSERT INTO test_exec VALUES (?)" (Only (1 :: Int))
-                assertEqual "rows affected" 1 count
-        , testCase "execute runs with positional parameters" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE exec_params (a INTEGER, b TEXT)"
-                count <- execute conn "INSERT INTO exec_params VALUES (?, ?)" (5 :: Int, "hi" :: String)
-                assertEqual "rows affected" 1 count
-        , testCase "rejects invalid direct execution" $
-            withConnection ":memory:" \conn ->
-                assertThrowsSQLError $
-                    execute_ conn "THIS IS NOT SQL"
-        , testCase "binds positional parameters" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE params (a INTEGER, b TEXT)"
-                withStatement conn "INSERT INTO params VALUES (?, ?)" \stmt -> do
-                    bind stmt [toField (5 :: Int), toField ("hi" :: String)]
-                    changed <- executeStatement stmt
-                    assertEqual "rows affected" 1 changed
-        , testCase "executeMany reuses prepared statements" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE params_many (a INTEGER, b TEXT)"
-                total <- executeMany conn "INSERT INTO params_many VALUES (?, ?)" [(1 :: Int, "x" :: String), (2 :: Int, "y" :: String)]
-                assertEqual "rows affected" 2 total
-        , testCase "executeNamed binds named parameters" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE named_params (a INTEGER, b TEXT)"
-                count <- executeNamed conn "INSERT INTO named_params VALUES ($a, $b)" ["$a" := (1 :: Int), "$b" := ("named" :: String)]
-                assertEqual "rows affected" 1 count
-                rows <- queryNamed conn "SELECT a FROM named_params WHERE b = $label" ["$label" := ("named" :: String)]
-                assertEqual "named query" [Only (1 :: Int)] rows
-        , testCase "rejects incorrect positional argument counts" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE param_count (a INTEGER, b INTEGER)"
-                assertThrowsFormatError
-                    (execute conn "INSERT INTO param_count VALUES (?, ?)" (Only (1 :: Int)))
-                    (Text.isInfixOf "parameter(s)" . formatErrorMessage)
-        , testCase "rejects positional bindings on named statements" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE mixed_mode (a INTEGER)"
-                assertThrowsFormatError
-                    (execute conn "INSERT INTO mixed_mode VALUES ($a)" (Only (1 :: Int)))
-                    (Text.isInfixOf "named parameters" . formatErrorMessage)
-        , testCase "reports error when mixing positional and named parameters" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE mixed_params (a INTEGER, b TEXT)"
-                assertThrows
-                    ( withStatement conn "INSERT INTO mixed_params VALUES (?, $label)" \stmt -> do
-                        bind stmt [toField (1 :: Int)]
-                        bindNamed stmt ["$label" := ("combo" :: String)]
-                        _ <- executeStatement stmt
-                        pure ()
-                    )
-                    ( \(err :: SQLError) ->
-                        Text.isInfixOf "Mixing named and positional parameters" (sqlErrorMessage err)
-                    )
-        , testCase "generic FromRow derivation works" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE person (id INTEGER, name TEXT)"
-                _ <- executeMany conn "INSERT INTO person VALUES (?, ?)" [(1 :: Int, "Alice" :: String), (2 :: Int, "Bob" :: String)]
-                people <- query_ conn "SELECT id, name FROM person ORDER BY id" :: IO [Person]
-                assertEqual "person rows" [Person 1 (Text.pack "Alice"), Person 2 (Text.pack "Bob")] people
-        , testCase "(:.) composes row parsing and parameter encoding" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE dot_pair (a INTEGER, b INTEGER, label TEXT)"
-                let payload = Only (7 :: Int) :. (8 :: Int, Text.pack "hi")
-                _ <- execute conn "INSERT INTO dot_pair VALUES (?, ?, ?)" payload
-                rows <- query_ conn "SELECT a, b, label FROM dot_pair" :: IO [Only Int :. (Int, Text.Text)]
-                case rows of
-                    [Only a :. (b, label)] -> do
-                        assertEqual "(:.) first" 7 a
-                        assertEqual "(:.) second" 8 b
-                        assertEqual "(:.) label" (Text.pack "hi") label
-                    other -> assertFailure ("unexpected (:.) rows: " <> show other)
-        , testCase "query_ fetches rows" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE query_rows (a INTEGER, b TEXT)"
-                _ <- executeMany conn "INSERT INTO query_rows VALUES (?, ?)" [(1 :: Int, "x" :: String), (2 :: Int, "y" :: String)]
-                rows <- query_ conn "SELECT a, b FROM query_rows ORDER BY a"
-                assertEqual "query rows" [(1 :: Int, "x" :: String), (2 :: Int, "y" :: String)] rows
-        , testCase "query decodes NULL as Maybe" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE maybe_vals (a TEXT)"
-                _ <- execute conn "INSERT INTO maybe_vals VALUES (?)" (Only (Just ("present" :: String)))
-                _ <- execute conn "INSERT INTO maybe_vals VALUES (?)" (Only (Nothing :: Maybe String))
-                rows <- query_ conn "SELECT a FROM maybe_vals ORDER BY a IS NULL, a"
-                assertEqual "maybe decoding" [Only (Just ("present" :: String)), Only Nothing] rows
-        , testCase "query fetches rows with parameters" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE query_params (a INTEGER, b TEXT)"
-                _ <- executeMany conn "INSERT INTO query_params VALUES (?, ?)" [(1 :: Int, "x" :: String), (2 :: Int, "y" :: String)]
-                rows <- query conn "SELECT a FROM query_params WHERE b = ?" (Only ("y" :: String))
-                assertEqual "query result" [Only (2 :: Int)] rows
-        , testCase "column mismatch surfaces as SQLError" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE mismatch (a INTEGER, b INTEGER)"
-                _ <- execute_ conn "INSERT INTO mismatch VALUES (1, 2)"
-                assertThrows
-                    (query_ conn "SELECT a, b FROM mismatch" :: IO [Only Int])
-                    (Text.isInfixOf "column index" . sqlErrorMessage)
-        , testCase "clears statement bindings without error" $
-            withConnection ":memory:" \conn -> do
-                stmt <- openStatement conn "SELECT ?"
-                clearStatementBindings stmt
-                closeStatement stmt
-        , testCase "resolves named parameter indices" $
-            withConnection ":memory:" \conn -> do
-                stmt <- openStatement conn "SELECT $named_param"
-                idx <- namedParameterIndex stmt "named_param"
-                assertEqual "named parameter index" (Just 1) idx
-                idxWithPrefix <- namedParameterIndex stmt "$named_param"
-                assertEqual "named parameter index with prefix" (Just 1) idxWithPrefix
-                colonIdx <- namedParameterIndex stmt ":named_param"
-                assertEqual "named parameter index with colon" (Just 1) colonIdx
-                none <- namedParameterIndex stmt "missing"
-                assertEqual "missing parameter index" Nothing none
-                closeStatement stmt
-        , testCase "reports column metadata for statements" $
-            withConnection ":memory:" \conn -> do
-                stmt <- openStatement conn "SELECT 1 AS a, 2 AS b"
-                count <- columnCount stmt
-                assertEqual "column count" 2 count
-                name0 <- columnName stmt 0
-                name1 <- columnName stmt 1
-                assertEqual "column names" [Text.pack "a", Text.pack "b"] [name0, name1]
-                assertThrows
-                    (columnName stmt 2)
-                    (Text.isInfixOf "out of bounds" . sqlErrorMessage)
-                closeStatement stmt
-        , testCase "bindNamed rejects statements without named placeholders" $
-            withConnection ":memory:" \conn -> do
-                stmt <- openStatement conn "SELECT ?"
-                assertThrowsFormatError
-                    (bindNamed stmt [":value" := (1 :: Int)])
-                    (Text.isInfixOf "does not define named parameters" . formatErrorMessage)
-                closeStatement stmt
-        , testCase "bindNamed rejects unknown parameters" $
-            withConnection ":memory:" \conn -> do
-                stmt <- openStatement conn "SELECT $known"
-                assertThrowsFormatError
-                    (bindNamed stmt ["$missing" := (1 :: Int)])
-                    (Text.isInfixOf "unknown named parameter" . formatErrorMessage)
-                closeStatement stmt
-        , testCase "numFieldsRemaining reports remaining columns" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE remaining (a INTEGER, b INTEGER, c INTEGER)"
-                _ <- execute conn "INSERT INTO remaining VALUES (?, ?, ?)" (1 :: Int, 2 :: Int, 3 :: Int)
-                rows <- query_ conn "SELECT a, b, c FROM remaining" :: IO [WithRemaining]
-                assertEqual "remaining count" [WithRemaining 1 2] rows
-        , testCase "RowParser alternatives fall back" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE yesno (answer TEXT)"
-                _ <- executeMany conn "INSERT INTO yesno VALUES (?)" [Only ("yes" :: String), Only ("no" :: String)]
-                rows <- query_ conn "SELECT answer FROM yesno ORDER BY answer" :: IO [YesNo]
-                assertEqual "yes/no parsing" [YesNo False, YesNo True] rows
-        ]
-
-data DuckDBExpectation
-    = ExpectEquals FieldValue
-    | ExpectSatisfies (FieldValue -> Assertion)
-    | ExpectException (SomeException -> Assertion)
-
-data DuckDBExpression
-    = CastExpression Text.Text Text.Text
-    | DirectExpression Text.Text
-
-data DuckDBCastCase = DuckDBCastCase
-    { castLabel :: String
-    , castExpression :: DuckDBExpression
-    , castExpectation :: DuckDBExpectation
-    , castExpectFailureReason :: Maybe String
-    }
-
-duckdbTypeCastTests :: TestTree
-duckdbTypeCastTests =
-    testGroup
-        "duckdb type casts"
-        (map buildCase duckdbCastCases)
-  where
-    buildCase DuckDBCastCase{castLabel, castExpression, castExpectation, castExpectFailureReason} =
-        let base =
-                testCase castLabel $
-                    withConnection ":memory:" \conn -> do
-                        let sql =
-                                Query
-                                    ( case castExpression of
-                                        CastExpression expressionValue expressionType ->
-                                            Text.concat ["SELECT CAST(", expressionValue, " AS ", expressionType, ")"]
-                                        DirectExpression expressionSQL ->
-                                            Text.concat ["SELECT ", expressionSQL]
-                                    )
-                        result <- try (query_ conn sql) :: IO (Either SomeException [Only FieldValue])
-                        runExpectation castLabel castExpectation result
-                        maybe (pure ()) assertFailure castExpectFailureReason
-         in maybe base (`expectFailBecause` base) castExpectFailureReason
-
-runExpectation :: String -> DuckDBExpectation -> Either SomeException [Only FieldValue] -> Assertion
-runExpectation label expectation outcome =
-    case expectation of
-        ExpectEquals expected ->
-            case outcome of
-                Right [Only fieldValue] ->
-                    assertEqual (label <> " result mismatch") expected fieldValue
-                Right other ->
-                    assertFailure (label <> " expected single row, got " <> show other)
-                Left err ->
-                    assertFailure (label <> " expected success, but query failed: " <> displayException err)
-        ExpectSatisfies predicate ->
-            case outcome of
-                Right [Only fieldValue] ->
-                    predicate fieldValue
-                Right other ->
-                    assertFailure (label <> " expected single row, got " <> show other)
-                Left err ->
-                    assertFailure (label <> " expected success, but query failed: " <> displayException err)
-        ExpectException predicate ->
-            case outcome of
-                Left err ->
-                    predicate err
-                Right rows ->
-                    assertFailure (label <> " expected failure, but query succeeded with " <> show rows)
-
-duckdbCastCases :: [DuckDBCastCase]
-duckdbCastCases =
-    [ successCase "BOOLEAN" (quoted "true") "BOOLEAN" (ExpectEquals (FieldBool True))
-    , successCase "TINYINT" (quotedValue tinyIntValue) "TINYINT" (ExpectEquals (FieldInt8 tinyIntValue))
-    , successCase "SMALLINT" (quotedValue smallIntValue) "SMALLINT" (ExpectEquals (FieldInt16 smallIntValue))
-    , successCase "INTEGER" (quotedValue intValue) "INTEGER" (ExpectEquals (FieldInt32 intValue))
-    , successCase "BIGINT" (quotedValue bigIntValue) "BIGINT" (ExpectEquals (FieldInt64 bigIntValue))
-    , successCase "UTINYINT" (quotedValue uTinyValue) "UTINYINT" (ExpectEquals (FieldWord8 uTinyValue))
-    , successCase "USMALLINT" (quotedValue uSmallValue) "USMALLINT" (ExpectEquals (FieldWord16 uSmallValue))
-    , successCase "UINTEGER" (quotedValue uIntValue) "UINTEGER" (ExpectEquals (FieldWord32 uIntValue))
-    , successCase "UBIGINT" (quotedValue uBigValue) "UBIGINT" (ExpectEquals (FieldWord64 uBigValue))
-    , successCase "FLOAT" (quoted "3.25") "FLOAT" (ExpectEquals (FieldFloat floatValue))
-    , successCase "DOUBLE" (quoted "2.5") "DOUBLE" (ExpectEquals (FieldDouble doubleValue))
-    , successCase "TIMESTAMP" (quoted "2024-01-02 03:04:05.123456") "TIMESTAMP" (ExpectEquals (FieldTimestamp (Finite timestampLocalTimeMicros)))
-    , successCase "DATE" (quoted "2024-10-12") "DATE" (ExpectEquals (FieldDate (Finite dateValue)))
-    , successCase "TIME" (quoted "14:30:15.123456") "TIME" (ExpectEquals (FieldTime timeValue))
-    , successCase "INTERVAL" (quoted "1 day") "INTERVAL" (ExpectEquals (FieldInterval intervalValue))
-    , successCase "HUGEINT" (quotedValue hugeIntLiteral) "HUGEINT" (ExpectEquals (FieldHugeInt hugeIntLiteral))
-    , successCase "UHUGEINT" (quotedValue uHugeIntLiteral) "UHUGEINT" (ExpectEquals (FieldUHugeInt uHugeIntLiteral))
-    , successCase "VARCHAR" (quoted varcharText) "VARCHAR" (ExpectEquals (FieldText varcharText))
-    , successCase "BLOB" (quoted "duckdb") "BLOB" (ExpectEquals (FieldBlob blobValue))
-    , successCase "DECIMAL" (quoted "12345.6789") "DECIMAL(18,4)" (ExpectEquals (FieldDecimal decimalValue))
-    , successCase "TIMESTAMP_S" (quoted "2024-01-02 03:04:05") "TIMESTAMP_S" (ExpectEquals (FieldTimestamp (Finite timestampLocalTimeSeconds)))
-    , successCase "TIMESTAMP_MS" (quoted "2024-01-02 03:04:05.123") "TIMESTAMP_MS" (ExpectEquals (FieldTimestamp (Finite timestampLocalTimeMillis)))
-    , successCase "TIMESTAMP_NS" (quoted "2024-01-02 03:04:05.123456789") "TIMESTAMP_NS" (ExpectEquals (FieldTimestamp (Finite timestampLocalTimeNanos)))
-    , successCase "ENUM" (quoted "beta") "ENUM('alpha','beta')" (ExpectEquals (FieldEnum 1))
-    , successCase "LIST" (quoted "[1,2,3]") "INTEGER[]" (ExpectEquals (FieldList listElements))
-    , successDirect "MAP" "MAP(['a','b'], [1,2])" (expectMapEntries mapPairs)
-    , successCase "TIMETZ" (quoted "03:04:05+02:30") "TIME WITH TIME ZONE" (ExpectEquals (FieldTimeTZ timeWithZoneValue))
-    , successCase "TIMESTAMPTZ" (quoted "2024-01-02 03:04:05+02:30") "TIMESTAMP WITH TIME ZONE" (ExpectEquals (FieldTimestampTZ (Finite timestampTzUtc)))
-    , successCase "BIGNUM" (quoted bigNumLiteralText) "BIGNUM" (ExpectEquals (FieldBigNum (BigNum bigNumLiteral)))
-    , successCase "UUID" (quoted $ UUID.toText uuid) "UUID" (ExpectEquals (FieldUUID uuid))
-    , successCase "BIT" (quoted $ Text.pack $ show bits) "BIT" (ExpectEquals (FieldBit bits))
-    , successCase "ARRAY" (quoted "[1,2,3]") "INTEGER[3]" (ExpectEquals (FieldArray arrayElements))
-    , -- This one is broken upstream, instead of a DuckDBTypeTimeNs, we get a DuckDBType 0
-      successCase "TIME_NS" (quoted "03:04:05.123456789") "TIME_NS" (ExpectEquals (FieldTime (TimeOfDay 3 4 5.123456789)))
-    , successDirect "STRUCT" "{'a': 1, 'b': 2}" (expectStruct structFields)
-    , successDirect "UNION" "CAST(union_value(a := 42) AS UNION(a INTEGER, b VARCHAR))" (expectUnion 0 (Text.pack "a") (FieldInt32 42))
-    , -- These can never surface from a query, only internally.
-      failCaseOK "ANY" (quoted "1") "ANY" (expectSQLErrorContaining "ANY")
-    , failCaseOK "STRING_LITERAL" (quoted literalText) "STRING_LITERAL" (expectSQLErrorContaining "STRING_LITERAL")
-    , failCaseOK "INTEGER_LITERAL" (quoted "123") "INTEGER_LITERAL" (expectSQLErrorContaining "INTEGER_LITERAL")
-    , failCaseOK "INVALID" "0" "INVALID" (expectSQLErrorContaining "INVALID")
-    , failCaseOK "SQLNULL" "NULL" "SQLNULL" (expectSQLErrorContaining "SQLNULL")
-    ]
-  where
-    bits = BitString 7 $ BS.pack [1, 255]
-    quoted t = Text.concat ["'", t, "'"]
-    quotedValue v = quoted (valueText v)
-    valueText :: (Show a) => a -> Text.Text
-    valueText = Text.pack . show
-    successCase label value ty expectation =
-        DuckDBCastCase
-            { castLabel = label
-            , castExpression = CastExpression value ty
-            , castExpectation = expectation
-            , castExpectFailureReason = Nothing
-            }
-    successDirect label expr expectation =
-        DuckDBCastCase
-            { castLabel = label
-            , castExpression = DirectExpression expr
-            , castExpectation = expectation
-            , castExpectFailureReason = Nothing
-            }
-    failCaseOK label value ty expectation =
-        DuckDBCastCase
-            { castLabel = label
-            , castExpression = CastExpression value ty
-            , castExpectation = expectation
-            , castExpectFailureReason = Nothing
-            }
-    expectMapEntries expectedPairs =
-        ExpectSatisfies $
-            \case
-                FieldMap actualPairs ->
-                    let normalize = sortOn (mapKey . fst)
-                        mapKey (FieldText txt) = txt
-                        mapKey other = Text.pack (show other)
-                     in assertEqual "map entries" (normalize expectedPairs) (normalize actualPairs)
-                other ->
-                    assertFailure ("expected FieldMap, but saw " <> show other)
-    structFields =
-        [ StructField{structFieldName = Text.pack "a", structFieldValue = FieldInt32 1}
-        , StructField{structFieldName = Text.pack "b", structFieldValue = FieldInt32 2}
-        ]
-    expectStruct expectedFields =
-        ExpectSatisfies $
-            \case
-                FieldStruct StructValue{structValueFields, structValueTypes, structValueIndex} -> do
-                    let actualFields = elems structValueFields
-                        actualTypes = elems structValueTypes
-                        expectedIndex = Map.fromList (zip (map structFieldName expectedFields) [0 ..])
-                        typeNames = map structFieldName actualTypes
-                    assertEqual "struct field names" (map structFieldName expectedFields) (map structFieldName actualFields)
-                    assertEqual "struct field values" (map structFieldValue expectedFields) (map structFieldValue actualFields)
-                    assertEqual "struct type field names" (map structFieldName expectedFields) typeNames
-                    assertEqual "struct index map" expectedIndex structValueIndex
-                other ->
-                    assertFailure ("expected FieldStruct, but saw " <> show other)
-    expectUnion expectedIndex expectedLabel expectedPayload =
-        ExpectSatisfies $
-            \case
-                FieldUnion UnionValue{unionValueIndex, unionValueLabel, unionValuePayload, unionValueMembers} -> do
-                    assertEqual "union tag index" expectedIndex unionValueIndex
-                    assertEqual "union tag label" expectedLabel unionValueLabel
-                    assertEqual "union payload" expectedPayload unionValuePayload
-                    let actualMembers = elems unionValueMembers
-                        expectedMembers = [Text.pack "a", Text.pack "b"]
-                    assertEqual "union member names" expectedMembers (map unionMemberName actualMembers)
-                other ->
-                    assertFailure ("expected FieldUnion, but saw " <> show other)
-    expectSQLErrorContaining :: Text.Text -> DuckDBExpectation
-    expectSQLErrorContaining needle =
-        ExpectException $ \err ->
-            case fromException err :: Maybe SQLError of
-                Just sqlErr ->
-                    let message = sqlErrorMessage sqlErr
-                     in assertBool
-                            ("expected SQLError containing " <> Text.unpack needle <> ", but saw: " <> Text.unpack message)
-                            (Text.isInfixOf needle message)
-                Nothing ->
-                    assertFailure ("expected SQLError, but saw " <> displayException err)
-    bsFromString :: String -> BS.ByteString
-    bsFromString = BS.pack . map (fromIntegral . fromEnum)
-    secondsWithFraction :: Integer -> Integer -> Integer -> Rational
-    secondsWithFraction whole numerator denominator =
-        fromIntegral whole + numerator % denominator
-    tinyIntValue :: Int8
-    tinyIntValue = 42
-    smallIntValue :: Int16
-    smallIntValue = 32000
-    intValue :: Int32
-    intValue = 2147483647
-    bigIntValue :: Int64
-    bigIntValue = 9223372036854775807
-    uTinyValue :: Word8
-    uTinyValue = 200
-    uSmallValue :: Word16
-    uSmallValue = 60000
-    uIntValue :: Word32
-    uIntValue = maxBound
-    uBigValue :: Word64
-    uBigValue = maxBound
-    floatValue :: Float
-    floatValue = 3.25
-    doubleValue :: Double
-    doubleValue = 2.5
-    timestampDay = fromGregorian 2024 1 2
-    timestampLocalTimeMicros =
-        LocalTime timestampDay (TimeOfDay 3 4 (fromRational (secondsWithFraction 5 123456 1000000)))
-    timestampLocalTimeSeconds =
-        LocalTime timestampDay (TimeOfDay 3 4 5)
-    timestampLocalTimeMillis =
-        LocalTime timestampDay (TimeOfDay 3 4 (fromRational (secondsWithFraction 5 123 1000)))
-    timestampLocalTimeNanos =
-        LocalTime timestampDay (TimeOfDay 3 4 (fromRational (secondsWithFraction 5 123456789 1000000000)))
-    dateValue = fromGregorian 2024 10 12
-    timeValue =
-        TimeOfDay 14 30 (fromRational (secondsWithFraction 15 123456 1000000))
-    intervalValue =
-        IntervalValue{intervalMonths = 0, intervalDays = 1, intervalMicros = 0}
-    decimalValue =
-        DecimalValue{decimalWidth = 18, decimalScale = 4, decimalInteger = 123456789}
-    listElements =
-        [FieldInt32 1, FieldInt32 2, FieldInt32 3]
-    arrayElements =
-        listArray (0, 2) listElements
-    mapPairs =
-        [ (FieldText (Text.pack "a"), FieldInt32 1)
-        , (FieldText (Text.pack "b"), FieldInt32 2)
-        ]
-    uuid :: UUID.UUID
-    uuid = fromJust $ UUID.fromText "123e4567-e89b-12d3-a456-426614174000"
-    timeWithZoneValue =
-        TimeWithZone{timeWithZoneTime = TimeOfDay 3 4 5, timeWithZoneZone = minutesToTimeZone 150}
-    timestampTzUtc =
-        UTCTime timestampDay (secondsToDiffTime 2045)
-    bigNumLiteral :: Integer
-    bigNumLiteral = 1234567890123456789012345678901234567890
-    bigNumLiteralText = valueText bigNumLiteral
-    varcharText :: Text.Text
-    varcharText = "Hello, DuckDB"
-    blobValue = bsFromString "duckdb"
-    hugeIntLiteral :: Integer
-    hugeIntLiteral = (2 ^ (120 :: Int)) + 123456789
-    uHugeIntLiteral :: Integer
-    uHugeIntLiteral = (2 ^ (128 :: Int)) - 1
-    literalText :: Text.Text
-    literalText = "literal"
-
-typeTests :: TestTree
-typeTests =
-    testGroup
-        "types"
-        [ duckdbTypeCastTests
-        , testCase "round-trips date/time/timestamp" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE temporals (d DATE, t TIME, ts TIMESTAMP)"
-                let dayVal = fromGregorian 2024 10 12
-                    timeVal = TimeOfDay 14 30 15.123456
-                    tsVal = LocalTime dayVal timeVal
-                _ <- execute conn "INSERT INTO temporals VALUES (?, ?, ?)" (dayVal, timeVal, tsVal)
-                [(dRes, tRes, tsRes)] <- query_ conn "SELECT d, t, ts FROM temporals"
-                assertEqual "date round-trip" dayVal dRes
-                assertEqual "time round-trip" timeVal tRes
-                assertEqual "timestamp round-trip" tsVal tsRes
-                [Only utcRes] <- query_ conn "SELECT ts FROM temporals" :: IO [Only UTCTime]
-                assertEqual "timestamp as UTC" (localTimeToUTC utc tsVal) utcRes
-        , testCase "round-trips blob payloads" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE blobs (payload BLOB)"
-                let payload = BS.pack [0, 1, 2, 3, 255]
-                _ <- execute conn "INSERT INTO blobs VALUES (?)" (Only payload)
-                [Only blobOut] <- query_ conn "SELECT payload FROM blobs"
-                assertEqual "blob round-trip" payload blobOut
-        , testCase "round-trips unsigned integers" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE unsigneds (u8 UTINYINT, u16 USMALLINT, u32 UINTEGER, u64 UBIGINT)"
-                let w8 = 200 :: Word8
-                    w16 = 60000 :: Word16
-                    w32 = 4000000000 :: Word32
-                    w64 = maxBound :: Word64
-                _ <- execute conn "INSERT INTO unsigneds VALUES (?, ?, ?, ?)" (w8, w16, w32, w64)
-                [(r8, r16, r32, r64)] <- query_ conn "SELECT u8, u16, u32, u64 FROM unsigneds"
-                assertEqual "Word8 round-trip" w8 r8
-                assertEqual "Word16 round-trip" w16 r16
-                assertEqual "Word32 round-trip" w32 r32
-                assertEqual "Word64 round-trip" w64 r64
-                [Only (asWord :: Word)] <- query_ conn "SELECT u64 FROM unsigneds"
-                assertEqual "Word from UBIGINT" (fromIntegral w64) asWord
-        , testCase "round-trips fixed-length arrays" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE arrays (vals INTEGER[3])"
-                let inputs =
-                        [ listArray (0, 2) [1, 2, 3]
-                        , listArray (0, 2) [4, 5, 6]
-                        ]
-                _ <- executeMany conn "INSERT INTO arrays VALUES (?)" (Only <$> inputs)
-                rows <- query_ conn "SELECT vals FROM arrays ORDER BY rowid" :: IO [Only (Array Int Int)]
-                let expected =
-                        fmap Only inputs
-                assertEqual "array round-trip" expected rows
-        , testCase "decodes huge integers as Integer" $
-            withConnection ":memory:" \conn -> do
-                let hugeValue = 170141183460469231731687303715884105727 :: Integer
-                [Only (hugeOut :: Integer)] <-
-                    query_ conn "SELECT 170141183460469231731687303715884105727::HUGEINT"
-                assertEqual "hugeint" hugeValue hugeOut
-        , testCase "decodes huge integers as Natural" $
-            withConnection ":memory:" \conn -> do
-                let hugeValue = 170141183460469231731687303715884105727 :: Natural
-                [Only (naturalOut :: Natural)] <-
-                    query_ conn "SELECT 170141183460469231731687303715884105727::HUGEINT"
-                assertEqual "hugeint natural" hugeValue naturalOut
-        , testCase "decodes unsigned huge integers as Natural" $
-            withConnection ":memory:" \conn -> do
-                let uhValue = 170141183460469231731687303715884105727 :: Natural
-                [Only (naturalOut :: Natural)] <-
-                    query_ conn "SELECT 170141183460469231731687303715884105727::UHUGEINT"
-                assertEqual "uhugeint natural" uhValue naturalOut
-        , testCase "FromField Integer consumes FieldBigNum" $ do
-            let original = 1234567899876543210123456789 :: Integer
-                bigField =
-                    Field
-                        { fieldName = "big"
-                        , fieldIndex = 0
-                        , fieldValue = FieldBigNum (BigNum original)
-                        }
-            case (fromField bigField :: Ok Integer) of
-                Ok result -> assertEqual "FieldBigNum Integer" original result
-                Errors err -> assertFailure ("unexpected parse failure: " <> show err)
-        , testCase "FromField Natural rejects negative FieldBigNum" $ do
-            let bigValue = BigNum (-5)
-                bigField =
-                    Field
-                        { fieldName = "big"
-                        , fieldIndex = 0
-                        , fieldValue = FieldBigNum bigValue
-                        }
-            case (fromField bigField :: Ok Natural) of
-                Errors _ -> pure ()
-                Ok result -> assertFailure ("expected failure, got " <> show result)
-        , testCase "BigNum conversions round-trip Integer" $ do
-            let original = (2 ^ (200 :: Int)) + 8675309 :: Integer
-                converted = toBigNumBytes original
-            assertEqual "round-trip Integer" original (fromBigNumBytes converted)
-        , testProperty "fromBigNumBytes . toBigNumBytes is identity" \(n :: Integer) ->
-            fromBigNumBytes (toBigNumBytes n) === n
-        , testCase "selects BIGNUM values as BigNum" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE bignums (val BIGNUM)"
-                let bigValues :: [Integer]
-                    bigValues =
-                        [ (2 ^ (200 :: Int)) + 8675309
-                        , 0
-                        , negate ((2 ^ (180 :: Int)) + 12345)
-                        ]
-                rows <- concat <$> mapM (\bv -> query_ conn $ fromString $ "SELECT CAST('" <> show bv <> "' AS BIGNUM)") bigValues
-                --  query_ conn "SELECT val FROM bignums ORDER BY rowid" :: IO [Only BigNum]
-                assertEqual "BIGNUM results" (fmap (Only . BigNum) bigValues) rows
-        , testCase "round-trips BIGNUM values through the database" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE bignum_roundtrip (val BIGNUM)"
-                let ints =
-                        [ (2 ^ (200 :: Int)) + 8675309
-                        , 0
-                        , negate ((2 ^ (180 :: Int)) + 12345)
-                        ]
-                _ <- executeMany conn "INSERT INTO bignum_roundtrip VALUES (?)" (fmap (Only . BigNum) ints)
-                rows <- query_ conn "SELECT val FROM bignum_roundtrip ORDER BY rowid" :: IO [Only Integer]
-                assertEqual "BIGNUM round-trip" (fmap Only ints) rows
-        , testCase "duckdbColumnType reports BIGNUM for Integer" $
-            assertEqual
-                "duckdbColumnType Integer"
-                (Text.pack "BIGNUM")
-                (duckdbColumnType (Proxy :: Proxy Integer))
-        , testCase "duckdbColumnType preserves Maybe parameter" $
-            assertEqual
-                "duckdbColumnType Maybe Word16"
-                (Text.pack "USMALLINT")
-                (duckdbColumnType (Proxy :: Proxy (Maybe Word16)))
-        , testCase "decodes interval components" $
-            withConnection ":memory:" \conn -> do
-                [Only intervalVal] <-
-                    query_ conn "SELECT INTERVAL '2 months 3 days 04:05:06.007008'"
-                let IntervalValue{intervalMonths, intervalDays, intervalMicros} = intervalVal
-                    expectedMicros =
-                        (((4 * 60 + 5) * 60) + 6) * 1000000 + 7008
-                assertEqual "interval months" 2 intervalMonths
-                assertEqual "interval days" 3 intervalDays
-                assertEqual "interval micros" expectedMicros intervalMicros
-        , testCase "decodes decimals via Double conversion" $
-            withConnection ":memory:" \conn -> do
-                [Only decimalAsDouble] <-
-                    (query_ conn "SELECT CAST(12345.6789 AS DECIMAL(18,4))" :: IO [Only Double])
-                let diff = abs (decimalAsDouble - 12345.6789)
-                assertBool
-                    ("decimal as double: " <> show diff)
-                    (diff < 1e-4)
-        , testCase "decodes time with time zone" $
-            withConnection ":memory:" \conn -> do
-                [Only tzVal] <- query_ conn "SELECT TIMETZ '14:30:15+02:30'"
-                let expectedTime = TimeOfDay 14 30 15
-                    expectedZone = minutesToTimeZone 150
-                assertEqual "timetz time" expectedTime (timeWithZoneTime tzVal)
-                assertEqual "timetz zone" expectedZone (timeWithZoneZone tzVal)
-        , testCase "decodes list columns into Haskell lists" $
-            withConnection ":memory:" \conn -> do
-                [Only (listOut :: [Int])] <-
-                    query_ conn "SELECT LIST_VALUE(1, 2, 3)::INTEGER[]"
-                assertEqual "list decode" [1, 2, 3] listOut
-        , testCase "decodes map columns into strict Map" $
-            withConnection ":memory:" \conn -> do
-                [Only (mapOut :: Map.Map Text.Text Int)] <-
-                    query_ conn "SELECT MAP(['a', 'b']::TEXT[], [1, 2]::INTEGER[])"
-                let expected = Map.fromList [(Text.pack "a", 1), (Text.pack "b", 2)]
-                assertEqual "map decode" expected mapOut
-        , testCase "decodes timestamp with time zone as UTC" $
-            withConnection ":memory:" \conn -> do
-                [Only utcVal] <-
-                    (query_ conn "SELECT TIMESTAMPTZ '2024-10-12 14:30:15+02:30'" :: IO [Only UTCTime])
-                let expected =
-                        UTCTime
-                            (fromGregorian 2024 10 12)
-                            (timeOfDayToTime (TimeOfDay 12 0 15))
-                assertEqual "timestamptz utc" expected utcVal
-        , testCase "custom FieldParser enforces invariants" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE nonempty (name TEXT)"
-                _ <- execute conn "INSERT INTO nonempty VALUES (?)" (Only (Text.pack "okay"))
-                rows <- query_ conn "SELECT name FROM nonempty" :: IO [Only NonEmptyText]
-                assertEqual "non-empty success" [Only (NonEmptyText (Text.pack "okay"))] rows
-                _ <- execute conn "INSERT INTO nonempty VALUES (?)" (Only (Text.pack ""))
-                assertThrows
-                    (query_ conn "SELECT name FROM nonempty" :: IO [Only NonEmptyText])
-                    (Text.isInfixOf "NonEmptyText requires a non-empty string" . sqlErrorMessage)
-        , testCase "round-trips uuid payloads" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE uuids (uuid UUID)"
-                let uuidTexts =
-                        [ "123e4567-e89b-12d3-a456-426614174000"
-                        , "923e4567-e89b-12d3-a456-426614174000"
-                        , "ffffffff-ffff-ffff-ffff-ffffffffffff"
-                        ]
-                    maybeUUIDs = traverse UUID.fromText uuidTexts
-                uuids <-
-                    case maybeUUIDs of
-                        Nothing -> assertFailure "invalid UUID literal in test data" >> pure []
-                        Just parsed -> pure parsed
-                _ <- executeMany conn "INSERT INTO uuids VALUES (?)" (fmap Only uuids)
-                rows <- query_ conn "SELECT uuid FROM uuids ORDER BY rowid" :: IO [Only UUID.UUID]
-                assertEqual "uuid round-trip" (fmap Only uuids) rows
-        , testCase "round-trips bitstring payloads" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE bits (bit BIT)"
-                let bitValues =
-                        [ bsFromBool [True]
-                        , bsFromBool [False, False, False, True, True, True, False, True, False]
-                        , bsFromBool [False, False, False, False, True, True, True, False, True, False]
-                        , bsFromBool [True, False, False, False, True, True, True, False, True, False]
-                        ]
-                _ <- executeMany conn "INSERT INTO bits VALUES (?)" (fmap Only bitValues)
-                rows <- query_ conn "SELECT bit FROM bits ORDER BY rowid" :: IO [Only BitString]
-                assertEqual "bit round-trip" (fmap Only bitValues) rows
-        , testCase "round-trips struct and union parameters" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE struct_union (s STRUCT(a INT, b INT), u UNION(a INT, b VARCHAR))"
-                [(structVal, unionVal)] <-
-                    query_ conn "SELECT {'a': 1, 'b': 2}, CAST(union_value(a := 42) AS UNION(a INTEGER, b VARCHAR))" :: IO [(StructValue FieldValue, UnionValue FieldValue)]
-                _ <- execute conn "INSERT INTO struct_union VALUES (?, ?)" (structVal, unionVal)
-                rows <- query_ conn "SELECT s, u FROM struct_union" :: IO [(StructValue FieldValue, UnionValue FieldValue)]
-                assertEqual "struct/union round-trip" [(structVal, unionVal)] rows
-        , testCase "generic struct into database" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE generic_struct (payload STRUCT(grId INT, grName TEXT))"
-                let records = [GenericRecord 1 (Text.pack "alpha"), GenericRecord 2 (Text.pack "beta")]
-                    structParams = traverse genericToStructValue records
-                case structParams of
-                    Nothing -> assertFailure "expected struct encoding"
-                    Just structs -> do
-                        _ <- executeMany conn "INSERT INTO generic_struct VALUES (?)" (map Only structs)
-                        rows <- query_ conn "SELECT payload FROM generic_struct ORDER BY payload.grId" :: IO [Only (StructValue FieldValue)]
-                        let unwrap (Only s) = s
-                            roundTripped = traverse (genericFromFieldValue . FieldStruct . unwrap) rows
-                        roundTripped @?= Right records
-        , testCase "generic struct encode/decode" $ do
-            let rec = GenericRecord 42 (Text.pack "duck")
-            case genericToStructValue rec of
-                Just structVal -> do
-                    map structFieldName (elems (structValueFields structVal)) @?= [Text.pack "grId", Text.pack "grName"]
-                    map structFieldValue (elems (structValueFields structVal)) @?= [FieldInt64 42, FieldText (Text.pack "duck")]
-                    genericFromFieldValue (FieldStruct structVal) @?= Right rec
-                Nothing -> assertFailure "expected struct encoding"
-        , testCase "generic union encode/decode" $ do
-            let sumVal = SumBool True
-            case genericToFieldValue sumVal of
-                FieldUnion uv -> do
-                    map unionMemberName (elems (unionValueMembers uv))
-                        @?= [ Text.pack "SumInt"
-                            , Text.pack "SumBool"
-                            , Text.pack "SumPair"
-                            ]
-                    unionValueLabel uv @?= Text.pack "SumBool"
-                    genericFromFieldValue (FieldUnion uv) @?= Right sumVal
-                other -> assertFailure ("expected FieldUnion, got " <> show other)
-        , testCase "generic union complex constructor" $ do
-            let sumVal = SumPair 7 (Text.pack "duck")
-            case genericToFieldValue sumVal of
-                FieldUnion uv -> do
-                    unionValueLabel uv @?= Text.pack "SumPair"
-                    case unionValuePayload uv of
-                        FieldStruct StructValue{structValueFields} -> do
-                            map structFieldName (elems structValueFields) @?= [Text.pack "field1", Text.pack "field2"]
-                            map structFieldValue (elems structValueFields)
-                                @?= [FieldInt64 7, FieldText (Text.pack "duck")]
-                        other -> assertFailure ("expected struct payload, got " <> show other)
-                    genericFromFieldValue (FieldUnion uv) @?= Right sumVal
-                other -> assertFailure ("expected FieldUnion, got " <> show other)
-        , testCase "deriving via generic struct round-trip" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE via_users (payload STRUCT(vuId BIGINT, vuName TEXT))"
-                let users = [ViaUser 10 (Text.pack "alice"), ViaUser 11 (Text.pack "bob")]
-                _ <- executeMany conn "INSERT INTO via_users VALUES (?)" (map Only users)
-                rows <- query_ conn "SELECT payload FROM via_users ORDER BY payload.vuId" :: IO [Only ViaUser]
-                rows @?= map Only users
-        , testCase "deriving via generic union round-trip" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE via_shapes (shape UNION(ViaCircle STRUCT(field1 DOUBLE), ViaSquare STRUCT(field1 DOUBLE)))"
-                let shapes = [ViaCircle 1.5, ViaSquare 3.0]
-                _ <- executeMany conn "INSERT INTO via_shapes VALUES (?)" (map Only shapes)
-                rows <- query_ conn "SELECT shape FROM via_shapes ORDER BY rowid" :: IO [Only ViaShape]
-                rows @?= map Only shapes
-        , testCase "generic enum null payload" $ do
-            case genericToFieldValue EnumRed of
-                FieldUnion uv -> do
-                    unionValuePayload uv @?= FieldNull
-                    genericFromFieldValue (FieldUnion uv) @?= Right EnumRed
-                other -> assertFailure ("expected FieldUnion, got " <> show other)
-        , -- Edge case tests
-          testCase "struct with multiple basic fields" $ do
-            -- Test a struct with multiple fields
-            let twoField = TwoFieldStruct 42 (Text.pack "text")
-            case genericToFieldValue twoField of
-                FieldStruct sv -> do
-                    genericFromFieldValue (FieldStruct sv) @?= Right twoField
-                other -> assertFailure ("expected FieldStruct for TwoFieldStruct, got " <> show other)
-        , testCase "large sum type with many constructors" $ do
-            let constructors = [LargeC1 1, LargeC2 2, LargeC3 3, LargeC4 4, LargeC5 5]
-            forM_ constructors $ \val -> do
-                case genericToFieldValue val of
-                    FieldUnion uv -> do
-                        genericFromFieldValue (FieldUnion uv) @?= Right val
-                    other -> assertFailure ("expected FieldUnion, got " <> show other)
-        , testCase "empty struct encodes as null" $ do
-            case genericToFieldValue EmptyStruct of
-                FieldNull -> pure ()
-                other -> assertFailure ("expected FieldNull for empty struct, got " <> show other)
-        , testCase "struct with Maybe fields" $ do
-            let withJust = OptionalFields (Just 42) (Just (Text.pack "text"))
-                withNothing = OptionalFields Nothing Nothing
-            case (genericToFieldValue withJust, genericToFieldValue withNothing) of
-                (FieldStruct sv1, FieldStruct sv2) -> do
-                    genericFromFieldValue (FieldStruct sv1) @?= Right withJust
-                    genericFromFieldValue (FieldStruct sv2) @?= Right withNothing
-                (other1, other2) -> assertFailure ("expected FieldStruct, got " <> show (other1, other2))
-        , -- Error case tests
-          testCase "decode wrong field type fails" $ do
-            let wrongType = FieldInt32 42 -- Trying to decode as GenericRecord
-            case genericFromFieldValue wrongType :: Either String GenericRecord of
-                Left err -> assertBool "error mentions STRUCT" (Text.pack "STRUCT" `Text.isInfixOf` Text.pack err)
-                Right _ -> assertFailure "expected decode error for wrong type"
-        , testCase "decode union as struct fails" $ do
-            case genericToFieldValue (SumInt 42) of
-                FieldUnion uv -> do
-                    case genericFromFieldValue (FieldUnion uv) :: Either String GenericRecord of
-                        Left err -> assertBool "error mentions product type" (Text.pack "product type" `Text.isInfixOf` Text.pack err)
-                        Right _ -> assertFailure "expected decode error"
-                other -> assertFailure ("expected FieldUnion, got " <> show other)
-        , testCase "decode struct as union fails" $ do
-            case genericToFieldValue (GenericRecord 1 (Text.pack "test")) of
-                FieldStruct sv -> do
-                    case genericFromFieldValue (FieldStruct sv) :: Either String GenericSum of
-                        Left err -> assertBool "error mentions sum type" (Text.pack "sum type" `Text.isInfixOf` Text.pack err)
-                        Right _ -> assertFailure "expected decode error"
-                other -> assertFailure ("expected FieldStruct, got " <> show other)
-        , testCase "decode struct with wrong field count fails" $
-            withConnection ":memory:" \conn -> do
-                -- Get a real struct with 3 fields from the database
-                _ <- execute_ conn "CREATE TABLE three_field (s STRUCT(a INT, b TEXT, c INT))"
-                [(Only threeField)] <- query_ conn "SELECT {'a': 1, 'b': 'test', 'c': 99}" :: IO [Only (StructValue FieldValue)]
-                -- Try to decode it as GenericRecord which only has 2 fields
-                case genericFromFieldValue (FieldStruct threeField) :: Either String GenericRecord of
-                    Left err -> assertBool "error mentions extra fields" (Text.pack "extra" `Text.isInfixOf` Text.pack err)
-                    Right _ -> assertFailure "expected decode error for extra fields"
-        , testCase "decode union with wrong tag fails" $
-            withConnection ":memory:" \conn -> do
-                -- Get a real union from the database
-                [(Only unionVal)] <-
-                    query_ conn "SELECT CAST(union_value(x := 42) AS UNION(x INT, y VARCHAR))" :: IO [Only (UnionValue FieldValue)]
-                -- Manually create a modified version with an out-of-range tag
-                let wrongTag = unionVal{unionValueIndex = 99, unionValueLabel = Text.pack "Invalid"}
-                case genericFromFieldValue (FieldUnion wrongTag) :: Either String GenericSum of
-                    Left err -> assertBool "error mentions tag or index" (Text.pack "tag" `Text.isInfixOf` Text.pack err || Text.pack "99" `Text.isInfixOf` Text.pack err)
-                    Right _ -> assertFailure "expected decode error for wrong tag"
-        ]
-
-streamingTests :: TestTree
-streamingTests =
-    testGroup
-        "streaming"
-        [ testCase "fold_ accumulates large result sets" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE stream_fold (n INTEGER)"
-                let rows = fmap Only [1 .. 1000 :: Int]
-                _ <- executeMany conn "INSERT INTO stream_fold VALUES (?)" rows
-                total <- fold_ conn "SELECT n FROM stream_fold ORDER BY n" 0 \acc (Only n) -> pure (acc + n)
-                assertEqual "folded sum" (sum ([1 .. 1000] :: [Int])) total
-        , testCase "fold and foldNamed respect parameters" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE stream_filter (n INTEGER)"
-                let values = fmap Only [1 .. 50 :: Int]
-                _ <- executeMany conn "INSERT INTO stream_filter VALUES (?)" values
-                gtTotal <-
-                    fold conn "SELECT n FROM stream_filter WHERE n > ?" (Only (40 :: Int)) 0 $
-                        \acc (Only n) -> pure (acc + n)
-                let expected = sum ([41 .. 50] :: [Int])
-                assertEqual "filtered fold sum" expected gtTotal
-                leCount <-
-                    foldNamed conn "SELECT n FROM stream_filter WHERE n <= $limit" ["$limit" := (10 :: Int)] 0 $
-                        \acc (Only (_ :: Int)) -> pure (acc + 1)
-                assertEqual "foldNamed count" (10 :: Int) leCount
-        , testCase "nextRow streams rows sequentially" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE stream_cursor (n INTEGER)"
-                _ <- executeMany conn "INSERT INTO stream_cursor VALUES (?)" (fmap Only [1 .. 3 :: Int])
-                withStatement conn "SELECT n FROM stream_cursor ORDER BY n" \stmt -> do
-                    first <- nextRow stmt
-                    second <- nextRow stmt
-                    third <- nextRow stmt
-                    done <- nextRow stmt
-                    assertEqual
-                        "cursor iteration"
-                        [Just (Only (1 :: Int)), Just (Only 2), Just (Only 3), Nothing]
-                        [first, second, third, done]
-        ]
-
-functionsTests :: TestTree
-functionsTests =
-    testGroup
-        "user-defined functions"
-        [ testCase "registers pure scalar function" $
-            withConnection ":memory:" \conn -> do
-                createFunction conn "hs_times_two" (\(x :: Int64) -> x * 2)
-                result <- query_ conn "SELECT hs_times_two(21)" :: IO [Only Int64]
-                assertEqual "times_two result" [Only 42] result
-        , testCase "handles nullable arguments and results" $
-            withConnection ":memory:" \conn -> do
-                createFunction conn "hs_optional" (\(mx :: Maybe Int64) -> fmap (+ 1) mx)
-                rows <-
-                    query_ conn "SELECT hs_optional(x) FROM (VALUES (NULL), (41)) AS t(x)" ::
-                        IO [Only (Maybe Int64)]
-                assertEqual "optional results" [Only Nothing, Only (Just 42)] rows
-        , testCase "supports IO-based functions" $
-            withConnection ":memory:" \conn -> do
-                ref <- newIORef (0 :: Int)
-                createFunction conn "hs_counter" $ do
-                    atomicModifyIORef' ref \n ->
-                        let next = n + 1
-                         in (next, next)
-                first <- query_ conn "SELECT hs_counter()" :: IO [Only Int]
-                second <- query_ conn "SELECT hs_counter()" :: IO [Only Int]
-                assertEqual "first counter call" [Only 1] first
-                assertEqual "second counter call" [Only 2] second
-        , testCase "supports thread-local function state" $ do
-            conn <- openWithConfig ":memory:" [("threads", "1")]
-            createFunctionWithState conn "hs_stateful_counter" (newIORef (0 :: Int)) \ref -> do
-                atomicModifyIORef' ref \n ->
-                    let next = n + 1
-                     in (next, next)
-            rows <- query_ conn "SELECT hs_stateful_counter() FROM range(3)" :: IO [Only Int]
-            close conn
-            assertEqual "stateful rows" [Only 1, Only 2, Only 3] rows
-        ]
-
-transactionTests :: TestTree
-transactionTests =
-    testGroup
-        "transactions"
-        [ testCase "withTransaction commits on success" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE tx_commit (x INTEGER)"
-                withTransaction conn $ do
-                    _ <- execute conn "INSERT INTO tx_commit VALUES (?)" (Only (1 :: Int))
-                    pure ()
-                rows <- query_ conn "SELECT COUNT(*) FROM tx_commit" :: IO [Only Int]
-                assertEqual "commit" [Only 1] rows
-        , testCase "withTransaction rolls back on exception" $
-            withConnection ":memory:" \conn -> do
-                _ <- execute_ conn "CREATE TABLE tx_rollback (x INTEGER)"
-                assertThrowsErrorCall $
-                    withTransaction conn $ do
-                        _ <- execute conn "INSERT INTO tx_rollback VALUES (?)" (Only (1 :: Int))
-                        error "boom"
-                rows <- query_ conn "SELECT COUNT(*) FROM tx_rollback" :: IO [Only Int]
-                assertEqual "rollback" [Only 0] rows
-        ]
-
-assertThrows :: forall e a. (Exception e) => IO a -> (e -> Bool) -> Assertion
-assertThrows action predicate = do
-    outcome <- try action
-    case outcome of
-        Left (err :: e) -> assertBool "unexpected exception" (predicate err)
-        Right _ -> assertFailure "expected exception, but action succeeded"
-
-assertThrowsSQLError :: IO a -> Assertion
-assertThrowsSQLError action =
-    assertThrows action (const True :: SQLError -> Bool)
-
-assertThrowsErrorCall :: IO a -> Assertion
-assertThrowsErrorCall action =
-    assertThrows action (const True :: ErrorCall -> Bool)
-
-assertThrowsFormatError :: IO a -> (FormatError -> Bool) -> Assertion
-assertThrowsFormatError = assertThrows
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE DeriveAnyClass #-}
+{-# LANGUAGE DeriveGeneric #-}
+{-# LANGUAGE DerivingVia #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications #-}
+{-# LANGUAGE TypeOperators #-}
+
+-- |
+-- Module      : Main
+-- Description : Tasty-based test suite for duckdb-simple.
+module Main (main) where
+
+import ArrowTests (arrowTests)
+import CancellationTests (callbackLockTests, cancellationTests)
+import Control.Applicative ((<|>))
+import Control.Concurrent (forkFinally, newEmptyMVar, putMVar, readMVar)
+import Control.Exception (ErrorCall, Exception, SomeException, bracket, displayException, fromException, throwIO, try)
+import Control.Monad (forM_, replicateM_, void, when)
+import CopyTests (copyTests)
+import CoreRegressionTests (coreRegressionTests)
+import Data.Array (elems, listArray)
+import qualified Data.ByteString as BS
+import Data.IORef (atomicModifyIORef', newIORef, readIORef)
+import Data.Int (Int16, Int32, Int64, Int8)
+import Data.List (sortOn)
+import qualified Data.Map.Strict as Map
+import Data.Maybe (fromJust)
+import Data.Proxy (Proxy (..))
+import Data.Ratio ((%))
+import Data.String (fromString)
+import qualified Data.Text as Text
+import Data.Time.Calendar (Day, fromGregorian)
+import Data.Time.Clock (UTCTime (..), secondsToDiffTime)
+import Data.Time.LocalTime (
+  LocalTime (..),
+  TimeOfDay (..),
+  localTimeToUTC,
+  timeOfDayToTime,
+  utc,
+ )
+import qualified Data.UUID as UUID
+import Data.Word (Word16, Word32, Word64, Word8)
+import Database.DuckDB.Simple
+import qualified Database.DuckDB.Simple.Catalog as Catalog
+import qualified Database.DuckDB.Simple.Config as Config
+import qualified Database.DuckDB.Simple.Copy as Copy
+import qualified Database.DuckDB.Simple.FileSystem as FileSystem
+import Database.DuckDB.Simple.FromField (
+  BigNum (..),
+  BitString (..),
+  DecimalValue (..),
+  Field (..),
+  FieldValue (..),
+  IntervalValue (..),
+  TimeWithZone (..),
+  bsFromBool,
+  fromBigNumBytes,
+  returnError,
+  toBigNumBytes,
+ )
+import Database.DuckDB.Simple.Generic (
+  DuckValue (..),
+  ViaDuckDB (..),
+  genericFromFieldValue,
+  genericLogicalType,
+  genericToFieldValue,
+  genericToStructValue,
+ )
+import qualified Database.DuckDB.Simple.Logging as Logging
+import Database.DuckDB.Simple.LogicalRep (
+  LogicalTypeRep (..),
+  StructField (..),
+  StructValue (..),
+  UnionMemberType (..),
+  UnionValue (..),
+ )
+import Database.DuckDB.Simple.Ok (Ok (..))
+import Database.DuckDB.Simple.Time (Unbounded (..))
+import Database.DuckDB.Simple.ToField (ToDuckValue (..))
+import Database.DuckDB.Simple.Variant (Variant (..), variantObject)
+import ExtensionRegressionTests (extensionRegressionTests)
+import GHC.Generics (Generic)
+import qualified GeometryRegressionTests
+import Numeric.Natural (Natural)
+import Properties (roundTripTests)
+import RegistrationTests (registrationTests)
+import SizedArrayTests (sizedArrayTests)
+import qualified SqlFeatureTests
+import StreamingTests (nativeStreamingTests)
+import System.Directory (doesFileExist, getTemporaryDirectory, removeFile)
+import System.IO (hClose, openBinaryTempFile)
+import System.Timeout (timeout)
+import Test.Tasty (TestTree, Timeout (..), adjustOption, defaultMain, mkTimeout, testGroup)
+import Test.Tasty.HUnit
+import Test.Tasty.QuickCheck (testProperty, (===))
+import TestUtils (sized)
+import TimeTests (timeTests)
+import TypedRegistrationTests (typedRegistrationTests)
+import UserCastTests (geometryArgumentTests, userCastTests)
+import ValueRegressionTests (valueRegressionTests)
+import qualified VariantRegressionTests
+
+data Person = Person
+  { personId :: Int
+  , personName :: Text.Text
+  }
+  deriving stock (Eq, Show, Generic)
+  deriving anyclass (FromRow)
+
+data WithRemaining = WithRemaining Int Int
+  deriving (Eq, Show)
+
+data GenericRecord = GenericRecord
+  { grId :: Int
+  , grName :: Text.Text
+  }
+  deriving stock (Eq, Show, Generic)
+
+data GenericSum
+  = SumInt Int
+  | SumBool Bool
+  | SumPair Int Text.Text
+  deriving stock (Eq, Show, Generic)
+
+data GenericEnum
+  = EnumRed
+  | EnumBlue
+  deriving stock (Eq, Show, Generic)
+
+data ViaUser = ViaUser
+  { vuId :: Int64
+  , vuName :: Text.Text
+  }
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToDuckValue, ToField, FromField) via (ViaDuckDB ViaUser)
+
+-- | A newtype with its own type text, for a scalar function argument.
+newtype Price = Price DecimalValue
+
+instance DuckDBColumnType Price where
+  duckdbColumnTypeFor _ = "DECIMAL(18,3)"
+
+instance FromField Price where
+  fromField value = Price <$> fromField value
+
+-- | A newtype with its own type text, for a scalar function result.
+newtype Amount = Amount Double
+
+instance DuckDBColumnType Amount where
+  duckdbColumnTypeFor _ = "DECIMAL(18,3)"
+
+instance ToDuckValue Amount where
+  toDuckValue factory (Amount value) = toDuckValue factory value
+
+data ViaShape
+  = ViaCircle Double
+  | ViaSquare Double
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToDuckValue, ToField, FromField) via (ViaDuckDB ViaShape)
+
+-- | A UNION with a STRUCT payload that contains a VARIANT.
+data VariantChoice = Payload Variant | NoPayload
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB VariantChoice)
+
+-- Edge case test types
+data TwoFieldStruct = TwoFieldStruct Int Text.Text
+  deriving stock (Eq, Show, Generic)
+
+data LargeSumType
+  = LargeC1 Int
+  | LargeC2 Int
+  | LargeC3 Int
+  | LargeC4 Int
+  | LargeC5 Int
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB LargeSumType)
+
+data EmptyStruct = EmptyStruct
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB EmptyStruct)
+
+-- | A field of the type EmptyStruct uses the generic encoding.
+instance DuckValue EmptyStruct where
+  duckToField = genericToFieldValue
+  duckFromField = genericFromFieldValue
+  duckLogicalType = genericLogicalType
+
+-- | A record with two optional fields of a type without fields.
+data OptionalEmpty = OptionalEmpty
+  { oeFirst :: Maybe EmptyStruct
+  , oeSecond :: Maybe EmptyStruct
+  }
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB OptionalEmpty)
+
+-- | A record with a field of a type without fields.
+data WithEmpty = WithEmpty
+  { weId :: Int64
+  , weEmpty :: EmptyStruct
+  }
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB WithEmpty)
+
+-- | A sum with a constructor that has a field and a constructor without fields.
+data Tally
+  = Counted Int64
+  | Uncounted
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB Tally)
+
+data OptionalFields = OptionalFields
+  { ofInt :: Maybe Int
+  , ofText :: Maybe Text.Text
+  }
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB OptionalFields)
+
+instance FromRow WithRemaining where
+  fromRow = do
+    firstVal <- field
+    remaining <- numFieldsRemaining
+    replicateM_ remaining (fieldWith (const (pure ())))
+    pure (WithRemaining firstVal remaining)
+
+newtype YesNo = YesNo Bool
+  deriving (Eq, Show)
+
+instance FromRow YesNo where
+  fromRow = parseYes <|> parseNo
+    where
+      parseYes = YesNo True <$ fieldWith (match (Text.pack "yes"))
+      parseNo = YesNo False <$ fieldWith (match (Text.pack "no"))
+
+      match expected fld@Field{} = do
+        txt <- fromField fld
+        if Text.toLower txt == expected
+          then pure ()
+          else returnError ConversionFailed fld "failed to match exact string"
+
+newtype NonEmptyText = NonEmptyText Text.Text
+  deriving (Eq, Show)
+
+nonEmptyTextParser :: FieldParser NonEmptyText
+nonEmptyTextParser f@Field{} = do
+  txt <- fromField f
+  if Text.null txt
+    then returnError ConversionFailed f "NonEmptyText requires a non-empty string"
+    else pure (NonEmptyText txt)
+
+instance FromField NonEmptyText where
+  fromField = nonEmptyTextParser
+
+-- | Run each case with a time limit of 10 minutes. Thus a deadlock fails its
+-- case, and not the job. The limit is long, because the suite also runs under
+-- Valgrind. The limit cannot stop a thread in a native call. A time limit of
+-- the command line (@--timeout@) replaces this limit.
+main :: IO ()
+main = defaultMain (adjustOption limit tests)
+  where
+    limit NoTimeout = mkTimeout (10 * 60 * 1000000)
+    limit given = given
+
+tests :: TestTree
+tests =
+  testGroup
+    "duckdb-simple"
+    [ connectionTests
+    , coreRegressionTests
+    , arrowTests
+    , cancellationTests
+    , callbackLockTests
+    , nativeStreamingTests
+    , extensionRegressionTests
+    , registrationTests
+    , typedRegistrationTests
+    , copyTests
+    , GeometryRegressionTests.tests
+    , VariantRegressionTests.tests
+    , userCastTests
+    , geometryArgumentTests
+    , valueRegressionTests
+    , sizedArrayTests
+    , timeTests
+    , SqlFeatureTests.tests
+    , withConnectionTests
+    , statementTests
+    , roundTripTests
+    , typeTests
+    , streamingTests
+    , functionsTests
+    , v20Tests
+    , transactionTests
+    ]
+
+connectionTests :: TestTree
+connectionTests =
+  testGroup
+    "open/close"
+    [ testCase "opens and closes an in-memory database" $ do
+        conn <- open ":memory:"
+        close conn
+    , testCase "allows closing the same connection twice" $ do
+        conn <- open ":memory:"
+        close conn
+        close conn
+    , testCase "opens with startup config" $ do
+        conn <- openWithConfig ":memory:" [("threads", "1")]
+        mValue <- Config.getConfigOption conn "threads"
+        close conn
+        case mValue of
+          Nothing -> assertFailure "expected threads config value"
+          Just value -> Config.configValueText value @?= Just "1"
+    ]
+
+v20Tests :: TestTree
+v20Tests =
+  testGroup
+    "DuckDB 2.0 wrappers"
+    [ testCase "lists config flags" $ do
+        flags <- withConnection ":memory:" Config.listConfigFlags
+        assertBool "expected at least one config flag" (not (null flags))
+        assertBool "expected threads flag" (any ((== "threads") . Config.configFlagName) flags)
+    , testCase "catalog lookup works inside a transaction" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE catalog_probe(id INTEGER)"
+          withTransaction conn $ do
+            mType <- Catalog.catalogTypeName conn "memory"
+            assertBool "expected catalog type name" (mType /= Nothing)
+            mEntry <- Catalog.lookupCatalogEntry conn "memory" "main" "catalog_probe" Catalog.CatalogTable
+            case mEntry of
+              Nothing -> assertFailure "expected catalog entry"
+              Just entry -> Catalog.catalogEntryName entry @?= "catalog_probe"
+    , testCase "file system wrappers round-trip bytes" $ withTemporaryPath \path -> do
+        let payload = BS.pack [0, 1, 2, 3, 255]
+        withConnection ":memory:" \conn -> do
+          FileSystem.withFileHandle conn path [FileSystem.FileFlagCreate, FileSystem.FileFlagWrite] \handle -> do
+            written <- FileSystem.writeFileHandleBytes handle payload
+            written @?= fromIntegral (BS.length payload)
+            FileSystem.fileHandleSync handle
+          FileSystem.withFileHandle conn path [FileSystem.FileFlagRead] \handle -> do
+            size <- FileSystem.fileHandleSize handle
+            size @?= fromIntegral (BS.length payload)
+            bytes <- FileSystem.readFileHandleChunk handle 32
+            bytes @?= payload
+        removeFile path
+    , testCase "copy wrappers receive COPY TO rows" $
+        withTemporaryPath \path -> withConnection ":memory:" \conn -> do
+          capturedRef <- newIORef ([] :: [Int])
+          pathRef <- newIORef Nothing
+          Copy.registerCopyToFunction
+            conn
+            "hs_capture"
+            (\bindInfo -> pure (length (Copy.copyBindColumnTypes bindInfo)))
+            ( \initInfo -> do
+                atomicModifyIORef' pathRef \_ -> (Just (Copy.copyInitFilePath initInfo), ())
+                pure (Copy.copyInitBindState initInfo)
+            )
+            ( \sinkInfo rows -> do
+                Copy.copySinkBindState sinkInfo @?= 1
+                Copy.copySinkGlobalState sinkInfo @?= 1
+                values <- mapM fieldInt rows
+                atomicModifyIORef' capturedRef \existing -> (existing <> values, ())
+            )
+            ( \finalizeInfo -> do
+                Copy.copyFinalizeBindState finalizeInfo @?= 1
+                Copy.copyFinalizeGlobalState finalizeInfo @?= 1
+            )
+          _ <- execute conn "COPY (SELECT * FROM (VALUES (1), (2), (3)) AS t(x)) TO ? (FORMAT hs_capture)" (Only (Text.pack path))
+          captured <- readIORef capturedRef
+          filePath <- readIORef pathRef
+          captured @?= [1, 2, 3]
+          filePath @?= Just path
+    , testCase "custom log storage registers a native sink" do
+        entries <- newIORef []
+        withConnection ":memory:" \conn -> do
+          Logging.registerLogStorage conn "hs_log_capture" (\entry -> atomicModifyIORef' entries (\values -> (entry : values, ())))
+          void $ execute_ conn "CALL enable_logging(); SET logging_storage = 'hs_log_capture'; SELECT write_log('registered')"
+        -- The sink receives the entry of write_log one time.
+        readIORef entries >>= (@?= ["registered"]) . filter (== "registered") . map Logging.logEntryMessage
+    ]
+
+fieldInt :: [Field] -> IO Int
+fieldInt [fld] =
+  runConversion (fromField fld) >>= \case
+    Errors err -> assertFailure (show err) >> pure 0
+    Ok value -> pure value
+fieldInt fields = assertFailure ("expected one field, got " <> show (length fields)) >> pure 0
+
+withConnectionTests :: TestTree
+withConnectionTests =
+  testGroup
+    "withConnection"
+    [ testCase "returns the action result" $ do
+        result <- withConnection ":memory:" \_ -> pure (21 :: Int)
+        assertEqual "action result" 21 result
+    , testCase "propagates exceptions from the action"
+        $ assertThrowsErrorCall
+        $ withConnection ":memory:" (\_ -> error "boom" :: IO ())
+    ]
+
+statementTests :: TestTree
+statementTests =
+  testGroup
+    "statements"
+    [ testCase "prepares and closes a simple statement" $
+        withConnection ":memory:" \conn -> do
+          stmt <- openStatement conn "SELECT 42"
+          closeStatement stmt
+    , testCase "allows closing a statement twice" $
+        withConnection ":memory:" \conn -> do
+          stmt <- openStatement conn "SELECT 1"
+          closeStatement stmt
+          closeStatement stmt
+    , testCase "rejects preparing statements on a closed connection" $ do
+        conn <- open ":memory:"
+        close conn
+        assertThrowsSQLError $
+          openStatement conn "SELECT 1"
+    , testCase "throws SQLError for invalid SQL" $
+        withConnection ":memory:" \conn ->
+          assertThrowsSQLError $
+            openStatement conn "THIS IS NOT VALID SQL"
+    , testCase "withStatement closes the statement automatically" $
+        withConnection ":memory:" \conn -> do
+          (result, stmt) <- withStatement conn "SELECT 1" \stmt -> pure ("done" :: String, stmt)
+          assertEqual "withStatement result" "done" result
+          -- A read of the closed statement raises an error.
+          assertThrowsSQLError (nextRow stmt :: IO (Maybe (Only Int)))
+    , testCase "withStatement closes statements even when the action fails" $
+        withConnection ":memory:" \conn -> do
+          used <- newIORef Nothing
+          assertThrowsErrorCall $
+            withStatement conn "SELECT 1" (\stmt -> atomicModifyIORef' used (const (Just stmt, ())) >> error "boom" :: IO ())
+          -- A read of the closed statement raises an error.
+          readIORef used
+            >>= maybe (assertFailure "the action did not run") (\closed -> assertThrowsSQLError (nextRow closed :: IO (Maybe (Only Int))))
+          stmt <- openStatement conn "SELECT 1"
+          closeStatement stmt
+    , testCase "execute returns affected row count" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE test_exec (x INTEGER)"
+          count <- execute conn "INSERT INTO test_exec VALUES (?)" (Only (1 :: Int))
+          assertEqual "rows affected" 1 count
+    , testCase "execute runs with positional parameters" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE exec_params (a INTEGER, b TEXT)"
+          count <- execute conn "INSERT INTO exec_params VALUES (?, ?)" (5 :: Int, "hi" :: String)
+          assertEqual "rows affected" 1 count
+    , testCase "rejects invalid direct execution" $
+        withConnection ":memory:" \conn ->
+          assertThrowsSQLError $
+            execute_ conn "THIS IS NOT SQL"
+    , testCase "binds positional parameters" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE params (a INTEGER, b TEXT)"
+          withStatement conn "INSERT INTO params VALUES (?, ?)" \stmt -> do
+            bind stmt [toField (5 :: Int), toField ("hi" :: String)]
+            changed <- executeStatement stmt
+            assertEqual "rows affected" 1 changed
+    , testCase "executeMany inserts each row and gives the total count" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE params_many (a INTEGER, b TEXT)"
+          total <- executeMany conn "INSERT INTO params_many VALUES (?, ?)" [(1 :: Int, "x" :: String), (2 :: Int, "y" :: String)]
+          assertEqual "rows affected" 2 total
+          query_ conn "SELECT a, b FROM params_many ORDER BY a" >>= (@?= [(1 :: Int, "x" :: String), (2, "y")])
+    , testCase "executeNamed binds named parameters" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE named_params (a INTEGER, b TEXT)"
+          count <- executeNamed conn "INSERT INTO named_params VALUES ($a, $b)" ["$a" := (1 :: Int), "$b" := ("named" :: String)]
+          assertEqual "rows affected" 1 count
+          rows <- queryNamed conn "SELECT a FROM named_params WHERE b = $label" ["$label" := ("named" :: String)]
+          assertEqual "named query" [Only (1 :: Int)] rows
+    , testCase "rejects incorrect positional argument counts" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE param_count (a INTEGER, b INTEGER)"
+          assertThrowsFormatError
+            (execute conn "INSERT INTO param_count VALUES (?, ?)" (Only (1 :: Int)))
+            (Text.isInfixOf "parameter(s)" . formatErrorMessage)
+    , testCase "rejects positional bindings on named statements" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE mixed_mode (a INTEGER)"
+          assertThrowsFormatError
+            (execute conn "INSERT INTO mixed_mode VALUES ($a)" (Only (1 :: Int)))
+            (Text.isInfixOf "named parameters" . formatErrorMessage)
+    , testCase "reports error when mixing positional and named parameters" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE mixed_params (a INTEGER, b TEXT)"
+          assertThrows
+            ( withStatement conn "INSERT INTO mixed_params VALUES (?, $label)" \stmt -> do
+                bind stmt [toField (1 :: Int)]
+                bindNamed stmt ["$label" := ("combo" :: String)]
+                _ <- executeStatement stmt
+                pure ()
+            )
+            ( \(err :: SQLError) ->
+                Text.isInfixOf "Mixing named and positional parameters" (sqlErrorMessage err)
+            )
+    , testCase "generic FromRow derivation works" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE person (id INTEGER, name TEXT)"
+          _ <- executeMany conn "INSERT INTO person VALUES (?, ?)" [(1 :: Int, "Alice" :: String), (2 :: Int, "Bob" :: String)]
+          people <- query_ conn "SELECT id, name FROM person ORDER BY id" :: IO [Person]
+          assertEqual "person rows" [Person 1 (Text.pack "Alice"), Person 2 (Text.pack "Bob")] people
+    , testCase "(:.) composes row parsing and parameter encoding" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE dot_pair (a INTEGER, b INTEGER, label TEXT)"
+          let payload = Only (7 :: Int) :. (8 :: Int, Text.pack "hi")
+          _ <- execute conn "INSERT INTO dot_pair VALUES (?, ?, ?)" payload
+          rows <- query_ conn "SELECT a, b, label FROM dot_pair" :: IO [Only Int :. (Int, Text.Text)]
+          case rows of
+            [Only a :. (b, label)] -> do
+              assertEqual "(:.) first" 7 a
+              assertEqual "(:.) second" 8 b
+              assertEqual "(:.) label" (Text.pack "hi") label
+            other -> assertFailure ("unexpected (:.) rows: " <> show other)
+    , testCase "query_ fetches rows" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE query_rows (a INTEGER, b TEXT)"
+          _ <- executeMany conn "INSERT INTO query_rows VALUES (?, ?)" [(1 :: Int, "x" :: String), (2 :: Int, "y" :: String)]
+          rows <- query_ conn "SELECT a, b FROM query_rows ORDER BY a"
+          assertEqual "query rows" [(1 :: Int, "x" :: String), (2 :: Int, "y" :: String)] rows
+    , testCase "query decodes NULL as Maybe" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE maybe_vals (a TEXT)"
+          _ <- execute conn "INSERT INTO maybe_vals VALUES (?)" (Only (Just ("present" :: String)))
+          _ <- execute conn "INSERT INTO maybe_vals VALUES (?)" (Only (Nothing :: Maybe String))
+          rows <- query_ conn "SELECT a FROM maybe_vals ORDER BY a IS NULL, a"
+          assertEqual "maybe decoding" [Only (Just ("present" :: String)), Only Nothing] rows
+    , testCase "query fetches rows with parameters" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE query_params (a INTEGER, b TEXT)"
+          _ <- executeMany conn "INSERT INTO query_params VALUES (?, ?)" [(1 :: Int, "x" :: String), (2 :: Int, "y" :: String)]
+          rows <- query conn "SELECT a FROM query_params WHERE b = ?" (Only ("y" :: String))
+          assertEqual "query result" [Only (2 :: Int)] rows
+    , testCase "column mismatch surfaces as SQLError" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE mismatch (a INTEGER, b INTEGER)"
+          _ <- execute_ conn "INSERT INTO mismatch VALUES (1, 2)"
+          assertThrows
+            (query_ conn "SELECT a, b FROM mismatch" :: IO [Only Int])
+            (Text.isInfixOf "column index" . sqlErrorMessage)
+    , testCase "clears statement bindings without error" $
+        withConnection ":memory:" \conn -> do
+          stmt <- openStatement conn "SELECT ?"
+          clearStatementBindings stmt
+          closeStatement stmt
+    , testCase "resolves named parameter indices" $
+        withConnection ":memory:" \conn -> do
+          stmt <- openStatement conn "SELECT $named_param"
+          idx <- namedParameterIndex stmt "named_param"
+          assertEqual "named parameter index" (Just 1) idx
+          idxWithPrefix <- namedParameterIndex stmt "$named_param"
+          assertEqual "named parameter index with prefix" (Just 1) idxWithPrefix
+          colonIdx <- namedParameterIndex stmt ":named_param"
+          assertEqual "named parameter index with colon" (Just 1) colonIdx
+          none <- namedParameterIndex stmt "missing"
+          assertEqual "missing parameter index" Nothing none
+          closeStatement stmt
+    , testCase "reports column metadata for statements" $
+        withConnection ":memory:" \conn -> do
+          stmt <- openStatement conn "SELECT 1 AS a, 2 AS b"
+          count <- columnCount stmt
+          assertEqual "column count" 2 count
+          name0 <- columnName stmt 0
+          name1 <- columnName stmt 1
+          assertEqual "column names" [Text.pack "a", Text.pack "b"] [name0, name1]
+          assertThrows
+            (columnName stmt 2)
+            (Text.isInfixOf "out of bounds" . sqlErrorMessage)
+          closeStatement stmt
+    , testCase "bindNamed rejects statements without named placeholders" $
+        withConnection ":memory:" \conn -> do
+          stmt <- openStatement conn "SELECT ?"
+          assertThrowsFormatError
+            (bindNamed stmt [":value" := (1 :: Int)])
+            (Text.isInfixOf "does not define named parameters" . formatErrorMessage)
+          closeStatement stmt
+    , testCase "bindNamed rejects unknown parameters" $
+        withConnection ":memory:" \conn -> do
+          stmt <- openStatement conn "SELECT $known"
+          assertThrowsFormatError
+            (bindNamed stmt ["$missing" := (1 :: Int)])
+            (Text.isInfixOf "unknown named parameter" . formatErrorMessage)
+          closeStatement stmt
+    , testCase "numFieldsRemaining reports remaining columns" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE remaining (a INTEGER, b INTEGER, c INTEGER)"
+          _ <- execute conn "INSERT INTO remaining VALUES (?, ?, ?)" (1 :: Int, 2 :: Int, 3 :: Int)
+          rows <- query_ conn "SELECT a, b, c FROM remaining" :: IO [WithRemaining]
+          assertEqual "remaining count" [WithRemaining 1 2] rows
+    , testCase "RowParser alternatives fall back" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE yesno (answer TEXT)"
+          _ <- executeMany conn "INSERT INTO yesno VALUES (?)" [Only ("yes" :: String), Only ("no" :: String)]
+          rows <- query_ conn "SELECT answer FROM yesno ORDER BY answer" :: IO [YesNo]
+          assertEqual "yes/no parsing" [YesNo False, YesNo True] rows
+    ]
+
+data DuckDBExpectation
+  = ExpectEquals FieldValue
+  | ExpectSatisfies (FieldValue -> Assertion)
+  | ExpectException (SomeException -> Assertion)
+
+data DuckDBExpression
+  = CastExpression Text.Text Text.Text
+  | DirectExpression Text.Text
+
+data DuckDBCastCase = DuckDBCastCase
+  { castLabel :: String
+  , castExpression :: DuckDBExpression
+  , castExpectation :: DuckDBExpectation
+  }
+
+duckdbTypeCastTests :: TestTree
+duckdbTypeCastTests =
+  testGroup
+    "duckdb type casts"
+    (map buildCase duckdbCastCases)
+  where
+    buildCase DuckDBCastCase{castLabel, castExpression, castExpectation} =
+      testCase castLabel $
+        withConnection ":memory:" \conn -> do
+          let sql =
+                Query
+                  ( case castExpression of
+                      CastExpression expressionValue expressionType ->
+                        Text.concat ["SELECT CAST(", expressionValue, " AS ", expressionType, ")"]
+                      DirectExpression expressionSQL ->
+                        Text.concat ["SELECT ", expressionSQL]
+                  )
+          result <- try (query_ conn sql) :: IO (Either SomeException [Only FieldValue])
+          runExpectation castLabel castExpectation result
+
+runExpectation :: String -> DuckDBExpectation -> Either SomeException [Only FieldValue] -> Assertion
+runExpectation label expectation outcome =
+  case expectation of
+    ExpectEquals expected ->
+      case outcome of
+        Right [Only fieldValue] ->
+          assertEqual (label <> " result mismatch") expected fieldValue
+        Right other ->
+          assertFailure (label <> " expected single row, got " <> show other)
+        Left err ->
+          assertFailure (label <> " expected success, but query failed: " <> displayException err)
+    ExpectSatisfies predicate ->
+      case outcome of
+        Right [Only fieldValue] ->
+          predicate fieldValue
+        Right other ->
+          assertFailure (label <> " expected single row, got " <> show other)
+        Left err ->
+          assertFailure (label <> " expected success, but query failed: " <> displayException err)
+    ExpectException predicate ->
+      case outcome of
+        Left err ->
+          predicate err
+        Right rows ->
+          assertFailure (label <> " expected failure, but query succeeded with " <> show rows)
+
+duckdbCastCases :: [DuckDBCastCase]
+duckdbCastCases =
+  [ successCase "BOOLEAN" (quoted "true") "BOOLEAN" (ExpectEquals (FieldBool True))
+  , successCase "TINYINT" (quotedValue tinyIntValue) "TINYINT" (ExpectEquals (FieldInt8 tinyIntValue))
+  , successCase "SMALLINT" (quotedValue smallIntValue) "SMALLINT" (ExpectEquals (FieldInt16 smallIntValue))
+  , successCase "INTEGER" (quotedValue intValue) "INTEGER" (ExpectEquals (FieldInt32 intValue))
+  , successCase "BIGINT" (quotedValue bigIntValue) "BIGINT" (ExpectEquals (FieldInt64 bigIntValue))
+  , successCase "UTINYINT" (quotedValue uTinyValue) "UTINYINT" (ExpectEquals (FieldWord8 uTinyValue))
+  , successCase "USMALLINT" (quotedValue uSmallValue) "USMALLINT" (ExpectEquals (FieldWord16 uSmallValue))
+  , successCase "UINTEGER" (quotedValue uIntValue) "UINTEGER" (ExpectEquals (FieldWord32 uIntValue))
+  , successCase "UBIGINT" (quotedValue uBigValue) "UBIGINT" (ExpectEquals (FieldWord64 uBigValue))
+  , successCase "FLOAT" (quoted "3.25") "FLOAT" (ExpectEquals (FieldFloat floatValue))
+  , successCase "DOUBLE" (quoted "2.5") "DOUBLE" (ExpectEquals (FieldDouble doubleValue))
+  , successCase "TIMESTAMP" (quoted "2024-01-02 03:04:05.123456") "TIMESTAMP" (ExpectEquals (FieldTimestamp (Finite timestampLocalTimeMicros)))
+  , successCase "DATE" (quoted "2024-10-12") "DATE" (ExpectEquals (FieldDate (Finite dateValue)))
+  , successCase "TIME" (quoted "14:30:15.123456") "TIME" (ExpectEquals (FieldTime timeValue))
+  , successCase "INTERVAL" (quoted "1 day") "INTERVAL" (ExpectEquals (FieldInterval intervalValue))
+  , successCase "HUGEINT" (quotedValue hugeIntLiteral) "HUGEINT" (ExpectEquals (FieldHugeInt hugeIntLiteral))
+  , successCase "UHUGEINT" (quotedValue uHugeIntLiteral) "UHUGEINT" (ExpectEquals (FieldUHugeInt uHugeIntLiteral))
+  , successCase "VARCHAR" (quoted varcharText) "VARCHAR" (ExpectEquals (FieldText varcharText))
+  , successCase "BLOB" (quoted "duckdb") "BLOB" (ExpectEquals (FieldBlob blobValue))
+  , successCase "DECIMAL" (quoted "12345.6789") "DECIMAL(18,4)" (ExpectEquals (FieldDecimal decimalValue))
+  , successCase "TIMESTAMP_S" (quoted "2024-01-02 03:04:05") "TIMESTAMP_S" (ExpectEquals (FieldTimestamp (Finite timestampLocalTimeSeconds)))
+  , successCase
+      "TIMESTAMP_MS"
+      (quoted "2024-01-02 03:04:05.123")
+      "TIMESTAMP_MS"
+      (ExpectEquals (FieldTimestamp (Finite timestampLocalTimeMillis)))
+  , successCase
+      "TIMESTAMP_NS"
+      (quoted "2024-01-02 03:04:05.123456789")
+      "TIMESTAMP_NS"
+      (ExpectEquals (FieldTimestamp (Finite timestampLocalTimeNanos)))
+  , successCase "ENUM" (quoted "beta") "ENUM('alpha','beta')" (ExpectEquals (FieldEnum 1 "beta"))
+  , successCase "LIST" (quoted "[1,2,3]") "INTEGER[]" (ExpectEquals (FieldList listElements))
+  , successDirect "MAP" "MAP(['a','b'], [1,2])" (expectMapEntries mapPairs)
+  , successCase "TIMETZ" (quoted "03:04:05+02:30") "TIME WITH TIME ZONE" (ExpectEquals (FieldTimeTZ timeWithZoneValue))
+  , successCase
+      "TIMESTAMPTZ"
+      (quoted "2024-01-02 03:04:05+02:30")
+      "TIMESTAMP WITH TIME ZONE"
+      (ExpectEquals (FieldTimestampTZ (Finite timestampTzUtc)))
+  , successCase "BIGNUM" (quoted bigNumLiteralText) "BIGNUM" (ExpectEquals (FieldBigNum (BigNum bigNumLiteral)))
+  , successCase "UUID" (quoted $ UUID.toText uuid) "UUID" (ExpectEquals (FieldUUID uuid))
+  , successCase "BIT" (quoted $ Text.pack $ show bits) "BIT" (ExpectEquals (FieldBit bits))
+  , successCase "ARRAY" (quoted "[1,2,3]") "INTEGER[3]" (ExpectEquals (FieldArray arrayElements))
+  , successCase "TIME_NS" (quoted "03:04:05.123456789") "TIME_NS" (ExpectEquals (FieldTime (TimeOfDay 3 4 5.123456789)))
+  , successDirect "STRUCT" "{'a': 1, 'b': 2}" (expectStruct structFields)
+  , successDirect "UNION" "CAST(union_value(a := 42) AS UNION(a INTEGER, b VARCHAR))" (expectUnion 0 (Text.pack "a") (FieldInt32 42))
+  , -- These can never surface from a query, only internally.
+    failCaseOK "ANY" (quoted "1") "ANY" (expectSQLErrorContaining "ANY")
+  , failCaseOK "STRING_LITERAL" (quoted literalText) "STRING_LITERAL" (expectSQLErrorContaining "STRING_LITERAL")
+  , failCaseOK "INTEGER_LITERAL" (quoted "123") "INTEGER_LITERAL" (expectSQLErrorContaining "INTEGER_LITERAL")
+  , failCaseOK "INVALID" "0" "INVALID" (expectSQLErrorContaining "INVALID")
+  , failCaseOK "SQLNULL" "NULL" "SQLNULL" (expectSQLErrorContaining "SQLNULL")
+  ]
+  where
+    bits = BitString 7 $ BS.pack [1, 255]
+    quoted t = Text.concat ["'", t, "'"]
+    quotedValue v = quoted (valueText v)
+    valueText :: (Show a) => a -> Text.Text
+    valueText = Text.pack . show
+    successCase label value ty expectation =
+      DuckDBCastCase
+        { castLabel = label
+        , castExpression = CastExpression value ty
+        , castExpectation = expectation
+        }
+    successDirect label expr expectation =
+      DuckDBCastCase
+        { castLabel = label
+        , castExpression = DirectExpression expr
+        , castExpectation = expectation
+        }
+    failCaseOK label value ty expectation =
+      DuckDBCastCase
+        { castLabel = label
+        , castExpression = CastExpression value ty
+        , castExpectation = expectation
+        }
+    expectMapEntries expectedPairs =
+      ExpectSatisfies $
+        \case
+          FieldMap actualPairs ->
+            let normalize = sortOn (mapKey . fst)
+                mapKey (FieldText txt) = txt
+                mapKey other = Text.pack (show other)
+            in  assertEqual "map entries" (normalize expectedPairs) (normalize actualPairs)
+          other ->
+            assertFailure ("expected FieldMap, but saw " <> show other)
+    structFields =
+      [ StructField{structFieldName = Text.pack "a", structFieldValue = FieldInt32 1}
+      , StructField{structFieldName = Text.pack "b", structFieldValue = FieldInt32 2}
+      ]
+    expectStruct expectedFields =
+      ExpectSatisfies $
+        \case
+          FieldStruct StructValue{structValueFields, structValueTypes, structValueIndex} -> do
+            let actualFields = elems structValueFields
+                actualTypes = elems structValueTypes
+                expectedIndex = Map.fromList (zip (map structFieldName expectedFields) [0 ..])
+                typeNames = map structFieldName actualTypes
+            assertEqual "struct field names" (map structFieldName expectedFields) (map structFieldName actualFields)
+            assertEqual "struct field values" (map structFieldValue expectedFields) (map structFieldValue actualFields)
+            assertEqual "struct type field names" (map structFieldName expectedFields) typeNames
+            assertEqual "struct index map" expectedIndex structValueIndex
+          other ->
+            assertFailure ("expected FieldStruct, but saw " <> show other)
+    expectUnion expectedIndex expectedLabel expectedPayload =
+      ExpectSatisfies $
+        \case
+          FieldUnion UnionValue{unionValueIndex, unionValueLabel, unionValuePayload, unionValueMembers} -> do
+            assertEqual "union tag index" expectedIndex unionValueIndex
+            assertEqual "union tag label" expectedLabel unionValueLabel
+            assertEqual "union payload" expectedPayload unionValuePayload
+            let actualMembers = elems unionValueMembers
+                expectedMembers = [Text.pack "a", Text.pack "b"]
+            assertEqual "union member names" expectedMembers (map unionMemberName actualMembers)
+          other ->
+            assertFailure ("expected FieldUnion, but saw " <> show other)
+    expectSQLErrorContaining :: Text.Text -> DuckDBExpectation
+    expectSQLErrorContaining needle =
+      ExpectException $ \err ->
+        case fromException err :: Maybe SQLError of
+          Just sqlErr ->
+            let message = sqlErrorMessage sqlErr
+            in  assertBool
+                  ("expected SQLError containing " <> Text.unpack needle <> ", but saw: " <> Text.unpack message)
+                  (Text.isInfixOf needle message)
+          Nothing ->
+            assertFailure ("expected SQLError, but saw " <> displayException err)
+    bsFromString :: String -> BS.ByteString
+    bsFromString = BS.pack . map (fromIntegral . fromEnum)
+    secondsWithFraction :: Integer -> Integer -> Integer -> Rational
+    secondsWithFraction whole numerator denominator =
+      fromIntegral whole + numerator % denominator
+    tinyIntValue :: Int8
+    tinyIntValue = 42
+    smallIntValue :: Int16
+    smallIntValue = 32000
+    intValue :: Int32
+    intValue = 2147483647
+    bigIntValue :: Int64
+    bigIntValue = 9223372036854775807
+    uTinyValue :: Word8
+    uTinyValue = 200
+    uSmallValue :: Word16
+    uSmallValue = 60000
+    uIntValue :: Word32
+    uIntValue = maxBound
+    uBigValue :: Word64
+    uBigValue = maxBound
+    floatValue :: Float
+    floatValue = 3.25
+    doubleValue :: Double
+    doubleValue = 2.5
+    timestampDay = fromGregorian 2024 1 2
+    timestampLocalTimeMicros =
+      LocalTime timestampDay (TimeOfDay 3 4 (fromRational (secondsWithFraction 5 123456 1000000)))
+    timestampLocalTimeSeconds =
+      LocalTime timestampDay (TimeOfDay 3 4 5)
+    timestampLocalTimeMillis =
+      LocalTime timestampDay (TimeOfDay 3 4 (fromRational (secondsWithFraction 5 123 1000)))
+    timestampLocalTimeNanos =
+      LocalTime timestampDay (TimeOfDay 3 4 (fromRational (secondsWithFraction 5 123456789 1000000000)))
+    dateValue = fromGregorian 2024 10 12
+    timeValue =
+      TimeOfDay 14 30 (fromRational (secondsWithFraction 15 123456 1000000))
+    intervalValue =
+      IntervalValue{intervalMonths = 0, intervalDays = 1, intervalMicros = 0}
+    decimalValue =
+      DecimalValue{decimalWidth = 18, decimalScale = 4, decimalInteger = 123456789}
+    listElements =
+      [FieldInt32 1, FieldInt32 2, FieldInt32 3]
+    arrayElements =
+      listArray (0, 2) listElements
+    mapPairs =
+      [ (FieldText (Text.pack "a"), FieldInt32 1)
+      , (FieldText (Text.pack "b"), FieldInt32 2)
+      ]
+    uuid :: UUID.UUID
+    uuid = fromJust $ UUID.fromText "123e4567-e89b-12d3-a456-426614174000"
+    timeWithZoneValue =
+      TimeWithZone{timeWithZoneTime = TimeOfDay 3 4 5, timeWithZoneOffsetSeconds = 9000}
+    timestampTzUtc =
+      UTCTime timestampDay (secondsToDiffTime 2045)
+    bigNumLiteral :: Integer
+    bigNumLiteral = 1234567890123456789012345678901234567890
+    bigNumLiteralText = valueText bigNumLiteral
+    varcharText :: Text.Text
+    varcharText = "Hello, DuckDB"
+    blobValue = bsFromString "duckdb"
+    hugeIntLiteral :: Integer
+    hugeIntLiteral = (2 ^ (120 :: Int)) + 123456789
+    uHugeIntLiteral :: Integer
+    uHugeIntLiteral = (2 ^ (128 :: Int)) - 1
+    literalText :: Text.Text
+    literalText = "literal"
+
+typeTests :: TestTree
+typeTests =
+  testGroup
+    "types"
+    [ duckdbTypeCastTests
+    , testCase "round-trips date/time/timestamp" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE temporals (d DATE, t TIME, ts TIMESTAMP)"
+          let dayVal = fromGregorian 2024 10 12
+              timeVal = TimeOfDay 14 30 15.123456
+              tsVal = LocalTime dayVal timeVal
+          _ <- execute conn "INSERT INTO temporals VALUES (?, ?, ?)" (dayVal, timeVal, tsVal)
+          [(dRes, tRes, tsRes)] <- query_ conn "SELECT d, t, ts FROM temporals"
+          assertEqual "date round-trip" dayVal dRes
+          assertEqual "time round-trip" timeVal tRes
+          assertEqual "timestamp round-trip" tsVal tsRes
+          -- A TIMESTAMP does not read as UTCTime. AT TIME ZONE 'UTC' gives the instant in UTC.
+          [Only utcRes] <- query_ conn "SELECT ts::TIMESTAMP AT TIME ZONE 'UTC' FROM temporals" :: IO [Only UTCTime]
+          assertEqual "timestamp at UTC" (localTimeToUTC utc tsVal) utcRes
+          (try (query_ conn "SELECT ts FROM temporals" :: IO [Only UTCTime])) >>= \case
+            Left SQLError{sqlErrorMessage} -> sqlErrorMessage @?= "duckdb-simple: column ts has type TIMESTAMP but expected UTCTime"
+            Right rows -> assertFailure ("expected Incompatible, got " <> show rows)
+    , testCase "round-trips blob payloads" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE blobs (payload BLOB)"
+          let payload = BS.pack [0, 1, 2, 3, 255]
+          _ <- execute conn "INSERT INTO blobs VALUES (?)" (Only payload)
+          [Only blobOut] <- query_ conn "SELECT payload FROM blobs"
+          assertEqual "blob round-trip" payload blobOut
+    , testCase "round-trips unsigned integers" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE unsigneds (u8 UTINYINT, u16 USMALLINT, u32 UINTEGER, u64 UBIGINT)"
+          let w8 = 200 :: Word8
+              w16 = 60000 :: Word16
+              w32 = 4000000000 :: Word32
+              w64 = maxBound :: Word64
+          _ <- execute conn "INSERT INTO unsigneds VALUES (?, ?, ?, ?)" (w8, w16, w32, w64)
+          [(r8, r16, r32, r64)] <- query_ conn "SELECT u8, u16, u32, u64 FROM unsigneds"
+          assertEqual "Word8 round-trip" w8 r8
+          assertEqual "Word16 round-trip" w16 r16
+          assertEqual "Word32 round-trip" w32 r32
+          assertEqual "Word64 round-trip" w64 r64
+          [Only (asWord :: Word)] <- query_ conn "SELECT u64 FROM unsigneds"
+          assertEqual "Word from UBIGINT" (fromIntegral w64) asWord
+    , testCase "round-trips fixed-length arrays" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE arrays (vals INTEGER[3])"
+          let inputs =
+                [ sized [1, 2, 3]
+                , sized [4, 5, 6]
+                ]
+          _ <- executeMany conn "INSERT INTO arrays VALUES (?)" (Only <$> inputs)
+          rows <- query_ conn "SELECT vals FROM arrays ORDER BY rowid" :: IO [Only (SizedArray 3 Int)]
+          let expected =
+                fmap Only inputs
+          assertEqual "array round-trip" expected rows
+    , testCase "decodes huge integers as Integer" $
+        withConnection ":memory:" \conn -> do
+          let hugeValue = 170141183460469231731687303715884105727 :: Integer
+          [Only (hugeOut :: Integer)] <-
+            query_ conn "SELECT 170141183460469231731687303715884105727::HUGEINT"
+          assertEqual "hugeint" hugeValue hugeOut
+    , testCase "decodes huge integers as Natural" $
+        withConnection ":memory:" \conn -> do
+          let hugeValue = 170141183460469231731687303715884105727 :: Natural
+          [Only (naturalOut :: Natural)] <-
+            query_ conn "SELECT 170141183460469231731687303715884105727::HUGEINT"
+          assertEqual "hugeint natural" hugeValue naturalOut
+    , testCase "decodes unsigned huge integers as Natural" $
+        withConnection ":memory:" \conn -> do
+          let uhValue = 170141183460469231731687303715884105727 :: Natural
+          [Only (naturalOut :: Natural)] <-
+            query_ conn "SELECT 170141183460469231731687303715884105727::UHUGEINT"
+          assertEqual "uhugeint natural" uhValue naturalOut
+    , testCase "FromField Integer consumes FieldBigNum" $ do
+        let original = 1234567899876543210123456789 :: Integer
+            bigField =
+              Field
+                { fieldName = "big"
+                , fieldIndex = 0
+                , fieldValue = FieldBigNum (BigNum original)
+                , fieldType = pure (LogicalTypeScalar LogicalTypeIdBigNum)
+                }
+        runConversion (fromField bigField :: Conversion Integer) >>= \case
+          Ok result -> assertEqual "FieldBigNum Integer" original result
+          Errors err -> assertFailure ("unexpected parse failure: " <> show err)
+    , testCase "FromField Natural rejects negative FieldBigNum" $ do
+        let bigValue = BigNum (-5)
+            bigField =
+              Field
+                { fieldName = "big"
+                , fieldIndex = 0
+                , fieldValue = FieldBigNum bigValue
+                , fieldType = pure (LogicalTypeScalar LogicalTypeIdBigNum)
+                }
+        runConversion (fromField bigField :: Conversion Natural) >>= \case
+          Errors _ -> pure ()
+          Ok result -> assertFailure ("expected failure, got " <> show result)
+    , testCase "BigNum conversions round-trip Integer" $ do
+        let original = (2 ^ (200 :: Int)) + 8675309 :: Integer
+            converted = toBigNumBytes original
+        assertEqual "round-trip Integer" original (fromBigNumBytes converted)
+    , testProperty "fromBigNumBytes . toBigNumBytes is identity" \(n :: Integer) ->
+        fromBigNumBytes (toBigNumBytes n) === n
+    , testCase "selects BIGNUM values as BigNum" $
+        withConnection ":memory:" \conn -> do
+          rows <- concat <$> mapM (\bv -> query_ conn $ fromString $ "SELECT CAST('" <> show bv <> "' AS BIGNUM)") bigNumValues
+          assertEqual "BIGNUM results" (fmap (Only . BigNum) bigNumValues) rows
+    , testCase "round-trips BIGNUM values through the database" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE bignum_roundtrip (val BIGNUM)"
+          _ <- executeMany conn "INSERT INTO bignum_roundtrip VALUES (?)" (fmap (Only . BigNum) bigNumValues)
+          rows <- query_ conn "SELECT val FROM bignum_roundtrip ORDER BY rowid" :: IO [Only Integer]
+          assertEqual "BIGNUM round-trip" (fmap Only bigNumValues) rows
+    , testCase "duckdbColumnType reports BIGNUM for Integer" $
+        assertEqual
+          "duckdbColumnType Integer"
+          (Text.pack "BIGNUM")
+          (duckdbColumnType (Proxy @Integer))
+    , testCase "duckdbColumnType preserves Maybe parameter" $
+        assertEqual
+          "duckdbColumnType Maybe Word16"
+          (Text.pack "USMALLINT")
+          (duckdbColumnType (Proxy @(Maybe Word16)))
+    , testCase "decodes interval components" $
+        withConnection ":memory:" \conn -> do
+          [Only intervalVal] <-
+            query_ conn "SELECT INTERVAL '2 months 3 days 04:05:06.007008'"
+          let IntervalValue{intervalMonths, intervalDays, intervalMicros} = intervalVal
+              expectedMicros =
+                (((4 * 60 + 5) * 60) + 6) * 1000000 + 7008
+          assertEqual "interval months" 2 intervalMonths
+          assertEqual "interval days" 3 intervalDays
+          assertEqual "interval micros" expectedMicros intervalMicros
+    , testCase "decodes decimals via Double conversion" $
+        withConnection ":memory:" \conn -> do
+          [Only decimalAsDouble] <-
+            (query_ conn "SELECT CAST(12345.6789 AS DECIMAL(18,4))" :: IO [Only Double])
+          let diff = abs (decimalAsDouble - 12345.6789)
+          assertBool
+            ("decimal as double: " <> show diff)
+            (diff < 1e-4)
+    , testCase "decodes time with time zone" $
+        withConnection ":memory:" \conn -> do
+          [Only tzVal] <- query_ conn "SELECT TIMETZ '14:30:15+02:30'"
+          let expectedTime = TimeOfDay 14 30 15
+          assertEqual "timetz time" expectedTime (timeWithZoneTime tzVal)
+          assertEqual "timetz offset" 9000 (timeWithZoneOffsetSeconds tzVal)
+    , testCase "decodes list columns into Haskell lists" $
+        withConnection ":memory:" \conn -> do
+          [Only (listOut :: [Int])] <-
+            query_ conn "SELECT LIST_VALUE(1, 2, 3)::INTEGER[]"
+          assertEqual "list decode" [1, 2, 3] listOut
+    , testCase "decodes map columns into strict Map" $
+        withConnection ":memory:" \conn -> do
+          [Only (mapOut :: Map.Map Text.Text Int)] <-
+            query_ conn "SELECT MAP(['a', 'b']::TEXT[], [1, 2]::INTEGER[])"
+          let expected = Map.fromList [(Text.pack "a", 1), (Text.pack "b", 2)]
+          assertEqual "map decode" expected mapOut
+    , testCase "decodes timestamp with time zone as UTC" $
+        withConnection ":memory:" \conn -> do
+          [Only utcVal] <-
+            (query_ conn "SELECT TIMESTAMPTZ '2024-10-12 14:30:15+02:30'" :: IO [Only UTCTime])
+          let expected =
+                UTCTime
+                  (fromGregorian 2024 10 12)
+                  (timeOfDayToTime (TimeOfDay 12 0 15))
+          assertEqual "timestamptz utc" expected utcVal
+    , testCase "custom FieldParser enforces invariants" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE nonempty (name TEXT)"
+          _ <- execute conn "INSERT INTO nonempty VALUES (?)" (Only (Text.pack "okay"))
+          rows <- query_ conn "SELECT name FROM nonempty" :: IO [Only NonEmptyText]
+          assertEqual "non-empty success" [Only (NonEmptyText (Text.pack "okay"))] rows
+          _ <- execute conn "INSERT INTO nonempty VALUES (?)" (Only (Text.pack ""))
+          assertThrows
+            (query_ conn "SELECT name FROM nonempty" :: IO [Only NonEmptyText])
+            (Text.isInfixOf "NonEmptyText requires a non-empty string" . sqlErrorMessage)
+    , testCase "round-trips uuid payloads" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE uuids (uuid UUID)"
+          let uuidTexts =
+                [ "123e4567-e89b-12d3-a456-426614174000"
+                , "923e4567-e89b-12d3-a456-426614174000"
+                , "ffffffff-ffff-ffff-ffff-ffffffffffff"
+                ]
+              maybeUUIDs = traverse UUID.fromText uuidTexts
+          uuids <-
+            case maybeUUIDs of
+              Nothing -> assertFailure "invalid UUID literal in test data" >> pure []
+              Just parsed -> pure parsed
+          _ <- executeMany conn "INSERT INTO uuids VALUES (?)" (fmap Only uuids)
+          rows <- query_ conn "SELECT uuid FROM uuids ORDER BY rowid" :: IO [Only UUID.UUID]
+          assertEqual "uuid round-trip" (fmap Only uuids) rows
+    , testCase "round-trips bitstring payloads" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE bits (bit BIT)"
+          let bitValues =
+                [ bsFromBool [True]
+                , bsFromBool [False, False, False, True, True, True, False, True, False]
+                , bsFromBool [False, False, False, False, True, True, True, False, True, False]
+                , bsFromBool [True, False, False, False, True, True, True, False, True, False]
+                ]
+          _ <- executeMany conn "INSERT INTO bits VALUES (?)" (fmap Only bitValues)
+          rows <- query_ conn "SELECT bit FROM bits ORDER BY rowid" :: IO [Only BitString]
+          assertEqual "bit round-trip" (fmap Only bitValues) rows
+    , testCase "round-trips struct and union parameters" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE struct_union (s STRUCT(a INT, b INT), u UNION(a INT, b VARCHAR))"
+          [(structVal, unionVal)] <-
+            query_ conn "SELECT {'a': 1, 'b': 2}, CAST(union_value(a := 42) AS UNION(a INTEGER, b VARCHAR))"
+              :: IO [(StructValue FieldValue, UnionValue FieldValue)]
+          _ <- execute conn "INSERT INTO struct_union VALUES (?, ?)" (structVal, unionVal)
+          rows <- query_ conn "SELECT s, u FROM struct_union" :: IO [(StructValue FieldValue, UnionValue FieldValue)]
+          assertEqual "struct/union round-trip" [(structVal, unionVal)] rows
+    , testCase "generic struct into database" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE generic_struct (payload STRUCT(grId INT, grName TEXT))"
+          let records = [GenericRecord 1 (Text.pack "alpha"), GenericRecord 2 (Text.pack "beta")]
+              structParams = traverse genericToStructValue records
+          case structParams of
+            Nothing -> assertFailure "expected struct encoding"
+            Just structs -> do
+              _ <- executeMany conn "INSERT INTO generic_struct VALUES (?)" (map Only structs)
+              rows <- query_ conn "SELECT payload FROM generic_struct ORDER BY payload.grId" :: IO [Only (StructValue FieldValue)]
+              let unwrap (Only s) = s
+              roundTripped <- runConversion (traverse (genericFromFieldValue . FieldStruct . unwrap) rows)
+              roundTripped @?= Ok records
+    , testCase "generic struct encode/decode" $ do
+        let rec = GenericRecord 42 (Text.pack "duck")
+        case genericToStructValue rec of
+          Just structVal -> do
+            map structFieldName (elems (structValueFields structVal)) @?= [Text.pack "grId", Text.pack "grName"]
+            map structFieldValue (elems (structValueFields structVal)) @?= [FieldInt64 42, FieldText (Text.pack "duck")]
+            runConversion (genericFromFieldValue (FieldStruct structVal)) >>= (@?= Ok rec)
+          Nothing -> assertFailure "expected struct encoding"
+    , testCase "generic union encode/decode" $ do
+        let sumVal = SumBool True
+        case genericToFieldValue sumVal of
+          FieldUnion uv -> do
+            map unionMemberName (elems (unionValueMembers uv))
+              @?= [ Text.pack "SumInt"
+                  , Text.pack "SumBool"
+                  , Text.pack "SumPair"
+                  ]
+            unionValueLabel uv @?= Text.pack "SumBool"
+            runConversion (genericFromFieldValue (FieldUnion uv)) >>= (@?= Ok sumVal)
+          other -> assertFailure ("expected FieldUnion, got " <> show other)
+    , testCase "generic union complex constructor" $ do
+        let sumVal = SumPair 7 (Text.pack "duck")
+        case genericToFieldValue sumVal of
+          FieldUnion uv -> do
+            unionValueLabel uv @?= Text.pack "SumPair"
+            case unionValuePayload uv of
+              FieldStruct StructValue{structValueFields} -> do
+                map structFieldName (elems structValueFields) @?= [Text.pack "field1", Text.pack "field2"]
+                map structFieldValue (elems structValueFields)
+                  @?= [FieldInt64 7, FieldText (Text.pack "duck")]
+              other -> assertFailure ("expected struct payload, got " <> show other)
+            runConversion (genericFromFieldValue (FieldUnion uv)) >>= (@?= Ok sumVal)
+          other -> assertFailure ("expected FieldUnion, got " <> show other)
+    , testCase "deriving via generic struct round-trip" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE via_users (payload STRUCT(vuId BIGINT, vuName TEXT))"
+          let users = [ViaUser 10 (Text.pack "alice"), ViaUser 11 (Text.pack "bob")]
+          _ <- executeMany conn "INSERT INTO via_users VALUES (?)" (map Only users)
+          rows <- query_ conn "SELECT payload FROM via_users ORDER BY payload.vuId" :: IO [Only ViaUser]
+          rows @?= map Only users
+    , testCase "deriving via generic union round-trip" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE via_shapes (shape UNION(ViaCircle STRUCT(field1 DOUBLE), ViaSquare STRUCT(field1 DOUBLE)))"
+          let shapes = [ViaCircle 1.5, ViaSquare 3.0]
+          _ <- executeMany conn "INSERT INTO via_shapes VALUES (?)" (map Only shapes)
+          rows <- query_ conn "SELECT shape FROM via_shapes ORDER BY rowid" :: IO [Only ViaShape]
+          rows @?= map Only shapes
+    , testCase "generic enum payload is a STRUCT without fields" $ do
+        case genericToFieldValue EnumRed of
+          FieldUnion uv -> do
+            unionValuePayload uv @?= FieldStruct (StructValue (listArray (0, -1) []) (listArray (0, -1) []) Map.empty)
+            runConversion (genericFromFieldValue (FieldUnion uv)) >>= (@?= Ok EnumRed)
+          other -> assertFailure ("expected FieldUnion, got " <> show other)
+    , -- Edge case tests
+      testCase "struct with multiple basic fields" $ do
+        -- Test a struct with multiple fields
+        let twoField = TwoFieldStruct 42 (Text.pack "text")
+        case genericToFieldValue twoField of
+          FieldStruct sv -> do
+            runConversion (genericFromFieldValue (FieldStruct sv)) >>= (@?= Ok twoField)
+          other -> assertFailure ("expected FieldStruct for TwoFieldStruct, got " <> show other)
+    , testCase "large sum type with many constructors" $ do
+        let constructors = [LargeC1 1, LargeC2 2, LargeC3 3, LargeC4 4, LargeC5 5]
+        forM_ constructors $ \val -> do
+          case genericToFieldValue val of
+            FieldUnion uv -> do
+              runConversion (genericFromFieldValue (FieldUnion uv)) >>= (@?= Ok val)
+            other -> assertFailure ("expected FieldUnion, got " <> show other)
+    , testCase "empty struct encodes as a STRUCT without fields" $ do
+        case genericToFieldValue EmptyStruct of
+          FieldStruct structVal -> do
+            elems (structValueFields structVal) @?= []
+            runConversion (genericFromFieldValue (FieldStruct structVal)) >>= (@?= Ok EmptyStruct)
+          other -> assertFailure ("expected a STRUCT without fields for empty struct, got " <> show other)
+    , testCase "empty struct binds as a STRUCT without fields" $
+        withConnection ":memory:" \conn -> do
+          query conn "SELECT typeof(?)" (Only EmptyStruct) >>= (@?= [Only (Text.pack "STRUCT")])
+          rows <- query conn "SELECT ?" (Only EmptyStruct) :: IO [Only FieldValue]
+          case rows of
+            [Only (FieldStruct structVal)] -> elems (structValueFields structVal) @?= []
+            other -> assertFailure ("expected a STRUCT without fields, got " <> show other)
+    , testCase "Just and Nothing of a type without fields stay different in a record" $
+        withConnection ":memory:" \conn -> do
+          let value = OptionalEmpty (Just EmptyStruct) Nothing
+          _ <- execute_ conn "CREATE TABLE optional_empty (r STRUCT(oeFirst STRUCT, oeSecond STRUCT))"
+          _ <- execute conn "INSERT INTO optional_empty VALUES (?)" (Only value)
+          (query_ conn "SELECT r::VARCHAR, r.oeFirst IS NULL, r.oeSecond IS NULL, r FROM optional_empty" :: IO [(Text.Text, Bool, Bool, OptionalEmpty)])
+            >>= (@?= [(Text.pack "{'oeFirst': {}, 'oeSecond': NULL}", False, True, value)])
+    , testCase "a constructor without fields binds the STRUCT without fields as its payload" $
+        withConnection ":memory:" \conn -> do
+          forM_ [(Counted 5, Text.pack "Counted"), (Uncounted, Text.pack "Uncounted")] \(value, tag) ->
+            query conn "SELECT union_tag(?)::VARCHAR" (Only value) >>= (@?= [Only tag])
+          _ <- execute_ conn "CREATE TABLE tallies (s UNION(Counted STRUCT(field1 BIGINT), Uncounted STRUCT))"
+          _ <- executeMany conn "INSERT INTO tallies VALUES (?)" [Only (Counted 5), Only Uncounted]
+          (query_ conn "SELECT union_tag(s)::VARCHAR, s::VARCHAR, s FROM tallies ORDER BY rowid" :: IO [(Text.Text, Text.Text, Tally)])
+            >>= (@?= [(Text.pack "Counted", Text.pack "{'field1': 5}", Counted 5), (Text.pack "Uncounted", Text.pack "{}", Uncounted)])
+    , testCase "the NULL of version 0.3 for a type without fields decodes but does not equal a new parameter" $
+        withConnection ":memory:" \conn -> do
+          -- Version 0.3 wrote NULL in place of the STRUCT without fields.
+          runConversion (genericFromFieldValue FieldNull) >>= (@?= Ok EmptyStruct)
+          case genericToFieldValue Uncounted of
+            FieldUnion uv -> do
+              let oldValue = uv{unionValuePayload = FieldNull}
+              runConversion (genericFromFieldValue (FieldUnion oldValue)) >>= (@?= Ok Uncounted)
+              _ <- execute_ conn "CREATE TABLE old_tallies (v UNION(Counted STRUCT(field1 BIGINT), Uncounted STRUCT))"
+              _ <- execute conn "INSERT INTO old_tallies VALUES (?)" (Only oldValue)
+              (query_ conn "SELECT v FROM old_tallies" :: IO [Only Tally]) >>= (@?= [Only Uncounted])
+              (query conn "SELECT count(*) FROM old_tallies WHERE v = ?" (Only Uncounted) :: IO [Only Int64]) >>= (@?= [Only 0])
+              _ <- execute conn "INSERT INTO old_tallies VALUES (?)" (Only Uncounted)
+              (query conn "SELECT count(*) FROM old_tallies WHERE v = ?" (Only Uncounted) :: IO [Only Int64]) >>= (@?= [Only 1])
+            other -> assertFailure ("expected FieldUnion, got " <> show other)
+          case genericToFieldValue (WithEmpty 7 EmptyStruct) of
+            FieldStruct sv -> do
+              let oldField item = if structFieldName item == Text.pack "weEmpty" then item{structFieldValue = FieldNull} else item
+                  oldValue = sv{structValueFields = fmap oldField (structValueFields sv)}
+              _ <- execute_ conn "CREATE TABLE old_with_empty (r STRUCT(weId BIGINT, weEmpty STRUCT))"
+              _ <- execute conn "INSERT INTO old_with_empty VALUES (?)" (Only oldValue)
+              (query_ conn "SELECT r FROM old_with_empty" :: IO [Only WithEmpty]) >>= (@?= [Only (WithEmpty 7 EmptyStruct)])
+              (query conn "SELECT count(*) FROM old_with_empty WHERE r = ?" (Only (WithEmpty 7 EmptyStruct)) :: IO [Only Int64]) >>= (@?= [Only 0])
+              _ <- execute conn "INSERT INTO old_with_empty VALUES (?)" (Only (WithEmpty 7 EmptyStruct))
+              (query conn "SELECT count(*) FROM old_with_empty WHERE r = ?" (Only (WithEmpty 7 EmptyStruct)) :: IO [Only Int64]) >>= (@?= [Only 1])
+            other -> assertFailure ("expected FieldStruct, got " <> show other)
+    , testCase "a record field of a type without fields round trips" $
+        withConnection ":memory:" \conn -> do
+          let value = WithEmpty 7 EmptyStruct
+          _ <- execute_ conn "CREATE TABLE with_empty (r STRUCT(weId BIGINT, weEmpty STRUCT))"
+          _ <- execute conn "INSERT INTO with_empty VALUES (?)" (Only value)
+          (query_ conn "SELECT r::VARCHAR, r FROM with_empty" :: IO [(Text.Text, WithEmpty)])
+            >>= (@?= [(Text.pack "{'weId': 7, 'weEmpty': {}}", value)])
+    , testCase "struct with Maybe fields" $ do
+        let withJust = OptionalFields (Just 42) (Just (Text.pack "text"))
+            withNothing = OptionalFields Nothing Nothing
+        case (genericToFieldValue withJust, genericToFieldValue withNothing) of
+          (FieldStruct sv1, FieldStruct sv2) -> do
+            runConversion (genericFromFieldValue (FieldStruct sv1)) >>= (@?= Ok withJust)
+            runConversion (genericFromFieldValue (FieldStruct sv2)) >>= (@?= Ok withNothing)
+          (other1, other2) -> assertFailure ("expected FieldStruct, got " <> show (other1, other2))
+    , -- Error case tests
+      testCase "decode wrong field type fails" $ do
+        let wrongType = FieldInt32 42 -- Trying to decode as GenericRecord
+        runConversion (genericFromFieldValue wrongType :: Conversion GenericRecord) >>= \case
+          Errors err -> assertBool "error mentions STRUCT" (Text.pack "STRUCT" `Text.isInfixOf` Text.pack (show err))
+          Ok _ -> assertFailure "expected decode error for wrong type"
+    , testCase "decode union as struct fails" $ do
+        case genericToFieldValue (SumInt 42) of
+          FieldUnion uv -> do
+            runConversion (genericFromFieldValue (FieldUnion uv) :: Conversion GenericRecord) >>= \case
+              Errors err -> assertBool "error mentions product type" (Text.pack "product type" `Text.isInfixOf` Text.pack (show err))
+              Ok _ -> assertFailure "expected decode error"
+          other -> assertFailure ("expected FieldUnion, got " <> show other)
+    , testCase "decode struct as union fails" $ do
+        case genericToFieldValue (GenericRecord 1 (Text.pack "test")) of
+          FieldStruct sv -> do
+            runConversion (genericFromFieldValue (FieldStruct sv) :: Conversion GenericSum) >>= \case
+              Errors err -> assertBool "error mentions sum type" (Text.pack "sum type" `Text.isInfixOf` Text.pack (show err))
+              Ok _ -> assertFailure "expected decode error"
+          other -> assertFailure ("expected FieldStruct, got " <> show other)
+    , testCase "decode struct with wrong field count fails" $
+        withConnection ":memory:" \conn -> do
+          -- Get a real struct with 3 fields from the database
+          _ <- execute_ conn "CREATE TABLE three_field (s STRUCT(a INT, b TEXT, c INT))"
+          [(Only threeField)] <- query_ conn "SELECT {'a': 1, 'b': 'test', 'c': 99}" :: IO [Only (StructValue FieldValue)]
+          -- Try to decode it as GenericRecord which only has 2 fields
+          runConversion (genericFromFieldValue (FieldStruct threeField) :: Conversion GenericRecord) >>= \case
+            Errors err -> assertBool "error mentions extra fields" (Text.pack "extra" `Text.isInfixOf` Text.pack (show err))
+            Ok _ -> assertFailure "expected decode error for extra fields"
+    , testCase "decode union with wrong tag fails" $
+        withConnection ":memory:" \conn -> do
+          -- Get a real union from the database
+          [(Only unionVal)] <-
+            query_ conn "SELECT CAST(union_value(x := 42) AS UNION(x INT, y VARCHAR))" :: IO [Only (UnionValue FieldValue)]
+          -- Manually create a modified version with an out-of-range tag
+          let wrongTag = unionVal{unionValueIndex = 99, unionValueLabel = Text.pack "Invalid"}
+          runConversion (genericFromFieldValue (FieldUnion wrongTag) :: Conversion GenericSum) >>= \case
+            Errors err ->
+              assertBool
+                "error mentions tag or index"
+                (Text.pack "tag" `Text.isInfixOf` Text.pack (show err) || Text.pack "99" `Text.isInfixOf` Text.pack (show err))
+            Ok _ -> assertFailure "expected decode error for wrong tag"
+    ]
+  where
+    -- 7 ^ 2900 has 1,018 magnitude bytes. A value of at most 9 magnitude bytes
+    -- has inline storage.
+    bigNumValues :: [Integer]
+    bigNumValues =
+      [ (2 ^ (200 :: Int)) + 8675309
+      , 0
+      , negate ((2 ^ (180 :: Int)) + 12345)
+      , 7 ^ (2900 :: Int)
+      , negate (7 ^ (2900 :: Int))
+      , 1
+      , -1
+      , 255
+      , 256
+      , -256
+      ]
+
+streamingTests :: TestTree
+streamingTests =
+  testGroup
+    "streaming"
+    [ testCase "fold_ accumulates large result sets" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE stream_fold (n INTEGER)"
+          let rows = fmap Only [1 .. 1000 :: Int]
+          _ <- executeMany conn "INSERT INTO stream_fold VALUES (?)" rows
+          total <- fold_ conn "SELECT n FROM stream_fold ORDER BY n" 0 \acc (Only n) -> pure (acc + n)
+          assertEqual "folded sum" (sum ([1 .. 1000] :: [Int])) total
+    , testCase "fold and foldNamed respect parameters" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE stream_filter (n INTEGER)"
+          let values = fmap Only [1 .. 50 :: Int]
+          _ <- executeMany conn "INSERT INTO stream_filter VALUES (?)" values
+          gtTotal <-
+            fold conn "SELECT n FROM stream_filter WHERE n > ?" (Only (40 :: Int)) 0 $
+              \acc (Only n) -> pure (acc + n)
+          let expected = sum ([41 .. 50] :: [Int])
+          assertEqual "filtered fold sum" expected gtTotal
+          leCount <-
+            foldNamed conn "SELECT n FROM stream_filter WHERE n <= $limit" ["$limit" := (10 :: Int)] 0 $
+              \acc (Only (_ :: Int)) -> pure (acc + 1)
+          assertEqual "foldNamed count" (10 :: Int) leCount
+    , testCase "nextRow streams rows sequentially" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE stream_cursor (n INTEGER)"
+          _ <- executeMany conn "INSERT INTO stream_cursor VALUES (?)" (fmap Only [1 .. 3 :: Int])
+          withStatement conn "SELECT n FROM stream_cursor ORDER BY n" \stmt -> do
+            first <- nextRow stmt
+            second <- nextRow stmt
+            third <- nextRow stmt
+            done <- nextRow stmt
+            assertEqual
+              "cursor iteration"
+              [Just (Only (1 :: Int)), Just (Only 2), Just (Only 3), Nothing]
+              [first, second, third, done]
+    ]
+
+functionsTests :: TestTree
+functionsTests =
+  testGroup
+    "user-defined functions"
+    [ testCase "registers pure scalar function" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "hs_times_two" (\(x :: Int64) -> x * 2)
+          result <- query_ conn "SELECT hs_times_two(21)" :: IO [Only Int64]
+          assertEqual "times_two result" [Only 42] result
+    , testCase "handles nullable arguments and results" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "hs_optional" (\(mx :: Maybe Int64) -> fmap (+ 1) mx)
+          rows <-
+            query_ conn "SELECT hs_optional(x) FROM (VALUES (NULL), (41)) AS t(x)"
+              :: IO [Only (Maybe Int64)]
+          assertEqual "optional results" [Only Nothing, Only (Just 42)] rows
+    , testCase "keeps the SQL types of the arguments of version 0.3" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "hs_id_bool" (id :: Bool -> Bool)
+          createFunction conn "hs_id_double" (id :: Double -> Double)
+          createFunction conn "hs_id_float" (id :: Float -> Float)
+          createFunction conn "hs_id_int" (id :: Int -> Int)
+          createFunction conn "hs_id_int16" (id :: Int16 -> Int16)
+          createFunction conn "hs_id_int32" (id :: Int32 -> Int32)
+          createFunction conn "hs_id_int64" (id :: Int64 -> Int64)
+          createFunction conn "hs_id_maybe" (id :: Maybe Word16 -> Maybe Word16)
+          createFunction conn "hs_id_string" (id :: String -> String)
+          createFunction conn "hs_id_text" (id :: Text.Text -> Text.Text)
+          createFunction conn "hs_id_word" (id :: Word -> Word)
+          createFunction conn "hs_id_word16" (id :: Word16 -> Word16)
+          createFunction conn "hs_id_word32" (id :: Word32 -> Word32)
+          createFunction conn "hs_id_word64" (id :: Word64 -> Word64)
+          query_
+            conn
+            "SELECT parameter_types::VARCHAR FROM duckdb_functions() WHERE function_name LIKE 'hs\\_id\\_%' ESCAPE '\\' ORDER BY function_name"
+            >>= ( @?=
+                    map
+                      Only
+                      [ "[BOOLEAN]" :: Text.Text
+                      , "[DOUBLE]"
+                      , "[FLOAT]"
+                      , "[BIGINT]"
+                      , "[SMALLINT]"
+                      , "[INTEGER]"
+                      , "[BIGINT]"
+                      , "[USMALLINT]"
+                      , "[VARCHAR]"
+                      , "[VARCHAR]"
+                      , "[UBIGINT]"
+                      , "[USMALLINT]"
+                      , "[UINTEGER]"
+                      , "[UBIGINT]"
+                      ]
+                )
+    , testCase "takes an argument of each type with FromField and DuckDBColumnType" $
+        withConnection ":memory:" \conn -> do
+          let user = ViaUser 7 "anna"
+          createFunction conn "hs_arg_int8" (\(x :: Int8) -> fromIntegral x * 2 :: Int64)
+          createFunction conn "hs_arg_integer" (\(x :: Integer) -> Text.pack (show (x * 2)))
+          createFunction conn "hs_arg_bytes" (\(x :: BS.ByteString) -> BS.length x)
+          createFunction conn "hs_arg_uuid" UUID.toText
+          createFunction conn "hs_arg_day" (\(x :: Day) -> Text.pack (show x))
+          createFunction conn "hs_arg_local" (\(x :: LocalTime) -> Text.pack (show x))
+          createFunction conn "hs_arg_utc" (\(x :: UTCTime) -> Text.pack (show x))
+          createFunction conn "hs_arg_list" (\(xs :: [Int64]) -> sum xs)
+          createFunction conn "hs_arg_map" (\(pairs :: Map.Map Text.Text Int64) -> sum (Map.elems pairs))
+          createFunction conn "hs_arg_interval" (\(IntervalValue months days micros) -> Text.pack (show (months, days, micros)))
+          createFunction conn "hs_arg_record" (\(ViaUser identifier name) -> name <> Text.pack (show identifier))
+          createFunction conn "hs_arg_records" (\(users :: [ViaUser]) -> length users)
+          createFunction conn "hs_arg_maybe_record" (\(found :: Maybe ViaUser) -> maybe "none" vuName found)
+          createFunction conn "hs_arg_price" (\(Price DecimalValue{decimalInteger}) -> fromIntegral decimalInteger :: Int64)
+          query_
+            conn
+            "SELECT hs_arg_int8(-3), hs_arg_integer(1267650600228229401496703205376::HUGEINT), hs_arg_bytes('\\x01\\x02'::BLOB), hs_arg_uuid('00000000-0000-0000-0000-000000000001')"
+            >>= (@?= [(-6 :: Int64, Text.pack (show (2 * 2 ^ (100 :: Int) :: Integer)), 2 :: Int, "00000000-0000-0000-0000-000000000001" :: Text.Text)])
+          query_
+            conn
+            "SELECT hs_arg_day(DATE '2026-11-15'), hs_arg_local(TIMESTAMP '2026-11-15 12:34:56'), hs_arg_utc(TIMESTAMPTZ '2026-11-15 12:34:56+00')"
+            >>= (@?= [("2026-11-15" :: Text.Text, "2026-11-15 12:34:56" :: Text.Text, "2026-11-15 12:34:56 UTC" :: Text.Text)])
+          query_ conn "SELECT hs_arg_list([1, 2, 3]), hs_arg_map(MAP {'a': 1, 'b': 2}), hs_arg_interval(INTERVAL '1 month 2 days 3 microseconds')"
+            >>= (@?= [(6 :: Int64, 3 :: Int64, "(1,2,3)" :: Text.Text)])
+          query conn "SELECT hs_arg_record(?), hs_arg_records([?, ?]), hs_arg_maybe_record(?), hs_arg_maybe_record(NULL)" (user, user, user, user)
+            >>= (@?= [("anna7" :: Text.Text, 2 :: Int, "anna" :: Text.Text, "none" :: Text.Text)])
+          query_ conn "SELECT hs_arg_price(1.25)" >>= (@?= [Only (1250 :: Int64)])
+          query_
+            conn
+            "SELECT function_name, parameter_types::VARCHAR FROM duckdb_functions() WHERE function_name IN ('hs_arg_int8', 'hs_arg_integer', 'hs_arg_record', 'hs_arg_records', 'hs_arg_price') ORDER BY function_name"
+            >>= ( @?=
+                    [ ("hs_arg_int8" :: Text.Text, "[TINYINT]" :: Text.Text)
+                    , ("hs_arg_integer", "[HUGEINT]")
+                    , ("hs_arg_price", "['DECIMAL(18,3)']")
+                    , ("hs_arg_record", "['STRUCT(vuId BIGINT, vuName VARCHAR)']")
+                    , ("hs_arg_records", "['STRUCT(vuId BIGINT, vuName VARCHAR)[]']")
+                    ]
+                )
+    , testCase "a UTCTime argument with a TIMESTAMP value gets the cast of DuckDB to TIMESTAMPTZ" $
+        withConnection ":memory:" \conn -> do
+          -- DuckDB casts the argument to the declared TIMESTAMPTZ with the
+          -- TimeZone setting of the session. The function reads that instant.
+          createFunction conn "hs_arg_utc_text" (\(x :: UTCTime) -> Text.pack (show x))
+          _ <- execute_ conn "SET TimeZone = 'Pacific/Auckland'"
+          query_ conn "SELECT hs_arg_utc_text(TIMESTAMP '2024-01-02 03:04:05'), (TIMESTAMP '2024-01-02 03:04:05')::TIMESTAMPTZ"
+            >>= (@?= [("2024-01-01 14:04:05 UTC" :: Text.Text, UTCTime (fromGregorian 2024 1 1) (secondsToDiffTime 50645))])
+    , testCase "declares the SQL type of each result type" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "hs_res_bool" True
+          createFunction conn "hs_res_int" (1 :: Int)
+          createFunction conn "hs_res_int8" (1 :: Int8)
+          createFunction conn "hs_res_int16" (1 :: Int16)
+          createFunction conn "hs_res_int32" (1 :: Int32)
+          createFunction conn "hs_res_int64" (1 :: Int64)
+          createFunction conn "hs_res_word" (1 :: Word)
+          createFunction conn "hs_res_word8" (1 :: Word8)
+          createFunction conn "hs_res_word16" (1 :: Word16)
+          createFunction conn "hs_res_word32" (1 :: Word32)
+          createFunction conn "hs_res_word64" (1 :: Word64)
+          createFunction conn "hs_res_float" (1.5 :: Float)
+          createFunction conn "hs_res_double" (1.5 :: Double)
+          createFunction conn "hs_res_text" ("x" :: Text.Text)
+          createFunction conn "hs_res_string" ("x" :: String)
+          createFunction conn "hs_res_io" (pure (1 :: Int16) :: IO Int16)
+          createFunction conn "hs_res_integer" (2 ^ (100 :: Int) :: Integer)
+          createFunction conn "hs_res_bytes" (BS.pack [1, 2])
+          createFunction conn "hs_res_uuid" UUID.nil
+          createFunction conn "hs_res_day" (fromGregorian 2026 11 15)
+          createFunction conn "hs_res_interval" (IntervalValue 1 2 3)
+          createFunction conn "hs_res_amount" (Amount 1.25)
+          forM_
+            [ ("hs_res_bool", "BOOLEAN")
+            , ("hs_res_int", "BIGINT")
+            , ("hs_res_int8", "TINYINT")
+            , ("hs_res_int16", "SMALLINT")
+            , ("hs_res_int32", "INTEGER")
+            , ("hs_res_int64", "BIGINT")
+            , ("hs_res_word", "UBIGINT")
+            , ("hs_res_word8", "UTINYINT")
+            , ("hs_res_word16", "USMALLINT")
+            , ("hs_res_word32", "UINTEGER")
+            , ("hs_res_word64", "UBIGINT")
+            , ("hs_res_float", "FLOAT")
+            , ("hs_res_double", "DOUBLE")
+            , ("hs_res_text", "VARCHAR")
+            , ("hs_res_string", "VARCHAR")
+            , ("hs_res_io", "SMALLINT")
+            , ("hs_res_integer", "HUGEINT")
+            , ("hs_res_bytes", "BLOB")
+            , ("hs_res_uuid", "UUID")
+            , ("hs_res_day", "DATE")
+            , ("hs_res_interval", "INTERVAL")
+            , ("hs_res_amount", "DECIMAL(18,3)")
+            ]
+            \(name, expected) -> query_ conn (Query ("SELECT typeof(" <> name <> "())")) >>= (@?= [Only (expected :: Text.Text)])
+          -- An Integer argument or result is HUGEINT, and a Natural one is UHUGEINT.
+          -- DuckDB casts no BIGNUM or UHUGEINT argument to HUGEINT, and
+          -- toDuckValue raises an error for a result outside the range.
+          createFunction conn "hs_arg_wide" (\(x :: Integer) -> x)
+          assertThrows
+            (query_ conn "SELECT hs_arg_wide('5'::BIGNUM)" :: IO [Only Integer])
+            (Text.isInfixOf "No function matches" . sqlErrorMessage)
+          assertThrows
+            (query_ conn "SELECT hs_arg_wide(5::UHUGEINT)" :: IO [Only Integer])
+            (Text.isInfixOf "No function matches" . sqlErrorMessage)
+          createFunction conn "hs_res_natural" (2 ^ (127 :: Int) :: Natural)
+          createFunction conn "hs_res_wide" (2 ^ (127 :: Int) :: Integer)
+          query_ conn "SELECT typeof(hs_res_natural()), hs_res_natural()" >>= (@?= [("UHUGEINT" :: Text.Text, 2 ^ (127 :: Int) :: Natural)])
+          assertThrows
+            (query_ conn "SELECT hs_res_wide()" :: IO [Only Integer])
+            (\err -> sqlErrorType err == Just ErrorTypeConversion && Text.isInfixOf "is outside the range of HUGEINT" (sqlErrorMessage err))
+          -- DuckDB casts a native result value to the declared type as the SQL cast does.
+          createFunction conn "hs_res_rounded" (Amount 1.2345)
+          createFunction conn "hs_res_too_large" (Amount 1e20)
+          query_ conn "SELECT hs_res_rounded()::VARCHAR, (1.2345::DOUBLE)::DECIMAL(18,3)::VARCHAR"
+            >>= (@?= [("1.235" :: Text.Text, "1.235" :: Text.Text)])
+          assertThrows
+            (query_ conn "SELECT hs_res_too_large()" :: IO [Only Double])
+            (Text.isInfixOf "to DECIMAL(18,3)" . sqlErrorMessage)
+          query_ conn "SELECT hs_res_int8(), hs_res_word16(), hs_res_float(), hs_res_string(), hs_res_integer(), hs_res_amount()::DOUBLE"
+            >>= (@?= [(1 :: Int8, 1 :: Word16, 1.5 :: Float, "x" :: Text.Text, 2 ^ (100 :: Int) :: Integer, 1.25 :: Double)])
+    , testCase "writes nested, record, union, and NULL results" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "hs_res_user" (\(i :: Int64) -> ViaUser i ("u" <> Text.pack (show i)))
+          createFunction conn "hs_res_maybe_user" (\(i :: Int64) -> if odd i then Nothing else Just (ViaUser i "even"))
+          createFunction conn "hs_res_shape" (\(i :: Int64) -> if even i then ViaCircle (fromIntegral i) else ViaSquare 1)
+          createFunction conn "hs_res_list" (\(i :: Int64) -> [0 .. i])
+          createFunction conn "hs_res_map" (\(i :: Int64) -> Map.fromList [(Text.pack (show i), fromIntegral i :: Int16)])
+          createFunction conn "hs_res_maybe_small" (\(i :: Int64) -> if odd i then Nothing else Just (fromIntegral i :: Int16))
+          query_
+            conn
+            "SELECT typeof(hs_res_user(1)), typeof(hs_res_maybe_user(1)), typeof(hs_res_shape(1)), typeof(hs_res_list(1)), typeof(hs_res_map(1)), typeof(hs_res_maybe_small(1))"
+            >>= ( @?=
+                    [
+                      ( "STRUCT(vuId BIGINT, vuName VARCHAR)" :: Text.Text
+                      , "STRUCT(vuId BIGINT, vuName VARCHAR)" :: Text.Text
+                      , "UNION(ViaCircle STRUCT(field1 DOUBLE), ViaSquare STRUCT(field1 DOUBLE))" :: Text.Text
+                      , "BIGINT[]" :: Text.Text
+                      , "MAP(VARCHAR, SMALLINT)" :: Text.Text
+                      , "SMALLINT" :: Text.Text
+                      )
+                    ]
+                )
+          rows <-
+            query_
+              conn
+              "SELECT hs_res_user(i), hs_res_maybe_user(i), hs_res_shape(i), hs_res_list(i), hs_res_map(i), hs_res_maybe_small(i) FROM range(5) t(i) ORDER BY i"
+          rows
+            @?= [ ( ViaUser i ("u" <> Text.pack (show i))
+                  , if odd i then Nothing else Just (ViaUser i "even")
+                  , if even i then ViaCircle (fromIntegral i) else ViaSquare 1
+                  , [0 .. i]
+                  , Map.fromList [(Text.pack (show i), fromIntegral i :: Int16)]
+                  , if odd i then Nothing else Just (fromIntegral i :: Int16)
+                  )
+                | i <- [0 .. 4 :: Int64]
+                ]
+          -- 5000 rows fill more than one chunk. Each odd row is NULL.
+          query_ conn "SELECT count(*) FILTER (hs_res_maybe_user(i) IS NULL), count(*) FILTER (hs_res_maybe_small(i) IS NULL) FROM range(5000) t(i)"
+            >>= (@?= [(2500 :: Int64, 2500 :: Int64)])
+    , testCase "keeps the SQL type of a narrow result in arithmetic" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "hs_small" (id :: Int16 -> Int16)
+          createFunction conn "hs_unsigned" (id :: Word16 -> Word16)
+          -- DuckDB computes SMALLINT * SMALLINT as SMALLINT, and USMALLINT - USMALLINT as USMALLINT.
+          assertThrows
+            (query_ conn "SELECT hs_small(30000) * hs_small(30000)" :: IO [Only Int64])
+            (Text.isInfixOf "Overflow in multiplication of INT16" . sqlErrorMessage)
+          assertThrows
+            (query_ conn "SELECT hs_unsigned(1) - hs_unsigned(2)" :: IO [Only Int64])
+            (Text.isInfixOf "Overflow in subtraction of UINT16" . sqlErrorMessage)
+          query_ conn "SELECT hs_small(30000)::INTEGER * hs_small(30000), hs_unsigned(1)::INTEGER - hs_unsigned(2)"
+            >>= (@?= [(900000000 :: Int64, -1 :: Int64)])
+    , testCase "rejects an argument or result type with no declaration" $
+        withConnection ":memory:" \conn -> do
+          let rejects expected action = assertThrows action (Text.isInfixOf expected . sqlErrorMessage)
+          rejects "hs_bad_struct: argument arg0: StructValue has no static field types" $
+            createFunction conn "hs_bad_struct" (\(_ :: StructValue FieldValue) -> True)
+          rejects "hs_bad_result: result: StructValue has no static field types" $
+            createFunction conn "hs_bad_result" (\(_ :: Int64) -> (undefined :: StructValue FieldValue))
+          query_ conn "SELECT count(*) FROM duckdb_functions() WHERE function_name LIKE 'hs\\_bad\\_%' ESCAPE '\\'" >>= (@?= [Only (0 :: Int64)])
+    , testCase "scalar callbacks read nested VARIANTs after the registering connection closes" $
+        withEnvironment \environment -> withInstance environment [] \instance' -> do
+          let payload = Variant (variantObject [("numbers", FieldList [FieldInt64 42, FieldNull])])
+              values = Map.singleton "a" [Just payload, Nothing]
+          withConnectionOn instance' \conn -> do
+            createFunction conn "hs_nested_variant" ((== values) :: Map.Map Text.Text [Maybe Variant] -> Bool)
+            createFunction conn "hs_variant_union" ((== Payload payload) :: VariantChoice -> Bool)
+            createFunctionWithState conn "hs_stateful_variant" (pure payload) (\expected (value :: Maybe Variant) -> Just expected == value)
+          withConnectionOn instance' \conn ->
+            query
+              conn
+              "SELECT hs_nested_variant(?), hs_variant_union(?), hs_variant_union(?), hs_stateful_variant(?), hs_stateful_variant(NULL)"
+              (values, Payload payload, NoPayload, payload)
+              >>= (@?= [(True, True, False, True, False)])
+    , testCase "two connections run the same VARIANT callback concurrently" $
+        withEnvironment \environment -> withInstance environment [("threads", "1")] \instance' ->
+          withConnectionOn instance' \first -> withConnectionOn instance' \second -> do
+            enteredFirst <- newEmptyMVar
+            enteredSecond <- newEmptyMVar
+            let meet entered other = do
+                  putMVar entered ()
+                  ready <- timeout 30000000 (readMVar other)
+                  when (ready == Nothing) (fail "the other VARIANT callback did not enter")
+            createFunction first "hs_variant_read" \case
+              Variant (FieldInt64 number) -> do
+                when (number == 0) (meet enteredFirst enteredSecond)
+                when (number == 5000) (meet enteredSecond enteredFirst)
+                pure number :: IO Int64
+              other -> fail ("unexpected VARIANT: " <> show other)
+            let run conn offset =
+                  query conn "SELECT sum(hs_variant_read((i + ?::BIGINT)::VARIANT))::BIGINT FROM range(5000) t(i)" (Only offset)
+                    >>= (@?= [Only (12497500 + 5000 * offset :: Int64)])
+            completed <- newEmptyMVar
+            bracket (forkFinally (run second 5000) (putMVar completed)) (const (void (readMVar completed))) \_ -> do
+              run first 0
+              readMVar completed >>= either throwIO pure
+    , testCase "rejects an empty name or a name with NUL at registration" $
+        withConnection ":memory:" \conn ->
+          forM_ ["", "hs_bad\0name"] \name ->
+            assertThrows
+              (createFunction conn name (id :: Int64 -> Int64))
+              (\err -> sqlErrorType err == Just ErrorInputInvalid && sqlErrorMessage err == "duckdb-simple: invalid scalar function name")
+    , testCase "raises the name error before the state of a closed connection" $ do
+        conn <- open ":memory:"
+        close conn
+        assertThrows
+          (createFunction conn "" (id :: Int64 -> Int64))
+          (\err -> sqlErrorType err == Just ErrorInputInvalid && sqlErrorMessage err == "duckdb-simple: invalid scalar function name")
+    , testCase "a failing call with constant arguments fails as with column arguments" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "hs_fail_negative" (\(x :: Int64) -> (if x < 0 then throwIO (userError "negative") else pure x) :: IO Int64)
+          let failsWith expected action = assertThrows action (\err -> sqlErrorType err == Just ErrorInputInvalid && expected `Text.isInfixOf` sqlErrorMessage err)
+          failsWith "negative" (query_ conn "SELECT hs_fail_negative(-1)" :: IO [Only Int64])
+          failsWith "negative" (query_ conn "SELECT hs_fail_negative(i - 1) FROM range(3) t(i)" :: IO [Only Int64])
+          failsWith
+            "duckdb-simple: argument arg0 is NULL, but Int64 cannot hold NULL"
+            (query_ conn "SELECT hs_fail_negative(NULL::BIGINT)" :: IO [Only Int64])
+          -- A failing constant in a CASE branch that is not taken does not raise.
+          query_ conn "SELECT CASE WHEN i > 5 THEN hs_fail_negative(-1) ELSE i END FROM range(3) t(i)" >>= (@?= map Only [0, 1, 2 :: Int64])
+    , testCase "names the argument that does not convert" $
+        withConnection ":memory:" \conn -> do
+          createFunction conn "hs_sum" (\(x :: Int64) (y :: Int64) -> x + y)
+          assertThrows
+            (query_ conn "SELECT hs_sum(1, NULL)" :: IO [Only Int64])
+            (Text.isInfixOf "duckdb-simple: argument arg1 is NULL, but Int64 cannot hold NULL" . sqlErrorMessage)
+    , testCase "supports IO-based functions" $
+        withConnection ":memory:" \conn -> do
+          ref <- newIORef (0 :: Int)
+          createFunction conn "hs_counter" $ do
+            atomicModifyIORef' ref \n ->
+              let next = n + 1
+              in  (next, next)
+          first <- query_ conn "SELECT hs_counter()" :: IO [Only Int]
+          second <- query_ conn "SELECT hs_counter()" :: IO [Only Int]
+          assertEqual "first counter call" [Only 1] first
+          assertEqual "second counter call" [Only 2] second
+    , testCase "supports thread-local function state" $ do
+        conn <- openWithConfig ":memory:" [("threads", "1")]
+        createFunctionWithState conn "hs_stateful_counter" (newIORef (0 :: Int)) \ref -> do
+          atomicModifyIORef' ref \n ->
+            let next = n + 1
+            in  (next, next)
+        rows <- query_ conn "SELECT hs_stateful_counter() FROM range(3)" :: IO [Only Int]
+        close conn
+        assertEqual "stateful rows" [Only 1, Only 2, Only 3] rows
+    , testCase "returns text rows of each length over more than one chunk" $
+        withConnection ":memory:" \conn -> do
+          let texts =
+                [ Just "a"
+                , Nothing
+                , Just "b"
+                , Just ""
+                , Just "a\0b"
+                , Just "123456789012"
+                , Just "1234567890123"
+                , Just (Text.replicate 4000 "abcdefghijklmnopqrstuvwxy")
+                , Just "liður ð þ ✓ 😀"
+                ]
+              pick (i :: Int64) = texts !! fromIntegral (i `mod` 9) :: Maybe Text.Text
+          createFunction conn "hs_pick" pick
+          createFunction conn "hs_echo" (\(text :: Maybe Text.Text) -> text)
+          -- 5000 rows fill more than one chunk. A NULL row is between two text rows.
+          rows <- query_ conn "SELECT hs_pick(i) FROM range(5000) t(i) ORDER BY i"
+          assertEqual "text rows" (map (Only . pick) [0 .. 4999]) rows
+          -- DuckDB compares the bytes in the vector, also the inline bytes after a short text.
+          query_
+            conn
+            "SELECT bool_and(hs_pick(i) IS NOT DISTINCT FROM CASE i % 9 WHEN 0 THEN 'a' WHEN 1 THEN NULL WHEN 2 THEN 'b' WHEN 3 THEN '' WHEN 4 THEN 'a' || chr(0) || 'b' WHEN 5 THEN '123456789012' WHEN 6 THEN '1234567890123' WHEN 7 THEN repeat('abcdefghijklmnopqrstuvwxy', 4000) ELSE 'liður ð þ ✓ 😀' END) FROM range(5000) t(i)"
+            >>= (@?= [Only True])
+          query_ conn "SELECT hs_echo('x'), hs_echo(NULL)" >>= (@?= [(Just "x" :: Maybe Text.Text, Nothing :: Maybe Text.Text)])
+    ]
+
+transactionTests :: TestTree
+transactionTests =
+  testGroup
+    "transactions"
+    [ testCase "withTransaction commits on success" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE tx_commit (x INTEGER)"
+          withTransaction conn $ do
+            _ <- execute conn "INSERT INTO tx_commit VALUES (?)" (Only (1 :: Int))
+            pure ()
+          rows <- query_ conn "SELECT COUNT(*) FROM tx_commit" :: IO [Only Int]
+          assertEqual "commit" [Only 1] rows
+    , testCase "withTransaction rolls back on exception" $
+        withConnection ":memory:" \conn -> do
+          _ <- execute_ conn "CREATE TABLE tx_rollback (x INTEGER)"
+          assertThrowsErrorCall $
+            withTransaction conn $ do
+              _ <- execute conn "INSERT INTO tx_rollback VALUES (?)" (Only (1 :: Int))
+              error "boom"
+          rows <- query_ conn "SELECT COUNT(*) FROM tx_rollback" :: IO [Only Int]
+          assertEqual "rollback" [Only 0] rows
+    ]
+
+assertThrows :: forall e a. (Exception e) => IO a -> (e -> Bool) -> Assertion
+assertThrows action predicate = do
+  outcome <- try action
+  case outcome of
+    Left (err :: e) -> assertBool "unexpected exception" (predicate err)
+    Right _ -> assertFailure "expected exception, but action succeeded"
+
+assertThrowsSQLError :: IO a -> Assertion
+assertThrowsSQLError action =
+  assertThrows action (const True :: SQLError -> Bool)
+
+assertThrowsErrorCall :: IO a -> Assertion
+assertThrowsErrorCall action =
+  assertThrows action (const True :: ErrorCall -> Bool)
+
+assertThrowsFormatError :: IO a -> (FormatError -> Bool) -> Assertion
+assertThrowsFormatError = assertThrows
+
+-- | Give the action a unique temporary path where no file exists. Remove the
+-- file after the action if the action created it. DuckDB writes a COPY TO
+-- target that exists through a second file, so the path has no file.
+withTemporaryPath :: (FilePath -> IO a) -> IO a
+withTemporaryPath = bracket acquire release
+  where
+    acquire = do
+      directory <- getTemporaryDirectory
+      (path, handle) <- openBinaryTempFile directory "duckdb-simple-spec"
+      hClose handle
+      removeFile path
+      pure path
+    release path = doesFileExist path >>= \exists -> when exists (removeFile path)
diff --git a/test/SqlFeatureTests.hs b/test/SqlFeatureTests.hs
new file mode 100644
--- /dev/null
+++ b/test/SqlFeatureTests.hs
@@ -0,0 +1,240 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE OverloadedStrings #-}
+
+-- |
+-- Module      : SqlFeatureTests
+-- Description : Integration checks for DuckDB 2.0 SQL features.
+module SqlFeatureTests (tests) where
+
+import Control.Exception (bracket, try)
+import Control.Monad (forM_, void, when)
+import Data.Int (Int64)
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Data.Time.LocalTime (TimeOfDay (..))
+import Database.DuckDB.Simple
+import Database.DuckDB.Simple.FromField (BitString (..), FieldValue (..), TimeWithZone (..))
+import Database.DuckDB.Simple.Variant (Variant (..), variantObject)
+import System.Directory (doesFileExist, getTemporaryDirectory, removeFile)
+import System.IO (hClose, openBinaryTempFile)
+import Test.Tasty (TestTree, testGroup)
+import Test.Tasty.HUnit (Assertion, assertBool, assertFailure, testCase, (@?=))
+import TestUtils (assertInputError)
+
+-- | Exercise the public query, binding, cursor, and fold operations.
+tests :: TestTree
+tests =
+  testGroup
+    "DuckDB 2.0 SQL features"
+    [ testCase "row triggers audit bound inserts and roll back failures" $
+        withConnection ":memory:" \conn -> do
+          void (execute_ conn "CREATE TABLE target(id BIGINT, label VARCHAR)")
+          void (execute_ conn "CREATE TABLE audit(id BIGINT PRIMARY KEY, label VARCHAR)")
+          void (execute_ conn "CREATE TRIGGER record_insert AFTER INSERT ON target FOR EACH ROW INSERT INTO audit VALUES (NEW.id, NEW.label)")
+          void (executeMany conn "INSERT INTO target VALUES (?, ?)" [(1 :: Int64, "first" :: Text), (2, "O'Reilly")])
+          query_ conn "SELECT * FROM audit ORDER BY id" >>= (@?= [(1 :: Int64, "first" :: Text), (2, "O'Reilly")])
+          assertDuckDBError
+            ErrorDatabaseConstraint
+            "Constraint Error: Duplicate key \"id: 1\" violates primary key constraint."
+            (execute conn "INSERT INTO target VALUES (?, ?)" (1 :: Int64, "duplicate" :: Text))
+          query_ conn "SELECT count(*) FROM target" >>= (@?= [Only (2 :: Int64)])
+    , testCase "DML CTEs bind values and deliver RETURNING rows to folds" $
+        withConnection ":memory:" \conn -> do
+          void (execute_ conn "CREATE TABLE moved(id BIGINT)")
+          query conn "WITH ins AS (INSERT INTO moved VALUES (?), (?) RETURNING id) SELECT id FROM ins ORDER BY id" (1 :: Int64, 2 :: Int64)
+            >>= (@?= [Only (1 :: Int64), Only 2])
+          total <- fold_ conn "WITH del AS (DELETE FROM moved RETURNING id) SELECT id FROM del" (0 :: Int64) \acc (Only value) -> pure (acc + value)
+          total @?= 3
+          query_ conn "SELECT count(*) FROM moved" >>= (@?= [Only (0 :: Int64)])
+    , testCase "nested schemas accept qualified parameterized DML" $
+        withConnection ":memory:" \conn -> do
+          void (execute_ conn "CREATE SCHEMA parent_schema")
+          void (execute_ conn "CREATE SCHEMA parent_schema.child_schema")
+          void (execute_ conn "CREATE TABLE parent_schema.child_schema.items(id BIGINT)")
+          void (execute conn "INSERT INTO parent_schema.child_schema.items VALUES (?)" (Only (17 :: Int64)))
+          query_ conn "SELECT id FROM memory.parent_schema.child_schema.items" >>= (@?= [Only (17 :: Int64)])
+          query_ conn "SELECT parent_schema FROM duckdb_schemas() WHERE schema_name='child_schema'" >>= (@?= [Only ("parent_schema" :: Text)])
+    , testCase "session variables supply cursor and fold defaults; named bindings override them" $
+        withConnection ":memory:" \conn -> do
+          void (execute_ conn "SET VARIABLE session_value = 41")
+          query_ conn "SELECT $session_value + 1" >>= (@?= [Only (42 :: Int64)])
+          withStatement conn "SELECT $session_value + 1" \stmt -> do
+            nextRow stmt >>= (@?= Just (Only (42 :: Int64)))
+            nextRow stmt >>= (@?= (Nothing :: Maybe (Only Int64)))
+          queryNamed conn "SELECT $session_value + 1" ["session_value" := (9 :: Int64)] >>= (@?= [Only (10 :: Int64)])
+          queryNamed conn "SELECT $session_value + $amount" ["amount" := (1 :: Int64)] >>= (@?= [Only (42 :: Int64)])
+          queryNamed conn "SELECT $session_value" [] >>= (@?= [Only (41 :: Int64)])
+          assertDuckDBError
+            ErrorInputInvalid
+            "Invalid Input Error: Values were not provided for the following parameters: missing"
+            (queryNamed conn "SELECT $session_value + $missing" [] :: IO [Only Int64])
+          void (execute_ conn "SET VARIABLE session_value = 83")
+          total <- fold_ conn "SELECT $session_value + 1" (0 :: Int64) \acc (Only value) -> pure (acc + value)
+          total @?= 84
+          void (execute_ conn "RESET VARIABLE session_value")
+          assertDuckDBError
+            ErrorInputInvalid
+            "Invalid Input Error: Values were not provided for the following parameters: session_value"
+            (query_ conn "SELECT $session_value" :: IO [Only Int64])
+    , testCase "named replacement preserves old values on failure and replaces session overrides on success" $
+        withConnection ":memory:" \conn -> do
+          void (execute_ conn "SET VARIABLE a = 80; SET VARIABLE b = 90; SET VARIABLE c = 91")
+          withStatement conn "SELECT $a::BIGINT, $b::BIGINT, $c::BIGINT" \stmt -> do
+            let rejected = bindNamed stmt ["a" := (4 :: Int64), "b" := BitString 8 "x", "c" := (6 :: Int64)]
+            assertInputError rejected
+            nextRow stmt >>= (@?= Just (80 :: Int64, 90 :: Int64, 91 :: Int64))
+            bindNamed stmt ["a" := (1 :: Int64), "b" := (2 :: Int64), "c" := (3 :: Int64)]
+            nextRow stmt >>= (@?= Just (1 :: Int64, 2 :: Int64, 3 :: Int64))
+            assertInputError rejected
+            nextRow stmt >>= (@?= Just (1 :: Int64, 2 :: Int64, 3 :: Int64))
+            bindNamed stmt ["a" := (7 :: Int64)]
+            nextRow stmt >>= (@?= Just (7 :: Int64, 90 :: Int64, 91 :: Int64))
+    , testCase "FETCH FIRST and OFFSET work with bound counts" $
+        withConnection ":memory:" \conn ->
+          query conn "SELECT i FROM range(10) t(i) ORDER BY i OFFSET ? ROWS FETCH FIRST ? ROWS ONLY" (3 :: Int64, 2 :: Int64)
+            >>= (@?= [Only (3 :: Int64), Only 4])
+    , testCase "SELECT expressions use the query and cursor paths" $
+        withConnection ":memory:" \conn -> do
+          query conn "SELECT ?::BIGINT + 1" (Only (41 :: Int64)) >>= (@?= [Only (42 :: Int64)])
+          withStatement conn "SELECT 42::BIGINT" \stmt -> do
+            nextRow stmt >>= (@?= Just (Only (42 :: Int64)))
+            nextRow stmt >>= (@?= (Nothing :: Maybe (Only Int64)))
+    , testCase "NEAREST joins rank candidates for bound input rows" $
+        withConnection ":memory:" \conn ->
+          query
+            conn
+            "SELECT q.id::BIGINT, t.value::BIGINT FROM (VALUES (1, ?::BIGINT), (2, ?::BIGINT)) q(id, value) INNER JOIN (VALUES (11), (19), (25), (100)) t(value) EXACT NEAREST 2 BY DISTANCE abs(q.value - t.value) ORDER BY q.id, t.value"
+            (10 :: Int64, 20 :: Int64)
+            >>= (@?= [(1 :: Int64, 11 :: Int64), (1, 19), (2, 19), (2, 25)])
+    , testCase "recursive USING KEY aggregates bound values before folding" $
+        withConnection ":memory:" \conn -> do
+          total <- fold
+            conn
+            "WITH RECURSIVE totals(k, total) USING KEY (k, sum(total)) AS (VALUES (1, ?::BIGINT) UNION SELECT k, 1::BIGINT FROM totals WHERE total < ?::BIGINT) SELECT total::BIGINT FROM totals"
+            (1 :: Int64, 4 :: Int64)
+            (0 :: Int64)
+            \acc (Only value) -> pure (acc + value)
+          total @?= 4
+    , testCase "lambda filter, transform, and reduce accept bound lists" $
+        withConnection ":memory:" \conn ->
+          query
+            conn
+            "SELECT list_reduce(list_transform(list_filter(?::BIGINT[], lambda x: x % 2 = 0), lambda x: x * 3), lambda x, y: x + y)"
+            (Only [1, 2, 3, 4 :: Int64])
+            >>= (@?= [Only (18 :: Int64)])
+    , testCase "JSON mutation accepts bound documents, paths, and values" $
+        withConnection ":memory:" \conn -> do
+          query conn "SELECT json_set(?::JSON, ?, ?::JSON)" ("{\"a\":1}" :: Text, "$.b" :: Text, "[2,3]" :: Text)
+            >>= (@?= [Only ("{\"a\":1,\"b\":[2,3]}" :: Text)])
+          query conn "SELECT json_set(?::JSON, ?, ?::JSON)::VARCHAR" ("{\"a\":1}" :: Text, "$.b" :: Text, "[2,3]" :: Text)
+            >>= (@?= [Only ("{\"a\":1,\"b\":[2,3]}" :: Text)])
+          query_ conn "SELECT json_remove(json_replace(json_insert('{\"a\":1}', '$.b', '2'), '$.a', '3'), '$.b')::VARCHAR"
+            >>= (@?= [Only ("{\"a\":3}" :: Text)])
+    , testCase "default 2.0 storage preserves bound VARIANT values after checkpoint and reopen" $
+        withFiles \path -> do
+          let value = Variant (variantObject [("n", FieldInt64 7), ("text", FieldText "saved")])
+          withConnection path \conn -> do
+            void (execute_ conn "CREATE TABLE stored(value VARIANT)")
+            void (execute conn "INSERT INTO stored VALUES (?)" (Only value))
+            void (execute_ conn "CHECKPOINT")
+            query_ conn "SELECT tags['storage_version'] FROM duckdb_databases() WHERE NOT internal" >>= (@?= [Only ("v2.0.0+" :: Text)])
+          withConnection path \conn -> do
+            query_ conn "SELECT tags['storage_version'] FROM duckdb_databases() WHERE NOT internal" >>= (@?= [Only ("v2.0.0+" :: Text)])
+            query_ conn "SELECT value FROM stored" >>= (@?= [Only value])
+    , testCase "VARIANT values survive native storage and explicit Parquet shredding" $
+        withFiles \path -> do
+          let parquet = path <> ".parquet"
+              expected = [(i, Text.pack (show i)) | i <- [0, 2048, 4096 :: Int64]]
+          withConnectionWithConfig path [("storage_compatibility_version", "v1.5.0")] \conn -> do
+            void (execute_ conn "SET variant_minimum_shredding_size = 0")
+            void (execute_ conn "CREATE TABLE variants AS SELECT i, {'n': i, 'text': i::VARCHAR}::VARIANT AS v FROM range(5000) t(i)")
+            void (execute_ conn "CHECKPOINT")
+          withConnectionWithConfig path [("storage_compatibility_version", "v1.5.0")] \conn -> do
+            query_ conn "SELECT v.n::BIGINT, v.text::VARCHAR FROM variants WHERE i % 2048 = 0 ORDER BY i" >>= (@?= expected)
+            query_ conn "SELECT v FROM variants WHERE i % 2048 = 0 ORDER BY i"
+              >>= (@?= [Only (Variant (variantObject [("n", FieldInt64 i), ("text", FieldText text)])) | (i, text) <- expected])
+            void (execute conn "COPY variants TO ? (FORMAT PARQUET, SHREDDING {'v': 'STRUCT(n BIGINT, text VARCHAR)'})" (Only (Text.pack parquet)))
+            query conn "SELECT v.n::BIGINT, v.text::VARCHAR FROM read_parquet(?) WHERE i % 2048 = 0 ORDER BY i" (Only (Text.pack parquet))
+              >>= (@?= expected)
+            query conn "SELECT count(*) > 0 FROM parquet_schema(?) WHERE name='typed_value'" (Only (Text.pack parquet)) >>= (@?= [Only True])
+            total <- fold conn "SELECT v.n::BIGINT FROM read_parquet(?)" (Only (Text.pack parquet)) (0 :: Int64) \acc (Only value) -> pure (acc + value)
+            total @?= 12497500
+    , -- Each case of this group runs the SQL form of a limit that the
+      -- documentation of duckdb-simple states. The case fails when DuckDB lifts
+      -- the limit.
+      testGroup
+        "limits that DuckDB sets"
+        [ testCase "an ARRAY type needs at least one element" $ withConnection ":memory:" \conn ->
+            assertDuckDBError
+              ErrorQueryBinder
+              "Binder Error: ARRAY type size must be at least 1"
+              (query_ conn "SELECT []::INTEGER[0]" :: IO [Only Text])
+        , testCase "a STRUCT for a VARIANT cannot have two equal keys" $ withConnection ":memory:" \conn ->
+            assertDuckDBError
+              ErrorQueryBinder
+              "Binder Error: Duplicate named argument \"a\""
+              (query_ conn "SELECT {'a': 1, 'a': 2}::VARIANT" :: IO [Only Variant])
+        , testCase "a VARIANT does not keep the CRS of a GEOMETRY" $ withConnection ":memory:" \conn ->
+            query_ conn "SELECT typeof('POINT (1 2)'::GEOMETRY('OGC:CRS84')::VARIANT::GEOMETRY), typeof('POINT (1 2)'::GEOMETRY('OGC:CRS84'))"
+              >>= (@?= [("GEOMETRY" :: Text, "GEOMETRY('OGC:CRS84')" :: Text)])
+        , testCase "a BIT value needs at least one bit" $ withConnection ":memory:" \conn -> do
+            assertDuckDBError
+              ErrorTypeConversion
+              "Conversion Error: Cannot cast empty string to BIT"
+              (query_ conn "SELECT bitstring('', 0)" :: IO [Only Text])
+            -- An empty string literal is one zero bit.
+            query_ conn "SELECT ''::BIT::VARCHAR" >>= (@?= [Only ("0" :: Text)])
+        , testCase "a value that is not NULL has no cast to the type NULL" $ withConnection ":memory:" \conn ->
+            assertDuckDBError
+              ErrorTypeConversion
+              "Conversion Error: Unimplemented type for cast (INTEGER -> \"NULL\")"
+              (query_ conn "SELECT 7::\"NULL\"" :: IO [Only Text])
+        , testCase "a TIMETZ offset is at most 15:59:59 in each direction" $ withConnection ":memory:" \conn -> do
+            forM_ ["12:00:00+16:00:00", "12:00:00-16:00:00"] \value ->
+              assertDuckDBError
+                ErrorTypeConversion
+                ("Conversion Error: time field value out of range: \"" <> value <> "\"")
+                (query_ conn (Query ("SELECT '" <> value <> "'::TIMETZ")) :: IO [Only Text])
+            query_ conn "SELECT '12:00:00+15:59:59'::TIMETZ, '12:00:00-15:59:59'::TIMETZ"
+              >>= (@?= [(TimeWithZone (TimeOfDay 12 0 0) 57599, TimeWithZone (TimeOfDay 12 0 0) (-57599))])
+        , testCase "DuckDB has no savepoints" $ withConnection ":memory:" \conn ->
+            assertDuckDBError ErrorQueryParser "Parser Error: syntax error at or near \"SAVEPOINT\"" (execute_ conn "SAVEPOINT a")
+        , testCase "the CRS of a GEOMETRY cast is a constant" $ withConnection ":memory:" \conn ->
+            assertDuckDBError
+              ErrorQueryParser
+              "Parser Error: Expected a constant as type modifier"
+              (withStatement conn "SELECT ?::GEOMETRY(?)" columnCount)
+        , testCase "VARIANT columns need the storage version v1.5.0" $ withFiles \path ->
+            withConnectionWithConfig path [("storage_compatibility_version", "v1.0.0")] \conn ->
+              assertDuckDBError
+                ErrorInputInvalid
+                "Invalid Input Error: VARIANT columns are not supported in storage versions prior to v1.5.0"
+                (execute_ conn "CREATE TABLE old_variant (v VARIANT)")
+        ]
+    ]
+
+-- | Require an SQL error whose message starts with the text of DuckDB, and
+-- whose type is the given one.
+assertDuckDBError :: ErrorType -> Text -> IO a -> Assertion
+assertDuckDBError expectedType expected action = do
+  outcome <- try action
+  case outcome of
+    Left err -> do
+      assertBool (Text.unpack (sqlErrorMessage err)) (expected `Text.isPrefixOf` sqlErrorMessage err)
+      sqlErrorType err @?= Just expectedType
+    Right _ -> assertFailure ("expected the DuckDB error " <> Text.unpack expected)
+
+-- | Reserve a database path. Remove the database, WAL, and Parquet file on exit.
+withFiles :: (FilePath -> IO a) -> IO a
+withFiles = bracket acquire release
+  where
+    acquire = do
+      directory <- getTemporaryDirectory
+      (path, handle) <- openBinaryTempFile directory "duckdb-sql-feature"
+      hClose handle
+      removeFile path
+      pure path
+    release path =
+      forM_ [path, path <> ".wal", path <> ".parquet"] \file -> do
+        exists <- doesFileExist file
+        when exists (removeFile file)
diff --git a/test/StreamingTests.hs b/test/StreamingTests.hs
--- a/test/StreamingTests.hs
+++ b/test/StreamingTests.hs
@@ -1,148 +1,280 @@
 {-# LANGUAGE BlockArguments #-}
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE ScopedTypeVariables #-}
-{-# OPTIONS_GHC -Wno-deprecations #-}
 
--- | Check the explicit native streaming API and its cursor ownership.
+-- |
+-- Module      : StreamingTests
+-- Description : Check the explicit native streaming API and its cursor ownership.
 module StreamingTests (nativeStreamingTests) where
 
+import Control.Concurrent (forkIO, newEmptyMVar, putMVar, takeMVar)
 import Control.Exception (IOException, throwIO, try)
 import Control.Monad (forM_, replicateM_, void, when)
+import qualified Data.ByteString as BS
+import qualified Data.ByteString.Builder as Builder
+import qualified Data.ByteString.Lazy as BL
 import Data.IORef (atomicWriteIORef, newIORef, readIORef, writeIORef)
 import Data.Int (Int64)
-import Data.List (isInfixOf)
+import Data.List (isInfixOf, sort, sortOn)
 import Data.Text (Text)
 import qualified Data.Text as Text
-import Database.DuckDB.FFI (c_duckdb_vector_size)
-import Database.DuckDB.FFI.Deprecated (c_duckdb_result_is_streaming)
+import qualified Database.DuckDB.FFI as Retained (c_duckdb_vector_size)
 import Database.DuckDB.Simple
-import qualified Database.DuckDB.Simple.Deprecated.Streaming as Streaming
-import Database.DuckDB.Simple.FromField (FieldValue)
-import Database.DuckDB.Simple.Internal (Statement (statementStream), StatementStream (statementStreamResult), StatementStreamState (..))
+import Database.DuckDB.Simple.FromField (Field (fieldType), FieldValue (..))
+import Database.DuckDB.Simple.Geometry (RawGeometry (..))
+import Database.DuckDB.Simple.Internal (
+  DuckDBV2ResultHandle (..),
+  Statement (statementStream),
+  StatementStream (statementStreamResult),
+  StatementStreamState (..),
+  nullHandle,
+ )
+import qualified Database.DuckDB.Simple.Streaming as Streaming
+import Database.DuckDB.Simple.Variant (Variant (..), variantObject)
+import System.Timeout (timeout)
 import Test.Tasty (TestTree, testGroup)
 import Test.Tasty.HUnit
+import TestUtils (assertReusable, filteredQueries)
 
 -- | Exercise native streaming, resets, metadata, and cleanup across chunks.
 nativeStreamingTests :: TestTree
 nativeStreamingTests =
-    testGroup
-        "explicit native streaming"
-        [ testCase "nextRow starts a native streaming result" $ withDb \conn ->
-            withStatement conn "SELECT i FROM range(10000) t(i)" \stmt -> do
-                Streaming.nextRow stmt >>= (@?= Just (Only (0 :: Int64)))
-                state <- readIORef (statementStream stmt)
-                case state of
-                    StatementStreamActive stream -> do
-                        flag <- c_duckdb_result_is_streaming (statementStreamResult stream)
-                        assertBool "expected a native streaming result" (flag /= 0)
-                    _ -> assertFailure "expected an active cursor"
-        , testCase "default execution remains materialized when cursor entry points change" $ withDb \conn ->
-            withStatement conn "SELECT i FROM range(10000) t(i)" \stmt -> do
-                nextRow stmt >>= (@?= Just (Only (0 :: Int64)))
-                Streaming.nextRow stmt >>= (@?= Just (Only (1 :: Int64)))
-                state <- readIORef (statementStream stmt)
-                case state of
-                    StatementStreamActive stream -> do
-                        flag <- c_duckdb_result_is_streaming (statementStreamResult stream)
-                        flag @?= 0
-                    _ -> assertFailure "expected an active cursor"
-        , testCase "nested values survive chunk cleanup" $ withDb \conn ->
-            forM_
-                [ "SELECT CASE WHEN i % 7 = 0 THEN NULL ELSE {'n': i, 'text': 'λ' || i::VARCHAR, 'list': [i, NULL], 'union': union_value(value := i)} END FROM range(5000) t(i)"
-                , "SELECT [{'n': i, 'text': 'λ' || i::VARCHAR}, NULL] FROM range(5000) t(i)"
-                , "SELECT map([i], [{'values': [i, NULL], 'union': union_value(value := i)}]) FROM range(5000) t(i)"
-                , "SELECT CASE WHEN i % 2 = 0 THEN union_value(n := i)::UNION(n BIGINT, text VARCHAR) ELSE union_value(text := i::VARCHAR)::UNION(n BIGINT, text VARCHAR) END FROM range(5000) t(i)"
-                ]
-                \sql -> do
-                    expected <- query_ conn sql :: IO [Only FieldValue]
-                    actual <- reverse <$> Streaming.fold_ conn sql [] (\acc row -> pure (row : acc))
-                    actual @?= expected
-        , testCase "fold and foldNamed use executed parameter types" $ withDb \conn -> do
-            positional <- Streaming.fold conn "SELECT coalesce(?, 'x') FROM range(3)" (Only (5000000000 :: Int64)) [] (\acc row -> pure (row : acc))
-            positional @?= replicate 3 (Only (5000000000 :: Int64))
-            named <- Streaming.foldNamed conn "SELECT $value FROM range(3)" ["value" := ("λ" :: Text)] [] (\acc row -> pure (row : acc))
-            named @?= replicate 3 (Only ("λ" :: Text))
-        , testCase "rebinding an active cursor replaces its metadata" $ withDb \conn ->
-            withStatement conn "SELECT ? FROM range(3)" \stmt -> do
-                bind stmt [toField (5000000000 :: Int64)]
-                Streaming.nextRow stmt >>= (@?= Just (Only (5000000000 :: Int64)))
-                bind stmt [toField ("λ" :: Text)]
-                Streaming.nextRow stmt >>= (@?= Just (Only ("λ" :: Text)))
-        , testCase "schema changes replace prepare-time metadata" $ withDb \conn -> do
-            void $ execute_ conn "CREATE TABLE stream_rebind(x VARCHAR)"
-            withStatement conn "SELECT x FROM stream_rebind" \stmt -> do
-                void $ execute_ conn "DROP TABLE stream_rebind"
-                void $ execute_ conn "CREATE TABLE stream_rebind(x BIGINT)"
-                void $ execute_ conn "INSERT INTO stream_rebind VALUES (5000000000)"
-                Streaming.nextRow stmt >>= (@?= Just (Only (5000000000 :: Int64)))
-        , testCase "EOF persists until an explicit binding reset" $ withDb \conn ->
-            withStatement conn "SELECT ?::BIGINT" \stmt -> do
-                bind stmt [toField (1 :: Int64)]
-                Streaming.nextRow stmt >>= (@?= Just (Only (1 :: Int64)))
-                replicateM_ 3 $ Streaming.nextRow stmt >>= (@?= (Nothing :: Maybe (Only Int64)))
-                bind stmt [toField (2 :: Int64)]
-                Streaming.nextRow stmt >>= (@?= Just (Only (2 :: Int64)))
-                Streaming.nextRow stmt >>= (@?= (Nothing :: Maybe (Only Int64)))
-        , testCase "clearing bindings discards an active result" $ withDb \conn ->
-            withStatement conn "SELECT ?::BIGINT FROM range(3)" \stmt -> do
-                bind stmt [toField (7 :: Int64)]
-                Streaming.nextRow stmt >>= (@?= Just (Only (7 :: Int64)))
-                clearStatementBindings stmt
-                void $ expectSqlError (Streaming.nextRow stmt :: IO (Maybe (Only Int64)))
-                bind stmt [toField (8 :: Int64)]
-                Streaming.nextRow stmt >>= (@?= Just (Only (8 :: Int64)))
-        , testCase "a DML cursor does not execute again after EOF" $ withDb \conn -> do
-            void $ execute_ conn "CREATE TABLE stream_once(x BIGINT)"
-            withStatement conn "INSERT INTO stream_once VALUES (1)" \stmt ->
-                replicateM_ 3 $ Streaming.nextRow stmt >>= (@?= (Nothing :: Maybe (Only Int64)))
-            query_ conn "SELECT count(*) FROM stream_once" >>= (@?= [Only (1 :: Int64)])
-        , testCase "nextRowWith runs the supplied parser" $ withDb \conn ->
-            withStatement conn "SELECT 20, 22" \stmt ->
-                Streaming.nextRowWith ((+) <$> field <*> field) stmt >>= (@?= Just (42 :: Int64))
-        , testCase "a fetch failure follows an already delivered batch" $ withDb \conn -> do
-            void $ execute_ conn "SET streaming_buffer_size = '64KB'"
-            failNext <- newIORef False
-            delivered <- newIORef (0 :: Int)
-            batchSize <- fromIntegral <$> c_duckdb_vector_size
-            createFunction conn "late_stream_error" \(value :: Int64) -> do
-                shouldFail <- readIORef failNext
-                when shouldFail (throwIO (userError "late stream error"))
-                pure value
-            err <- expectSqlError $ Streaming.fold_ conn "SELECT late_stream_error(i) FROM range(1000000) t(i)" (0 :: Int) \count (Only (_ :: Int64)) -> do
-                let next = count + 1
-                writeIORef delivered next
-                when (next == batchSize) (atomicWriteIORef failNext True)
-                pure next
-            count <- readIORef delivered
-            assertBool "the first batch must precede the error" (count >= batchSize)
-            assertBool "fetch error must retain its message" ("late stream error" `Text.isInfixOf` sqlErrorMessage err)
-            assertReusable conn
-        , testCase "Arrow reports a fetch failure after a delivered batch" $ withDb \conn -> do
-            void $ execute_ conn "SET streaming_buffer_size = '64KB'"
-            failNext <- newIORef False
-            createFunction conn "late_arrow_error" \(value :: Int64) -> do
-                shouldFail <- readIORef failNext
-                when shouldFail (throwIO (userError "late Arrow error"))
-                pure value
-            err <- expectSqlError $ Streaming.foldArrow_ conn "SELECT late_arrow_error(i) FROM range(1000000) t(i)" () \() _ _ ->
-                atomicWriteIORef failNext True
-            readIORef failNext >>= assertBool "a batch reached the callback"
-            assertBool "fetch error must retain its message" ("late Arrow error" `Text.isInfixOf` sqlErrorMessage err)
-            assertReusable conn
-        , testCase "row decode failure exhausts and releases the cursor" $ withDb \conn -> do
-            withStatement conn "SELECT {'n': i} FROM range(5000) t(i)" \stmt -> do
-                void $ expectSqlError (Streaming.nextRow stmt :: IO (Maybe (Only Int64)))
-                Streaming.nextRow stmt >>= (@?= (Nothing :: Maybe (Only Int64)))
-            assertReusable conn
-        , testCase "fold callback failure releases the active chunk" $ withDb \conn -> do
-            outcome <- try $ Streaming.fold_ conn "SELECT {'n': i, 'list': [i, NULL]} FROM range(5000) t(i)" (0 :: Int) \count (Only (_ :: FieldValue)) ->
-                if count == 2050 then throwIO (userError "stream step failure") else pure (count + 1)
-            case outcome of
-                Left (err :: IOException) -> assertBool "original callback error" ("stream step failure" `isInfixOf` show err)
-                Right _ -> assertFailure "expected the callback to fail"
-            assertReusable conn
-        ]
+  testGroup
+    "explicit native streaming"
+    [ testCase "nextRow starts a native streaming result" $ withDb \conn ->
+        withStatement conn "SELECT i FROM range(10000) t(i)" \stmt -> do
+          Streaming.nextRow stmt >>= (@?= Just (Only (0 :: Int64)))
+          state <- readIORef (statementStream stmt)
+          case state of
+            StatementStreamActive stream -> do
+              assertBool "expected a live native cursor" (statementStreamResult stream /= nullHandle)
+            _ -> assertFailure "expected an active cursor"
+    , testCase "default execution remains materialized when cursor entry points change" $ withDb \conn ->
+        withStatement conn "SELECT i FROM range(10000) t(i)" \stmt -> do
+          nextRow stmt >>= (@?= Just (Only (0 :: Int64)))
+          Streaming.nextRow stmt >>= (@?= Just (Only (1 :: Int64)))
+          state <- readIORef (statementStream stmt)
+          case state of
+            StatementStreamActive stream -> do
+              assertBool "expected a released execution cursor" (statementStreamResult stream == nullHandle)
+            _ -> assertFailure "expected an active cursor"
+    , testCase "nested values survive chunk cleanup" $ withDb \conn ->
+        forM_
+          [ "SELECT CASE WHEN i % 7 = 0 THEN NULL ELSE {'n': i, 'text': 'λ' || i::VARCHAR, 'list': [i, NULL], 'union': union_value(value := i)} END FROM range(5000) t(i)"
+          , "SELECT [{'n': i, 'text': 'λ' || i::VARCHAR}, NULL] FROM range(5000) t(i)"
+          , "SELECT map([i], [{'values': [i, NULL], 'union': union_value(value := i)}]) FROM range(5000) t(i)"
+          , "SELECT CASE WHEN i % 2 = 0 THEN union_value(n := i)::UNION(n BIGINT, text VARCHAR) ELSE union_value(text := i::VARCHAR)::UNION(n BIGINT, text VARCHAR) END FROM range(5000) t(i)"
+          ]
+          \sql -> do
+            expected <- query_ conn sql :: IO [Only FieldValue]
+            actual <- reverse <$> Streaming.fold_ conn sql [] (\acc row -> pure (row : acc))
+            actual @?= expected
+    , testCase "fold and foldNamed use executed parameter types" $ withDb \conn -> do
+        positional <- Streaming.fold conn "SELECT coalesce(?, 'x') FROM range(3)" (Only (5000000000 :: Int64)) [] (\acc row -> pure (row : acc))
+        positional @?= replicate 3 (Only (5000000000 :: Int64))
+        named <- Streaming.foldNamed conn "SELECT $value FROM range(3)" ["value" := ("λ" :: Text)] [] (\acc row -> pure (row : acc))
+        named @?= replicate 3 (Only ("λ" :: Text))
+    , testCase "rebinding an active cursor replaces its metadata" $ withDb \conn ->
+        withStatement conn "SELECT ? FROM range(3)" \stmt -> do
+          bind stmt [toField (5000000000 :: Int64)]
+          Streaming.nextRow stmt >>= (@?= Just (Only (5000000000 :: Int64)))
+          bind stmt [toField ("λ" :: Text)]
+          Streaming.nextRow stmt >>= (@?= Just (Only ("λ" :: Text)))
+    , testCase "schema changes replace prepare-time metadata" $ withDb \conn -> do
+        void $ execute_ conn "CREATE TABLE stream_rebind(x VARCHAR)"
+        withStatement conn "SELECT x FROM stream_rebind" \stmt -> do
+          void $ execute_ conn "DROP TABLE stream_rebind"
+          void $ execute_ conn "CREATE TABLE stream_rebind(x BIGINT)"
+          void $ execute_ conn "INSERT INTO stream_rebind VALUES (5000000000)"
+          Streaming.nextRow stmt >>= (@?= Just (Only (5000000000 :: Int64)))
+    , testCase "EOF persists until an explicit binding reset" $ withDb \conn ->
+        withStatement conn "SELECT ?::BIGINT" \stmt -> do
+          bind stmt [toField (1 :: Int64)]
+          Streaming.nextRow stmt >>= (@?= Just (Only (1 :: Int64)))
+          replicateM_ 3 $ Streaming.nextRow stmt >>= (@?= (Nothing :: Maybe (Only Int64)))
+          bind stmt [toField (2 :: Int64)]
+          Streaming.nextRow stmt >>= (@?= Just (Only (2 :: Int64)))
+          Streaming.nextRow stmt >>= (@?= (Nothing :: Maybe (Only Int64)))
+    , testCase "clearing bindings discards an active result" $ withDb \conn ->
+        withStatement conn "SELECT ?::BIGINT FROM range(3)" \stmt -> do
+          bind stmt [toField (7 :: Int64)]
+          Streaming.nextRow stmt >>= (@?= Just (Only (7 :: Int64)))
+          clearStatementBindings stmt
+          void $ expectSqlError (Streaming.nextRow stmt :: IO (Maybe (Only Int64)))
+          bind stmt [toField (8 :: Int64)]
+          Streaming.nextRow stmt >>= (@?= Just (Only (8 :: Int64)))
+    , testCase "a DML cursor does not execute again after EOF" $ withDb \conn -> do
+        void $ execute_ conn "CREATE TABLE stream_once(x BIGINT)"
+        withStatement conn "INSERT INTO stream_once VALUES (1)" \stmt -> do
+          Streaming.nextRow stmt >>= (@?= Just (Only (1 :: Int64)))
+          replicateM_ 3 $ Streaming.nextRow stmt >>= (@?= (Nothing :: Maybe (Only Int64)))
+        query_ conn "SELECT count(*) FROM stream_once" >>= (@?= [Only (1 :: Int64)])
+        Streaming.fold_ conn "INSERT INTO stream_once VALUES (2)" [] (\acc row -> pure (row : acc)) >>= (@?= [Only (1 :: Int64)])
+        query_ conn "SELECT count(*) FROM stream_once" >>= (@?= [Only (2 :: Int64)])
+    , testCase "nextRowWith runs the supplied parser" $ withDb \conn ->
+        withStatement conn "SELECT 20, 22" \stmt ->
+          Streaming.nextRowWith ((+) <$> field <*> field) stmt >>= (@?= Just (42 :: Int64))
+    , testGroup "decoder cursor ownership" $
+        map (uncurry decoderCursorTests) [("materialized", nextRowWith), ("streaming", Streaming.nextRowWith)]
+    , testCase "eager decoder cannot read uncached native metadata after connection close" $
+        withEnvironment \env -> withInstance env [] \inst -> withConnectionOn inst \conn -> do
+          let parser = fieldWith \column -> liftConversion (close conn) >> fieldType column
+          err <- expectSqlError (queryWith_ parser conn "SELECT 42")
+          assertBool "expected closed connection" ("connection is closed" `Text.isInfixOf` sqlErrorMessage err)
+    , testCase "a fetch failure follows an already delivered batch" $ withDb \conn -> do
+        void $ execute_ conn "SET streaming_buffer_size = '64KB'"
+        failNext <- newIORef False
+        delivered <- newIORef (0 :: Int)
+        batchSize <- fromIntegral <$> Retained.c_duckdb_vector_size
+        createFunction conn "late_stream_error" \(value :: Int64) -> do
+          shouldFail <- readIORef failNext
+          when shouldFail (throwIO (userError "late stream error"))
+          pure value
+        err <- expectSqlError $ Streaming.fold_ conn "SELECT late_stream_error(i) FROM range(1000000) t(i)" (0 :: Int) \count (Only (_ :: Int64)) -> do
+          let next = count + 1
+          writeIORef delivered next
+          when (next == batchSize) (atomicWriteIORef failNext True)
+          pure next
+        count <- readIORef delivered
+        assertBool "the first batch must precede the error" (count >= batchSize)
+        assertBool "fetch error must retain its message" ("late stream error" `Text.isInfixOf` sqlErrorMessage err)
+        assertReusable conn
+    , testCase "Arrow reports a fetch failure after a delivered batch" $ withDb \conn -> do
+        void $ execute_ conn "SET streaming_buffer_size = '64KB'"
+        failNext <- newIORef False
+        createFunction conn "late_arrow_error" \(value :: Int64) -> do
+          shouldFail <- readIORef failNext
+          when shouldFail (throwIO (userError "late Arrow error"))
+          pure value
+        err <- expectSqlError $ Streaming.foldArrow_ conn "SELECT late_arrow_error(i) FROM range(1000000) t(i)" () \() _ _ ->
+          atomicWriteIORef failNext True
+        readIORef failNext >>= assertBool "a batch reached the callback"
+        assertBool "fetch error must retain its message" ("late Arrow error" `Text.isInfixOf` sqlErrorMessage err)
+        assertReusable conn
+    , testCase "row decode failure exhausts and releases the cursor" $ withDb \conn -> do
+        withStatement conn "SELECT {'n': i} FROM range(5000) t(i)" \stmt -> do
+          void $ expectSqlError (Streaming.nextRow stmt :: IO (Maybe (Only Int64)))
+          cursor <- readIORef (statementStream stmt)
+          case cursor of
+            StatementStreamExhausted -> pure ()
+            _ -> assertFailure "expected an exhausted cursor after the decode failure"
+          Streaming.nextRow stmt >>= (@?= (Nothing :: Maybe (Only Int64)))
+        assertReusable conn
+        -- DuckDB refuses each other query of the connection while a native stream
+        -- runs. A query that works while the statement is open shows that the
+        -- failure released the native result. The large result keeps the stream
+        -- running after the first chunk.
+        withStatement conn "SELECT {'n': i} FROM range(1000000) t(i)" \stmt -> do
+          void $ expectSqlError (Streaming.nextRow stmt :: IO (Maybe (Only Int64)))
+          assertReusable conn
+    , -- The case of the leak test for a statement that closes with a live cursor
+      -- checks the release of the chunks.
+      testCase "a failing step of a streaming fold raises its error and leaves the connection usable" $ withDb \conn -> do
+        outcome <- try $ Streaming.fold_ conn "SELECT {'n': i, 'list': [i, NULL]} FROM range(5000) t(i)" (0 :: Int) \count (Only (_ :: FieldValue)) ->
+          if count == 2050 then throwIO (userError "stream step failure") else pure (count + 1)
+        case outcome of
+          Left (err :: IOException) -> assertBool "original callback error" ("stream step failure" `isInfixOf` show err)
+          Right _ -> assertFailure "expected the callback to fail"
+        assertReusable conn
+    , testCase "a query of another thread during an explicit stream fails and the stream continues" $ withDb \conn -> do
+        -- The case needs a statement that still runs after the first row, so
+        -- the stream reads a large result.
+        finished <- timeout 120000000 $ withStatement conn "SELECT i FROM range(1000000) t(i)" \stmt -> do
+          Streaming.nextRow stmt >>= (@?= Just (Only (0 :: Int64)))
+          other <- newEmptyMVar
+          _ <- forkIO (try (query_ conn "SELECT 42" :: IO [Only Int64]) >>= putMVar other)
+          outcome <- takeMVar other
+          case outcome of
+            Left (err :: SQLError) -> sqlErrorType err @?= Just ErrorResourceInUse
+            Right _ -> assertFailure "expected a busy connection during the stream"
+          let readFrom expected = do
+                row <- Streaming.nextRow stmt
+                case row of
+                  Nothing -> pure expected
+                  Just (Only value) -> do
+                    when (value /= expected) $ assertFailure ("expected row " <> show expected <> ", got " <> show value)
+                    readFrom (expected + 1)
+          readFrom (1 :: Int64) >>= (@?= 1000000)
+        finished @?= Just ()
+        assertReusable conn
+    , testCase "filtered results give each row through each read function" $
+        forM_ ["1", "4"] \threads -> withConnectionWithConfig ":memory:" [("threads", threads)] \conn ->
+          forM_ filteredQueries \(sql, expected) ->
+            forM_ readFunctions \(name, readRows) -> do
+              rows <- map fromOnly <$> readRows conn sql
+              -- With more than one thread, DuckDB can give the rows in another order.
+              assertEqual (name <> " with " <> Text.unpack threads <> " threads: " <> show sql) expected (if threads == "1" then rows else sort rows)
+    , testCase "filtered and joined VARIANT and GEOMETRY columns give the value of their row" $ withDb \conn -> do
+        -- A filter or the probe side of a hash join can give a vector with a
+        -- selection. Each row holds its own key, so a value of another row fails.
+        void $
+          execute_ conn "CREATE TABLE shaped AS SELECT i, {'n': i}::VARIANT AS v, ('POINT (' || i || ' 0)')::GEOMETRY AS g FROM range(5000) t(i)"
+        forM_
+          [ ("SELECT i, v, g FROM shaped WHERE i % 3 = 1", [1, 4 .. 4999])
+          , ("SELECT a.i, a.v, a.g FROM shaped a JOIN (SELECT j FROM range(0, 5000, 7) t(j)) b ON a.i = b.j", [0, 7 .. 4999])
+          ]
+          \(sql, keys) ->
+            forM_ readFunctions \(name, readRows) -> do
+              rows <- readRows conn sql
+              assertEqual
+                (name <> ": " <> show sql)
+                [(key, Variant (variantObject [("n", FieldInt64 key)]), pointWkb key) | key <- keys]
+                (sortOn (\(key, _, _) -> key) [(key, value, rawGeometryWKB geometry) | (key, value, geometry) <- rows])
+    ]
 
+-- | Check operations on the same statement from inside its decoder.
+decoderCursorTests :: String -> (RowParser Int64 -> Statement -> IO (Maybe Int64)) -> TestTree
+decoderCursorTests name next =
+  testGroup
+    name
+    [ testCase "a nested fetch consumes the next row" $ withDb \conn ->
+        withStatement conn "SELECT i FROM range(1,4) t(i)" \stmt -> do
+          let parser = fieldWith \column -> do
+                liftConversion (next field stmt >>= (@?= Just 2))
+                fromField column
+          next parser stmt >>= (@?= Just 1)
+          next field stmt >>= (@?= Just 3)
+    , testCase "reset on the last row leaves the statement idle" $ withDb \conn ->
+        withStatement conn "SELECT 42" \stmt -> do
+          let parser = fieldWith \column -> do
+                liftConversion (clearStatementBindings stmt)
+                fromField column
+          next parser stmt >>= (@?= Just 42)
+          next field stmt >>= (@?= Just 42)
+    , testCase "decoder failure preserves a replacement cursor" $ withDb \conn ->
+        withStatement conn "SELECT ?::BIGINT + i FROM range(2) t(i)" \stmt -> do
+          bind stmt [toField (10 :: Int64)]
+          let parser = fieldWith \_ -> liftConversion do
+                bind stmt [toField (20 :: Int64)]
+                next field stmt >>= (@?= Just 20)
+                throwIO (userError "decoder failed after rebind")
+          outcome <- try (next parser stmt)
+          case outcome of
+            Left (err :: IOException) -> assertBool "original decoder error" ("decoder failed after rebind" `isInfixOf` show err)
+            Right _ -> assertFailure "expected the decoder to fail"
+          next field stmt >>= (@?= Just 21)
+    ]
+
+-- | Read the rows of a query with each read function of the library.
+readFunctions :: (FromRow row) => [(String, Connection -> Query -> IO [row])]
+readFunctions =
+  [ ("query_", query_)
+  , ("fold_", \conn sql -> reverse <$> fold_ conn sql [] (\rows row -> pure (row : rows)))
+  , ("nextRow", \conn sql -> withStatement conn sql (readEach nextRow))
+  , ("Streaming.fold_", \conn sql -> reverse <$> Streaming.fold_ conn sql [] (\rows row -> pure (row : rows)))
+  , ("Streaming.nextRow", \conn sql -> withStatement conn sql (readEach Streaming.nextRow))
+  ]
+  where
+    readEach :: (Statement -> IO (Maybe row)) -> Statement -> IO [row]
+    readEach next stmt = go []
+      where
+        go rows = next stmt >>= maybe (pure (reverse rows)) (\row -> go (row : rows))
+
+-- | The WKB of the point (x, 0) in the little-endian byte order. DuckDB 2.0.0
+-- gives the same bytes for 'POINT (x 0)'::GEOMETRY::BLOB.
+pointWkb :: Int64 -> BS.ByteString
+pointWkb x = BL.toStrict (Builder.toLazyByteString (Builder.word8 1 <> Builder.word32LE 1 <> Builder.doubleLE (fromIntegral x) <> Builder.doubleLE 0))
+
 -- | Run each case with one native worker so row order is stable.
 withDb :: (Connection -> IO a) -> IO a
 withDb = withConnectionWithConfig ":memory:" [("threads", "1")]
@@ -150,13 +282,7 @@
 -- | Require a SQL or field conversion error and retain its diagnostic fields.
 expectSqlError :: IO a -> IO SQLError
 expectSqlError action = do
-    outcome <- try action
-    case outcome of
-        Left err -> pure err
-        Right _ -> assertFailure "expected SQLError" >> fail "expected SQLError"
-
--- | Verify that cleanup leaves the connection ready for another query.
-assertReusable :: Connection -> Assertion
-assertReusable conn = do
-    rows <- query_ conn "SELECT 42" :: IO [Only Int64]
-    rows @?= [Only 42]
+  outcome <- try action
+  case outcome of
+    Left err -> pure err
+    Right _ -> assertFailure "expected SQLError" >> fail "expected SQLError"
diff --git a/test/TestUtils.hs b/test/TestUtils.hs
--- a/test/TestUtils.hs
+++ b/test/TestUtils.hs
@@ -1,13 +1,245 @@
--- | Assertions that several test modules share.
-module TestUtils (assertFailureIO) where
+{-# LANGUAGE OverloadedStrings #-}
 
+-- |
+-- Module      : TestUtils
+-- Description : Assertions that several test modules share.
+module TestUtils (
+  NativeTimestamp (..),
+  assertFailureIO,
+  assertInputError,
+  assertInputErrorContaining,
+  assertRangeError,
+  assertReleasedAfter,
+  assertReusable,
+  assertSqlErrorContaining,
+  assertSqlErrorType,
+  filteredQueries,
+  nativeLocalTime,
+  raiseCapabilities,
+  sized,
+  withConstCString,
+  writeIntegers,
+  writeNullRows,
+) where
+
+import Control.Concurrent (MVar, getNumCapabilities, newMVar, setNumCapabilities, withMVar)
 import Control.Exception (SomeException, try)
-import Test.Tasty.HUnit (Assertion, assertFailure)
+import Control.Monad (forM_, void, when)
+import Data.IORef (IORef, mkWeakIORef, newIORef)
+import Data.Int (Int64)
+import Data.Maybe (fromMaybe, isNothing)
+import Data.Ratio ((%))
+import qualified Data.Text as Text
+import Data.Time.Clock.POSIX (posixSecondsToUTCTime)
+import Data.Time.LocalTime (LocalTime, utc, utcToLocalTime)
+import Database.DuckDB.FFI.V2 (
+  DuckDBV2CastFunctionExecInfoHandle,
+  DuckDBV2VectorHandle,
+  c_duckdb_v2_cast_function_exec_get_output,
+  c_duckdb_v2_cast_function_exec_get_row_count,
+  c_duckdb_v2_value_create_timestamp,
+  c_duckdb_v2_value_create_timestamp_ms,
+  c_duckdb_v2_value_create_timestamp_ns,
+  c_duckdb_v2_value_create_timestamp_sec,
+  c_duckdb_v2_vector_flatten,
+  c_duckdb_v2_vector_get_data_mutable,
+  c_duckdb_v2_vector_set_null,
+  c_duckdb_v2_vector_set_size,
+ )
+import Database.DuckDB.Simple (Connection, ErrorType (..), Only (..), Query, SQLError (..), SizedArray, query_, sizedArrayFromList)
+import Database.DuckDB.Simple.ToField (DuckDBColumnType (..), ToDuckValue (..), ToField)
+import Database.DuckDB.Simple.V2.Registration (checked, output)
+import Foreign.C.ConstPtr (ConstPtr (..))
+import Foreign.C.String (withCString)
+import Foreign.C.Types (CChar)
+import Foreign.Ptr (castPtr)
+import Foreign.Storable (pokeElemOff)
+import GHC.TypeLits (KnownNat)
+import System.IO.Unsafe (unsafePerformIO)
+import System.Mem (performMajorGC)
+import System.Mem.Weak (deRefWeak)
+import Test.Tasty.HUnit (Assertion, assertBool, assertFailure, (@?=))
 
+{- Note [Capabilities of the tests]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Some cases need more than one capability of the GHC runtime, for example to
+run several Haskell threads on one connection at the same time. Such a case
+raises the capability count with raiseCapabilities. No case lowers the count,
+also not to restore it after the case.
+
+The reason is a defect of the GHC runtime, seen with GHC 9.14.1. After
+setNumCapabilities lowers the count, the runtime keeps the other capabilities
+as disabled capabilities. A callback from a foreign thread, for example from
+a DuckDB worker thread, can then run on a disabled capability. A garbage
+collection can then lose the wake-up of that callback. The callback then
+waits for ever, and the test run does not end.
+
+The capability count is shared by all cases in the process. capabilityLock
+serializes the read and change in raiseCapabilities. Without this lock, two
+cases can read the same count, then set a larger count followed by a smaller
+count.
+-}
+
+-- | Serialize capability changes in this process. See
+-- Note [Capabilities of the tests].
+capabilityLock :: MVar ()
+capabilityLock = unsafePerformIO (newMVar ())
+{-# NOINLINE capabilityLock #-}
+
+-- | Raise the capability count of the GHC runtime to the given count. Do not
+-- lower it. See Note [Capabilities of the tests].
+raiseCapabilities :: Int -> IO ()
+raiseCapabilities wanted = withMVar capabilityLock $ \_ -> do
+  current <- getNumCapabilities
+  when (wanted > current) (setNumCapabilities wanted)
+
 -- | Require an exception without depending on native error text.
 assertFailureIO :: IO a -> Assertion
 assertFailureIO action = do
-    result <- try (action >> pure ()) :: IO (Either SomeException ())
-    case result of
-        Left _ -> pure ()
-        Right () -> assertFailure "expected an exception"
+  result <- try (action >> pure ()) :: IO (Either SomeException ())
+  case result of
+    Left _ -> pure ()
+    Right () -> assertFailure "expected an exception"
+
+-- | A timestamp in the raw unit of one of the four TIMESTAMP types. A
+-- parameter of this type stores the raw value, also one that no Haskell time
+-- type can bind, such as a value of seconds outside the range of microseconds.
+data NativeTimestamp = Seconds Int64 | Milliseconds Int64 | Microseconds Int64 | Nanoseconds Int64
+  deriving (Show)
+
+instance DuckDBColumnType NativeTimestamp where
+  duckdbColumnTypeFor _ = "TIMESTAMP"
+
+instance ToDuckValue NativeTimestamp where
+  toDuckValue factory (Seconds value) = output (c_duckdb_v2_value_create_timestamp_sec factory value)
+  toDuckValue factory (Milliseconds value) = output (c_duckdb_v2_value_create_timestamp_ms factory value)
+  toDuckValue factory (Microseconds value) = output (c_duckdb_v2_value_create_timestamp factory value)
+  toDuckValue factory (Nanoseconds value) = output (c_duckdb_v2_value_create_timestamp_ns factory value)
+
+instance ToField NativeTimestamp
+
+-- | The local time in UTC of a raw timestamp. The computation uses neither
+-- DuckDB nor duckdb-simple.
+nativeLocalTime :: NativeTimestamp -> LocalTime
+nativeLocalTime timestamp = utcToLocalTime utc (posixSecondsToUTCTime (fromRational (toInteger value % units)))
+  where
+    (value, units) = case timestamp of
+      Seconds raw -> (raw, 1)
+      Milliseconds raw -> (raw, 1000)
+      Microseconds raw -> (raw, 1000000)
+      Nanoseconds raw -> (raw, 1000000000)
+
+-- | Require the error of an input check of the library: an 'SQLError' of the
+-- type 'ErrorInputInvalid' whose message starts with "duckdb-simple: ".
+assertInputError :: IO a -> Assertion
+assertInputError = assertInputErrorContaining Text.empty
+
+-- | Require the error of an input check of the library, of the type
+-- ErrorInputInvalid, which includes the expected message.
+assertInputErrorContaining :: Text.Text -> IO a -> Assertion
+assertInputErrorContaining expected action = do
+  outcome <- try (void action)
+  case outcome of
+    Left err -> do
+      sqlErrorType err @?= Just ErrorInputInvalid
+      -- The prefix shows that a check of the library raised the error, not DuckDB.
+      assertBool ("expected an input error containing " <> show expected <> ", got " <> show err) $
+        ("duckdb-simple: " `Text.isPrefixOf` sqlErrorMessage err) && expected `Text.isInfixOf` sqlErrorMessage err
+    Right () -> assertFailure "expected the error of an input check"
+
+-- | Require the error of a check of the library for a value that its SQL type
+-- cannot hold: an 'SQLError' of the type 'ErrorTypeConversion' whose message
+-- starts with "duckdb-simple: ".
+assertRangeError :: IO a -> Assertion
+assertRangeError action = do
+  result <- try action
+  case result of
+    Left err -> do
+      sqlErrorType err @?= Just ErrorTypeConversion
+      assertBool (Text.unpack (sqlErrorMessage err)) ("duckdb-simple: " `Text.isPrefixOf` sqlErrorMessage err)
+    Right _ -> assertFailure "expected an SQLError of the type ErrorTypeConversion"
+
+-- | Require that the connection runs another query. A case uses it after a
+-- cleanup or an interrupted query, to show that the connection state is released.
+assertReusable :: Connection -> Assertion
+assertReusable conn = do
+  rows <- query_ conn "SELECT 42" :: IO [Only Int64]
+  rows @?= [Only 42]
+
+-- | Require a SQL exception which includes the expected message.
+assertSqlErrorContaining :: Text.Text -> IO a -> Assertion
+assertSqlErrorContaining expected action = do
+  outcome <- try (void action)
+  case outcome of
+    Left err ->
+      assertBool ("expected SQL error containing " <> show expected <> ", got " <> show err) $
+        expected `Text.isInfixOf` sqlErrorMessage err
+    Right () -> assertFailure "expected SQL error"
+
+-- | Require an 'SQLError' of DuckDB with the given type. An error of
+-- duckdb-simple, whose message starts with "duckdb-simple: ", fails the
+-- assertion, also when it has the same type.
+assertSqlErrorType :: ErrorType -> IO a -> Assertion
+assertSqlErrorType expected action = do
+  result <- try action
+  case result of
+    Left err -> do
+      assertBool
+        ("expected an error of DuckDB, got " <> Text.unpack (sqlErrorMessage err))
+        (not ("duckdb-simple: " `Text.isPrefixOf` sqlErrorMessage err))
+      sqlErrorType err @?= Just expected
+    Right _ -> assertFailure ("expected an SQLError of the type " <> show expected)
+
+-- | Run an action with a new token, and require that no value keeps the token
+-- after the action and two major collections. The action gives the token to the
+-- callbacks of a registration that fails, is replaced, or ends with its database.
+assertReleasedAfter :: String -> (IORef Int64 -> IO ()) -> Assertion
+assertReleasedAfter label action = do
+  weak <- do
+    token <- newIORef 1
+    weak <- mkWeakIORef token (pure ())
+    action token
+    pure weak
+  performMajorGC
+  performMajorGC
+  deRefWeak weak >>= assertBool (label <> " keeps its callback after the case") . isNothing
+
+-- | Supply a constant C string for one native call.
+withConstCString :: String -> (ConstPtr CChar -> IO a) -> IO a
+withConstCString text action = withCString text (action . ConstPtr)
+
+-- | Set the size of a BIGINT vector and write the values to its rows. The
+-- function flattens the vector first, so that each row has its own slot: the
+-- header gives the data pointer of a FLAT or CONSTANT vector, and a CONSTANT
+-- vector has one value for all rows. A flatten does nothing for a FLAT vector.
+writeIntegers :: DuckDBV2VectorHandle -> [Int64] -> IO ()
+writeIntegers vector values = do
+  checked (c_duckdb_v2_vector_set_size vector (fromIntegral (length values)))
+  checked (c_duckdb_v2_vector_flatten vector)
+  raw <- output (c_duckdb_v2_vector_get_data_mutable vector)
+  forM_ (zip [0 ..] values) $ \(index, value) -> pokeElemOff (castPtr raw) index value
+
+-- | Write NULL to each row of the output vector of a cast call. The function
+-- reads no input row.
+writeNullRows :: DuckDBV2CastFunctionExecInfoHandle -> IO ()
+writeNullRows info = do
+  rows <- output (c_duckdb_v2_cast_function_exec_get_row_count info)
+  vector <- output (c_duckdb_v2_cast_function_exec_get_output info)
+  checked (c_duckdb_v2_vector_set_size vector rows)
+  checked (c_duckdb_v2_vector_flatten vector)
+  forM_ [0 .. fromIntegral rows - 1 :: Int] $ \row -> checked (c_duckdb_v2_vector_set_null vector (fromIntegral row))
+
+-- | Filtered queries over more than one chunk, each with the rows that DuckDB
+-- gives. After the filter, most chunks of the second and the third query have
+-- no row.
+filteredQueries :: [(Query, [Int64])]
+filteredQueries =
+  [ ("SELECT i FROM range(100000) t(i) WHERE i < 3 OR i >= 99997", [0, 1, 2, 99997, 99998, 99999])
+  , ("SELECT i FROM range(1000000) t(i) WHERE i % 100000 = 99999", [99999, 199999 .. 999999])
+  , ("SELECT i FROM range(1000000) t(i) WHERE i = 999999", [999999])
+  ]
+
+-- | Make a 'SizedArray' from a list of its length. A list of another length
+-- is a defect of the case.
+sized :: (KnownNat n) => [a] -> SizedArray n a
+sized values = fromMaybe (error ("sized: a list of " <> show (length values) <> " elements")) (sizedArrayFromList values)
diff --git a/test/TimeTests.hs b/test/TimeTests.hs
--- a/test/TimeTests.hs
+++ b/test/TimeTests.hs
@@ -1,92 +1,149 @@
+{-# LANGUAGE DataKinds #-}
 {-# LANGUAGE DeriveGeneric #-}
 {-# LANGUAGE DerivingVia #-}
+{-# LANGUAGE LambdaCase #-}
 {-# LANGUAGE NamedFieldPuns #-}
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE ScopedTypeVariables #-}
 
--- | Round trips for finite dates and native temporal infinities.
+-- |
+-- Module      : TimeTests
+-- Description : Round trips for finite dates and native temporal infinities.
 module TimeTests (timeTests) where
 
-import Control.Exception (try)
-import Control.Monad (forM_)
+import Control.Exception (fromException, throwIO, try)
+import Control.Monad (forM_, void)
 import Data.Array (listArray)
+import Data.Int (Int64)
+import qualified Data.Map.Strict as Map
+import Data.Ratio ((%))
 import qualified Data.Text as Text
-import Data.Time (Day, LocalTime (..), TimeOfDay (..), UTCTime, fromGregorian, localTimeToUTC, utc)
+import Data.Time (Day, LocalTime (..), TimeOfDay (..), UTCTime (..), addDays, fromGregorian, localTimeToUTC, utc, utcToLocalTime)
+import Data.Time.Clock.POSIX (posixSecondsToUTCTime)
 import Database.DuckDB.Simple
-import Database.DuckDB.Simple.FromField (Field (..), FieldValue (..), returnError)
+import Database.DuckDB.Simple.FromField (Field (..), FieldValue (..), TimeWithZone (..), returnError)
 import Database.DuckDB.Simple.Generic (ViaDuckDB (..))
+import Database.DuckDB.Simple.LogicalRep (
+  LogicalTypeRep (..),
+  StructField (..),
+  StructValue (..),
+  TupleValue (..),
+  UnionMemberType (..),
+  UnionValue (..),
+ )
+import Database.DuckDB.Simple.Ok (Ok (..))
+import qualified Database.DuckDB.Simple.Registration as R
 import Database.DuckDB.Simple.Time
+import Database.DuckDB.Simple.Variant (Variant (..))
 import GHC.Generics (Generic)
 import Test.Tasty (TestTree, testGroup)
 import Test.Tasty.HUnit
+import TestUtils (assertInputError, assertRangeError, sized)
 
 -- | Record fields exercise the generic scalar and collection instances.
 data TemporalRecord = TemporalRecord
-    { dateValue :: Date
-    , localValue :: LocalTimestamp
-    , utcValue :: UTCTimestamp
-    , optionalValue :: Maybe Date
-    , dates :: [Date]
-    }
-    deriving stock (Eq, Show, Generic)
-    deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB TemporalRecord)
+  { dateValue :: Date
+  , localValue :: LocalTimestamp
+  , utcValue :: UTCTimestamp
+  , optionalValue :: Maybe Date
+  , dates :: [Date]
+  }
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB TemporalRecord)
 
 -- | Each constructor retains its temporal member type.
 data TemporalSum = ADate Date | ALocal LocalTimestamp | AUtc UTCTimestamp | ADateNull (Maybe Date)
-    deriving stock (Eq, Show, Generic)
-    deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB TemporalSum)
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB TemporalSum)
 
 -- | A custom decoder must receive infinity before any finite conversion.
 newtype InfinitySign = InfinitySign Int
-    deriving (Eq, Show)
+  deriving (Eq, Show)
 
 instance FromField InfinitySign where
-    fromField f@Field{fieldValue} = case fieldValue of
-        FieldDate NegInfinity -> pure (InfinitySign (-1))
-        FieldDate (Finite _) -> pure (InfinitySign 0)
-        FieldDate PosInfinity -> pure (InfinitySign 1)
-        _ -> returnError Incompatible f "expected DATE"
+  fromField f@Field{fieldValue} = case fieldValue of
+    FieldDate NegInfinity -> pure (InfinitySign (-1))
+    FieldDate (Finite _) -> pure (InfinitySign 0)
+    FieldDate PosInfinity -> pure (InfinitySign 1)
+    _ -> returnError Incompatible f "expected DATE"
 
 -- | Exercise native binding, eager queries, cursors, and generic composites.
 timeTests :: TestTree
 timeTests =
-    testGroup
-        "temporal infinity"
-        [ testCase "dates bind and decode with their SQL type" $ withConnection ":memory:" $ \conn ->
-            forM_ [NegInfinity, Finite day, PosInfinity] $ \value -> do
-                (query conn "SELECT ?, typeof(?)" (value, value) :: IO [(Date, String)]) >>= (@?= [(value, "DATE")])
-                (query conn "SELECT ?::VARCHAR" (Only value) :: IO [Only String]) >>= (@?= [Only (dateText value)])
-        , testCase "local timestamps bind and decode with their SQL type" $ withConnection ":memory:" $ \conn ->
-            forM_ [NegInfinity, Finite local, PosInfinity] $ \value ->
-                (query conn "SELECT ?, typeof(?)" (value, value) :: IO [(LocalTimestamp, String)]) >>= (@?= [(value, "TIMESTAMP")])
-        , testCase "UTC timestamps preserve instants and infinities outside UTC" $ withConnection ":memory:" $ \conn -> do
-            _ <- execute_ conn "SET TimeZone='Pacific/Auckland'"
-            forM_ [NegInfinity, Finite instant, PosInfinity] $ \value ->
-                (query conn "SELECT ?, typeof(?)" (value, value) :: IO [(UTCTimestamp, String)]) >>= (@?= [(value, "TIMESTAMP WITH TIME ZONE")])
-        , testCase "infinity and NULL remain distinct" $ withConnection ":memory:" $ \conn -> do
-            (query conn "SELECT ?::DATE, ?::TIMESTAMP, ?::TIMESTAMPTZ" (Nothing :: Maybe Date, Nothing :: Maybe LocalTimestamp, Nothing :: Maybe UTCTimestamp) :: IO [(Maybe Date, Maybe LocalTimestamp, Maybe UTCTimestamp)]) >>= (@?= [(Nothing, Nothing, Nothing)])
-            (query_ conn "SELECT 'infinity'::DATE" :: IO [Only (Maybe Date)]) >>= (@?= [Only (Just PosInfinity)])
-        , testCase "ordinary finite targets reject infinity with a conversion error" $ withConnection ":memory:" $ \conn -> do
-            assertConversionError (query_ conn "SELECT 'infinity'::DATE" :: IO [Only Day])
-            assertConversionError (query_ conn "SELECT '-infinity'::TIMESTAMP" :: IO [Only LocalTime])
-            assertConversionError (query_ conn "SELECT 'infinity'::TIMESTAMPTZ" :: IO [Only UTCTime])
-            assertConversionError (query_ conn "SELECT 'infinity'::TIMESTAMP" :: IO [Only TimeOfDay])
-            (query_ conn "SELECT 42" :: IO [Only Int]) >>= (@?= [Only 42])
-        , testCase "custom FromField receives native infinity" $ withConnection ":memory:" $ \conn ->
-            (query_ conn "SELECT value FROM (VALUES ('-infinity'::DATE), (DATE '2000-01-02'), ('infinity'::DATE)) t(value) ORDER BY value" :: IO [Only InfinitySign]) >>= (@?= map (Only . InfinitySign) [-1, 0, 1])
-        , testCase "cursors preserve infinities" $ withConnection ":memory:" $ \conn -> do
-            values <- fold_ conn "SELECT value FROM (VALUES ('-infinity'::DATE), (DATE '2000-01-02'), ('infinity'::DATE)) t(value) ORDER BY value" [] (\acc (Only value) -> pure (value : acc))
-            reverse values @?= [NegInfinity, Finite day, PosInfinity]
-        , testCase "date arrays preserve infinities" $ withConnection ":memory:" $ \conn -> do
-            let values = listArray (0 :: Int, 2) [NegInfinity, Finite day, PosInfinity]
-            query conn "SELECT ?" (Only values) >>= (@?= [Only values])
-        , testCase "generic records retain finite values infinities and NULL" $ withConnection ":memory:" $ \conn -> do
-            let values = TemporalRecord NegInfinity (Finite local) PosInfinity Nothing [PosInfinity, Finite day, NegInfinity]
-            query conn "SELECT ?" (Only values) >>= (@?= [Only values])
-        , testCase "generic union payloads retain their types" $ withConnection ":memory:" $ \conn ->
-            forM_ [ADate NegInfinity, ADate (Finite day), ALocal PosInfinity, AUtc NegInfinity, ADateNull Nothing] $ \value ->
-                query conn "SELECT ?" (Only value) >>= (@?= [Only value])
-        ]
+  testGroup
+    "temporal infinity"
+    $ [ testCase "dates bind and decode with their SQL type" $ withConnection ":memory:" $ \conn ->
+          forM_ [NegInfinity, Finite day, PosInfinity] $ \value -> do
+            (query conn "SELECT ?, typeof(?)" (value, value) :: IO [(Date, String)]) >>= (@?= [(value, "DATE")])
+            (query conn "SELECT ?::VARCHAR" (Only value) :: IO [Only String]) >>= (@?= [Only (dateText value)])
+      , testCase "local timestamps bind and decode with their SQL type" $ withConnection ":memory:" $ \conn ->
+          forM_ [NegInfinity, Finite local, PosInfinity] $ \value ->
+            (query conn "SELECT ?, typeof(?)" (value, value) :: IO [(LocalTimestamp, String)]) >>= (@?= [(value, "TIMESTAMP")])
+      , testCase "UTC timestamps preserve instants and infinities outside UTC" $ withConnection ":memory:" $ \conn -> do
+          _ <- execute_ conn "SET TimeZone='Pacific/Auckland'"
+          forM_ [NegInfinity, Finite instant, PosInfinity] $ \value ->
+            (query conn "SELECT ?, typeof(?)" (value, value) :: IO [(UTCTimestamp, String)]) >>= (@?= [(value, "TIMESTAMP WITH TIME ZONE")])
+      , testCase "infinity and NULL remain distinct" $ withConnection ":memory:" $ \conn -> do
+          ( query
+              conn
+              "SELECT ?::DATE, ?::TIMESTAMP, ?::TIMESTAMPTZ"
+              (Nothing :: Maybe Date, Nothing :: Maybe LocalTimestamp, Nothing :: Maybe UTCTimestamp)
+              :: IO [(Maybe Date, Maybe LocalTimestamp, Maybe UTCTimestamp)]
+            )
+            >>= (@?= [(Nothing, Nothing, Nothing)])
+          (query_ conn "SELECT 'infinity'::DATE" :: IO [Only (Maybe Date)]) >>= (@?= [Only (Just PosInfinity)])
+      , testCase "ordinary finite targets reject infinity with a conversion error" $ withConnection ":memory:" $ \conn -> do
+          assertConversionError (query_ conn "SELECT 'infinity'::DATE" :: IO [Only Day])
+          assertConversionError (query_ conn "SELECT '-infinity'::TIMESTAMP" :: IO [Only LocalTime])
+          assertConversionError (query_ conn "SELECT 'infinity'::TIMESTAMPTZ" :: IO [Only UTCTime])
+          assertConversionError (query_ conn "SELECT 'infinity'::TIMESTAMP" :: IO [Only TimeOfDay])
+          (query_ conn "SELECT 42" :: IO [Only Int]) >>= (@?= [Only 42])
+      , testCase "a conversion error names a time zone type as DuckDB does" $ withConnection ":memory:" $ \conn -> do
+          [(timestamp, time)] <- query_ conn "SELECT TIMESTAMPTZ '2000-01-02 03:04:05+00', TIMETZ '03:04:05+00'"
+          -- A Field of the type VARIANT names the type of its value with the
+          -- text of DuckDB.
+          forM_ [(timestamp, "TIMESTAMP WITH TIME ZONE"), (time, "TIME WITH TIME ZONE")] $ \(value, name) ->
+            runConversion
+              ( fromField Field{fieldName = "value", fieldIndex = 0, fieldValue = value, fieldType = pure (LogicalTypeScalar LogicalTypeIdVariant)}
+                  :: Conversion Int64
+              )
+              >>= \case
+                Errors errors -> map (fmap errSQLType . fromException) errors @?= [Just name]
+                Ok number -> assertFailure ("expected a conversion error, got " <> show number)
+          -- The message of a query names the column type with the text of DuckDB.
+          forM_
+            [ ("SELECT TIMESTAMPTZ '2000-01-02 03:04:05+00'", " has type TIMESTAMP WITH TIME ZONE ")
+            , ("SELECT TIMETZ '03:04:05+00'", " has type TIME WITH TIME ZONE ")
+            ]
+            $ \(sql, expected) -> do
+              result <- try (query_ conn sql :: IO [Only Int64])
+              case result of
+                Left SQLError{sqlErrorMessage = message} -> assertBool (Text.unpack message) (expected `Text.isInfixOf` message)
+                Right rows -> assertFailure ("expected a conversion error, got " <> show rows)
+      , testCase "custom FromField receives native infinity" $ withConnection ":memory:" $ \conn ->
+          ( query_ conn "SELECT value FROM (VALUES ('-infinity'::DATE), (DATE '2000-01-02'), ('infinity'::DATE)) t(value) ORDER BY value"
+              :: IO [Only InfinitySign]
+          )
+            >>= (@?= map (Only . InfinitySign) [-1, 0, 1])
+      , testCase "cursors preserve infinities" $ withConnection ":memory:" $ \conn -> do
+          values <-
+            fold_
+              conn
+              "SELECT value FROM (VALUES ('-infinity'::DATE), (DATE '2000-01-02'), ('infinity'::DATE)) t(value) ORDER BY value"
+              []
+              (\acc (Only value) -> pure (value : acc))
+          reverse values @?= [NegInfinity, Finite day, PosInfinity]
+      , testCase "date arrays preserve infinities" $ withConnection ":memory:" $ \conn -> do
+          let values = sized [NegInfinity, Finite day, PosInfinity] :: SizedArray 3 (Unbounded Day)
+          query conn "SELECT ?" (Only values) >>= (@?= [Only values])
+      , testCase "generic records retain finite values infinities and NULL" $ withConnection ":memory:" $ \conn -> do
+          let values = TemporalRecord NegInfinity (Finite local) PosInfinity Nothing [PosInfinity, Finite day, NegInfinity]
+          query conn "SELECT ?" (Only values) >>= (@?= [Only values])
+      , testCase "generic union payloads retain their types" $ withConnection ":memory:" $ \conn ->
+          forM_ [ADate NegInfinity, ADate (Finite day), ALocal PosInfinity, AUtc NegInfinity, ADateNull Nothing] $ \value ->
+            query conn "SELECT ?" (Only value) >>= (@?= [Only value])
+      ]
+      <> nanosecondTimeTests
   where
     day = fromGregorian 2000 1 2
     local = LocalTime day (TimeOfDay 3 4 5)
@@ -95,11 +152,723 @@
     dateText PosInfinity = "infinity"
     dateText (Finite _) = "2000-01-02"
 
+-- | Check explicit nanosecond targets without changing ordinary UTC parameter types.
+nanosecondTimeTests :: [TestTree]
+nanosecondTimeTests =
+  [ testCase "nanosecond UTC results and VARIANTs preserve precision and infinity" $ withConnection ":memory:" $ \conn -> do
+      _ <- execute_ conn "SET TimeZone='Pacific/Auckland'"
+      let precise = localTimeToUTC utc (LocalTime (fromGregorian 2000 1 2) (TimeOfDay 3 4 5.123456789))
+      forM_ [("'2000-01-02 03:04:05.123456789+00'", Finite precise), ("'infinity'", PosInfinity), ("'-infinity'", NegInfinity)] $ \(literal, expected) -> do
+        let sql = Query ("SELECT " <> literal <> "::TIMESTAMPTZ_NS, (" <> literal <> "::TIMESTAMPTZ_NS)::VARIANT")
+        (query_ conn sql :: IO [(UTCTimestamp, Variant)]) >>= (@?= [(expected, Variant (FieldTimestampTZ expected))])
+      let value = Variant (FieldTimestampTZ (Finite precise))
+      query conn "SELECT ?" (Only value) >>= (@?= [Only value])
+  , testCase "explicit nanosecond UTC parameters preserve finite units and infinities" $ withConnection ":memory:" $ \conn -> do
+      _ <- execute_ conn "SET TimeZone='Pacific/Auckland'"
+      forM_ [minBound, negate (maxBound :: Int64) + 1, -1, 0, 1, 123456789, maxBound - 1] $ \nanos -> do
+        let instant = posixSecondsToUTCTime (fromRational (toInteger nanos % 1000000000))
+        (query conn "SELECT ?::TIMESTAMPTZ_NS" (Only instant) :: IO [Only UTCTime]) >>= (@?= [Only instant])
+        (query conn "SELECT ?::TIMESTAMPTZ_NS" (Only (Finite instant)) :: IO [Only UTCTimestamp]) >>= (@?= [Only (Finite instant)])
+      forM_ [NegInfinity, PosInfinity] $ \value ->
+        (query conn "SELECT ?::TIMESTAMPTZ_NS" (Only (value :: UTCTimestamp)) :: IO [Only UTCTimestamp]) >>= (@?= [Only value])
+      let precise = posixSecondsToUTCTime 0.123456789
+          ordinary = posixSecondsToUTCTime 0.123456
+      (query conn "SELECT typeof(?), ?" (precise, precise) :: IO [(String, UTCTime)]) >>= (@?= [("TIMESTAMP WITH TIME ZONE", ordinary)])
+  , testCase "reused statements refresh nanosecond UTC parameter metadata after ALTER" $ withConnection ":memory:" $ \conn -> do
+      void $ execute_ conn "CREATE TABLE utc_rebind(value TIMESTAMPTZ)"
+      let coarse = posixSecondsToUTCTime 0.123456
+          precise = posixSecondsToUTCTime 0.123456789
+      withStatement conn "INSERT INTO utc_rebind VALUES (?)" $ \stmt -> do
+        bind stmt [toField coarse]
+        void $ executeStatement stmt
+        void $ execute_ conn "ALTER TABLE utc_rebind ALTER COLUMN value TYPE TIMESTAMPTZ_NS"
+        bind stmt [toField precise]
+        void $ executeStatement stmt
+      (query_ conn "SELECT epoch_ns(value) FROM utc_rebind ORDER BY value" :: IO [Only Int64]) >>= (@?= [Only 123456000, Only 123456789])
+  , testCase "executeMany stores the same UTC values as single execute calls" $ withConnection ":memory:" $ \conn -> do
+      let rows = [(t, t, t) | t <- map posixSecondsToUTCTime [0.123456789, 1.5, -0.000000001]]
+          columns = " (tz TIMESTAMPTZ, ts TIMESTAMP, ns TIMESTAMPTZ_NS)"
+          readBack table = query_ conn (Query ("SELECT epoch_ns(tz), epoch_ns(ts), epoch_ns(ns) FROM " <> table <> " ORDER BY ns")) :: IO [(Int64, Int64, Int64)]
+      void $ execute_ conn (Query ("CREATE TABLE utc_many" <> columns))
+      void $ execute_ conn (Query ("CREATE TABLE utc_single" <> columns))
+      executeMany conn "INSERT INTO utc_many VALUES (?, ?, ?)" rows >>= (@?= 3)
+      forM_ rows (void . execute conn "INSERT INTO utc_single VALUES (?, ?, ?)")
+      many <- readBack "utc_many"
+      readBack "utc_single" >>= (@?= many)
+      -- The rows after the first row keep their nanoseconds with the kept parameter types.
+      map (\(_, _, ns) -> ns) many @?= [-1, 123456789, 1500000000]
+  , testCase "nanosecond UTC arrays retain NULLs and reject empty arrays" $ withConnection ":memory:" $ \conn -> do
+      let precise = posixSecondsToUTCTime 0.123456789
+          negative = posixSecondsToUTCTime (-0.000000001)
+          values = sized [Just precise, Nothing, Just negative] :: SizedArray 3 (Maybe UTCTime)
+          empty = sized [] :: SizedArray 0 (Maybe UTCTime)
+          nulls = sized [Nothing, Nothing] :: SizedArray 2 (Maybe UTCTime)
+      (query conn "SELECT ?::TIMESTAMPTZ_NS[]" (Only values) :: IO [Only [Maybe UTCTime]]) >>= (@?= [Only [Just precise, Nothing, Just negative]])
+      assertEmptyArrayUnavailable (query conn "SELECT ?::TIMESTAMPTZ_NS[]" (Only empty) :: IO [Only [Maybe UTCTime]])
+      (query conn "SELECT ?::TIMESTAMPTZ_NS[]" (Only nulls) :: IO [Only [Maybe UTCTime]]) >>= (@?= [Only [Nothing, Nothing]])
+      (query conn "SELECT ?::TIMESTAMPTZ_NS" (Only (Nothing :: Maybe UTCTime)) :: IO [Only (Maybe UTCTime)]) >>= (@?= [Only Nothing])
+      let nested = sized [values, values] :: SizedArray 2 (SizedArray 3 (Maybe UTCTime))
+      (query conn "SELECT ?::TIMESTAMPTZ_NS[][]" (Only nested) :: IO [Only [[Maybe UTCTime]]])
+        >>= (@?= [Only (replicate 2 [Just precise, Nothing, Just negative])])
+  , testCase "nanosecond targets preserve matching STRUCT MAP and UNION leaves" $ withConnection ":memory:" $ \conn -> do
+      let precise = Finite (posixSecondsToUTCTime 0.123456789)
+          coarse = Finite (localTimeToUTC utc (LocalTime (fromGregorian 5000 1 1) (TimeOfDay 0 0 0)))
+          utcType = LogicalTypeScalar LogicalTypeIdTimestampTz
+          fields =
+            listArray
+              (0, 3)
+              [ StructField "Precise" (FieldTimestampTZ precise)
+              , StructField "Coarse" (FieldTimestampTZ coarse)
+              , StructField "items" (FieldList [FieldTimestampTZ precise, FieldNull, FieldTimestampTZ NegInfinity])
+              , StructField "lookup" (FieldMap [(FieldInt64 1, FieldTimestampTZ precise)])
+              ]
+          types =
+            listArray
+              (0, 3)
+              [ StructField "Precise" utcType
+              , StructField "Coarse" utcType
+              , StructField "items" (LogicalTypeList utcType)
+              , StructField "lookup" (LogicalTypeMap (LogicalTypeScalar LogicalTypeIdBigInt) utcType)
+              ]
+          struct = StructValue fields types (Map.fromList [("Precise", 0), ("Coarse", 1), ("items", 2), ("lookup", 3)])
+          sql =
+            "WITH bound AS (SELECT ?::STRUCT(coarse TIMESTAMPTZ, items TIMESTAMPTZ_NS[], lookup MAP(BIGINT, TIMESTAMPTZ_NS), precise TIMESTAMPTZ_NS) AS value) SELECT value.precise, value.coarse, value.items, map_values(value.lookup) FROM bound"
+      (query conn sql (Only struct) :: IO [(UTCTimestamp, UTCTimestamp, [Maybe UTCTimestamp], [UTCTimestamp])])
+        >>= (@?= [(precise, coarse, [Just precise, Nothing, Just NegInfinity], [precise])])
+      let union = UnionValue 0 "Value" (FieldTimestampTZ precise) (listArray (0, 0) [UnionMemberType "Value" utcType])
+      (query conn "SELECT union_extract(?::UNION(value TIMESTAMPTZ_NS), 'value')" (Only union) :: IO [Only UTCTimestamp]) >>= (@?= [Only precise])
+      assertInputError
+        (query conn sql (Only struct{structValueFields = listArray (0, 0) [StructField "wrong" (FieldTimestampTZ precise)]}) :: IO [Only FieldValue])
+      assertInputError (query conn "SELECT ?::UNION(value TIMESTAMPTZ_NS)" (Only union{unionValueLabel = "wrong"}) :: IO [Only FieldValue])
+  , testCase "nanosecond tuple targets match positional fields" $ withConnection ":memory:" $ \conn -> do
+      let precise = Finite (posixSecondsToUTCTime 0.123456789)
+          utcType = LogicalTypeScalar LogicalTypeIdTimestampTz
+          structure names =
+            StructValue
+              (listArray (3, 5) (zipWith StructField names [FieldTimestampTZ precise, FieldTimestampTZ precise, FieldNull]))
+              (listArray (7, 9) [StructField name utcType | name <- names])
+              (Map.fromList (zip names [0 ..]))
+          tuple = TupleValue (listArray (3, 5) [FieldTimestampTZ precise, FieldTimestampTZ precise, FieldNull]) (listArray (7, 9) (replicate 3 utcType))
+          named = structure ["first", "second", "optional"]
+          sql =
+            "SELECT epoch_ns(value[1]), epoch_ns(value[2]), value[3] IS NULL FROM (SELECT ?::TUPLE(TIMESTAMPTZ,TIMESTAMPTZ_NS,TIMESTAMPTZ_NS) AS value)"
+      (query conn sql (Only tuple) :: IO [(Int64, Int64, Bool)]) >>= (@?= [(123456000, 123456789, True)])
+      (query conn sql (Only named) :: IO [(Int64, Int64, Bool)]) >>= (@?= [(123456000, 123456789, True)])
+      ( query
+          conn
+          "SELECT epoch_ns(value.first), epoch_ns(value.second), value.optional IS NULL FROM (SELECT ?::STRUCT(first TIMESTAMPTZ,second TIMESTAMPTZ_NS,optional TIMESTAMPTZ_NS) AS value)"
+          (Only tuple)
+          :: IO [(Int64, Int64, Bool)]
+        )
+        >>= (@?= [(123456000, 123456789, True)])
+      result <- try (query conn "SELECT ?::TUPLE(TIMESTAMPTZ,TIMESTAMPTZ_NS)" (Only tuple) :: IO [Only FieldValue])
+      case result of
+        Left (_ :: SQLError) -> pure ()
+        Right _ -> assertFailure "expected tuple arity mismatch"
+  , testCase "nested tuple lists retain independent temporal field metadata" $ withConnection ":memory:" $ \conn -> do
+      let precise = Finite (posixSecondsToUTCTime 0.123456789)
+          utcType = LogicalTypeScalar LogicalTypeIdTimestampTz
+          innerTypes = listArray (4, 4) [StructField "value" utcType]
+          inner = StructValue (listArray (2, 2) [StructField "value" (FieldTimestampTZ precise)]) innerTypes (Map.singleton "value" 0)
+          tuple = TupleValue (listArray (3, 4) (replicate 2 (FieldStruct inner))) (listArray (6, 7) (replicate 2 (LogicalTypeStruct innerTypes)))
+          container =
+            StructValue
+              (listArray (1, 1) [StructField "items" (FieldList [FieldTuple tuple])])
+              (listArray (5, 5) [StructField "items" (LogicalTypeList (LogicalTypeTuple (tupleValueTypes tuple)))])
+              (Map.singleton "items" 0)
+          sql =
+            "SELECT epoch_ns((value.items[1][1]).value), epoch_ns((value.items[1][2]).value) FROM (SELECT ?::STRUCT(items TUPLE(STRUCT(value TIMESTAMPTZ),STRUCT(value TIMESTAMPTZ_NS))[]) AS value)"
+      (query conn sql (Only container) :: IO [(Int64, Int64)]) >>= (@?= [(123456000, 123456789)])
+  , testCase "a time value keeps its digits below a microsecond only for a nanosecond parameter" $ withConnection ":memory:" $ \conn -> do
+      _ <- execute_ conn "SET TimeZone='UTC'"
+      let day = fromGregorian 2026 1 2
+          time = TimeOfDay 3 4 5.123456999
+          local = LocalTime day time
+          instant = localTimeToUTC utc local
+          stored :: (ToField a) => Text.Text -> Text.Text -> a -> IO [Only Text.Text]
+          stored column cast value = do
+            _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE stored (v " <> column <> ")"))
+            _ <- execute conn (Query ("INSERT INTO stored VALUES (?" <> cast <> ")")) (Only value)
+            query_ conn "SELECT v::VARCHAR FROM stored"
+          check :: (ToField a) => [(Text.Text, Text.Text, Text.Text)] -> a -> Assertion
+          check rows value = forM_ rows $ \(column, cast, expected) ->
+            stored column cast value >>= assertEqual (Text.unpack (column <> " ?" <> cast)) [Only expected]
+          selected :: (ToField a) => Text.Text -> a -> IO [Only Text.Text]
+          selected sql value = query conn (Query sql) (Only value)
+      check
+        [ ("TIMESTAMP_NS", "", "2026-01-02 03:04:05.123456999")
+        , ("TIMESTAMP", "", "2026-01-02 03:04:05.123456")
+        , ("TIMESTAMP_NS", "::TIMESTAMP_NS", "2026-01-02 03:04:05.123456999")
+        ]
+        local
+      check [("TIMESTAMP_NS", "", "2026-01-02 03:04:05.123456999"), ("TIMESTAMP", "", "2026-01-02 03:04:05.123456")] (Finite local)
+      check [("TIME_NS", "", "03:04:05.123456999"), ("TIME", "", "03:04:05.123456"), ("TIME_NS", "::TIME_NS", "03:04:05.123456999")] time
+      check
+        [ ("TIMESTAMPTZ_NS", "", "2026-01-02 03:04:05.123456999+00")
+        , ("TIMESTAMPTZ", "", "2026-01-02 03:04:05.123456+00")
+        , ("TIMESTAMPTZ_NS", "::TIMESTAMPTZ_NS", "2026-01-02 03:04:05.123456999+00")
+        ]
+        instant
+      check [("TIMESTAMPTZ_NS", "", "2026-01-02 03:04:05.123456999+00"), ("TIMESTAMPTZ", "", "2026-01-02 03:04:05.123456+00")] (Finite instant)
+      -- A parameter with no known type gets the microsecond value.
+      selected "SELECT ?::VARCHAR" local >>= (@?= [Only "2026-01-02 03:04:05.123456"])
+      selected "SELECT ?::VARCHAR" time >>= (@?= [Only "03:04:05.123456"])
+      selected "SELECT ?::VARCHAR" instant >>= (@?= [Only "2026-01-02 03:04:05.123456+00"])
+      -- A comparison with a nanosecond column finds the exact value.
+      void $ execute_ conn "CREATE TABLE precise (v TIMESTAMP_NS, t TIME_NS)"
+      void $ execute_ conn "INSERT INTO precise VALUES ('2026-01-02 03:04:05.123456999', '03:04:05.123456999')"
+      (query conn "SELECT count(*) FROM precise WHERE v = ?" (Only local) :: IO [Only Int64]) >>= (@?= [Only 1])
+      (query conn "SELECT count(*) FROM precise WHERE t = ?" (Only time) :: IO [Only Int64]) >>= (@?= [Only 1])
+  , testCase "an explicit nanosecond cast for a microsecond column rounds as in SQL text" $ withConnection ":memory:" $ \conn -> do
+      -- An explicit cast to a nanosecond type makes a nanosecond parameter. The
+      -- cast of DuckDB from the nanosecond type to the microsecond type rounds.
+      -- A plain parameter for the microsecond column cuts the digits.
+      _ <- execute_ conn "SET TimeZone='UTC'"
+      let local = LocalTime (fromGregorian 2026 1 2) (TimeOfDay 3 4 5.123456999)
+          time = localTimeOfDay local
+          instant = localTimeToUTC utc local
+          stored :: (ToField a) => Text.Text -> Text.Text -> a -> IO [Only Text.Text]
+          stored column cast value = do
+            _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE stored (v " <> column <> ")"))
+            _ <- execute conn (Query ("INSERT INTO stored VALUES (?" <> cast <> ")")) (Only value)
+            query_ conn "SELECT v::VARCHAR FROM stored"
+      stored "TIMESTAMP" "::TIMESTAMP_NS" local >>= (@?= [Only "2026-01-02 03:04:05.123457"])
+      stored "TIMESTAMP" "" local >>= (@?= [Only "2026-01-02 03:04:05.123456"])
+      stored "TIME" "::TIME_NS" time >>= (@?= [Only "03:04:05.123457"])
+      stored "TIME" "" time >>= (@?= [Only "03:04:05.123456"])
+      stored "TIMESTAMPTZ" "::TIMESTAMPTZ_NS" instant >>= (@?= [Only "2026-01-02 03:04:05.123457+00"])
+      stored "TIMESTAMPTZ" "" instant >>= (@?= [Only "2026-01-02 03:04:05.123456+00"])
+      (query conn "SELECT (?::TIMESTAMP_NS + INTERVAL 1 DAY)::VARCHAR" (Only local) :: IO [Only Text.Text])
+        >>= (@?= [Only "2026-01-03 03:04:05.123457"])
+      (query conn "SELECT (? + INTERVAL 1 DAY)::VARCHAR" (Only local) :: IO [Only Text.Text]) >>= (@?= [Only "2026-01-03 03:04:05.123456"])
+  , testCase "nested time values keep their digits below a microsecond only for nanosecond leaves" $ withConnection ":memory:" $ \conn -> do
+      let day = fromGregorian 2026 1 2
+          precise = LocalTime day (TimeOfDay 3 4 5.123456999)
+          coarse = LocalTime day (TimeOfDay 3 4 5.123456)
+          time = TimeOfDay 3 4 5.123456999
+          stored :: (ToField a) => Text.Text -> a -> IO [Only Text.Text]
+          stored column value = do
+            _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE stored (v " <> column <> ")"))
+            _ <- execute conn "INSERT INTO stored VALUES (?)" (Only value)
+            query_ conn "SELECT v::VARCHAR FROM stored"
+          struct value logical =
+            StructValue (listArray (0, 0) [StructField "v" value]) (listArray (0, 0) [StructField "v" logical]) (Map.singleton "v" 0)
+      stored "TIMESTAMP_NS[]" [precise, coarse] >>= (@?= [Only "['2026-01-02 03:04:05.123456999', '2026-01-02 03:04:05.123456']"])
+      stored "TIMESTAMP[]" [precise, coarse] >>= (@?= [Only "['2026-01-02 03:04:05.123456', '2026-01-02 03:04:05.123456']"])
+      stored "TIMESTAMP_NS[2]" (sized [precise, coarse] :: SizedArray 2 LocalTime)
+        >>= (@?= [Only "['2026-01-02 03:04:05.123456999', '2026-01-02 03:04:05.123456']"])
+      stored "TIME_NS[]" [time] >>= (@?= [Only "['03:04:05.123456999']"])
+      stored "TIME[]" [time] >>= (@?= [Only "['03:04:05.123456']"])
+      stored "MAP(VARCHAR, TIMESTAMP_NS)" (Map.fromList [("a" :: Text.Text, precise)]) >>= (@?= [Only "{a='2026-01-02 03:04:05.123456999'}"])
+      stored "MAP(VARCHAR, TIMESTAMP)" (Map.fromList [("a" :: Text.Text, precise)]) >>= (@?= [Only "{a='2026-01-02 03:04:05.123456'}"])
+      let localStruct = struct (FieldTimestamp (Finite precise)) (LogicalTypeScalar LogicalTypeIdTimestamp)
+          timeStruct = struct (FieldTime time) (LogicalTypeScalar LogicalTypeIdTime)
+      stored "STRUCT(v TIMESTAMP_NS)" localStruct >>= (@?= [Only "{'v': '2026-01-02 03:04:05.123456999'}"])
+      stored "STRUCT(v TIMESTAMP)" localStruct >>= (@?= [Only "{'v': '2026-01-02 03:04:05.123456'}"])
+      stored "STRUCT(v TIME_NS)" timeStruct >>= (@?= [Only "{'v': '03:04:05.123456999'}"])
+      stored "STRUCT(v TIME)" timeStruct >>= (@?= [Only "{'v': '03:04:05.123456'}"])
+      let timestamp = LogicalTypeScalar LogicalTypeIdTimestamp
+          list = LogicalTypeList timestamp
+          record = LogicalTypeStruct (listArray (0, 0) [StructField "v" timestamp])
+          listValue = FieldList [FieldTimestamp (Finite precise)]
+          recordValue = FieldStruct localStruct
+      forM_
+        [ ("time_list", list, listValue, "STRUCT(v TIMESTAMP_NS[])", "{'v': ['2026-01-02 03:04:05.123456999']}")
+        , ("time_record", record, recordValue, "STRUCT(v STRUCT(v TIMESTAMP_NS))", "{'v': {'v': '2026-01-02 03:04:05.123456999'}}")
+        ]
+        $ \(name, base, value, target, expected) -> do
+          R.registerCustomType conn name (R.StructuredType base)
+          let aliased = struct value (LogicalTypeAlias name base)
+          (query conn "SELECT typeof((?).v)" (Only aliased) :: IO [Only Text.Text]) >>= (@?= [Only name])
+          stored target aliased >>= (@?= [Only expected])
+      let nested = struct (FieldList [recordValue]) (LogicalTypeList (LogicalTypeAlias "time_record" record))
+      stored "STRUCT(v STRUCT(v TIMESTAMP_NS)[])" nested
+        >>= (@?= [Only "{'v': [{'v': '2026-01-02 03:04:05.123456999'}]}"])
+  , testCase "a FieldMap gives its key target to its keys and its value target to its values" $ withConnection ":memory:" $ \conn -> do
+      _ <- execute_ conn "CREATE TABLE stored (v MAP(VARCHAR, TIME_NS))"
+      _ <-
+        execute
+          conn
+          "INSERT INTO stored VALUES (?)"
+          (Only (FieldMap [(FieldText "a", FieldTime (TimeOfDay 3 4 5)), (FieldText "b", FieldTime (TimeOfDay 3 4 5.123456789))]))
+      (query_ conn "SELECT v::VARCHAR FROM stored" :: IO [Only Text.Text]) >>= (@?= [Only "{a='03:04:05', b='03:04:05.123456789'}"])
+      _ <- execute_ conn "CREATE TABLE stored_keys (v MAP(TIME_NS, VARCHAR))"
+      _ <-
+        execute
+          conn
+          "INSERT INTO stored_keys VALUES (?)"
+          (Only (FieldMap [(FieldTime (TimeOfDay 3 4 5), FieldText "a"), (FieldTime (TimeOfDay 3 4 5.123456789), FieldText "b")]))
+      (query_ conn "SELECT v::VARCHAR FROM stored_keys" :: IO [Only Text.Text]) >>= (@?= [Only "{'03:04:05'=a, '03:04:05.123456789'=b}"])
+  , testCase "a FieldList with a microsecond element first keeps the nanosecond element" $ withConnection ":memory:" $ \conn -> do
+      _ <- execute_ conn "CREATE TABLE stored (v TIME_NS[])"
+      _ <- execute conn "INSERT INTO stored VALUES (?)" (Only (FieldList [FieldTime (TimeOfDay 3 4 5), FieldTime (TimeOfDay 3 4 5.123456789)]))
+      (query_ conn "SELECT v::VARCHAR FROM stored" :: IO [Only Text.Text]) >>= (@?= [Only "['03:04:05', '03:04:05.123456789']"])
+  , testCase "executeMany binds time rows with and without digits below a microsecond" $ withConnection ":memory:" $ \conn -> do
+      let day = fromGregorian 2026 1 2
+          rows =
+            [ (0 :: Int64, LocalTime day (TimeOfDay 3 4 5.123456999))
+            , (1, LocalTime day (TimeOfDay 3 4 5.123456))
+            , (2, LocalTime day (TimeOfDay 3 4 5.000000001))
+            ]
+      forM_
+        [ ("TIMESTAMP_NS", ["2026-01-02 03:04:05.123456999", "2026-01-02 03:04:05.123456", "2026-01-02 03:04:05.000000001"])
+        , ("TIMESTAMP", ["2026-01-02 03:04:05.123456", "2026-01-02 03:04:05.123456", "2026-01-02 03:04:05"])
+        ]
+        $ \(column, expected) -> do
+          _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE many (i BIGINT, v " <> column <> ")"))
+          _ <- executeMany conn "INSERT INTO many VALUES (?, ?)" rows
+          (query_ conn "SELECT v::VARCHAR FROM many ORDER BY i" :: IO [Only Text.Text]) >>= assertEqual (Text.unpack column) (map Only expected)
+  , testCase "a time value outside the nanosecond range and an infinity for a nanosecond parameter" $ withConnection ":memory:" $ \conn -> do
+      let moment year month day hours minutes seconds = LocalTime (fromGregorian year month day) (TimeOfDay hours minutes seconds)
+          early = moment 1600 1 2 3 4 5.123456999
+          -- DuckDB can cast the microsecond value of this value to TIMESTAMP_NS.
+          edge = moment 2262 4 11 23 47 16.854775900
+          precise = moment 2026 1 2 3 4 5.123456999
+          stamp = FieldTimestamp . Finite
+          timestamp = LogicalTypeScalar LogicalTypeIdTimestamp
+          pair second =
+            StructValue
+              (listArray (0, 1) [StructField "a" (stamp precise), StructField "b" (stamp second)])
+              (listArray (0, 1) [StructField "a" timestamp, StructField "b" timestamp])
+              (Map.fromList [("a", 0), ("b", 1)])
+          tuple = TupleValue (listArray (0, 0) [stamp early]) (listArray (0, 0) [timestamp])
+          union = UnionValue 0 "v" (stamp early) (listArray (0, 0) [UnionMemberType "v" timestamp])
+          insert :: (ToField a) => Text.Text -> a -> IO ()
+          insert column value = do
+            _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE stored (v " <> column <> ")"))
+            void (execute conn "INSERT INTO stored VALUES (?)" (Only value))
+          noRows label = (query_ conn "SELECT count(*) FROM stored" :: IO [Only Int64]) >>= assertEqual label [Only 0]
+          duckdbError expected label action =
+            try action >>= \case
+              Left SQLError{sqlErrorMessage, sqlErrorType} -> do
+                assertEqual label (Just expected) sqlErrorType
+                assertBool label ("Could not convert Timestamp to higher precision" `Text.isInfixOf` sqlErrorMessage)
+                noRows label
+              Right () -> assertFailure (label <> ": expected the cast error of DuckDB")
+          encoderError label action =
+            try action >>= \case
+              Left SQLError{sqlErrorType, sqlErrorMessage} -> do
+                assertEqual label (Just ErrorTypeConversion) sqlErrorType
+                assertBool label ("duckdb-simple: TIMESTAMP value out of finite range" `Text.isInfixOf` sqlErrorMessage)
+                noRows label
+              Right () -> assertFailure (label <> ": expected the range error of the encoder")
+      -- DuckDB raises the error when it also cannot cast the microsecond value.
+      forM_ [early, moment 1600 1 2 3 4 5, moment 2262 4 11 23 47 16.854776001, moment 1677 9 21 0 12 43.145224100] $ \value ->
+        duckdbError ErrorTypeConversion (show value) (insert "TIMESTAMP_NS" value)
+      duckdbError ErrorTypeConversion "UTCTime with no digits" (insert "TIMESTAMPTZ_NS" (localTimeToUTC utc (moment 1600 1 2 3 4 5)))
+      duckdbError ErrorTypeConversion "UTCTime" (insert "TIMESTAMPTZ_NS" (localTimeToUTC utc early))
+      -- For an element, the library checks the range before the constructor of
+      -- the list, the array, or the map casts the element.
+      encoderError "list" (insert "TIMESTAMP_NS[]" [precise, early])
+      encoderError "SizedArray" (insert "TIMESTAMP_NS[2]" (sized [precise, early] :: SizedArray 2 LocalTime))
+      encoderError "Map key" (insert "MAP(TIMESTAMP_NS, VARCHAR)" (Map.fromList [(moment 2300 1 1 0 0 0, "a" :: Text.Text)]))
+      encoderError "Map value" (insert "MAP(VARCHAR, TIMESTAMP_NS)" (Map.fromList [("a" :: Text.Text, precise), ("b", early)]))
+      encoderError "list of UTCTime with no digits" (insert "TIMESTAMPTZ_NS[]" [localTimeToUTC utc (moment 1600 1 2 3 4 5)])
+      -- The encoder raises the error when the cast would cut the digits.
+      encoderError "edge" (insert "TIMESTAMP_NS" edge)
+      encoderError "edge list" (insert "TIMESTAMP_NS[]" [precise, edge])
+      encoderError "UTCTime edge" (insert "TIMESTAMPTZ_NS" (localTimeToUTC utc edge))
+      -- A leaf of a STRUCT, TUPLE, or UNION gets the error of the encoder, also in
+      -- TRY_CAST, where a microsecond value would keep the other leaf with its
+      -- digits cut.
+      encoderError "STRUCT" (insert "STRUCT(a TIMESTAMP_NS, b TIMESTAMP_NS)" (pair early))
+      encoderError "STRUCT with no digits" (insert "STRUCT(a TIMESTAMP_NS, b TIMESTAMP_NS)" (pair (moment 1600 1 2 3 4 5)))
+      encoderError "TUPLE" (insert "TUPLE(TIMESTAMP_NS)" tuple)
+      encoderError "UNION" (insert "UNION(v TIMESTAMP_NS)" union)
+      assertRangeError
+        (query conn "SELECT TRY_CAST(? AS STRUCT(a TIMESTAMP_NS, b TIMESTAMP_NS))::VARCHAR" (Only (pair early)) :: IO [Only Text.Text])
+      -- In TRY_CAST, DuckDB gives NULL for a parameter that it cannot cast, and
+      -- the check of a list element raises its error first.
+      (query conn "SELECT TRY_CAST(? AS TIMESTAMP_NS) IS NULL" (Only early) :: IO [Only Bool]) >>= (@?= [Only True])
+      try (query conn "SELECT TRY_CAST(? AS TIMESTAMP_NS[])::VARCHAR" (Only [precise, early]) :: IO [Only Text.Text]) >>= \case
+        Left SQLError{sqlErrorType} -> sqlErrorType @?= Just ErrorTypeConversion
+        Right rows -> assertFailure ("TRY_CAST list: " <> show rows)
+      -- The last values in the range keep their digits.
+      insert "TIMESTAMP_NS[]" [moment 2262 4 11 23 47 16.854775806, moment 1677 9 21 0 12 43.145224500]
+      (query_ conn "SELECT v::VARCHAR FROM stored" :: IO [Only Text.Text])
+        >>= (@?= [Only "['2262-04-11 23:47:16.854775806', '1677-09-21 00:12:43.1452245']"])
+      _ <- execute_ conn "CREATE OR REPLACE TABLE stored (v TIMESTAMP_NS, z TIMESTAMPTZ_NS)"
+      _ <- execute conn "INSERT INTO stored VALUES (?, ?)" (PosInfinity :: LocalTimestamp, NegInfinity :: UTCTimestamp)
+      (query_ conn "SELECT v::VARCHAR, z::VARCHAR FROM stored" :: IO [(Text.Text, Text.Text)]) >>= (@?= [("infinity", "-infinity")])
+  , testCase "a time value with digits below a microsecond keeps them for a VARIANT parameter" $ withConnection ":memory:" $ \conn -> do
+      _ <- execute_ conn "SET TimeZone = 'UTC'; CREATE TABLE v (x VARIANT); CREATE TABLE l (x VARIANT[])"
+      let day = fromGregorian 2026 1 2
+          tod = TimeOfDay 3 4 5.123456789
+          local = LocalTime day tod
+          early = LocalTime (fromGregorian 1600 1 2) tod
+          stored :: (ToField a) => a -> IO [(Text.Text, Text.Text)]
+          stored value = do
+            _ <- execute_ conn "DELETE FROM v"
+            _ <- execute conn "INSERT INTO v VALUES (?)" (Only value)
+            query_ conn "SELECT variant_typeof(x), x::VARCHAR FROM v"
+      -- A value with such digits gets the nanosecond type.
+      stored tod >>= (@?= [("TIME_NANOS", "03:04:05.123456789")])
+      stored local >>= (@?= [("TIMESTAMP_NANOS", "2026-01-02 03:04:05.123456789")])
+      stored (Finite local) >>= (@?= [("TIMESTAMP_NANOS", "2026-01-02 03:04:05.123456789")])
+      stored (localTimeToUTC utc local) >>= (@?= [("TIMESTAMP_NANOS_TZ", "2026-01-02 03:04:05.123456789+00")])
+      -- A value with no such digits keeps the microsecond type.
+      stored (TimeOfDay 3 4 5.123456) >>= (@?= [("TIME_MICROS", "03:04:05.123456")])
+      stored (LocalTime day (TimeOfDay 3 4 5.123456)) >>= (@?= [("TIMESTAMP_MICROS", "2026-01-02 03:04:05.123456")])
+      -- A value that the nanosecond type cannot hold gets the microsecond value.
+      stored early >>= (@?= [("TIMESTAMP_MICROS", "1600-01-02 03:04:05.123456")])
+      stored (LocalTime (fromGregorian 2262 4 11) (TimeOfDay 23 47 16.854775900)) >>= (@?= [("TIMESTAMP_MICROS", "2262-04-11 23:47:16.854775")])
+      stored (localTimeToUTC utc early) >>= (@?= [("TIMESTAMP_MICROS_TZ", "1600-01-02 03:04:05.123456+00")])
+      -- A value outside the range of TIMESTAMP_NS gets the microsecond value, as
+      -- a parameter with no known type, also as a Variant payload.
+      let far = LocalTime (fromGregorian 3000 1 2) tod
+      (query conn "SELECT ?::VARCHAR" (Only far) :: IO [Only Text.Text]) >>= (@?= [Only "3000-01-02 03:04:05.123456"])
+      stored far >>= (@?= [("TIMESTAMP_MICROS", "3000-01-02 03:04:05.123456")])
+      stored (Variant (FieldTimestamp (Finite far))) >>= (@?= [("TIMESTAMP_MICROS", "3000-01-02 03:04:05.123456")])
+      stored (Variant (FieldTimestampTZ (Finite (localTimeToUTC utc far)))) >>= (@?= [("TIMESTAMP_MICROS_TZ", "3000-01-02 03:04:05.123456+00")])
+      -- A Variant payload and a FieldValue read from a VARIANT keep the digits.
+      stored (Variant (FieldTimestamp (Finite local))) >>= (@?= [("TIMESTAMP_NANOS", "2026-01-02 03:04:05.123456789")])
+      _ <-
+        execute_
+          conn
+          "CREATE TABLE src (i INTEGER, x VARIANT); INSERT INTO src VALUES (1, '03:04:05.123456789'::TIME_NS), (2, '2026-01-02 03:04:05.123456789'::TIMESTAMP_NS), (3, '2026-01-02 03:04:05.123456789+00'::TIMESTAMPTZ_NS)"
+      values <- query_ conn "SELECT i, x FROM src ORDER BY i" :: IO [(Int64, FieldValue)]
+      forM_ values $ \(i, value) -> do
+        _ <- execute_ conn "DELETE FROM v"
+        _ <- execute conn "INSERT INTO v VALUES (?)" (Only value)
+        (query conn "SELECT count(*) FROM src, v WHERE src.i = ? AND src.x IS NOT DISTINCT FROM v.x" (Only i) :: IO [Only Int64])
+          >>= assertEqual (show value) [Only 1]
+      -- A VARIANT object reads as a FieldStruct with VARIANT fields, so its leaves keep the digits.
+      [Only object] <- query_ conn "SELECT {'t': '2026-01-02 03:04:05.123456789'::TIMESTAMP_NS}::VARIANT" :: IO [Only FieldValue]
+      stored object >>= (@?= [("OBJECT(t)", "{'t': '2026-01-02 03:04:05.123456789'}")])
+      -- A VARIANT array reads as a FieldList, whose elements get the microsecond value.
+      [Only array] <- query_ conn "SELECT ['2026-01-02 03:04:05.123456789'::TIMESTAMP_NS]::VARIANT" :: IO [Only FieldValue]
+      stored array >>= (@?= [("ARRAY(1)", "['2026-01-02 03:04:05.123456']")])
+      -- An element of a VARIANT list keeps the microsecond type, as the list has one element type.
+      _ <- execute conn "INSERT INTO l VALUES (?)" (Only [local, LocalTime day (TimeOfDay 3 4 5)])
+      (query_ conn "SELECT variant_typeof(x[1]), x::VARCHAR FROM l" :: IO [(Text.Text, Text.Text)])
+        >>= (@?= [("TIMESTAMP_MICROS", "[2026-01-02 03:04:05.123456, 2026-01-02 03:04:05]")])
+  , testCase "a UTCTime outside the nanosecond range binds as a LocalTime does" $ withConnection ":memory:" $ \conn -> do
+      -- See Note [Nanosecond parameters] in "Database.DuckDB.Simple.ToField".
+      let at year time = LocalTime (fromGregorian year 1 1) time
+          digits = TimeOfDay 0 0 0.000000001
+          plain = TimeOfDay 0 0 0.000001
+          typeOf :: (ToField a) => Text.Text -> a -> IO (Maybe (Maybe ErrorType))
+          typeOf column value = do
+            _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE stored (v " <> column <> ")"))
+            try (execute conn "INSERT INTO stored VALUES (?)" (Only value)) >>= \case
+              Left SQLError{sqlErrorType} -> pure (Just sqlErrorType)
+              Right _ -> pure Nothing
+      -- DuckDB does not cast a parameter that it does not evaluate, so the
+      -- microsecond value of each type gives the row.
+      _ <- execute_ conn "CREATE TABLE present (c TIMESTAMP_NS, z TIMESTAMPTZ_NS)"
+      _ <- execute_ conn "INSERT INTO present VALUES ('2000-01-01 00:00:00', '2000-01-01 00:00:00+00')"
+      (query conn "SELECT coalesce(c, ?)::VARCHAR FROM present" (Only (at 2300 digits)) :: IO [Only Text.Text])
+        >>= (@?= [Only "2000-01-01 00:00:00"])
+      (query conn "SELECT count(*) FROM present WHERE z = ? OR true" (Only (localTimeToUTC utc (at 2300 digits))) :: IO [Only Int64])
+        >>= (@?= [Only 1])
+      -- DuckDB does not mix TIMESTAMPTZ_NS and TIMESTAMPTZ in coalesce, so a
+      -- UTCTime there gets the Binder Error of DuckDB with and without digits.
+      let coalesced instant =
+            try (query conn "SELECT coalesce(z, ?) FROM present" (Only instant) :: IO [Only UTCTime]) >>= \case
+              Left SQLError{sqlErrorType} -> pure sqlErrorType
+              Right _ -> pure Nothing
+      coalesced (localTimeToUTC utc (at 2300 digits)) >>= (@?= Just ErrorQueryBinder)
+      coalesced (localTimeToUTC utc (at 2300 plain)) >>= (@?= Just ErrorQueryBinder)
+      -- A plain parameter and a list element get the same error for each type.
+      forM_ [(2300, digits), (2300, plain), (300000, digits), (300000, plain)] $ \(year, time) -> do
+        let local = at year time
+            instant = localTimeToUTC utc local
+            label position = show year <> " " <> show time <> " " <> position
+        localPlain <- typeOf "TIMESTAMP_NS" local
+        utcPlain <- typeOf "TIMESTAMPTZ_NS" instant
+        assertEqual (label "plain parameter") localPlain utcPlain
+        localList <- typeOf "TIMESTAMP_NS[]" [local]
+        utcList <- typeOf "TIMESTAMPTZ_NS[]" [instant]
+        assertEqual (label "list element") localList utcList
+        assertEqual (label "plain parameter type") (Just (Just ErrorTypeConversion)) utcPlain
+        assertEqual (label "list element type") (Just (Just ErrorTypeConversion)) utcList
+      let rejects :: (ToField a) => String -> Text.Text -> a -> ErrorType -> Text.Text -> Assertion
+          rejects position column value expectedType expectedText = do
+            _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE stored (v " <> column <> ")"))
+            try (execute conn "INSERT INTO stored VALUES (?)" (Only value)) >>= \case
+              Left SQLError{sqlErrorType, sqlErrorMessage} -> do
+                assertEqual (position <> " type") (Just expectedType) sqlErrorType
+                assertBool (position <> ": " <> Text.unpack sqlErrorMessage) (expectedText `Text.isInfixOf` sqlErrorMessage)
+              Right _ -> assertFailure (position <> ": expected an error")
+          late = localTimeToUTC utc (at 2300 digits)
+      -- A Map value and an Array element get the range check of an element,
+      -- before the native constructor casts them. A FieldTimestampTZ binds the
+      -- microsecond value, and DuckDB raises its error.
+      rejects
+        "Map value"
+        "MAP(VARCHAR, TIMESTAMPTZ_NS)"
+        (Map.singleton ("k" :: Text.Text) late)
+        ErrorTypeConversion
+        "TIMESTAMP value out of finite range"
+      rejects
+        "SizedArray element"
+        "TIMESTAMPTZ_NS[1]"
+        (sized [late] :: SizedArray 1 UTCTime)
+        ErrorTypeConversion
+        "TIMESTAMP value out of finite range"
+      rejects
+        "FieldTimestampTZ"
+        "TIMESTAMPTZ_NS"
+        (FieldTimestampTZ (Finite late))
+        ErrorTypeConversion
+        "Could not convert Timestamp to higher precision"
+      -- The 2262 zone keeps the error of the encoder, from its first to its last
+      -- nanosecond. The nanosecond before the zone binds with its digits.
+      let near nanos = localTimeToUTC utc (LocalTime (fromGregorian 2262 4 11) (TimeOfDay 23 47 nanos))
+      forM_ [16.854775807, 16.8547759, 16.854775999] $ \nanos ->
+        rejects ("2262 zone " <> show nanos) "TIMESTAMPTZ_NS" (near nanos) ErrorTypeConversion "TIMESTAMP value out of finite range"
+      _ <- execute conn "INSERT INTO stored VALUES (?)" (Only (near 16.854775806))
+      (query_ conn "SELECT epoch_ns(v) FROM stored" :: IO [Only Int64]) >>= (@?= [Only (maxBound - 1)])
+      -- A microsecond target and a VARIANT keep their values.
+      typeOf "TIMESTAMPTZ" (localTimeToUTC utc (at 2300 digits)) >>= (@?= Nothing)
+      typeOf "VARIANT" (localTimeToUTC utc (at 2300 digits)) >>= (@?= Nothing)
+  , testCase "a FieldList or a FieldMap of time values for VARIANT elements binds microsecond elements" $ withConnection ":memory:" $ \conn -> do
+      let precise = FieldTimestamp (Finite (LocalTime (fromGregorian 2026 1 2) (TimeOfDay 3 4 5.123456789)))
+      (query conn "SELECT [variant_typeof(e) FOR e IN ?::VARIANT[]]" (Only (FieldList [precise])) :: IO [Only [Text.Text]])
+        >>= (@?= [Only ["TIMESTAMP_MICROS"]])
+      (query conn "SELECT variant_typeof((?::MAP(VARCHAR, VARIANT))['a'])" (Only (FieldMap [(FieldText "a", precise)])) :: IO [Only Text.Text])
+        >>= (@?= [Only "TIMESTAMP_MICROS"])
+  , testCase "a Map or an Array of time values for VARIANT elements binds microsecond values" $ withConnection ":memory:" $ \conn -> do
+      let precise = LocalTime (fromGregorian 2026 1 2) (TimeOfDay 3 4 5.123456789)
+      (query conn "SELECT (?::MAP(VARCHAR, VARIANT))::VARCHAR" (Only (Map.singleton ("a" :: Text.Text) precise)) :: IO [Only Text.Text])
+        >>= (@?= [Only "{a=2026-01-02 03:04:05.123456}"])
+      (query conn "SELECT (?::VARIANT[1])::VARCHAR" (Only (sized [precise] :: SizedArray 1 LocalTime)) :: IO [Only Text.Text])
+        >>= (@?= [Only "[2026-01-02 03:04:05.123456]"])
+  , testCase "nanosecond UTC targets reject finite overflow and sentinel collisions" $ withConnection ":memory:" $ \conn -> do
+      forM_
+        [ toInteger (minBound :: Int64) - 1
+        , negate (toInteger (maxBound :: Int64))
+        , toInteger (maxBound :: Int64)
+        , toInteger (maxBound :: Int64) + 1
+        ]
+        $ \nanos -> do
+          -- A UTCTime gets the error of a LocalTime of the same instant in UTC:
+          -- below the range, the cast of DuckDB raises; at the top, the encoder
+          -- raises, because the cast would cut the digits. See
+          -- Note [Nanosecond parameters] in "Database.DuckDB.Simple.ToField".
+          let instant = posixSecondsToUTCTime (fromRational (nanos % 1000000000))
+              errorType :: (ToField a) => Query -> a -> IO (Maybe ErrorType)
+              errorType sql value =
+                try (query conn sql (Only value) :: IO [Only FieldValue]) >>= \case
+                  Left SQLError{sqlErrorType} -> pure sqlErrorType
+                  Right rows -> assertFailure ("expected an error, got " <> show rows)
+              expected = Just ErrorTypeConversion
+          errorType "SELECT ?::TIMESTAMPTZ_NS" instant >>= (@?= expected)
+          errorType "SELECT ?::TIMESTAMPTZ_NS" (Finite instant :: UTCTimestamp) >>= (@?= expected)
+          errorType "SELECT ?::TIMESTAMP_NS" (utcToLocalTime utc instant) >>= (@?= expected)
+      (query_ conn "SELECT 42" :: IO [Only Int]) >>= (@?= [Only 42])
+  , testCase "dates and timestamps at the ends of the range of DuckDB bind, and a value outside raises an error" $ withConnection ":memory:" $ \conn -> do
+      -- See Note [Time ranges] in "Database.DuckDB.Simple.ToField".
+      let epoch = fromGregorian 1970 1 1
+          firstDay = addDays (-2147483646) epoch
+          -- Day -2147483647 is -infinity, so -2147483648 is the only INT32 day before the range.
+          beforeDay = addDays (-2147483648) epoch
+          lastDay = addDays 2147483646 epoch
+          -- Day 2147483647 is infinity.
+          afterDay = addDays 2147483647 epoch
+          local units count = utcToLocalTime utc (posixSecondsToUTCTime (fromRational (count % units)))
+          firstTime = local 1000000 (-9223372022400000000)
+          beforeTime = local 1000000 (-9223372022400000001)
+          lastTime = local 1000000 9223372036854775806
+          -- The microsecond value 2^63 - 1 is infinity.
+          afterTime = local 1000000 9223372036854775807
+          structOf logical value =
+            StructValue
+              (listArray (0, 0) [StructField "a" value])
+              (listArray (0, 0) [StructField "a" (LogicalTypeScalar logical)])
+              (Map.fromList [("a", 0)])
+          create column = void (execute_ conn (Query ("CREATE OR REPLACE TABLE stored (v " <> column <> ")")))
+          stored :: forall a. (ToField a, FromField a, Eq a, Show a) => Text.Text -> a -> IO ()
+          stored column value = do
+            create column
+            void (execute conn "INSERT INTO stored VALUES (?)" (Only value))
+            (query_ conn "SELECT v FROM stored" :: IO [Only a]) >>= assertEqual (Text.unpack column) [Only value]
+          rejected :: (ToField a) => Text.Text -> a -> IO ()
+          rejected column value = do
+            create column
+            try (execute conn "INSERT INTO stored VALUES (?)" (Only value)) >>= \case
+              Left SQLError{sqlErrorType} -> assertEqual (Text.unpack column) (Just ErrorTypeConversion) sqlErrorType
+              Right _ -> assertFailure (Text.unpack column <> ": expected the range error")
+            (query_ conn "SELECT count(*) FROM stored" :: IO [Only Int64]) >>= assertEqual (Text.unpack column) [Only 0]
+      stored "DATE" firstDay
+      rejected "DATE" beforeDay
+      stored "DATE" lastDay
+      rejected "DATE" afterDay
+      -- A value at -infinity, and a value below the storage, get the same error.
+      rejected "DATE" (addDays (-2147483647) epoch)
+      rejected "DATE" (addDays (-3000000000) epoch)
+      stored "DATE" (Finite firstDay :: Date)
+      rejected "DATE" (Finite beforeDay :: Date)
+      stored "DATE[]" [firstDay]
+      rejected "DATE[]" [firstDay, beforeDay]
+      stored "STRUCT(a DATE)" (structOf LogicalTypeIdDate (FieldDate (Finite firstDay)))
+      rejected "STRUCT(a DATE)" (structOf LogicalTypeIdDate (FieldDate (Finite beforeDay)))
+      stored "VARIANT" (Variant (FieldDate (Finite firstDay)))
+      rejected "VARIANT" (Variant (FieldDate (Finite beforeDay)))
+      stored "TIMESTAMP" firstTime
+      rejected "TIMESTAMP" beforeTime
+      stored "TIMESTAMP" lastTime
+      rejected "TIMESTAMP" afterTime
+      rejected "TIMESTAMP" (local 1000000 (-9223372036854775807))
+      rejected "TIMESTAMP" (local 1000000 (-9223372036854775809))
+      stored "TIMESTAMP" (Finite firstTime :: LocalTimestamp)
+      rejected "TIMESTAMP" (Finite beforeTime :: LocalTimestamp)
+      stored "TIMESTAMP[]" [firstTime]
+      rejected "TIMESTAMP[]" [firstTime, beforeTime]
+      stored "STRUCT(a TIMESTAMP)" (structOf LogicalTypeIdTimestamp (FieldTimestamp (Finite firstTime)))
+      rejected "STRUCT(a TIMESTAMP)" (structOf LogicalTypeIdTimestamp (FieldTimestamp (Finite beforeTime)))
+      stored "VARIANT" (Variant (FieldTimestamp (Finite firstTime)))
+      rejected "VARIANT" (Variant (FieldTimestamp (Finite beforeTime)))
+      stored "TIMESTAMPTZ" (localTimeToUTC utc firstTime)
+      rejected "TIMESTAMPTZ" (localTimeToUTC utc beforeTime)
+      stored "TIMESTAMPTZ" (localTimeToUTC utc lastTime)
+      rejected "TIMESTAMPTZ" (localTimeToUTC utc afterTime)
+      stored "TIMESTAMPTZ" (Finite (localTimeToUTC utc firstTime) :: UTCTimestamp)
+      rejected "TIMESTAMPTZ" (Finite (localTimeToUTC utc beforeTime) :: UTCTimestamp)
+      -- A second or a millisecond value has the range of a microsecond value at
+      -- both ends. A STRUCT field can have these types.
+      forM_
+        [ (LogicalTypeIdTimestampSec, "STRUCT(a TIMESTAMP_S)", 1, 9223372036854)
+        , (LogicalTypeIdTimestampMs, "STRUCT(a TIMESTAMP_MS)", 1000, 9223372036854775)
+        ]
+        $ \(logical, column, units, largest) -> do
+          let at count = structOf logical (FieldTimestamp (Finite (local units count)))
+          stored column (at (-9223372022400000000 * units `div` 1000000))
+          stored column (at largest)
+          rejected column (at (-9223372022400000000 * units `div` 1000000 - 1))
+          rejected column (at (largest + 1))
+  , testCase "each bind path checks the range of DuckDB for a date and a timestamp" $ withConnection ":memory:" $ \conn -> do
+      -- See Note [Time ranges] in "Database.DuckDB.Simple.ToField".
+      let epoch = fromGregorian 1970 1 1
+          local micros = utcToLocalTime utc (posixSecondsToUTCTime (fromRational (micros % 1000000)))
+          rejected :: (ToField a) => Text.Text -> String -> Text.Text -> a -> IO ()
+          rejected bound label column value = do
+            _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE stored (v " <> column <> ")"))
+            try (execute conn "INSERT INTO stored VALUES (?)" (Only value)) >>= \case
+              Left SQLError{sqlErrorType, sqlErrorMessage} -> do
+                assertEqual label (Just ErrorTypeConversion) sqlErrorType
+                assertBool (label <> ": " <> Text.unpack sqlErrorMessage) (bound `Text.isInfixOf` sqlErrorMessage)
+              Right _ -> assertFailure (label <> ": expected the range error")
+      forM_
+        [ ("below the smallest", addDays (-2147483648) epoch, local (-9223372022400000001))
+        , ("above the largest", addDays 2147483647 epoch, local 9223372036854775807)
+        ]
+        $ \(bound, day, time) -> do
+          forM_ [("DATE", FieldDate (Finite day)), ("TIMESTAMP", FieldTimestamp (Finite time))] $ \(sqlType, value) -> do
+            let label part = Text.unpack (bound <> " " <> sqlType) <> " " <> part
+            rejected bound (label "FieldValue") sqlType value
+            rejected bound (label "FieldValue for a VARIANT") "VARIANT" value
+            rejected bound (label "FieldList") (sqlType <> "[]") (FieldList [FieldNull, value])
+            rejected bound (label "FieldArray") (sqlType <> "[2]") (FieldArray (listArray (0, 1) [FieldNull, value]))
+            rejected bound (label "FieldMap key") ("MAP(" <> sqlType <> ", VARCHAR)") (FieldMap [(value, FieldText "v")])
+            rejected bound (label "FieldMap value") ("MAP(VARCHAR, " <> sqlType <> ")") (FieldMap [(FieldText "k", value)])
+            rejected bound (label "Variant payload in a list") "VARIANT" (Variant (FieldList [value]))
+          let label part = Text.unpack bound <> " " <> part
+          rejected bound (label "list of Maybe Day") "DATE[]" [Nothing, Just day]
+          rejected bound (label "Map key of Day") "MAP(DATE, VARCHAR)" (Map.fromList [(day, "v" :: Text.Text)])
+          rejected bound (label "Map of Day") "MAP(VARCHAR, DATE)" (Map.fromList [("k" :: Text.Text, day)])
+          rejected bound (label "SizedArray of LocalTime") "TIMESTAMP[1]" (sized [time] :: SizedArray 1 LocalTime)
+          rejected bound (label "Map key of LocalTime") "MAP(TIMESTAMP, VARCHAR)" (Map.fromList [(time, "v" :: Text.Text)])
+          rejected bound (label "Map of LocalTime") "MAP(VARCHAR, TIMESTAMP)" (Map.fromList [("k" :: Text.Text, time)])
+          rejected bound (label "LocalTime for a VARIANT") "VARIANT" time
+  , testCase "a leap second binds as the next second, as make_time and make_timestamp give it" $ withConnection ":memory:" $ \conn -> do
+      let leap = TimeOfDay 23 59 60
+          next = LocalTime (fromGregorian 2017 1 1) (TimeOfDay 0 0 0)
+      -- The SQL literal '23:59:60' raises an error. See Note [Time ranges] in
+      -- "Database.DuckDB.Simple.ToField".
+      ( query
+          conn
+          "SELECT ?, make_time(23, 59, 60), ?, make_timestamp(2016, 12, 31, 23, 59, 60), ?, ?"
+          (leap, LocalTime (fromGregorian 2016 12 31) leap, TimeWithZone leap 0, UTCTime (fromGregorian 2016 12 31) 86400)
+          :: IO [(TimeOfDay, TimeOfDay, LocalTime, LocalTime, TimeWithZone, UTCTime)]
+        )
+        >>= (@?= [(TimeOfDay 24 0 0, TimeOfDay 24 0 0, next, next, TimeWithZone (TimeOfDay 24 0 0) 0, localTimeToUTC utc next)])
+      -- A TIME_NS value with 60 seconds also binds as the next second.
+      (query conn "SELECT ?::TIME_NS, ?::TIME_NS" (TimeOfDay 23 59 60, TimeOfDay 12 59 60.000000001) :: IO [(TimeOfDay, TimeOfDay)])
+        >>= (@?= [(TimeOfDay 24 0 0, TimeOfDay 13 0 0.000000001)])
+      -- A time after 24:00:00 raises an error, for example 60.5 seconds in the last minute of a day.
+      assertRangeError (query conn "SELECT ?" (Only (TimeOfDay 23 59 60.5)) :: IO [Only TimeOfDay])
+      assertRangeError (query conn "SELECT ?" (Only (LocalTime (fromGregorian 2016 12 31) (TimeOfDay 23 59 60.5))) :: IO [Only LocalTime])
+      assertRangeError (query conn "SELECT ?" (Only (UTCTime (fromGregorian 2016 12 31) 86400.5)) :: IO [Only UTCTime])
+      assertRangeError (query conn "SELECT ?::TIME_NS" (Only (TimeOfDay 23 59 60.000000001)) :: IO [Only TimeOfDay])
+  , testCase "each bind path raises the range error for a time of day that is not a TIME value" $ withConnection ":memory:" $ \conn -> do
+      -- See timeOfDayUnits in "Database.DuckDB.Simple.ToField".
+      let rejected :: (ToField a) => String -> Text.Text -> Text.Text -> a -> IO ()
+          rejected label expected column value = do
+            _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE stored (v " <> column <> ")"))
+            outcome <- try (execute conn "INSERT INTO stored VALUES (?)" (Only value))
+            either (\err -> assertBool (label <> ": " <> show err) (expected `Text.isInfixOf` sqlErrorMessage err)) (const (pure ())) outcome
+            assertRangeError (either throwIO pure outcome)
+      forM_
+        [ ("24:00:00 + 1 ps", TimeOfDay 24 0 0.000000000001, "time of day out of range")
+        , ("24:00:01", TimeOfDay 24 0 1, "time of day out of range")
+        , ("23:59:60.5", TimeOfDay 23 59 60.5, "time of day out of range")
+        , ("25:00:00", TimeOfDay 25 0 0, "time of day out of range")
+        , ("23:61:00", TimeOfDay 23 61 0, "invalid time of day")
+        , ("-01:00:00", TimeOfDay (-1) 0 0, "invalid time of day")
+        , ("23:59:61", TimeOfDay 23 59 61, "invalid time of day")
+        ]
+        $ \(name, time, expected) -> do
+          let label part = name <> " " <> part
+              timeType = LogicalTypeScalar LogicalTypeIdTime
+              leaf =
+                FieldStruct
+                  ( StructValue
+                      (listArray (0, 0) [StructField "a" (FieldTime time)])
+                      (listArray (0, 0) [StructField "a" timeType])
+                      (Map.fromList [("a", 0)])
+                  )
+              stamp = LocalTime (fromGregorian 2026 1 2) time
+          rejected (label "TimeOfDay") expected "TIME" time
+          rejected (label "TimeOfDay for TIME_NS") expected "TIME_NS" time
+          rejected (label "TimeWithZone") expected "TIMETZ" (TimeWithZone time 0)
+          rejected (label "list of TimeOfDay") expected "TIME[]" [time]
+          rejected (label "list of TimeOfDay for TIME_NS[]") expected "TIME_NS[]" [time]
+          rejected (label "list of TimeWithZone") expected "TIMETZ[]" [TimeWithZone time 0]
+          rejected (label "Map of TimeOfDay") expected "MAP(VARCHAR, TIME)" (Map.fromList [("k" :: Text.Text, time)])
+          rejected (label "FieldTime") expected "TIME" (FieldTime time)
+          rejected (label "FieldTimeTZ") expected "TIMETZ" (FieldTimeTZ (TimeWithZone time 0))
+          rejected (label "FieldStruct leaf") expected "STRUCT(a TIME)" leaf
+          rejected (label "Variant payload") expected "VARIANT" (Variant (FieldTime time))
+          rejected (label "Variant list payload") expected "VARIANT" (Variant (FieldList [FieldTime time]))
+          rejected (label "SizedArray of TimeOfDay") expected "TIME[1]" (sized [time] :: SizedArray 1 TimeOfDay)
+          rejected
+            (label "FieldTuple leaf")
+            expected
+            "TUPLE(TIME)"
+            (FieldTuple (TupleValue (listArray (0, 0) [FieldTime time]) (listArray (0, 0) [timeType])))
+          rejected
+            (label "FieldUnion leaf")
+            expected
+            "UNION(a TIME)"
+            (FieldUnion (UnionValue 0 "a" (FieldTime time) (listArray (0, 0) [UnionMemberType "a" timeType])))
+          rejected (label "LocalTime") expected "TIMESTAMP" stamp
+          rejected (label "FieldTimestamp") expected "TIMESTAMP" (FieldTimestamp (Finite stamp))
+      -- A UTCTime holds a time after 24:00:00 only in a leap second.
+      rejected "UTCTime at 23:59:60.5" "time of day out of range" "TIMESTAMPTZ" (UTCTime (fromGregorian 2026 1 2) 86400.5)
+      rejected "UTCTime at 23:59:61.5" "invalid time of day" "TIMESTAMPTZ" (UTCTime (fromGregorian 2026 1 2) 86401.5)
+      -- A time with digits below a microsecond binds through the nanosecond
+      -- encoder for a TIME_NS target.
+      forM_ [TimeOfDay 24 0 0.000000001, TimeOfDay 23 59 60.000000001] $ \time -> do
+        rejected (show time <> " TimeOfDay for TIME_NS") "time of day out of range" "TIME_NS" time
+        rejected (show time <> " list for TIME_NS[]") "time of day out of range" "TIME_NS[]" [time]
+  ]
+
 -- | Require a field conversion error, rather than an unrelated exception.
 assertConversionError :: IO a -> Assertion
 assertConversionError action = do
-    result <- try action
-    case result of
-        Left SQLError{sqlErrorMessage = message} ->
-            assertBool "error must identify infinity" ("infinity" `Text.isInfixOf` message)
-        Right _ -> assertFailure "expected a conversion error"
+  result <- try action
+  case result of
+    Left SQLError{sqlErrorMessage = message} ->
+      assertBool "error must identify infinity" ("infinity" `Text.isInfixOf` message)
+    Right _ -> assertFailure "expected a conversion error"
+
+-- | Require the error of the library for an ARRAY parameter with no elements.
+assertEmptyArrayUnavailable :: IO a -> Assertion
+assertEmptyArrayUnavailable action = do
+  result <- try action
+  case result of
+    Left SQLError{sqlErrorMessage = message, sqlErrorType} -> do
+      assertBool "must identify empty ARRAY" ("empty ARRAY" `Text.isInfixOf` message)
+      sqlErrorType @?= Just ErrorInputInvalid
+    Right _ -> assertFailure "expected the empty ARRAY error"
diff --git a/test/TypedRegistrationTests.hs b/test/TypedRegistrationTests.hs
new file mode 100644
--- /dev/null
+++ b/test/TypedRegistrationTests.hs
@@ -0,0 +1,2023 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE DeriveGeneric #-}
+{-# LANGUAGE DerivingVia #-}
+{-# LANGUAGE GeneralizedNewtypeDeriving #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications #-}
+
+-- |
+-- Module      : TypedRegistrationTests
+-- Description : Integration checks for typed registration through SQL.
+module TypedRegistrationTests (typedRegistrationTests) where
+
+import Control.Exception (SomeException, bracket, displayException, throwIO, try)
+import Control.Monad (forM, forM_, void, when)
+import Data.Array (listArray)
+import qualified Data.Geometry as G
+import Data.IORef (IORef, atomicModifyIORef', mkWeakIORef, modifyIORef', newIORef, readIORef, writeIORef)
+import Data.Int (Int16, Int32, Int64)
+import qualified Data.Map.Strict as Map
+import Data.Maybe (fromJust, isJust, isNothing)
+import Data.Text (Text)
+import qualified Data.Text as Text
+import qualified Data.Text.IO as TextIO
+import Data.Time.Calendar (Day, addDays, fromGregorian)
+import Data.Time.LocalTime (TimeOfDay (..))
+import Data.Word (Word64)
+import Database.DuckDB.Simple
+import Database.DuckDB.Simple.Config (
+  CustomOption (..),
+  SettingScope (..),
+  customOption,
+  getConfigValue,
+  registerCustomOption,
+  setConfigValue,
+ )
+import Database.DuckDB.Simple.Copy (
+  CopyBindInfo (..),
+  CopyFromInfo (..),
+  CopyInitInfo (..),
+  CopySinkInfo (..),
+  CopyTo (..),
+  defaultMultiFileOptions,
+  registerCopyFromFunction,
+  registerCopyFunction,
+  registerCopyToFunction,
+  registerMultiFileFunction,
+ )
+import Database.DuckDB.Simple.FromField (BigNum (..), Field (..), FieldValue (..), IntervalValue (..), TimeWithZone (..))
+import Database.DuckDB.Simple.Function (FunctionResult)
+import Database.DuckDB.Simple.Generic (DuckValue (..), ViaDuckDB (..))
+import Database.DuckDB.Simple.Internal (Connection (..))
+import qualified Database.DuckDB.Simple.Logging as Logging
+import Database.DuckDB.Simple.LogicalRep (
+  LogicalTypeRep (..),
+  StructValue (..),
+  TupleValue,
+  UnionValue,
+ )
+import Database.DuckDB.Simple.Ok (Ok (..))
+import Database.DuckDB.Simple.Pragma (PragmaCallback (..), registerPragmaFunction)
+import Database.DuckDB.Simple.Registration (
+  FunctionParameter (..),
+  Replacement (..),
+  TypeDeclaration (..),
+  defaultValue,
+  parameter,
+  registerCustomType,
+  registerInstanceReplacementScan,
+  registerReplacementScan,
+ )
+import Database.DuckDB.Simple.ToField (ToDuckValue (..))
+import qualified Database.DuckDB.Simple.V2.Registration as R
+import Database.DuckDB.Simple.Variant (Variant (..))
+import GHC.Generics (Generic)
+import Numeric.Natural (Natural)
+import System.Directory (createDirectory, getTemporaryDirectory, removeFile, removePathForcibly)
+import System.FilePath ((</>))
+import System.IO (hClose, openTempFile)
+import System.IO.Unsafe (unsafeInterleaveIO)
+import System.Mem (performMajorGC)
+import System.Mem.Weak (Weak, deRefWeak)
+import Test.Tasty (TestTree, localOption, mkTimeout, testGroup)
+import Test.Tasty.HUnit (Assertion, assertBool, assertEqual, assertFailure, testCase, (@?=))
+import TestUtils (assertInputErrorContaining, assertReleasedAfter, writeNullRows)
+
+-- | Check the typed registrations through SQL.
+typedRegistrationTests :: TestTree
+typedRegistrationTests =
+  testGroup
+    "typed registration"
+    [ testCase "a scalar function that changes a value gives the rows of its Haskell result in a filter and a join" testScalarFilterJoin
+    , testCase "replacement scan reads the rows of a query" testReplacementQuery
+    , testCase "replacement scan that declines gives the unknown table error" testReplacementDecline
+    , testCase "replacement scan gets the name parts as written" testReplacementNames
+    , testCase "replacement scan errors fail the query" testReplacementErrors
+    , testCase "connection replacement scan serves only its connection" testReplacementConnectionScope
+    , testCase "instance replacement scan serves each connection" testReplacementInstance
+    , testCase "replacement scans run in the order of registration" testReplacementOrder
+    , testCase "query pragma with no parameter" testPragmaNoParameter
+    , testCase "query pragma with a default parameter" testPragmaDefault
+    , testCase "query pragma with an Integer default for each integer type" testPragmaIntegerDefault
+    , testCase "pragma row has the order of the declaration" testPragmaRow
+    , testCase "exec pragma counts its calls" testPragmaExec
+    , testCase "pragma argument rows that do not decode" testPragmaDecodeErrors
+    , testCase "pragma parameters read VARIANT in declared and ANY arguments" testPragmaVariantParameters
+    , testCase "pragma exceptions become SQL errors" testPragmaExceptions
+    , testCase "pragma registration checks the name before the state of a closed connection" testPragmaClosedName
+    , testCase "an SQL error in each callback kind keeps its type and one prefix" testCallbackErrorTypes
+    , testCase "an SQL error of each type in a callback under the syntactic invalidation policy" testCallbackErrorPolicy
+    , testCase "custom option update accepts and rejects BIGINT values" testOptionUpdate
+    , testCase "custom option update gets VARCHAR values and can reject RESET" testOptionText
+    , testCase "table function with one parameter over several chunks" testTableSquares
+    , testCase "table function with no, two, and NULL parameters" testTableParameters
+    , testCase "table function columns of several types and a record row" testTableTypes
+    , testCase "table function with Integer and Natural columns" testTableIntegers
+    , testCase "table function with INTERVAL and TIMETZ columns" testTableIntervals
+    , testCase "table function with a MAP column" testTableMaps
+    , testCase "table function and aggregate with record, list, map, and union types" testTableRecords
+    , testCase "a record field of an alias type declares the alias" testAliasDeclaration
+    , testCase "a scalar function argument gives its type to FromField" testArgumentType
+    , testCase "scalar callback metadata expires after success and failure" testArgumentTypeScope
+    , testCase "table argument metadata expires before its deferred scan action" testTableArgumentTypeScope
+    , testCase "typed registration rejects a type with no declaration" testNoDeclaration
+    , testCase "a newtype with a sized ARRAY type text declares an ARRAY in each position" testSizedArray
+    , testCase "record field outside the range of its declared type" testRecordFieldRange
+    , testCase "table function runs one time for each scan" testTableRuns
+    , -- A defect can make the scan run without end. Then the time limit fails
+      -- the case. The limit is long, because the suite also runs under Valgrind.
+      localOption (mkTimeout (10 * 60 * 1000000)) (testCase "table function reads an infinite list with LIMIT" testTableLazy)
+    , testCase "table function registration and argument errors" testTableArgumentErrors
+    , testCase "table function exceptions become SQL errors" testTableExceptions
+    , testCase "table function evaluates only the columns that the query uses" testTableProjection
+    , testCase "table function releases the list of each scan" testTableRelease
+    , testCase "multi-file function gives each row of a typed table function one time" testTableMultiFile
+    , testCase "COPY format with both directions under one name" testCopyBothDirections
+    , testCase "COPY keeps the first registration of a format name" testCopyFirstRegistration
+    , testCase "COPY TO registration checks the name before the state of a closed connection" testCopyClosedName
+    , testCase "COPY errors in each function fail only their statement" testCopyErrors
+    , testCase "COPY format on two connections of one database" testCopySharedDatabase
+    , testCase "COPY FROM gives the name and the type of each column" testCopyFromColumns
+    , testCase "aggregate over one group and over many groups" testAggregateGroups
+    , testCase "aggregate with other state table stripe counts" testAggregateStripes
+    , testCase "aggregate registration does not keep its connection" testAggregateConnectionRelease
+    , testCase "aggregate skips NULL rows and gives the initial result" testAggregateNulls
+    , testCase "aggregate arguments, states, and result types" testAggregateTypes
+    , testCase "aggregate exceptions fail the query only" testAggregateErrors
+    , testCase "aggregate as a window function and with modifiers" testAggregateModifiers
+    , testCase "aggregate result types and custom result encoders" testAggregateResultTypes
+    , testCase "aggregate native results preserve nullable values in groups and windows" testAggregateNativeResults
+    , testCase "aggregate decodes VARIANT list elements across chunks" testAggregateVariant
+    , testCase "aggregate states are released" testAggregateRelease
+    , testGroup
+        "the callback closure of each registration kind is released when its database closes"
+        [testCase kind (assertReleasedAfter kind use) | (kind, use) <- closureKinds]
+    ]
+
+-- | Run the SQL of a query pragma without a parameter.
+testPragmaNoParameter :: Assertion
+testPragmaNoParameter = withConnection ":memory:" \conn -> do
+  registerPragmaFunction conn "typed_answer" [] (QueryPragma \() -> pure "SELECT 42::BIGINT")
+  query_ conn "PRAGMA typed_answer" >>= (@?= [Only (42 :: Int64)])
+
+-- | Give the default value to the callback when the call omits the argument.
+testPragmaDefault :: Assertion
+testPragmaDefault = withConnection ":memory:" \conn -> do
+  let amount = (parameter "amount" (TypeExpression "BIGINT")){parameterDefault = Just (defaultValue (42 :: Int64))}
+  registerPragmaFunction conn "typed_amount" [amount] $
+    QueryPragma \(Only (value :: Maybe Int64)) -> pure (maybe "SELECT NULL::BIGINT" (\number -> "SELECT " <> Text.pack (show number) <> "::BIGINT") value)
+  query_ conn "PRAGMA typed_amount" >>= (@?= [Only (Just (42 :: Int64))])
+  query_ conn "PRAGMA typed_amount(7)" >>= (@?= [Only (Just (7 :: Int64))])
+  query_ conn "PRAGMA typed_amount(amount = 9)" >>= (@?= [Only (Just (9 :: Int64))])
+  query_ conn "PRAGMA typed_amount(NULL)" >>= (@?= [Only (Nothing :: Maybe Int64)])
+
+-- | Give an Integer default to parameters of several integer types. DuckDB
+-- casts the default to the type of the parameter and checks the range.
+testPragmaIntegerDefault :: Assertion
+testPragmaIntegerDefault = withConnection ":memory:" \conn -> do
+  seen <- newIORef FieldNull
+  let register name dtype (value :: Integer) =
+        registerPragmaFunction conn name [(parameter "amount" (TypeExpression dtype)){parameterDefault = Just (defaultValue value)}] $
+          QueryPragma \(Only received) -> writeIORef seen received >> pure "SELECT 1::BIGINT"
+      omitted name = do
+        query_ conn (Query ("PRAGMA " <> name)) >>= (@?= [Only (1 :: Int64)])
+        readIORef seen
+  register "typed_default_bigint" "BIGINT" 42
+  omitted "typed_default_bigint" >>= (@?= FieldInt64 42)
+  register "typed_default_hugeint" "HUGEINT" 42
+  omitted "typed_default_hugeint" >>= (@?= FieldHugeInt 42)
+  register "typed_default_bignum" "BIGNUM" 42
+  omitted "typed_default_bignum" >>= (@?= FieldBigNum (BigNum 42))
+  register "typed_default_unsigned" "UBIGINT" (-5)
+  assertSqlError "out of range for the destination type UINT64" (query_ conn "PRAGMA typed_default_unsigned" :: IO [Only Int64])
+
+-- | Decode two parameters of different types as a tuple. The row has the order
+-- of the declaration when the call gives the arguments by name in another order.
+-- An omitted argument has its default value.
+testPragmaRow :: Assertion
+testPragmaRow = withConnection ":memory:" \conn -> do
+  let label = (parameter "label" (TypeExpression "VARCHAR")){parameterDefault = Just (defaultValue ("none" :: Text))}
+  registerPragmaFunction conn "typed_pair" [parameter "amount" (TypeExpression "BIGINT"), label] $
+    QueryPragma \(amount :: Int64, text :: Text) -> pure ("SELECT " <> Text.pack (show amount) <> "::BIGINT, '" <> Text.replace "'" "''" text <> "'")
+  query_ conn "PRAGMA typed_pair(3, 'liður ''x''')" >>= (@?= [(3 :: Int64, "liður 'x'" :: Text)])
+  query_ conn "PRAGMA typed_pair(label = 'named', amount = 4)" >>= (@?= [(4 :: Int64, "named" :: Text)])
+  query_ conn "PRAGMA typed_pair(5)" >>= (@?= [(5 :: Int64, "none" :: Text)])
+
+-- | Run the action of an exec pragma once for each statement. The action gets
+-- the argument or the default value.
+testPragmaExec :: Assertion
+testPragmaExec = withConnection ":memory:" \conn -> do
+  calls <- newIORef (0 :: Int64)
+  let step = (parameter "step" (TypeExpression "BIGINT")){parameterDefault = Just (defaultValue (1 :: Int64))}
+  registerPragmaFunction conn "typed_count" [step] (ExecPragma \(Only increment) -> modifyIORef' calls (+ increment))
+  void (execute_ conn "PRAGMA typed_count")
+  void (execute_ conn "PRAGMA typed_count")
+  readIORef calls >>= (@?= 2)
+  void (execute_ conn "PRAGMA typed_count(5)")
+  readIORef calls >>= (@?= 7)
+
+-- | Name the pragma when the row has another type, another size, or a NULL.
+testPragmaDecodeErrors :: Assertion
+testPragmaDecodeErrors = withConnection ":memory:" \conn -> do
+  let amount = parameter "amount" (TypeExpression "BIGINT")
+  registerPragmaFunction
+    conn
+    "typed_text"
+    [parameter "label" (TypeExpression "VARCHAR")]
+    (QueryPragma \(Only (_ :: Int64)) -> pure "SELECT 1")
+  assertSqlError
+    "cannot decode the arguments of pragma typed_text: column label has type"
+    (query_ conn "PRAGMA typed_text('x')" :: IO [Only Int64])
+  registerPragmaFunction conn "typed_size" [amount] (QueryPragma \() -> pure "SELECT 1")
+  assertSqlError "cannot decode the arguments of pragma typed_size" (query_ conn "PRAGMA typed_size(1)" :: IO [Only Int64])
+  registerPragmaFunction conn "typed_strict" [amount] (ExecPragma \(Only (_ :: Int64)) -> pure ())
+  assertSqlError "cannot decode the arguments of pragma typed_strict: column amount is NULL" (execute_ conn "PRAGMA typed_strict(NULL)")
+  query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+
+-- | Compare pragma arguments with the same expressions read by SELECT.
+testPragmaVariantParameters :: Assertion
+testPragmaVariantParameters = withConnection ":memory:" \conn -> do
+  seen <- newIORef Nothing
+  let check (name, declaration, expression) = do
+        registerPragmaFunction conn name [parameter "value" declaration] $
+          QueryPragma \(Only value) -> writeIORef seen (Just value) >> pure "SELECT 1"
+        [Only expected] <- query_ conn (Query ("SELECT " <> expression)) :: IO [Only FieldValue]
+        query_ conn (Query ("PRAGMA " <> name <> "(" <> expression <> ")")) >>= (@?= [Only (1 :: Int64)])
+        readIORef seen >>= (@?= Just expected)
+  mapM_
+    check
+    [ ("typed_variant_scalar", TypeExpression "VARIANT", "42::VARIANT")
+    , ("typed_variant_list", TypeExpression "VARIANT[]", "[1::VARIANT, NULL]")
+    , ("typed_variant_struct", TypeExpression "STRUCT(v VARIANT)", "{'v': [2,3]::VARIANT}")
+    , ("typed_variant_map", TypeExpression "MAP(VARCHAR, VARIANT)", "map(['n'], [4::VARIANT])")
+    , ("typed_variant_union", TypeExpression "UNION(v VARIANT)", "union_value(v := 5::VARIANT)")
+    , ("typed_any_parameter", StructuredType (LogicalTypeScalar LogicalTypeIdAny), "{'a': 6}::VARIANT")
+    , ("typed_geometry_parameter", TypeExpression "GEOMETRY", "'POINT (1 2)'::GEOMETRY")
+    ]
+
+-- | Raise the input error of an empty pragma name, also on a closed
+-- connection. The name check comes before the read of the state of the
+-- connection.
+testPragmaClosedName :: Assertion
+testPragmaClosedName = do
+  closed <- open ":memory:"
+  close closed
+  assertInputErrorContaining "pragma function name must be nonempty" $
+    registerPragmaFunction closed "" [] (QueryPragma \() -> pure "SELECT 1")
+
+-- | Make an SQL error from an exception of each callback kind.
+testPragmaExceptions :: Assertion
+testPragmaExceptions = withConnection ":memory:" \conn -> do
+  registerPragmaFunction conn "typed_query_failure" [] (QueryPragma \() -> throwIO (userError "typed query pragma failure"))
+  assertSqlError "typed query pragma failure" (query_ conn "PRAGMA typed_query_failure" :: IO [Only Int64])
+  query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+  registerPragmaFunction conn "typed_exec_failure" [] (ExecPragma \() -> throwIO (userError "typed exec pragma failure"))
+  assertSqlError "typed exec pragma failure" (execute_ conn "PRAGMA typed_exec_failure")
+  query_ conn "SELECT 43" >>= (@?= [Only (43 :: Int64)])
+
+-- | Give the type and the text of an error in a callback to the outer
+-- statement. The failing statement runs on a connection of another database.
+-- See Note [Errors that leave a callback] in "Database.DuckDB.Simple.Callback".
+testCallbackErrorTypes :: Assertion
+testCallbackErrorTypes = withDirectory \directory -> withConnection ":memory:" \conn -> withConnection ":memory:" \other -> withConnection ":memory:" \third -> do
+  let failing = void (query_ other "SELECT 'abc'::INTEGER" :: IO [Only Int64])
+      run sql = void (query_ conn sql :: IO [[FieldValue]])
+      file = Text.pack (directory </> "rows.txt")
+      conversion = "Conversion Error: Could not convert string 'abc' to INT32"
+  -- The body of a native error is its text without the prefix.
+  try failing >>= \case
+    Left (err :: SQLError) -> ("Conversion Error: " <>) <$> sqlErrorBody err @?= Just (sqlErrorMessage err)
+    Right () -> assertFailure "expected a Conversion Error"
+  writeFile (directory </> "rows.txt") ""
+  createFunction conn "error_scalar" (failing >> pure (0 :: Int64))
+  createFunctionWithState conn "error_state" failing \() -> (0 :: Int64)
+  createAggregate conn "error_update" sumAggregate{aggregateStep = \_ (Only (_ :: Int64)) -> failing >> pure 0}
+  createAggregate conn "error_combine" sumAggregate{aggregateCombine = \_ _ -> failing >> pure 0}
+  createAggregate conn "error_finalize" sumAggregate{aggregateResult = \_ -> failing >> pure (0 :: Int64)}
+  createTableFunction conn "error_init" ["n"] \() -> failing >> pure [Only (1 :: Int64)]
+  createTableFunction conn "error_exec" ["n"] \() -> unsafeInterleaveIO (failing >> pure [Only (1 :: Int64)])
+  registerCustomType conn "error_target" (TypeExpression "BIGINT")
+  R.registerCast conn (TypeExpression "BIGINT") (TypeExpression "error_target") Nothing \_ _ -> failing
+  registerPragmaFunction conn "error_query_pragma" [] (QueryPragma \() -> failing >> pure "SELECT 1")
+  registerPragmaFunction conn "error_exec_pragma" [] (ExecPragma \() -> failing)
+  registerCustomOption conn (customOption "error_option" (TypeExpression "BIGINT")){customOptionUpdate = Just \_ -> failing}
+  registerCopyToFunction conn "error_sink" (\_ -> pure ()) (\_ -> pure ()) (\_ _ -> failing) (\_ -> pure ())
+  registerCopyToFunction conn "error_final" (\_ -> pure ()) (\_ -> pure ()) (\_ _ -> pure ()) (\_ -> failing)
+  registerCopyFromFunction conn "error_from" \_ -> failing >> pure [Only (1 :: Int64)]
+  void (execute_ conn "CREATE TABLE error_rows (value BIGINT)")
+  registerReplacementScan conn \parts -> if parts == ["error_missing"] then failing >> pure Nothing else pure Nothing
+  forM_
+    [ ("scalar function", run "SELECT error_scalar()")
+    , ("state of a scalar function", run "SELECT error_state() FROM range(3)")
+    , ("aggregate update", run "SELECT error_update(i) FROM range(10) t(i)")
+    , ("aggregate combine", run "SELECT error_combine(i) OVER (ORDER BY i ROWS BETWEEN CURRENT ROW AND UNBOUNDED FOLLOWING) FROM range(32) t(i)")
+    , ("aggregate finalize", run "SELECT error_finalize(i) FROM range(10) t(i)")
+    , ("table function init", run "SELECT * FROM error_init()")
+    , ("table function exec", run "SELECT * FROM error_exec()")
+    , ("query pragma", run "PRAGMA error_query_pragma")
+    , ("exec pragma", void (execute_ conn "PRAGMA error_exec_pragma"))
+    , ("option update", void (execute_ conn "SET error_option = 1"))
+    , ("COPY TO sink", void (execute conn "COPY (SELECT 1) TO ? (FORMAT error_sink)" (Only file)))
+    , ("COPY TO finalize", void (execute conn "COPY (SELECT 1) TO ? (FORMAT error_final)" (Only file)))
+    , ("COPY FROM", void (execute conn "COPY error_rows FROM ? (FORMAT error_from)" (Only file)))
+    , ("replacement scan", run "SELECT * FROM error_missing")
+    ]
+    \(label, action) -> assertErrorType label ErrorTypeConversion conversion action
+  -- A cast writes the code of a failed cast and the whole message. See
+  -- Note [The error code of a failed cast] in
+  -- "Database.DuckDB.Simple.V2.Registration".
+  assertErrorType "cast" ErrorTypeMismatch ("Mismatch Type Error: " <> conversion) (run "SELECT CAST(1::BIGINT AS error_target)::BIGINT")
+  -- An error that passes through two callbacks keeps its type.
+  createFunction other "error_middle" (void (query_ third "SELECT 'abc'::INTEGER" :: IO [Only Int64]) >> pure (0 :: Int64))
+  createFunction conn "error_outer" (void (query_ other "SELECT error_middle()" :: IO [Only Int64]) >> pure (0 :: Int64))
+  assertErrorType "two callbacks" ErrorTypeConversion conversion (run "SELECT error_outer()")
+  -- An error of the library keeps its type and gets one prefix.
+  createFunction
+    conn
+    "error_range"
+    (void (query other "SELECT ?::TINYINT" (Only (2 ^ (200 :: Int) :: Integer)) :: IO [Only Int64]) >> pure (0 :: Int64))
+  assertErrorType "an error of the library" ErrorTypeConversion "Conversion Error: duckdb-simple: the value " (run "SELECT error_range()")
+  -- An INTERNAL error does not keep its type, because DuckDB then invalidates
+  -- the database.
+  createFunction
+    conn
+    "error_internal"
+    (throwIO (SQLError "INTERNAL Error: inner" (Just ErrorRuntimeInternal) Nothing (Just "inner")) :: IO Int64)
+  assertErrorType "an INTERNAL error" ErrorInputInvalid "Invalid Input Error: INTERNAL Error: inner" (run "SELECT error_internal()")
+  query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+
+-- | Raise an 'SQLError' of each type in a scalar function inside an INSERT
+-- that has written rows, in an explicit transaction, under the DuckDB setting
+-- SYNTACTIC_ERRORS_DO_NOT_INVALIDATE. Check the type of the outer error, the
+-- rows of that INSERT after COMMIT, and that the same connection and a new
+-- connection of the database still run a query. See
+-- Note [Errors that leave a callback] in "Database.DuckDB.Simple.Callback".
+testCallbackErrorPolicy :: Assertion
+testCallbackErrorPolicy = do
+  outcomes <- forM [minBound .. maxBound] \errorType -> withEnvironment \environment -> withInstance environment [] \instance' -> do
+    attachDatabase instance' ":memory:" "typed_policy" []
+    setDefaultDatabase instance' "typed_policy"
+    (outerType, rows, same) <- withConnectionOn instance' \conn -> do
+      -- With one thread, the INSERT writes two chunks of 2048 rows before the
+      -- chunk with row 5000 fails.
+      void (execute_ conn "SET threads = 1")
+      void (execute_ conn "SET default_transaction_invalidation_policy = 'SYNTACTIC_ERRORS_DO_NOT_INVALIDATE'")
+      void (execute_ conn "SET current_transaction_invalidation_policy = 'SYNTACTIC_ERRORS_DO_NOT_INVALIDATE'")
+      void (execute_ conn "CREATE TABLE typed_policy_rows (v BIGINT)")
+      createFunction conn "typed_policy_fail" \(i :: Int64) ->
+        if i < 5000
+          then pure i
+          else
+            throwIO
+              SQLError{sqlErrorMessage = "typed failure", sqlErrorType = Just errorType, sqlErrorQuery = Nothing, sqlErrorBody = Just "typed failure"}
+              :: IO Int64
+      void (execute_ conn "BEGIN")
+      void (execute_ conn "INSERT INTO typed_policy_rows VALUES (-1)")
+      outer <- try (execute_ conn "INSERT INTO typed_policy_rows SELECT typed_policy_fail(i) FROM range(10000) t(i)")
+      void (execute_ conn "COMMIT")
+      rows <- query_ conn "SELECT count(*) FROM typed_policy_rows WHERE v >= 0"
+      same <- query_ conn "SELECT 42"
+      pure (either sqlErrorType (const Nothing) (outer :: Either SQLError Int), rows, same)
+    new <- withConnectionOn instance' \other -> query_ other "SELECT 42"
+    pure (errorType, outerType, rows :: [Only Int64], same :: [Only Int64], new :: [Only Int64])
+  let invalidInput =
+        [ ErrorQueryBinder
+        , ErrorDatabaseCatalog
+        , ErrorResourceConnection
+        , ErrorQueryParameterNotAllowed
+        , ErrorQueryParser
+        , ErrorConfigurationPermission
+        , ErrorResourceInUse
+        , ErrorApi
+        , ErrorIOFileNotFound
+        , ErrorIOReadFailure
+        , ErrorIOEof
+        , ErrorInputParameterInvalid
+        , ErrorInputMetadataDeferred
+        , ErrorIONetwork
+        , ErrorRuntimeInternal
+        , ErrorRuntimeFatal
+        ]
+      expectedType errorType
+        | errorType `elem` invalidInput = ErrorInputInvalid
+        | otherwise = errorType
+  outcomes
+    @?= [ (errorType, Just (expectedType errorType), [Only 0], [Only 42], [Only 42])
+        | errorType <- [minBound .. maxBound]
+        ]
+
+-- | Require an 'SQLError' of the type, with a message that starts with the
+-- text.
+assertErrorType :: String -> ErrorType -> Text -> IO () -> Assertion
+assertErrorType label expected prefix action =
+  try action >>= \case
+    Left (err :: SQLError) -> do
+      assertEqual label (Just expected) (sqlErrorType err)
+      assertBool (label <> ": " <> show (sqlErrorMessage err)) (prefix `Text.isPrefixOf` sqlErrorMessage err)
+    Right () -> assertFailure (label <> ": expected an SQL error")
+
+-- | Accept and reject the values of a BIGINT option from SET, RESET, and
+-- 'setConfigValue'. The function gets each value after the cast to BIGINT. A
+-- rejected value does not change the option.
+testOptionUpdate :: Assertion
+testOptionUpdate = withConnection ":memory:" \conn -> do
+  seen <- newIORef []
+  registerCustomOption
+    conn
+    (customOption "typed_limit" (TypeExpression "BIGINT"))
+      { customOptionDefault = Just (defaultValue (3 :: Int64))
+      , customOptionUpdate = Just \value -> do
+          modifyIORef' seen (value :)
+          case value of
+            FieldInt64 number | number < 0 -> throwIO (userError "typed_limit must not be negative")
+            _ -> pure ()
+      }
+  let current = fst <$> getConfigValue conn "typed_limit"
+  void (execute_ conn "SET typed_limit = 7")
+  current >>= (@?= FieldInt64 7)
+  void (execute_ conn "SET typed_limit = '5'")
+  current >>= (@?= FieldInt64 5)
+  assertSqlError "typed_limit must not be negative" (execute_ conn "SET typed_limit = -1")
+  current >>= (@?= FieldInt64 5)
+  void (execute_ conn "RESET typed_limit")
+  current >>= (@?= FieldInt64 3)
+  setConfigValue conn SettingScopeDefault "typed_limit" (11 :: Int64)
+  current >>= (@?= FieldInt64 11)
+  assertSqlError "typed_limit must not be negative" (setConfigValue conn SettingScopeDefault "typed_limit" (-2 :: Int64))
+  current >>= (@?= FieldInt64 11)
+  readIORef seen >>= (@?= reverse (map FieldInt64 [7, 5, -1, 3, 11, -2]))
+
+-- | Give the values of a VARCHAR option to the function. A RESET of an option
+-- without a default gives NULL. A function that rejects NULL rejects the RESET.
+testOptionText :: Assertion
+testOptionText = withConnection ":memory:" \conn -> do
+  seen <- newIORef []
+  registerCustomOption
+    conn
+    (customOption "typed_option_label" (TypeExpression "VARCHAR")){customOptionUpdate = Just \value -> modifyIORef' seen (value :)}
+  void (execute_ conn "SET typed_option_label = 'liður'")
+  void (execute_ conn "SET typed_option_label = 42")
+  setConfigValue conn SettingScopeDefault "typed_option_label" ("set" :: Text)
+  void (execute_ conn "RESET typed_option_label")
+  readIORef seen >>= (@?= reverse [FieldText "liður", FieldText "42", FieldText "set", FieldNull])
+  let required value = case value of
+        FieldNull -> throwIO (userError "typed_option_required must have a value")
+        _ -> pure ()
+  registerCustomOption conn (customOption "typed_option_required" (TypeExpression "VARCHAR")){customOptionUpdate = Just required}
+  void (execute_ conn "SET typed_option_required = 'kept'")
+  assertSqlError "typed_option_required must have a value" (execute_ conn "RESET typed_option_required")
+  fst <$> getConfigValue conn "typed_option_required" >>= (@?= FieldText "kept")
+
+-- | A scalar function that changes its argument gives the rows of its Haskell
+-- result in a filter, in an equality filter, and in a join condition. A
+-- registered cast between two built-in types can give other rows there, so
+-- the README names a scalar function for such a conversion.
+testScalarFilterJoin :: Assertion
+testScalarFilterJoin = withConnection ":memory:" \conn -> do
+  let bend x = 100 - x * x :: Int64
+      values = [-20 .. 20]
+      targets = [100, 99, 64, 0, -300]
+  createFunction conn "typed_bend" bend
+  void (execute_ conn "CREATE TABLE bend_values AS SELECT i::BIGINT AS c FROM range(-20, 21) t(i)")
+  void (execute_ conn "CREATE TABLE bend_targets AS SELECT d::BIGINT AS d FROM (VALUES (100), (99), (64), (0), (-300)) t(d)")
+  query_ conn "SELECT c FROM bend_values WHERE typed_bend(c) > 50 ORDER BY c" >>= (@?= [Only c | c <- values, bend c > 50])
+  query_ conn "SELECT c FROM bend_values WHERE typed_bend(c) = 100 ORDER BY c" >>= (@?= [Only c | c <- values, bend c == 100])
+  query_ conn "SELECT a.c, u.d FROM bend_values a JOIN bend_targets u ON typed_bend(a.c) = u.d ORDER BY a.c"
+    >>= (@?= [(c, d) | c <- values, d <- targets, bend c == d])
+
+-- | Replace one name with a query. Read the rows under the table name and an alias.
+testReplacementQuery :: Assertion
+testReplacementQuery = withConnection ":memory:" \conn -> do
+  _ <- execute_ conn "CREATE TABLE typed_present AS SELECT 9::BIGINT AS amount"
+  registerReplacementScan conn \parts ->
+    pure
+      (if parts `elem` [["typed_missing"], ["typed_present"]] then Just (ReplaceWithQuery "SELECT i AS amount FROM range(3) t(i)") else Nothing)
+  query_ conn "SELECT amount FROM typed_missing ORDER BY amount" >>= (@?= map Only [0, 1, 2 :: Int64])
+  query_ conn "SELECT typed_missing.amount FROM typed_missing ORDER BY 1" >>= (@?= map Only [0, 1, 2 :: Int64])
+  query_ conn "SELECT x.amount FROM typed_missing AS x ORDER BY 1" >>= (@?= map Only [0, 1, 2 :: Int64])
+  -- DuckDB does not call the scan for a table that the catalog has.
+  query_ conn "SELECT amount FROM typed_present" >>= (@?= [Only (9 :: Int64)])
+
+-- | Decline a name. Require the same error as on a connection with no scan.
+testReplacementDecline :: Assertion
+testReplacementDecline = withConnection ":memory:" \conn -> do
+  before <- sqlErrorOf (query_ conn "SELECT * FROM typed_unknown" :: IO [Only Int64])
+  assertBool (Text.unpack before) ("Table with name typed_unknown does not exist" `Text.isInfixOf` before)
+  registerReplacementScan conn \_ -> pure Nothing
+  sqlErrorOf (query_ conn "SELECT * FROM typed_unknown" :: IO [Only Int64]) >>= (@?= before)
+
+-- | Return the parts of each name. Compare them with the query text.
+testReplacementNames :: Assertion
+testReplacementNames = withConnection ":memory:" \conn -> do
+  registerReplacementScan conn \parts ->
+    pure (Just (ReplaceWithQuery ("SELECT '" <> Text.replace "'" "''" (Text.intercalate "|" parts) <> "' AS parts")))
+  let check name expected = query_ conn (Query ("SELECT parts FROM " <> name)) >>= assertEqual (Text.unpack name) [Only (Text.intercalate "|" expected)]
+  check "MiXeD" ["MiXeD"]
+  check "\"Quoted Name\"" ["Quoted Name"]
+  check "\"has.dot\"" ["has.dot"]
+  check "\"a\"\"b\"" ["a\"b"]
+  -- The catalog "memory" and the schema "main" exist. The others do not.
+  check "main.typed_t" ["main", "typed_t"]
+  check "MAIN.Typed_T" ["MAIN", "Typed_T"]
+  check "typed_schema.typed_t" ["typed_schema", "typed_t"]
+  check "memory.main.typed_t" ["memory", "main", "typed_t"]
+  check "typed_catalog.main.typed_t" ["typed_catalog", "main", "typed_t"]
+  check "'typed file.csv'" ["typed file.csv"]
+  check "'typed''quote.parquet'" ["typed'quote.parquet"]
+
+-- | Fail the query with an exception and with query text that is not one SELECT.
+testReplacementErrors :: Assertion
+testReplacementErrors = withConnection ":memory:" \conn -> do
+  registerReplacementScan conn \case
+    ["typed_reserved"] -> ioError (userError "typed_reserved: the table name is reserved")
+    ["typed_two"] -> pure (Just (ReplaceWithQuery "SELECT 1; SELECT 2"))
+    ["typed_create"] -> pure (Just (ReplaceWithQuery "CREATE TABLE typed_created (i BIGINT)"))
+    _ -> pure Nothing
+  assertSqlError "typed_reserved: the table name is reserved" (query_ conn "SELECT * FROM typed_reserved" :: IO [Only Int64])
+  query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+  assertSqlError "exactly one SELECT statement" (query_ conn "SELECT * FROM typed_two" :: IO [Only Int64])
+  assertSqlError "must be a SELECT statement" (query_ conn "SELECT * FROM typed_create" :: IO [Only Int64])
+  query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+
+-- | Register a scan on one connection of an instance. The other connection does
+-- not use it. The scan replaces a file path before the built-in file scan.
+testReplacementConnectionScope :: Assertion
+testReplacementConnectionScope = withEnvironment \environment -> withInstance environment [] \instance' ->
+  withConnectionOn instance' \first -> withConnectionOn instance' \second -> do
+    registerReplacementScan first \parts ->
+      pure (if parts `elem` [["typed_scoped"], ["typed_missing.csv"]] then Just (ReplaceWithQuery "SELECT 'first' AS source") else Nothing)
+    query_ first "SELECT source FROM typed_scoped" >>= (@?= [Only ("first" :: Text)])
+    assertSqlError "Table with name typed_scoped does not exist" (query_ second "SELECT source FROM typed_scoped" :: IO [Only Text])
+    query_ first "SELECT source FROM 'typed_missing.csv'" >>= (@?= [Only ("first" :: Text)])
+    assertSqlError "No files found" (query_ second "SELECT source FROM 'typed_missing.csv'" :: IO [Only Text])
+
+-- | Register a scan on an instance before its connections. Each connection uses
+-- it. A connection scan comes first and passes a declined name to it.
+testReplacementInstance :: Assertion
+testReplacementInstance = withEnvironment \environment -> withInstance environment [] \instance' -> do
+  registerInstanceReplacementScan instance' \parts -> pure (if parts `elem` [["typed_shared"], ["typed_instance"]] then Just (ReplaceWithQuery "SELECT 'instance' AS source") else Nothing)
+  withConnectionOn instance' \first -> withConnectionOn instance' \second -> do
+    query_ first "SELECT source FROM typed_shared" >>= (@?= [Only ("instance" :: Text)])
+    query_ second "SELECT source FROM typed_shared" >>= (@?= [Only ("instance" :: Text)])
+    registerReplacementScan first \parts -> pure (if parts == ["typed_shared"] then Just (ReplaceWithQuery "SELECT 'connection' AS source") else Nothing)
+    query_ first "SELECT source FROM typed_shared" >>= (@?= [Only ("connection" :: Text)])
+    query_ first "SELECT source FROM typed_instance" >>= (@?= [Only ("instance" :: Text)])
+    query_ second "SELECT source FROM typed_shared" >>= (@?= [Only ("instance" :: Text)])
+
+-- | Register two scans on one connection. The first scan that replaces a name wins.
+testReplacementOrder :: Assertion
+testReplacementOrder = withConnection ":memory:" \conn -> do
+  registerReplacementScan conn \parts -> pure (if parts == ["typed_both"] then Just (ReplaceWithQuery "SELECT 'first' AS source") else Nothing)
+  registerReplacementScan conn \parts -> pure (if parts `elem` [["typed_both"], ["typed_later"]] then Just (ReplaceWithQuery "SELECT 'second' AS source") else Nothing)
+  query_ conn "SELECT source FROM typed_both" >>= (@?= [Only ("first" :: Text)])
+  query_ conn "SELECT source FROM typed_later" >>= (@?= [Only ("second" :: Text)])
+
+-- | Require an 'SQLError' and return its message.
+sqlErrorOf :: IO a -> IO Text
+sqlErrorOf action =
+  try action >>= \case
+    Left (err :: SQLError) -> pure (sqlErrorMessage err)
+    Right _ -> assertFailure "expected an SQL error"
+
+-- | Add BIGINT values.
+sumAggregate :: Aggregate Int64 (Only Int64) Int64
+sumAggregate =
+  Aggregate
+    { aggregateInitial = 0
+    , aggregateStep = \total (Only value) -> pure (total + value)
+    , aggregateCombine = \a b -> pure (a + b)
+    , aggregateResult = pure
+    }
+
+-- | Compare the two columns of each row.
+assertColumnsEqual :: Connection -> Query -> Assertion
+assertColumnsEqual conn sql = do
+  rows <- query_ conn sql
+  assertBool "rows" (not (null rows))
+  forM_ rows \(typed, builtin) -> assertEqual (Text.unpack (fromQuery sql)) (builtin :: Maybe Int64) typed
+
+-- | Fold one group and many groups, also with partial states from 4 threads.
+testAggregateGroups :: Assertion
+testAggregateGroups = withConnection ":memory:" \conn -> do
+  combines <- newIORef (0 :: Int)
+  createAggregate
+    conn
+    "typed_sum"
+    sumAggregate{aggregateCombine = \a b -> atomicModifyIORef' combines (\count -> (count + 1, ())) >> pure (a + b)}
+  query_ conn "SELECT typed_sum(i) FROM range(10) t(i)" >>= (@?= [Only (45 :: Int64)])
+  -- A chunk has at most 2048 rows. Thus 5000 rows need more than one update call.
+  assertColumnsEqual conn "SELECT typed_sum(i), sum(i)::BIGINT FROM range(5000) t(i) GROUP BY i % 50"
+  query_ conn "SELECT count(*) FROM (SELECT i % 50 AS g, typed_sum(i) FROM range(5000) t(i) GROUP BY g)" >>= (@?= [Only (50 :: Int64)])
+  -- A table of 3 row groups lets 4 threads make partial states. DuckDB then combines them.
+  void (execute_ conn "SET threads = 4")
+  void (execute_ conn "CREATE TABLE typed_numbers AS SELECT i FROM range(300000) t(i)")
+  assertColumnsEqual conn "SELECT typed_sum(i), sum(i)::BIGINT FROM typed_numbers GROUP BY i % 1000"
+  -- An ungrouped aggregate combines the state of each thread into one state.
+  -- Thus the combine function runs at least one time.
+  writeIORef combines 0
+  assertColumnsEqual conn "SELECT typed_sum(i), sum(i)::BIGINT FROM typed_numbers"
+  readIORef combines >>= \count -> assertBool ("combine calls: " <> show count) (count > 0)
+  query_ conn "SELECT typed_sum(i), typed_sum(i + 1) FROM range(10) t(i)" >>= (@?= [(45 :: Int64, 55 :: Int64)])
+
+-- | One stripe gives the same results as the default stripes, also with
+-- partial states from 4 threads. More stripes than states give the same
+-- results. A connection with another stripe count calls the aggregate of a
+-- first connection. A stripe count of 0 fails the open.
+testAggregateStripes :: Assertion
+testAggregateStripes = do
+  withConnectionWithOptions ":memory:" defaultConnectionOptions{connectionAggregateStripes = 1} \conn -> do
+    createAggregate conn "typed_sum" sumAggregate
+    void (execute_ conn "SET threads = 4")
+    void (execute_ conn "CREATE TABLE typed_numbers AS SELECT i FROM range(300000) t(i)")
+    assertColumnsEqual conn "SELECT typed_sum(i), sum(i)::BIGINT FROM typed_numbers GROUP BY i % 1000"
+    assertColumnsEqual conn "SELECT typed_sum(i), sum(i)::BIGINT FROM typed_numbers"
+  withEnvironment \environment -> withInstance environment [] \instance' ->
+    bracket (connectWithOptions instance' defaultConnectionOptions{connectionAggregateStripes = 1000}) close \first ->
+      bracket (connectWithOptions instance' defaultConnectionOptions{connectionAggregateStripes = 1}) close \second -> do
+        createAggregate first "typed_wide_sum" sumAggregate
+        forM_ [first, second] \conn -> do
+          assertColumnsEqual conn "SELECT typed_wide_sum(i), sum(i)::BIGINT FROM range(10) t(i) GROUP BY i % 3"
+          assertColumnsEqual conn "SELECT typed_wide_sum(i), sum(i)::BIGINT FROM range(10) t(i)"
+  try (withConnectionWithOptions ":memory:" defaultConnectionOptions{connectionAggregateStripes = 0} (const (pure ()))) >>= \case
+    Left (err :: SQLError) -> do
+      sqlErrorType err @?= Just ErrorInputInvalid
+      assertBool ("unexpected message: " <> show err) ("connectionAggregateStripes" `Text.isInfixOf` sqlErrorMessage err)
+    Right () -> assertFailure "a stripe count of 0 opened a connection"
+
+-- | The callbacks of an aggregate do not keep the connection that registered
+-- it. A connection with no close and no query becomes garbage, and its
+-- finalizer closes it. The aggregate still runs on another connection of the
+-- database.
+testAggregateConnectionRelease :: Assertion
+testAggregateConnectionRelease = withEnvironment \environment -> withInstance environment [] \instance' -> do
+  weak <- do
+    conn <- connect instance'
+    createAggregate conn "typed_dropped_sum" sumAggregate{aggregateResult = pure . Variant . FieldInt64}
+    mkWeakIORef (connectionState conn) (pure ())
+  performMajorGC
+  performMajorGC
+  deRefWeak weak >>= assertBool "the aggregate keeps the connection that registered it" . isNothing
+  withConnectionOn instance' \other ->
+    query_ other "SELECT typed_dropped_sum(i)::BIGINT FROM range(10) t(i)" >>= (@?= [Only (45 :: Int64)])
+
+-- | Skip the rows with NULL. A group without other rows gives the initial result.
+testAggregateNulls :: Assertion
+testAggregateNulls = withConnection ":memory:" \conn -> do
+  createAggregate conn "typed_sum" sumAggregate
+  query_ conn "SELECT typed_sum(v) FROM (VALUES (1::BIGINT), (NULL), (2)) t(v)" >>= (@?= [Only (3 :: Int64)])
+  -- The built-in sum gives NULL for group 2. The initial state gives 0.
+  query_ conn "SELECT g, typed_sum(v) FROM (VALUES (1::BIGINT, 10::BIGINT), (1, NULL), (2, NULL)) t(g, v) GROUP BY g ORDER BY g"
+    >>= (@?= [(1 :: Int64, 10 :: Int64), (2, 0)])
+  query_ conn "SELECT typed_sum(i) FROM range(0) t(i)" >>= (@?= [Only (0 :: Int64)])
+  query_ conn "SELECT typed_sum(NULL::BIGINT)" >>= (@?= [Only (0 :: Int64)])
+  query_ conn "SELECT count(*) FROM (SELECT typed_sum(i) FROM range(0) t(i) GROUP BY i)" >>= (@?= [Only (0 :: Int64)])
+
+-- | Count the words of each group in a 'Map'. The result lists each word and
+-- its count, and an empty map gives NULL.
+tallyAggregate :: Aggregate (Map.Map Text Int64) (Text, Int64) (Maybe Text)
+tallyAggregate =
+  Aggregate
+    { aggregateInitial = Map.empty
+    , aggregateStep = \tally (word, count) -> pure (Map.insertWith (+) word count tally)
+    , aggregateCombine = \a b -> pure (Map.unionWith (+) a b)
+    , aggregateResult = \tally ->
+        pure
+          if Map.null tally then Nothing else Just (Text.intercalate "," [word <> "=" <> Text.pack (show count) | (word, count) <- Map.toList tally])
+    }
+
+-- | Use a tuple of two argument types, a 'Map' state, and each result type.
+testAggregateTypes :: Assertion
+testAggregateTypes = withConnection ":memory:" \conn -> do
+  createAggregate conn "typed_tally" tallyAggregate
+  -- Group 2 has the 12 bytes that fit inline. Group 3 has 13 bytes. Group 4 has 14
+  -- bytes in 8 characters. Group 5 has NULL in each row.
+  _ <-
+    execute_
+      conn
+      "CREATE TABLE typed_words AS SELECT * FROM (VALUES (1, 'a', 1::BIGINT), (1, 'a', 2), (1, NULL, 5), (1, 'b', NULL), (2, 'abcdefghij', 1), (3, 'abcdefghijk', 1), (4, '\240\240\240\240\240\240', 1), (5, NULL, 1), (5, 'c', NULL), (6, 'cherry', 2), (6, 'apple', 3), (6, 'banana', 5)) t(g, w, n)"
+  let expected =
+        [ Just "a=3"
+        , Just "abcdefghij=1"
+        , Just "abcdefghijk=1"
+        , Just "\240\240\240\240\240\240=1"
+        , Nothing
+        , Just "apple=3,banana=5,cherry=2" :: Maybe Text
+        ]
+  query_ conn "SELECT typed_tally(w, n) FROM typed_words GROUP BY g ORDER BY g" >>= (@?= map Only expected)
+  -- DuckDB compares the bytes of the results with the bytes of the literals.
+  query_
+    conn
+    "SELECT typed_tally(w, n) = 'abcdefghij=1', typed_tally(w, n) = 'abcdefghijk=1' FROM typed_words WHERE g IN (2, 3) GROUP BY g ORDER BY g"
+    >>= (@?= [(Just True, Just False), (Just False, Just True :: Maybe Bool)])
+  query_ conn "SELECT typed_tally(w, n) FROM typed_words"
+    >>= (@?= [Only (Just "a=3,abcdefghij=1,abcdefghijk=1,apple=3,banana=5,cherry=2,\240\240\240\240\240\240=1" :: Maybe Text)])
+  query_ conn "SELECT typed_tally(w, n) FROM typed_words WHERE g = 5" >>= (@?= [Only (Nothing :: Maybe Text)])
+  query_
+    conn
+    "SELECT typed_tally(w, n) OVER (ORDER BY g ROWS BETWEEN CURRENT ROW AND 1 FOLLOWING) FROM (VALUES (1, 'abcdefghij', 1::BIGINT), (2, 'abcdefghijk', 1), (3, NULL, 1)) t(g, w, n) ORDER BY g"
+    >>= (@?= map Only [Just "abcdefghij=1,abcdefghijk=1", Just "abcdefghijk=1", Nothing :: Maybe Text])
+  createAggregate
+    conn
+    "typed_any_odd"
+    Aggregate
+      { aggregateInitial = False
+      , aggregateStep = \seen (Only (value :: Int64)) -> pure (seen || odd value)
+      , aggregateCombine = \a b -> pure (a || b)
+      , aggregateResult = pure
+      }
+  createAggregate
+    conn
+    "typed_mean"
+    Aggregate
+      { aggregateInitial = (0, 0)
+      , aggregateStep = \(total, count) (Only value) -> pure (total + value, count + 1 :: Int64)
+      , aggregateCombine = \(t1, c1) (t2, c2) -> pure (t1 + t2, c1 + c2)
+      , aggregateResult = \(total, count) -> pure (if count == 0 then Nothing else Just (total / fromIntegral count :: Double))
+      }
+  createAggregate
+    conn
+    "typed_count"
+    Aggregate
+      { aggregateInitial = 0
+      , aggregateStep = \count (Only (_ :: Int32)) -> pure (count + 1)
+      , aggregateCombine = \a b -> pure (a + b)
+      , aggregateResult = pure :: Word64 -> IO Word64
+      }
+  createAggregate
+    conn
+    "typed_small"
+    Aggregate
+      { aggregateInitial = 0
+      , aggregateStep = \total (Only value) -> pure (total + value)
+      , aggregateCombine = \a b -> pure (a + b)
+      , aggregateResult = pure :: Int32 -> IO Int32
+      }
+  createAggregate
+    conn
+    "typed_label"
+    Aggregate
+      { aggregateInitial = 0 :: Int
+      , aggregateStep = \count (Only (_ :: Text)) -> pure (count + 1)
+      , aggregateCombine = \a b -> pure (a + b)
+      , aggregateResult = \count -> pure (Text.replicate count "ab")
+      }
+  query_
+    conn
+    "SELECT typed_any_odd(i), typed_mean(i::DOUBLE), typed_count(i::INTEGER), typed_small(i::INTEGER), typed_label(i::VARCHAR) FROM range(8) t(i) GROUP BY i < 1 ORDER BY i < 1"
+    >>= (@?= [(True, Just (4 :: Double), 7 :: Word64, 28 :: Int32, "ababababababab" :: Text), (False, Just 0, 1, 0, "ab")])
+  query_ conn "SELECT typed_any_odd(i), typed_mean(i::DOUBLE), typed_count(i::INTEGER), typed_label(i::VARCHAR) FROM range(0) t(i)"
+    >>= (@?= [(False, Nothing :: Maybe Double, 0 :: Word64, "" :: Text)])
+  -- An Int32 argument and an Int32 result are INTEGER.
+  query_
+    conn
+    "SELECT typeof(typed_any_odd(1)), typeof(typed_mean(1)), typeof(typed_count(1)), typeof(typed_small(1)), typeof(typed_label('x'))"
+    >>= (@?= [("BOOLEAN" :: Text, "DOUBLE" :: Text, "UBIGINT" :: Text, "INTEGER" :: Text, "VARCHAR" :: Text)])
+  query_
+    conn
+    "SELECT function_name, parameters::VARCHAR, parameter_types::VARCHAR FROM duckdb_functions() WHERE function_name IN ('typed_small', 'typed_tally') ORDER BY function_name"
+    >>= (@?= [("typed_small" :: Text, "[arg0]" :: Text, "[INTEGER]" :: Text), ("typed_tally", "[arg0, arg1]", "[VARCHAR, BIGINT]")])
+
+-- | Fail the query for an exception in each function. The next query works.
+testAggregateErrors :: Assertion
+testAggregateErrors = withConnection ":memory:" \conn -> do
+  createAggregate
+    conn
+    "typed_bad_step"
+    sumAggregate{aggregateStep = \total (Only value) -> if value == 13 then throwIO (userError "typed_bad_step: 13") else pure (total + value)}
+  assertSqlError "typed_bad_step: 13" (query_ conn "SELECT typed_bad_step(i) FROM range(20) t(i) GROUP BY i % 3" :: IO [Only Int64])
+  query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+  -- The step evaluates its state, so the error belongs to the step.
+  createAggregate
+    conn
+    "typed_lazy_step"
+    sumAggregate{aggregateStep = \total (Only value) -> pure (if value == 7 then error "typed_lazy_step: 7" else total + value)}
+  assertSqlError "typed_lazy_step: 7" (query_ conn "SELECT typed_lazy_step(i) FROM range(20) t(i)" :: IO [Only Int64])
+  query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+  -- DuckDB adds rows 0 to 15 and rows 16 to 31 of the frame of row 0 in separate
+  -- states. Then it combines them.
+  createAggregate conn "typed_bad_combine" sumAggregate{aggregateCombine = \_ _ -> throwIO (userError "typed_bad_combine: combine")}
+  assertSqlError
+    "typed_bad_combine: combine"
+    ( query_ conn "SELECT typed_bad_combine(i) OVER (ORDER BY i ROWS BETWEEN CURRENT ROW AND UNBOUNDED FOLLOWING) FROM range(32) t(i)"
+        :: IO [Only Int64]
+    )
+  query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+  -- A Natural argument is UHUGEINT. DuckDB casts a BIGINT to it only with an
+  -- explicit cast, and the cast of a negative value fails.
+  createAggregate
+    conn
+    "typed_natural_sum"
+    Aggregate
+      { aggregateInitial = 0
+      , aggregateStep = \total (value :: Int64, extra :: Natural) -> pure (total + value + fromIntegral extra)
+      , aggregateCombine = \a b -> pure (a + b)
+      , aggregateResult = pure :: Int64 -> IO Int64
+      }
+  query_ conn "SELECT typed_natural_sum(i, i::UHUGEINT) FROM range(10) t(i)" >>= (@?= [Only (90 :: Int64)])
+  assertSqlError "No function matches" (query_ conn "SELECT typed_natural_sum(i, i) FROM range(10) t(i)" :: IO [Only Int64])
+  assertSqlError
+    "out of range for the destination type UINT128"
+    (query_ conn "SELECT typed_natural_sum(i, (i - 5)::UHUGEINT) FROM range(10) t(i)" :: IO [Only Int64])
+  query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+  createAggregate
+    conn
+    "typed_bad_result"
+    sumAggregate{aggregateResult = \total -> if total > 100 then throwIO (userError "typed_bad_result: too large") else pure total}
+  query_ conn "SELECT typed_bad_result(i) FROM range(10) t(i)" >>= (@?= [Only (45 :: Int64)])
+  assertSqlError
+    "typed_bad_result: too large"
+    (query_ conn "SELECT typed_bad_result(i) FROM range(100) t(i) GROUP BY i % 2" :: IO [Only Int64])
+  query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+  createAggregate
+    conn
+    "typed_lazy_result"
+    sumAggregate{aggregateResult = \total -> pure (if total == 0 then error "typed_lazy_result: 0" else total)}
+  assertSqlError "typed_lazy_result: 0" (query_ conn "SELECT typed_lazy_result(i) FROM range(1) t(i)" :: IO [Only Int64])
+  query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+
+-- | Declare the true type of a SMALLINT and a FLOAT result. Write them also in
+-- an ordered window, where the result vector of a finalize call has the size 0.
+-- Use the native value encoder for results without a raw writer.
+testAggregateResultTypes :: Assertion
+testAggregateResultTypes = withConnection ":memory:" \conn -> do
+  createAggregate
+    conn
+    "typed_small_count"
+    Aggregate
+      { aggregateInitial = 0 :: Int16
+      , aggregateStep = \count (Only (_ :: Int64)) -> pure (count + 1)
+      , aggregateCombine = \a b -> pure (a + b)
+      , aggregateResult = pure
+      }
+  createAggregate
+    conn
+    "typed_float_mean"
+    Aggregate
+      { aggregateInitial = (0, 0 :: Int)
+      , aggregateStep = \(total, count) (Only value) -> pure (total + value, count + 1)
+      , aggregateCombine = \(t1, c1) (t2, c2) -> pure (t1 + t2, c1 + c2)
+      , aggregateResult = \(total, count) -> pure (if count == 0 then Nothing else Just (realToFrac (total / fromIntegral count :: Double) :: Float))
+      }
+  query_ conn "SELECT typeof(typed_small_count(1)), typeof(typed_float_mean(1.0::DOUBLE))" >>= (@?= [("SMALLINT" :: Text, "FLOAT" :: Text)])
+  query_ conn "SELECT min(c), max(c), count(*) FROM (SELECT typed_small_count(i) AS c FROM range(100000) t(i) GROUP BY i % 5000)"
+    >>= (@?= [(20 :: Int16, 20 :: Int16, 5000 :: Int64)])
+  query_
+    conn
+    "SELECT min(c), max(c), count(*) FROM (SELECT typed_small_count(i) OVER (ORDER BY i ROWS BETWEEN 2 PRECEDING AND CURRENT ROW) AS c FROM range(5000) t(i))"
+    >>= (@?= [(1 :: Int16, 3 :: Int16, 5000 :: Int64)])
+  query_
+    conn
+    "SELECT bool_and(m = CASE WHEN i = 0 THEN 0 ELSE i - 0.5 END), typeof(any_value(m)) FROM (SELECT i, typed_float_mean(i::DOUBLE) OVER (ORDER BY i ROWS BETWEEN 1 PRECEDING AND CURRENT ROW) AS m FROM range(5000) t(i))"
+    >>= (@?= [(True, "FLOAT" :: Text)])
+  -- A newtype over a raw type with a derived FunctionResult has the raw writer.
+  createAggregate
+    conn
+    "typed_oldest"
+    Aggregate
+      { aggregateInitial = Age 0
+      , aggregateStep = \oldest (Only value) -> pure (max oldest (Age value))
+      , aggregateCombine = \a b -> pure (max a b)
+      , aggregateResult = pure
+      }
+  query_ conn "SELECT typeof(typed_oldest(1::SMALLINT)), typed_oldest(i::SMALLINT) FROM range(10) t(i)"
+    >>= (@?= [("SMALLINT" :: Text, Age 9)])
+  createFunction conn "typed_age" (Age 5)
+  query_ conn "SELECT typeof(typed_age()), typed_age()" >>= (@?= [("SMALLINT" :: Text, Age 5)])
+  createAggregate conn "typed_years" sumAggregate{aggregateResult = pure . Years . fromIntegral}
+  query_ conn "SELECT typeof(typed_years(i)), typed_years(i) FROM range(10) t(i)"
+    >>= (@?= [("SMALLINT" :: Text, 45 :: Int16)])
+  createAggregate conn "typed_peak_result" sumAggregate{aggregateResult = \total -> pure (Peak "total" (fromIntegral total) "")}
+  query_ conn "SELECT typed_peak_result(i) FROM range(10) t(i)"
+    >>= (@?= [Only (Peak "total" 45 "")])
+  createAggregate conn "typed_integer_result" sumAggregate{aggregateResult = pure . toInteger}
+  query_ conn "SELECT typed_integer_result(i) FROM range(10) t(i)"
+    >>= (@?= [Only (45 :: Integer)])
+  registerCustomType conn "aggregate_total" (TypeExpression "BIGINT")
+  createAggregate conn "typed_alias_result" sumAggregate{aggregateResult = pure . AggregateTotal}
+  query_ conn "SELECT typeof(typed_alias_result(i)), typed_alias_result(i)::BIGINT FROM range(10) t(i)"
+    >>= (@?= [("aggregate_total" :: Text, 45 :: Int64)])
+  createAggregate conn "typed_catalog_encoder" sumAggregate{aggregateResult = pure . CatalogTotal}
+  outcome <- try (query_ conn "SELECT typed_catalog_encoder(i) FROM range(10) t(i)" :: IO [Only Int64])
+  case outcome of
+    Left (err :: SQLError) ->
+      assertBool (show err) ("aggregate_total" `Text.isInfixOf` Text.toLower (sqlErrorMessage err))
+    Right rows -> assertFailure ("catalog lookup in an aggregate encoder succeeded: " <> show rows)
+  query_ conn "SELECT typed_alias_result(i)::BIGINT FROM range(10) t(i)" >>= (@?= [Only (45 :: Int64)])
+  assertSqlError
+    "typed_struct_result: result: StructValue has no static field types"
+    (createAggregate conn "typed_struct_result" sumAggregate{aggregateResult = \_ -> pure (undefined :: StructValue FieldValue)})
+  assertInputErrorContaining "aggregate function name must be nonempty" (createAggregate conn "" sumAggregate)
+
+-- | Check native values across chunks and finalize calls with result offsets.
+-- Compare geometry bytes in SQL so that output conversion cannot hide changes.
+testAggregateNativeResults :: Assertion
+testAggregateNativeResults = withConnection ":memory:" \conn -> do
+  let nullable n value = if n `mod` 7 == 0 then Nothing else Just value
+  createAggregate conn "typed_native_variant" countAggregate{aggregateResult = \n -> pure (nullable n (Variant (FieldInt64 n)))}
+  createAggregate
+    conn
+    "typed_native_geometry"
+    countAggregate{aggregateResult = \n -> pure (nullable n (G.PointGeometry (G.PointXY (G.XY (fromIntegral n) 0))))}
+  createAggregate conn "typed_native_nested" countAggregate{aggregateResult = \n -> pure [Just (Variant (FieldInt64 n)), Nothing]}
+  forM_
+    [ ("typed_native_variant", "q::BIGINT IS DISTINCT FROM e")
+    , ("typed_native_geometry", "q::BLOB IS DISTINCT FROM (('POINT (' || e || ' 0)')::GEOMETRY)::BLOB")
+    ]
+    \(name, differs) ->
+      forM_
+        [ (name <> "(i)", "GROUP BY i % 3001", "count(*)", 3001)
+        , (name <> "(i ORDER BY i DESC)", "GROUP BY i % 13", "count(*)", 13)
+        , (name <> "(i) OVER w", "WINDOW w AS (PARTITION BY i % 3 ORDER BY i ROWS BETWEEN 9 PRECEDING AND CURRENT ROW)", "count(*) OVER w", 8192)
+        ]
+        \(call, suffix, expected, rows) -> do
+          let sql =
+                "SELECT count(*)::BIGINT, count(*) FILTER (WHERE "
+                  <> differs
+                  <> ")::BIGINT FROM (SELECT q, CASE WHEN n % 7 <> 0 THEN n END AS e FROM (SELECT "
+                  <> call
+                  <> " AS q, "
+                  <> expected
+                  <> " AS n FROM range(8192) t(i) "
+                  <> suffix
+                  <> "))"
+          query_ conn (Query sql) >>= (@?= [(rows :: Int64, 0 :: Int64)])
+  query_ conn "SELECT typed_native_nested(i) FROM range(10) t(i)"
+    >>= (@?= [Only [Just (Variant (FieldInt64 10)), Nothing]])
+  query_ conn "SELECT typed_native_variant(i) FROM range(0) t(i)"
+    >>= (@?= [Only (Nothing :: Maybe Variant)])
+  createAggregate
+    conn
+    "typed_native_order"
+    Aggregate
+      { aggregateInitial = []
+      , aggregateStep = \seen (Only (value :: Int64)) -> pure (value : seen)
+      , aggregateCombine = \a b -> pure (b <> a)
+      , aggregateResult = pure . reverse
+      }
+  query_
+    conn
+    "SELECT bool_and(actual = expected) FROM (SELECT typed_native_order(i ORDER BY i DESC) AS actual, list(i ORDER BY i DESC) AS expected FROM range(8192) t(i) GROUP BY i % 13)"
+    >>= (@?= [Only True])
+
+-- | Read each BIGINT and NULL from a VARIANT list in aggregate update.
+testAggregateVariant :: Assertion
+testAggregateVariant = withEnvironment \environment -> withInstance environment [("threads", "4")] \instance' -> do
+  let step total (Only values) = case values of
+        [Just (Variant (FieldInt64 number)), Nothing] -> pure (total + number)
+        _ -> fail ("unexpected VARIANT list: " <> show values)
+  withConnectionOn instance' \registering -> createAggregate registering "variant_sum" countAggregate{aggregateStep = step}
+  withConnectionOn instance' \other ->
+    query_ other "SELECT variant_sum([i::VARIANT, NULL::VARIANT]), sum(i)::BIGINT FROM range(5000) t(i)"
+      >>= (@?= [(12497500 :: Int64, 12497500 :: Int64)])
+
+-- | An aggregate that counts its rows. Change 'aggregateStep' for another
+-- argument type.
+countAggregate :: Aggregate Int64 (Only Int64) Int64
+countAggregate =
+  Aggregate
+    { aggregateInitial = 0
+    , aggregateStep = \count _ -> pure (count + 1)
+    , aggregateCombine = \a b -> pure (a + b)
+    , aggregateResult = pure
+    }
+
+-- | Compare window, DISTINCT, and FILTER uses with the built-in sum. Use ORDER BY in the call.
+testAggregateModifiers :: Assertion
+testAggregateModifiers = withConnection ":memory:" \conn -> do
+  createAggregate conn "typed_sum" sumAggregate
+  forM_
+    [ "ROWS BETWEEN 2 PRECEDING AND CURRENT ROW"
+    , "ROWS UNBOUNDED PRECEDING"
+    , "ROWS BETWEEN CURRENT ROW AND UNBOUNDED FOLLOWING"
+    , "PARTITION BY i % 3"
+    , "PARTITION BY i % 3 ORDER BY i"
+    , ""
+    ]
+    \frame -> do
+      let window = if Text.null frame || "PARTITION" `Text.isPrefixOf` frame then frame else "ORDER BY i " <> frame
+      -- The built-in sum gives NULL for a frame without values. The initial state gives 0.
+      assertColumnsEqual
+        conn
+        ( Query
+            ( "SELECT typed_sum(v) OVER ("
+                <> window
+                <> "), coalesce(sum(v) OVER ("
+                <> window
+                <> "), 0)::BIGINT FROM (SELECT i, CASE WHEN i % 7 = 0 THEN NULL ELSE i END AS v FROM range(100) t(i))"
+            )
+        )
+  assertColumnsEqual conn "SELECT typed_sum(DISTINCT i % 5), sum(DISTINCT i % 5)::BIGINT FROM range(100) t(i)"
+  assertColumnsEqual conn "SELECT typed_sum(DISTINCT i % 5), sum(DISTINCT i % 5)::BIGINT FROM range(100) t(i) GROUP BY i % 2"
+  assertColumnsEqual conn "SELECT typed_sum(i) FILTER (WHERE i % 2 = 0), sum(i) FILTER (WHERE i % 2 = 0)::BIGINT FROM range(10) t(i)"
+  createAggregate
+    conn
+    "typed_words"
+    Aggregate
+      { aggregateInitial = []
+      , aggregateStep = \seen (Only word) -> pure (word : seen)
+      , aggregateCombine = \a b -> pure (b <> a)
+      , aggregateResult = pure . Text.intercalate "," . reverse
+      }
+  query_ conn "SELECT typed_words(w ORDER BY k DESC) FROM (VALUES (1, 'a'), (2, 'b'), (3, 'c')) t(k, w)" >>= (@?= [Only ("c,b,a" :: Text)])
+
+-- | Release each Haskell state after a query, also after a failed query and
+-- after a query that stops early. The step makes a new 'IORef' for each state and
+-- keeps a weak pointer to it.
+testAggregateRelease :: Assertion
+testAggregateRelease = withConnection ":memory:" \conn -> do
+  cells <- newIORef []
+  failure <- newIORef ""
+  let newCell value = do
+        cell <- newIORef value
+        weak <- mkWeakIORef cell (pure ())
+        atomicModifyIORef' cells \weaks -> (weak : weaks, ())
+        pure (Just cell)
+      failIn phase = readIORef failure >>= \current -> if current == phase then throwIO (userError ("typed_release: " <> phase)) else pure ()
+      step state (Only value) = do
+        failIn "step"
+        maybe (newCell value) (\cell -> Just cell <$ atomicModifyIORef' cell \total -> (total + value, ())) state
+      combine a b = do
+        failIn "combine"
+        totals <- mapM readIORef [cell | Just cell <- [a, b]]
+        if null totals then pure Nothing else newCell (sum totals)
+      result state = do
+        failIn "result"
+        value <- maybe (pure 0) readIORef state
+        phase <- readIORef failure
+        pure (EncodedTotal value (phase == "encode" && value == 3))
+      run phase sql = do
+        writeIORef failure phase
+        outcome <- try (query_ conn sql :: IO [Only Int64])
+        case (phase, outcome) of
+          ("", Left err) -> assertFailure (show err)
+          ("", Right _) -> pure ()
+          (_, Left (err :: SQLError)) ->
+            assertBool (Text.unpack (sqlErrorMessage err)) (Text.pack ("typed_release: " <> phase) `Text.isInfixOf` sqlErrorMessage err)
+          (_, Right _) -> assertFailure ("expected an error in " <> Text.unpack (fromQuery sql))
+  createAggregate
+    conn
+    "typed_release"
+    Aggregate
+      { aggregateInitial = Nothing
+      , aggregateStep = step
+      , aggregateCombine = combine
+      , aggregateResult = result :: Maybe (IORef Int64) -> IO EncodedTotal
+      }
+  run "" "SELECT typed_release(i) FROM range(5000) t(i) GROUP BY i % 50"
+  run "" "SELECT typed_release(i) OVER (ORDER BY i ROWS BETWEEN 2 PRECEDING AND CURRENT ROW) FROM range(100) t(i)"
+  run "" "SELECT typed_release(DISTINCT i % 5) + typed_release(i) FROM range(100) t(i)"
+  -- A prepared statement keeps its bind data over its runs. DuckDB keeps the
+  -- states of the last run until the statement runs again or closes.
+  withStatement conn "SELECT typed_release(i) FROM range(10) t(i)" \statement -> do
+    nextRow statement >>= (@?= Just (Only (45 :: Int64)))
+    void (executeStatement statement)
+    earlier <- readIORef cells
+    nextRow statement >>= (@?= Just (Only (45 :: Int64)))
+    assertReleased "the earlier runs of a prepared statement" earlier
+  run "step" "SELECT typed_release(i) FROM range(5000) t(i) GROUP BY i % 50"
+  run "combine" "SELECT typed_release(i) OVER (ORDER BY i ROWS BETWEEN CURRENT ROW AND UNBOUNDED FOLLOWING) FROM range(32) t(i)"
+  -- DuckDB does not destroy these states. The release of the bind data releases them.
+  run "result" "SELECT typed_release(i) FROM range(20000) t(i) GROUP BY i % 10000"
+  run "result" "SELECT typed_release(i) OVER (ORDER BY i ROWS BETWEEN 2 PRECEDING AND CURRENT ROW) FROM range(100) t(i)"
+  -- Earlier rows have already been written when DuckDB fails to cast row 3.
+  run "encode" "SELECT typed_release(i) OVER (ORDER BY i ROWS BETWEEN CURRENT ROW AND CURRENT ROW) FROM range(10) t(i)"
+  run "" "SELECT typed_release(i) FROM range(10) t(i)"
+  void (execute_ conn "SET threads = 4")
+  void (execute_ conn "CREATE TABLE typed_numbers AS SELECT i FROM range(300000) t(i)")
+  run "" "SELECT typed_release(i) FROM range(20000) t(i) GROUP BY i % 10000 LIMIT 1"
+  run "" "SELECT typed_release(i) FROM typed_numbers GROUP BY i % 5000 LIMIT 1"
+  run "combine" "SELECT typed_release(i) FROM typed_numbers GROUP BY i % 50"
+  run "result" "SELECT typed_release(i) FROM typed_numbers GROUP BY i % 5000"
+  readIORef cells >>= assertReleased "the queries"
+
+-- | Require that no weak pointer of the list is alive after a major collection.
+assertReleased :: String -> [Weak (IORef Int64)] -> Assertion
+assertReleased label weaks = do
+  assertBool ("states made in " <> label) (not (null weaks))
+  performMajorGC
+  performMajorGC
+  alive <- length . filter isJust <$> mapM deRefWeak weaks
+  assertEqual ("live states after " <> label) 0 alive
+
+-- | Require an 'SQLError' with a message that contains the text.
+assertSqlError :: Text -> IO a -> Assertion
+assertSqlError expected action = do
+  outcome <- try action
+  case outcome of
+    Left (err :: SQLError) -> do
+      let message = sqlErrorMessage err
+      assertBool (Text.unpack message) (expected `Text.isInfixOf` message)
+      -- The SQL error has the plain message of the Haskell exception.
+      assertBool (Text.unpack message) (not (any (`Text.isInfixOf` message) ["user error", "SQLError {"]))
+    Right _ -> assertFailure "expected an SQL error"
+
+-- | Read one column, both columns, and more than one chunk of the example.
+testTableSquares :: Assertion
+testTableSquares = withConnection ":memory:" \conn -> do
+  createTableFunction conn "typed_squares" ["n", "square"] \(Only count) ->
+    pure [(n, n * n) | n <- [0 .. count - 1 :: Int64]]
+  query_ conn "SELECT * FROM typed_squares(3)" >>= (@?= [(0 :: Int64, 0 :: Int64), (1, 1), (2, 4)])
+  query_ conn "SELECT square FROM typed_squares(3)" >>= (@?= map Only [0, 1, 4 :: Int64])
+  query_ conn "SELECT * FROM typed_squares(0)" >>= (@?= ([] :: [(Int64, Int64)]))
+  -- A chunk has at most 2048 rows. Thus 5000 rows need three chunks.
+  query_ conn "SELECT n, square FROM typed_squares(5000)" >>= (@?= [(n, n * n) | n <- [0 .. 4999 :: Int64]])
+
+-- | Call table functions with no parameter, two parameters, and NULL.
+testTableParameters :: Assertion
+testTableParameters = withConnection ":memory:" \conn -> do
+  createTableFunction conn "typed_words" ["word"] \() -> pure (map Only ["eitt", "tvö" :: Text])
+  query_ conn "SELECT word FROM typed_words()" >>= (@?= map Only ["eitt", "tvö" :: Text])
+  createTableFunction conn "typed_labels" ["label", "n"] \(prefix :: Text, start :: Int64) ->
+    pure [(prefix <> Text.pack (show n), n) | n <- [start .. start + 2]]
+  query_ conn "SELECT * FROM typed_labels('x', 5)" >>= (@?= [("x5" :: Text, 5 :: Int64), ("x6", 6), ("x7", 7)])
+  -- DuckDB casts an argument to the parameter type.
+  query_ conn "SELECT n FROM typed_labels('y', 1::INTEGER)" >>= (@?= map Only [1, 2, 3 :: Int64])
+  query_ conn "SELECT parameters::VARCHAR FROM duckdb_functions() WHERE function_name = 'typed_labels'"
+    >>= (@?= [Only ("[arg0, arg1]" :: Text)])
+  -- A NULL argument converts to Nothing.
+  createTableFunction conn "typed_optional" ["value"] \(Only (value :: Maybe Int64)) -> pure [Only value]
+  query_ conn "SELECT value FROM typed_optional(NULL)" >>= (@?= [Only (Nothing :: Maybe Int64)])
+  query_ conn "SELECT value FROM typed_optional(4)" >>= (@?= [Only (Just 4 :: Maybe Int64)])
+  createTableFunction conn "typed_variant" ["value"] \(Only (value :: Maybe Variant)) -> pure [Only value]
+  query_ conn "SELECT value FROM typed_variant(NULL)" >>= (@?= [Only (Nothing :: Maybe Variant)])
+  expected <- query_ conn "SELECT {'a': [1,2]}::VARIANT" :: IO [Only Variant]
+  query_ conn "SELECT value FROM typed_variant({'a': [1,2]}::VARIANT)" >>= (@?= expected)
+
+-- | A row type with a 'Generic' instance.
+data Reading = Reading
+  { readingStation :: Text
+  , readingValue :: Double
+  , readingDay :: Day
+  , readingNote :: Maybe Text
+  }
+  deriving (Generic)
+
+instance TypedRow Reading
+
+-- | Write columns of several types and NULLs from tuples and from a record.
+testTableTypes :: Assertion
+testTableTypes = withConnection ":memory:" \conn -> do
+  let start = fromGregorian 2026 11 12
+      mixed = [("a" :: Text, 0.5 :: Double, start, Just (1 :: Int64)), ("liður", -1.25, addDays 1 start, Nothing)]
+  createTableFunction conn "typed_mixed" ["label", "value", "day", "amount"] \() -> pure mixed
+  query_ conn "SELECT * FROM typed_mixed()" >>= (@?= mixed)
+  query_ conn "SELECT typeof(label), typeof(value), typeof(day), typeof(amount) FROM typed_mixed() LIMIT 1"
+    >>= (@?= [("VARCHAR" :: Text, "DOUBLE" :: Text, "DATE" :: Text, "BIGINT" :: Text)])
+  createTableFunction conn "typed_readings" ["station", "value", "day", "note"] \(Only count) ->
+    pure
+      [ Reading ("s" <> Text.pack (show n)) (fromIntegral n / 2) (addDays (fromIntegral n) start) (if even n then Nothing else Just "odd")
+      | n <- [0 .. count - 1 :: Int64]
+      ]
+  query_ conn "SELECT * FROM typed_readings(3)"
+    >>= ( @?=
+            [("s0" :: Text, 0 :: Double, start, Nothing :: Maybe Text), ("s1", 0.5, addDays 1 start, Just "odd"), ("s2", 1, addDays 2 start, Nothing)]
+        )
+  query_ conn "SELECT count(*) FROM typed_readings(3000) WHERE note IS NULL" >>= (@?= [Only (1500 :: Int64)])
+
+-- | Give Integer and Natural columns. The declared column type is HUGEINT for
+-- Integer and UHUGEINT for Natural, also for the elements of a list and the
+-- values of a MAP. A value outside that range raises an error.
+testTableIntegers :: Assertion
+testTableIntegers = withConnection ":memory:" \conn -> do
+  let integers = [5, -5, 2 ^ (100 :: Int), 2 ^ (127 :: Int) - 1 :: Integer]
+  createTableFunction conn "typed_integers" ["v"] \() -> pure (map Only integers)
+  query_ conn "SELECT typeof(v), v FROM typed_integers()" >>= (@?= [("HUGEINT" :: Text, value) | value <- integers])
+  let naturals = [("small" :: Text, 7 :: Natural), ("large", 2 ^ (128 :: Int) - 1)]
+  createTableFunction conn "typed_naturals" ["label", "v"] \() -> pure naturals
+  query_ conn "SELECT label, typeof(v), v FROM typed_naturals()"
+    >>= (@?= [(label, "UHUGEINT" :: Text, value) | (label, value) <- naturals])
+  let nested = [([5, 2 ^ (100 :: Int)], Map.fromList [("a", 2 ^ (127 :: Int) :: Natural)])] :: [([Integer], Map.Map Text Natural)]
+  createTableFunction conn "typed_integer_lists" ["vs", "m"] \() -> pure nested
+  query_ conn "SELECT typeof(vs), typeof(m), vs, m FROM typed_integer_lists()"
+    >>= (@?= [("HUGEINT[]" :: Text, "MAP(VARCHAR, UHUGEINT)" :: Text, vs, m) | (vs, m) <- nested])
+  -- A MAP of a type text and an Integer or a Natural, also in a list, declares
+  -- the text MAP(K, V) with the type text of the other part.
+  let keyed = Map.fromList [([1, 2], 2 ^ (100 :: Int))] :: Map.Map [Int64] Integer
+      listed = Map.fromList [([3], [5, -5])] :: Map.Map [Int64] [Integer]
+      nestedMaps = [[Map.fromList [([4], 2 ^ (127 :: Int))]], []] :: [[Map.Map [Int64] Natural]]
+  createTableFunction conn "typed_text_maps" ["k", "l", "n", "p"] \() ->
+    pure [(keyed, listed, maps, Map.fromList [(7 :: Natural, Price 1.5)]) | maps <- nestedMaps]
+  query_ conn "SELECT DISTINCT typeof(k), typeof(l), typeof(n), typeof(p) FROM typed_text_maps()"
+    >>= ( @?=
+            [
+              ( "MAP(BIGINT[], HUGEINT)" :: Text
+              , "MAP(BIGINT[], HUGEINT[])" :: Text
+              , "MAP(BIGINT[], UHUGEINT)[]" :: Text
+              , "MAP(UHUGEINT, DECIMAL(18,3))" :: Text
+              )
+            ]
+        )
+  query_ conn "SELECT k, l, n, p::VARCHAR FROM typed_text_maps()"
+    >>= (@?= [(keyed, listed, maps, "{7=1.500}" :: Text) | maps <- nestedMaps])
+  -- DuckDB sums a UHUGEINT column as a DOUBLE.
+  query_ conn "SELECT typeof(sum(v)), sum(v) FROM typed_naturals()" >>= (@?= [("DOUBLE" :: Text, 2 ^ (128 :: Int) :: Double)])
+  -- toDuckValue raises an error for a value outside the range. A BIGNUM value
+  -- would reach the HUGEINT column, and DuckDB casts the BIGNUM 2^128 to 0.
+  let outside typeName = "Conversion Error: duckdb-simple: the value 340282366920938463463374607431768211456 is outside the range of " <> typeName
+  createTableFunction conn "typed_wide_integer" ["v"] \() -> pure [Only (2 ^ (128 :: Int) :: Integer)]
+  assertErrorType
+    "Integer"
+    ErrorTypeConversion
+    (outside "HUGEINT")
+    (void (query_ conn "SELECT v FROM typed_wide_integer()" :: IO [Only Integer]))
+  createTableFunction conn "typed_wide_list" ["v"] \() -> pure [Only [5, 2 ^ (128 :: Int) :: Integer]]
+  assertErrorType
+    "Integer list"
+    ErrorTypeConversion
+    (outside "HUGEINT")
+    (void (query_ conn "SELECT v FROM typed_wide_list()" :: IO [Only [Integer]]))
+  createTableFunction conn "typed_wide_natural" ["v"] \() -> pure [Only (2 ^ (128 :: Int) :: Natural)]
+  assertErrorType
+    "Natural"
+    ErrorTypeConversion
+    (outside "UHUGEINT")
+    (void (query_ conn "SELECT v FROM typed_wide_natural()" :: IO [Only Natural]))
+  -- A BigNum column holds each value.
+  createTableFunction conn "typed_bignums" ["v"] \() -> pure [Only (BigNum (2 ^ (130 :: Int)))]
+  query_ conn "SELECT typeof(v), v FROM typed_bignums()" >>= (@?= [("BIGNUM" :: Text, BigNum (2 ^ (130 :: Int)))])
+
+-- | Give IntervalValue and TimeWithZone columns.
+testTableIntervals :: Assertion
+testTableIntervals = withConnection ":memory:" \conn -> do
+  let rows =
+        [ (IntervalValue 1 2 3, TimeWithZone (TimeOfDay 12 34 0) 19800)
+        , (IntervalValue (-1) 0 0, TimeWithZone (TimeOfDay 0 0 0) 3630)
+        ]
+  createTableFunction conn "typed_intervals" ["duration", "moment"] \() -> pure rows
+  query_ conn "SELECT typeof(duration), typeof(moment) FROM typed_intervals() LIMIT 1"
+    >>= (@?= [("INTERVAL" :: Text, "TIME WITH TIME ZONE" :: Text)])
+  query_ conn "SELECT duration, moment FROM typed_intervals()" >>= (@?= rows)
+
+-- | Give a MAP column. The pairs go in ascending key order.
+testTableMaps :: Assertion
+testTableMaps = withConnection ":memory:" \conn -> do
+  let rows = map Only [Map.fromList [("b", 2), ("a", 1)], Map.empty :: Map.Map Text Int64]
+  createTableFunction conn "typed_maps" ["pairs"] \() -> pure rows
+  query_ conn "SELECT typeof(pairs), map_keys(pairs) FROM typed_maps()"
+    >>= (@?= [("MAP(VARCHAR, BIGINT)" :: Text, ["a", "b"] :: [Text]), ("MAP(VARCHAR, BIGINT)", [])])
+  query_ conn "SELECT pairs FROM typed_maps()" >>= (@?= rows)
+
+-- | A record for a STRUCT column. A String field is VARCHAR.
+data Peak = Peak {peak :: Text, metres :: Int32, remark :: String}
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToDuckValue, ToField, FromField) via (ViaDuckDB Peak)
+
+-- | A text of the type JSON. A record field of this type has the type JSON.
+newtype JsonText = JsonText Text
+  deriving newtype (Eq, Show, FromField, ToField)
+
+instance DuckValue JsonText where
+  duckToField (JsonText text) = duckToField text
+  duckFromField = fmap JsonText . duckFromField
+  duckLogicalType _ = LogicalTypeAlias "JSON" (LogicalTypeScalar LogicalTypeIdVarchar)
+
+-- | A record with a field of the type JSON.
+data Doc = Doc {serial :: Int64, body :: JsonText}
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToDuckValue, ToField, FromField) via (ViaDuckDB Doc)
+
+-- | A sum type for a UNION column.
+data Weather = Sunny | Rain Double
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToDuckValue, FromField) via (ViaDuckDB Weather)
+
+-- | A record with an Integer field, of the type HUGEINT, and a Natural field,
+-- of the type UHUGEINT.
+data Counts = Counts {signed :: Integer, unsigned :: Natural}
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToDuckValue, ToField, FromField) via (ViaDuckDB Counts)
+
+-- | A list of three BIGINT values. Its type text gives the size.
+newtype Triple = Triple [Int64]
+  deriving newtype (Eq, Show, FromField, ToField, ToDuckValue)
+
+instance DuckDBColumnType Triple where
+  duckdbColumnTypeFor _ = "BIGINT[3]"
+
+-- | A record with a field of a sized ARRAY type.
+newtype Boxed = Boxed {boxed :: SizedArray 3 Int64}
+  deriving stock (Generic)
+  deriving (DuckDBColumnType, ToDuckValue, FromField) via (ViaDuckDB Boxed)
+
+-- | A newtype over a raw result type. It derives the raw result writer.
+newtype Age = Age Int16
+  deriving newtype (Eq, Ord, Show, DuckDBColumnType, ToDuckValue, FromField, FunctionResult)
+
+-- | A newtype over a raw result type, with the catch-all 'FunctionResult'.
+newtype Years = Years Int16
+  deriving newtype (DuckDBColumnType, ToDuckValue)
+
+-- | Produce an uncastable value to exercise cleanup after a native write fails.
+data EncodedTotal = EncodedTotal Int64 Bool
+
+instance DuckDBColumnType EncodedTotal where
+  duckdbColumnTypeFor _ = "BIGINT"
+
+instance ToDuckValue EncodedTotal where
+  toDuckValue factory (EncodedTotal value failing)
+    | failing = toDuckValue factory ("typed_release: encode" :: Text)
+    | otherwise = toDuckValue factory value
+
+-- | A catalog type whose encoder needs only the built-in BIGINT factory.
+newtype AggregateTotal = AggregateTotal Int64
+  deriving newtype (ToDuckValue)
+
+instance DuckDBColumnType AggregateTotal where
+  duckdbColumnTypeFor _ = "aggregate_total"
+
+-- | An encoder that requires catalog lookup from its factory.
+newtype CatalogTotal = CatalogTotal Int64
+
+instance DuckDBColumnType CatalogTotal where
+  duckdbColumnTypeFor _ = "aggregate_total"
+
+instance ToDuckValue CatalogTotal where
+  toDuckValue factory (CatalogTotal value) =
+    R.withTypeDeclaration factory (TypeExpression "aggregate_total") \_ -> toDuckValue factory value
+
+-- | A newtype with its own type text.
+newtype Price = Price Double
+
+instance DuckDBColumnType Price where
+  duckdbColumnTypeFor _ = "DECIMAL(18,3)"
+
+instance ToDuckValue Price where
+  toDuckValue factory (Price value) = toDuckValue factory value
+
+-- | Declare record, list, MAP, and UNION columns and a record aggregate
+-- argument from the generic types. An empty list and an empty MAP of records
+-- take the element type from the declaration.
+testTableRecords :: Assertion
+testTableRecords = withConnection ":memory:" \conn -> do
+  let peaks = [Peak "Hekla" 1491 "volcano", Peak "Esja" 914 ""]
+      rows =
+        [(row, peaks, Map.fromList [(peak p, p) | p <- peaks], weather) | (row, weather) <- zip peaks [Sunny, Rain 2.5]]
+          <> [(Peak "Snæfell" 1833 "", [], Map.empty, Rain 0)]
+  createTableFunction conn "typed_peaks" ["peak", "nearby", "by_name", "weather"] \() -> pure rows
+  query_ conn "SELECT typeof(peak), typeof(nearby), typeof(by_name), typeof(weather) FROM typed_peaks() LIMIT 1"
+    >>= ( @?=
+            [
+              ( "STRUCT(peak VARCHAR, metres INTEGER, remark VARCHAR)" :: Text
+              , "STRUCT(peak VARCHAR, metres INTEGER, remark VARCHAR)[]" :: Text
+              , "MAP(VARCHAR, STRUCT(peak VARCHAR, metres INTEGER, remark VARCHAR))" :: Text
+              , "UNION(Sunny STRUCT, Rain STRUCT(field1 DOUBLE))" :: Text
+              )
+            ]
+        )
+  query_ conn "SELECT peak, nearby, by_name, weather FROM typed_peaks()" >>= (@?= rows)
+  createAggregate
+    conn
+    "typed_highest"
+    Aggregate
+      { aggregateInitial = 0
+      , aggregateStep = \highest (Only p) -> pure (max highest (metres p))
+      , aggregateCombine = \a b -> pure (max a b)
+      , aggregateResult = pure :: Int32 -> IO Int32
+      }
+  query_ conn "SELECT typed_highest(peak) FROM typed_peaks()" >>= (@?= [Only (1833 :: Int32)])
+  query_ conn "SELECT parameter_types::VARCHAR FROM duckdb_functions() WHERE function_name = 'typed_highest'"
+    >>= (@?= [Only ("['STRUCT(peak VARCHAR, metres INTEGER, remark VARCHAR)']" :: Text)])
+  query conn "SELECT ?, typeof(?)" ([] :: [Peak], [] :: [Peak])
+    >>= (@?= [([] :: [Peak], "STRUCT(peak VARCHAR, metres INTEGER, remark VARCHAR)[]" :: Text)])
+  -- With no target type, a list of NULL records also takes the declaration.
+  -- With a target type, the empty list and the list of NULL records take the
+  -- target type, as for each element type.
+  query conn "SELECT typeof(?)" (Only [Nothing :: Maybe Peak])
+    >>= (@?= [Only ("STRUCT(peak VARCHAR, metres INTEGER, remark VARCHAR)[]" :: Text)])
+  _ <- execute_ conn "CREATE TABLE typed_short_peaks (ps STRUCT(peak VARCHAR, metres INTEGER)[])"
+  _ <- execute conn "INSERT INTO typed_short_peaks VALUES (?), (?)" ([] :: [Peak], [Nothing :: Maybe Peak])
+  query_ conn "SELECT len(ps) FROM typed_short_peaks ORDER BY len(ps)" >>= (@?= [Only (0 :: Int64), Only 1])
+
+-- | The type of a DECIMAL(4,1) argument, as its text.
+newtype ArgumentType = ArgumentType Text
+
+instance DuckDBColumnType ArgumentType where
+  duckdbColumnTypeFor _ = "DECIMAL(4,1)"
+
+instance FromField ArgumentType where
+  fromField Field{fieldType} = ArgumentType . Text.pack . show <$> fieldType
+
+-- | The argument of a scalar function gives the type of its vector.
+testArgumentType :: Assertion
+testArgumentType = withConnection ":memory:" \conn -> do
+  createFunction conn "argument_type" \(ArgumentType text) -> text
+  query_ conn "SELECT argument_type(1.5) FROM range(3000) t(i) LIMIT 1" >>= (@?= [Only ("LogicalTypeDecimal 4 1" :: Text)])
+
+-- | A scalar argument with its value and native metadata action.
+data ScopedArgument = ScopedArgument Double (Conversion LogicalTypeRep)
+
+instance DuckDBColumnType ScopedArgument where
+  duckdbColumnTypeFor _ = "DOUBLE"
+
+instance FromField ScopedArgument where
+  fromField entry = ScopedArgument <$> fromField entry <*> pure (fieldType entry)
+
+instance ToDuckValue ScopedArgument where
+  toDuckValue factory (ScopedArgument value _) = toDuckValue factory value
+
+-- | Pure snapshots survive a scalar callback; its native actions expire.
+testArgumentTypeScope :: Assertion
+testArgumentTypeScope = forM_ [False, True] \cached -> forM_ [False, True] \fails -> withConnection ":memory:" \conn -> do
+  captured <- newIORef Nothing
+  createFunction conn "argument_scope" \(ScopedArgument value logical) -> do
+    value @?= 1.5
+    snapshot <-
+      if cached
+        then
+          runConversion logical >>= \case
+            Ok rep -> pure (Just rep)
+            Errors errors -> assertFailure (show errors) >> pure Nothing
+        else pure Nothing
+    writeIORef captured (Just (logical, snapshot))
+    when fails (ioError (userError "scope callback failed"))
+    pure (7 :: Int64)
+  try (query_ conn "SELECT argument_scope(1.5)" :: IO [Only Int64]) >>= \case
+    Left SQLError{sqlErrorMessage} -> assertBool (Text.unpack sqlErrorMessage) (fails && "scope callback failed" `Text.isInfixOf` sqlErrorMessage)
+    Right rows -> do
+      assertBool "the callback should have failed" (not fails)
+      rows @?= [Only 7]
+  performMajorGC
+  readIORef captured >>= \case
+    Nothing -> assertFailure "the scalar callback did not capture its argument type"
+    Just (logical, snapshot) -> do
+      snapshot @?= if cached then Just (LogicalTypeScalar LogicalTypeIdDouble) else Nothing
+      try (runConversion logical) >>= \case
+        Left SQLError{sqlErrorMessage} -> sqlErrorMessage @?= "duckdb-simple: field type scope is closed"
+        Right _ -> assertFailure "scalar metadata survived its callback"
+
+-- | A deferred table scan cannot use native metadata from its bind callback.
+testTableArgumentTypeScope :: Assertion
+testTableArgumentTypeScope = withConnection ":memory:" \conn -> do
+  createTableFunction conn "table_argument_scope" ["value"] \(Only (ScopedArgument value logical)) -> do
+    try (runConversion logical) >>= \case
+      Left SQLError{sqlErrorMessage} -> sqlErrorMessage @?= "duckdb-simple: field type scope is closed"
+      Right _ -> assertFailure "table metadata survived its bind callback"
+    pure [Only value]
+  query_ conn "SELECT value FROM table_argument_scope(1.5)" >>= (@?= [Only (1.5 :: Double)])
+
+-- | A record field of an alias type declares the alias in the STRUCT type of a
+-- table function column. A record parameter, a list of records, and a list of
+-- NULL records have the same type. A value of the field reads as its base type.
+testAliasDeclaration :: Assertion
+testAliasDeclaration = withConnection ":memory:" \conn -> do
+  let docs = [Doc 1 (JsonText "{\"a\": 1}"), Doc 2 (JsonText "[2]")]
+  createTableFunction conn "typed_docs" ["doc"] \() -> pure (map Only docs)
+  query_ conn "SELECT typeof(doc), typeof(doc.body) FROM typed_docs() LIMIT 1"
+    >>= (@?= [("STRUCT(serial BIGINT, body JSON)" :: Text, "JSON" :: Text)])
+  query_ conn "SELECT doc FROM typed_docs()" >>= (@?= map Only docs)
+  query conn "SELECT typeof(?), typeof(?), typeof(?)" (Doc 3 (JsonText "{}"), docs, [Nothing :: Maybe Doc])
+    >>= ( @?=
+            [("STRUCT(serial BIGINT, body JSON)" :: Text, "STRUCT(serial BIGINT, body JSON)[]" :: Text, "STRUCT(serial BIGINT, body JSON)[]" :: Text)]
+        )
+
+-- | Reject a column, a parameter, or an argument type with no declaration at
+-- registration, also inside a list, and a MAP of a type text and a record.
+testNoDeclaration :: Assertion
+testNoDeclaration = withConnection ":memory:" \conn -> do
+  assertSqlError
+    "typed_struct: column s: StructValue has no static field types"
+    (createTableFunction conn "typed_struct" ["s"] \() -> pure ([] :: [Only (StructValue FieldValue)]))
+  assertSqlError
+    "typed_tuple: column t: TupleValue has no static field types"
+    (createTableFunction conn "typed_tuple" ["t"] \() -> pure ([] :: [Only (TupleValue FieldValue)]))
+  assertSqlError
+    "typed_union: column u: UnionValue has no static field types"
+    (createTableFunction conn "typed_union" ["u"] \() -> pure ([] :: [Only (UnionValue FieldValue)]))
+  assertSqlError
+    "typed_structs: column s: StructValue has no static field types"
+    (createTableFunction conn "typed_structs" ["n", "s"] \() -> pure ([] :: [(Int64, [Maybe (StructValue FieldValue)])]))
+  assertSqlError
+    "typed_struct_parameter: parameter arg0: StructValue has no static field types"
+    (createTableFunction conn "typed_struct_parameter" ["n"] \(Only (_ :: StructValue FieldValue)) -> pure [Only (1 :: Int64)])
+  assertSqlError
+    "typed_struct_count: argument arg0: StructValue has no static field types"
+    ( createAggregate
+        conn
+        "typed_struct_count"
+        Aggregate
+          { aggregateInitial = 0 :: Int64
+          , aggregateStep = \count (Only (_ :: StructValue FieldValue)) -> pure (count + 1)
+          , aggregateCombine = \a b -> pure (a + b)
+          , aggregateResult = pure
+          }
+    )
+  assertSqlError
+    "typed_priced: column p: a MAP with the type text DECIMAL(18,3) and a structured type has no declaration"
+    (createTableFunction conn "typed_priced" ["p"] \() -> pure ([] :: [Only (Map.Map Price Peak)]))
+  query_ conn "SELECT count(*) FROM duckdb_functions() WHERE function_name LIKE 'typed\\_%' ESCAPE '\\'" >>= (@?= [Only (0 :: Int64)])
+
+-- | Use a SizedArray of size 3 in each position, and a newtype with a sized ARRAY type
+-- text as an argument. DuckDB rejects an ARRAY of another size when it binds
+-- the call, casts a LIST of the same length to the ARRAY, and rejects a LIST
+-- of another length when the statement runs. See Note [Sized arrays] in
+-- "Database.DuckDB.Simple.ToField".
+testSizedArray :: Assertion
+testSizedArray = withConnection ":memory:" \conn -> do
+  let total = sum :: SizedArray 3 Int64 -> Int64
+      triple x = fromJust (sizedArrayFromList @3 [x, x, x :: Int64])
+  createFunction conn "sized_argument" total
+  createFunction conn "sized_newtype" \(Triple values) -> sum values
+  createFunction conn "sized_maybe" (maybe (-1) total :: Maybe (SizedArray 3 Int64) -> Int64)
+  createFunction conn "sized_list" (sum . map total :: [SizedArray 3 Int64] -> Int64)
+  createFunction conn "sized_record" \(Boxed values) -> total values
+  createAggregate
+    conn
+    "sized_aggregate"
+    Aggregate
+      { aggregateInitial = 0 :: Int64
+      , aggregateStep = \sum' (Only values) -> pure (sum' + total values)
+      , aggregateCombine = \a b -> pure (a + b)
+      , aggregateResult = pure
+      }
+  createTableFunction conn "sized_table" ["total"] \(Only values) -> pure [Only (total values)]
+  -- The third part is the type of the error for a LIST of another length.
+  -- DuckDB casts the parameter of a table function as a constant value, and
+  -- that cast raises ErrorInputInvalid "Failed to cast value".
+  let positions :: [(String, Text -> Text, ErrorType)]
+      positions =
+        [ ("scalar argument", \v -> "SELECT sized_argument(" <> v <> ")", ErrorTypeConversion)
+        , ("newtype argument", \v -> "SELECT sized_newtype(" <> v <> ")", ErrorTypeConversion)
+        , ("Maybe argument", \v -> "SELECT sized_maybe(" <> v <> ")", ErrorTypeConversion)
+        , ("list argument", \v -> "SELECT sized_list([" <> v <> "])", ErrorTypeConversion)
+        , ("record field", \v -> "SELECT sized_record({'boxed': " <> v <> "})", ErrorTypeConversion)
+        , ("aggregate argument", \v -> "SELECT sized_aggregate(" <> v <> ")", ErrorTypeConversion)
+        , ("table function parameter", \v -> "SELECT * FROM sized_table(" <> v <> ")", ErrorInputInvalid)
+        ]
+      values :: ErrorType -> [(String, Text, Either (ErrorType, Text) Int64)]
+      values lengthError =
+        [ ("ARRAY of 3", "[1, 2, 3]::BIGINT[3]", Right 6)
+        , ("ARRAY of 4", "[1, 2, 3, 4]::BIGINT[4]", Left (ErrorQueryBinder, "No function matches"))
+        , ("LIST of 3", "[1, 2, 3]", Right 6)
+        , ("LIST of 2", "[1, 2]", Left (lengthError, "Cannot cast list with length 2 to array with length 3"))
+        ]
+      check :: String -> IO [Only Int64] -> Either (ErrorType, Text) Int64 -> Assertion
+      check name action expected = do
+        outcome <- try action
+        case (outcome, expected) of
+          (Right rows, Right value) -> assertEqual name [Only value] rows
+          (Left err, Left (errorType, text)) -> do
+            assertEqual (name <> ": " <> Text.unpack (sqlErrorMessage err)) (Just errorType) (sqlErrorType err)
+            assertBool (name <> ": " <> Text.unpack (sqlErrorMessage err)) (text `Text.isInfixOf` sqlErrorMessage err)
+          (Right rows, Left _) -> assertFailure (name <> ": expected an error, got " <> show rows)
+          (Left (err :: SQLError), Right _) -> assertFailure (name <> ": " <> show err)
+  forM_ positions \(position, sql, lengthError) -> forM_ (values lengthError) \(label, value, expected) ->
+    check (position <> ", " <> label) (query_ conn (Query (sql value))) expected
+  -- A bound SizedArray binds as an ARRAY of its size, and a FieldArray as an
+  -- ARRAY of its own size. DuckDB casts a bound list of the same length.
+  let fieldArray items = FieldArray (listArray (0, length items - 1) (map FieldInt64 items))
+  check "bound SizedArray of 3" (query conn "SELECT sized_argument(?)" (Only (triple 1))) (Right 3)
+  check "bound FieldArray of 3" (query conn "SELECT sized_argument(?)" (Only (fieldArray [1, 2, 3]))) (Right 6)
+  check
+    "bound FieldArray of 4"
+    (query conn "SELECT sized_argument(?)" (Only (fieldArray [1, 2, 3, 4])))
+    (Left (ErrorQueryBinder, "No function matches"))
+  check "bound list of 3" (query conn "SELECT sized_argument(?)" (Only [1, 2, 3 :: Int64])) (Right 6)
+  -- A result and a column of a table function are ARRAY values of the size.
+  createFunction conn "sized_result" triple
+  createTableFunction conn "sized_rows" ["t"] \(Only (x :: Int64)) -> pure [Only (triple x)]
+  query_ conn "SELECT typeof(sized_result(1)), sized_result(1)::VARCHAR" >>= (@?= [("BIGINT[3]" :: Text, "[1, 1, 1]" :: Text)])
+  query_ conn "SELECT typeof(t), t::VARCHAR FROM sized_rows(2)" >>= (@?= [("BIGINT[3]" :: Text, "[2, 2, 2]" :: Text)])
+  -- A result of another size raises the cast error of DuckDB when the function
+  -- runs. A SizedArray has no value of another size, but a hand-written newtype has.
+  createFunction conn "sized_wrong_result" \(x :: Int64) -> Triple [x, x, x, x]
+  check
+    "result of 4"
+    (query_ conn "SELECT len(sized_wrong_result(1))")
+    (Left (ErrorInputInvalid, "Cannot cast list with length 4 to array with length 3"))
+
+-- | Give an error, and no other value, for a record field outside the range
+-- of its declared type, as a parameter, as a column, and as a scalar result.
+testRecordFieldRange :: Assertion
+testRecordFieldRange = withConnection ":memory:" \conn -> do
+  let largest = Counts (2 ^ (127 :: Int) - 1) (2 ^ (128 :: Int) - 1)
+      outside = [(Counts (2 ^ (127 :: Int)) 0, "HUGEINT value out of range"), (Counts 0 (2 ^ (128 :: Int)), "UHUGEINT value out of range")]
+      cases = largest : map fst outside
+  query conn "SELECT ?" (Only largest) >>= (@?= [Only largest])
+  createFunction conn "typed_counts_result" (\(index :: Int) -> cases !! index)
+  query_ conn "SELECT typeof(typed_counts_result(0)), typed_counts_result(0)"
+    >>= (@?= [("STRUCT(signed HUGEINT, unsigned UHUGEINT)" :: Text, largest)])
+  createTableFunction conn "typed_counts" ["c"] \(Only (index :: Int)) -> pure [Only (cases !! index)]
+  query_ conn "SELECT typeof(c), c FROM typed_counts(0)" >>= (@?= [("STRUCT(signed HUGEINT, unsigned UHUGEINT)" :: Text, largest)])
+  forM_ (zip [1 :: Int ..] outside) \(index, (counts, message)) -> do
+    outcome <- try (query conn "SELECT ?" (Only counts) :: IO [Only Counts])
+    case outcome of
+      Left (err :: SomeException) -> assertBool (displayException err) (message `Text.isInfixOf` Text.pack (displayException err))
+      Right rows -> assertFailure ("expected an error, got " <> show rows)
+    assertSqlError message (query_ conn (Query ("SELECT c FROM typed_counts(" <> Text.pack (show index) <> ")")) :: IO [Only Counts])
+    assertSqlError message (query_ conn (Query ("SELECT typed_counts_result(" <> Text.pack (show index) <> ")")) :: IO [Only Counts])
+
+-- | Run the function for each scan. Do not run it at registration or preparation.
+testTableRuns :: Assertion
+testTableRuns = withConnection ":memory:" \conn -> do
+  calls <- newIORef (0 :: Int)
+  createTableFunction conn "typed_counted" ["n"] \(Only count) -> do
+    modifyIORef' calls (+ 1)
+    pure (map Only [1 .. count :: Int64])
+  readIORef calls >>= (@?= 0)
+  withStatement conn "SELECT n FROM typed_counted(2)" \statement -> do
+    readIORef calls >>= (@?= 0)
+    _ <- executeStatement statement
+    readIORef calls >>= (@?= 1)
+    _ <- executeStatement statement
+    readIORef calls >>= (@?= 2)
+  query_ conn "SELECT a.n, b.n FROM typed_counted(2) a JOIN typed_counted(3) b ON a.n = b.n ORDER BY a.n"
+    >>= (@?= [(1 :: Int64, 1 :: Int64), (2, 2)])
+  readIORef calls >>= (@?= 4)
+
+-- | Read the first rows of an infinite list.
+testTableLazy :: Assertion
+testTableLazy = withConnection ":memory:" \conn -> do
+  createTableFunction conn "typed_naturals" ["n"] \() -> pure (map Only [0 :: Int64 ..])
+  query_ conn "SELECT n FROM typed_naturals() LIMIT 3" >>= (@?= map Only [0, 1, 2 :: Int64])
+  -- 10000 rows need more than one chunk.
+  query_ conn "SELECT sum(n)::BIGINT FROM (SELECT n FROM typed_naturals() LIMIT 10000)" >>= (@?= [Only (49995000 :: Int64)])
+
+-- | Reject wrong column names at registration. Fail a query with an argument that does not convert.
+testTableArgumentErrors :: Assertion
+testTableArgumentErrors = withConnection ":memory:" \conn -> do
+  assertSqlError
+    "1 column names for 2 result columns"
+    (createTableFunction conn "typed_bad_names" ["a"] \() -> pure [(1 :: Int64, 2 :: Int64)])
+  assertSqlError "at least one result column" (createTableFunction conn "typed_no_columns" [] \() -> pure [()])
+  -- A Natural parameter is UHUGEINT. DuckDB does not cast a negative literal to it.
+  createTableFunction conn "typed_natural" ["n"] \(Only (value :: Natural)) -> pure [Only (fromIntegral value :: Int64)]
+  query_ conn "SELECT n FROM typed_natural(7)" >>= (@?= [Only (7 :: Int64)])
+  assertSqlError "No function matches" (query_ conn "SELECT n FROM typed_natural(-7)" :: IO [Only Int64])
+  assertSqlError "typed_natural: argument arg0 is NULL" (query_ conn "SELECT n FROM typed_natural(NULL)" :: IO [Only Int64])
+  query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+
+-- | Fail a query with an exception in the function and in a row of the second chunk.
+testTableExceptions :: Assertion
+testTableExceptions = withConnection ":memory:" \conn -> do
+  createTableFunction conn "typed_checked" ["n"] \(Only count) ->
+    if count < 0 then throwIO (userError "typed_checked: the count is negative") else pure (map Only [1 .. count :: Int64])
+  assertSqlError "typed_checked: the count is negative" (query_ conn "SELECT n FROM typed_checked(-1)" :: IO [Only Int64])
+  query_ conn "SELECT n FROM typed_checked(2)" >>= (@?= map Only [1, 2 :: Int64])
+  -- Row 3000 is in the second chunk.
+  createTableFunction conn "typed_partial" ["n"] \() ->
+    pure [Only (if n == 3000 then error "typed_partial: row 3000 fails" else n) | n <- [0 :: Int64 ..]]
+  assertSqlError "typed_partial: row 3000 fails" (query_ conn "SELECT count(*) FROM typed_partial()" :: IO [Only Int64])
+  query_ conn "SELECT n FROM typed_partial() LIMIT 2" >>= (@?= map Only [0, 1 :: Int64])
+  query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+
+-- | Evaluate only the columns that the query uses. A column that the query does
+-- not use can raise an exception, and the query does not fail. A column in
+-- WHERE or in ORDER BY is a column that the query uses. SELECT * reads all
+-- columns, and count(*) reads the first column. The row is evaluated with each
+-- strict field.
+testTableProjection :: Assertion
+testTableProjection = withConnection ":memory:" \conn -> do
+  createTableFunction conn "typed_pairs" ["n", "failing"] \(Only count) ->
+    pure [(n, if n == 2500 then error "typed_pairs: the column fails" else n * 2) | n <- [0 .. count - 1 :: Int64]]
+  query_ conn "SELECT n FROM typed_pairs(3000) WHERE n % 1000 = 1" >>= (@?= map Only [1, 1001, 2001 :: Int64])
+  query_ conn "SELECT sum(n)::BIGINT FROM typed_pairs(3000)" >>= (@?= [Only (sum [0 .. 2999 :: Int64])])
+  assertSqlError "typed_pairs: the column fails" (query_ conn "SELECT failing FROM typed_pairs(3000)" :: IO [Only Int64])
+  query_ conn "SELECT failing FROM typed_pairs(3)" >>= (@?= map Only [0, 2, 4 :: Int64])
+  query_ conn "SELECT * FROM typed_pairs(3)" >>= (@?= ([(0, 0), (1, 2), (2, 4)] :: [(Int64, Int64)]))
+  query_ conn "SELECT failing, n FROM typed_pairs(3)" >>= (@?= ([(0, 0), (2, 1), (4, 2)] :: [(Int64, Int64)]))
+  assertSqlError "typed_pairs: the column fails" (query_ conn "SELECT failing, n FROM typed_pairs(3000)" :: IO [(Int64, Int64)])
+  query_ conn "SELECT n, n FROM typed_pairs(3000) WHERE n % 1000 = 1" >>= (@?= ([(1, 1), (1001, 1001), (2001, 2001)] :: [(Int64, Int64)]))
+  query_ conn "SELECT failing, failing FROM typed_pairs(3)" >>= (@?= ([(0, 0), (2, 2), (4, 4)] :: [(Int64, Int64)]))
+  query_ conn "SELECT n FROM typed_pairs(3) WHERE failing > 2" >>= (@?= [Only (2 :: Int64)])
+  query_ conn "SELECT n FROM typed_pairs(3) ORDER BY failing DESC" >>= (@?= map Only [2, 1, 0 :: Int64])
+  assertSqlError "typed_pairs: the column fails" (query_ conn "SELECT n FROM typed_pairs(3000) WHERE failing >= 0" :: IO [Only Int64])
+  assertSqlError "typed_pairs: the column fails" (query_ conn "SELECT n FROM typed_pairs(3000) ORDER BY failing" :: IO [Only Int64])
+  query_ conn "SELECT count(*) FROM typed_pairs(3000)" >>= (@?= [Only (3000 :: Int64)])
+  createTableFunction conn "typed_pairs_first" ["failing", "n"] \(Only count) ->
+    pure [(if n == 2500 then error "typed_pairs_first: the column fails" else n * 2, n) | n <- [0 .. count - 1 :: Int64]]
+  assertSqlError "typed_pairs_first: the column fails" (query_ conn "SELECT count(*) FROM typed_pairs_first(3000)" :: IO [Only Int64])
+  query_ conn "SELECT n FROM typed_pairs_first(3000) WHERE n % 1000 = 1" >>= (@?= map Only [1, 1001, 2001 :: Int64])
+  createTableFunction conn "typed_strict_pairs" ["n", "failing"] \(Only count) ->
+    pure [StrictPair n (if n == 2500 then error "typed_strict_pairs: the field fails" else n * 2) | n <- [0 .. count - 1 :: Int64]]
+  query_ conn "SELECT n FROM typed_strict_pairs(3)" >>= (@?= map Only [0, 1, 2 :: Int64])
+  assertSqlError "typed_strict_pairs: the field fails" (query_ conn "SELECT n FROM typed_strict_pairs(3000)" :: IO [Only Int64])
+
+-- | A row type with strict fields.
+data StrictPair = StrictPair !Int64 !Int64
+  deriving (Generic)
+
+instance TypedRow StrictPair
+
+-- | Release the list of each scan after a full scan, after LIMIT, and after an
+-- error. Each call makes a token. The rows that the scan did not read refer to
+-- the token. Release the function when the connection closes.
+testTableRelease :: Assertion
+testTableRelease = do
+  closure <- withConnection ":memory:" \conn -> do
+    tokens <- newIORef []
+    offset <- newIORef (0 :: Int64)
+    offsetWeak <- mkWeakIORef offset (pure ())
+    createTableFunction conn "typed_tokens" ["n"] \(count :: Int64, failure :: Int64) -> do
+      token <- readIORef offset >>= newIORef
+      weak <- mkWeakIORef token (pure ())
+      modifyIORef' tokens (weak :)
+      let rowsFrom n
+            | n == count = pure []
+            | otherwise = unsafeInterleaveIO do
+                value <- readIORef token
+                when (n == failure) $ throwIO (userError "typed_tokens: the row fails")
+                (Only (value + n) :) <$> rowsFrom (n + 1)
+      rowsFrom 0
+    -- Check the token of the last scan before the next statement.
+    let released scan = do
+          performMajorGC
+          performMajorGC
+          scans <- readIORef tokens
+          case scans of
+            weak : _ -> deRefWeak weak >>= assertBool (scan <> " keeps its list after the scan ends") . isNothing
+            [] -> assertFailure (scan <> " did not run the function")
+    query_ conn "SELECT count(*) FROM typed_tokens(3000, -1)" >>= (@?= [Only (3000 :: Int64)])
+    released "a full scan"
+    query_ conn "SELECT n FROM typed_tokens(-1, -1) LIMIT 3" >>= (@?= map Only [0, 1, 2 :: Int64])
+    released "a scan with LIMIT"
+    assertSqlError "typed_tokens: the row fails" (query_ conn "SELECT count(*) FROM typed_tokens(-1, 2500)" :: IO [Only Int64])
+    released "a failed scan"
+    readIORef tokens >>= (@?= 3) . length
+    pure offsetWeak
+  performMajorGC
+  performMajorGC
+  deRefWeak closure >>= assertBool "the table function remains after the connection closes" . isNothing
+
+-- | Write 3000 rows with NULLs to a file and read them back with one format.
+-- The rows need more than one chunk in each direction.
+testCopyBothDirections :: Assertion
+testCopyBothDirections = withDirectory \directory -> withConnection ":memory:" \conn -> do
+  calls <- newIORef ([] :: [CopyFromInfo])
+  registerCopyFunction conn "typed_lines" linesTo \info -> do
+    modifyIORef' calls (info :)
+    readLines (copyFromPath info)
+  let file = directory </> "lines.txt"
+      expected = [if i `mod` 1000 == 7 then Nothing else Just i | i <- [0 .. 2999 :: Int64]]
+  void
+    ( execute
+        conn
+        "COPY (SELECT CASE WHEN i % 1000 = 7 THEN NULL ELSE i END AS value FROM range(3000) t(i)) TO ? (FORMAT typed_lines)"
+        (Only (Text.pack file))
+    )
+  readFile file >>= (@?= unlines (map (maybe "" show) expected))
+  void (execute_ conn "CREATE TABLE typed_copied (value BIGINT)")
+  -- The function runs one time for each run of a COPY FROM statement.
+  forM_ [1 :: Int, 2] \_ -> void (execute conn "COPY typed_copied FROM ? (FORMAT typed_lines)" (Only (Text.pack file)))
+  query_ conn "SELECT value FROM typed_copied ORDER BY rowid" >>= (@?= map Only (expected <> expected))
+  infos <- readIORef calls
+  length infos @?= 2
+  forM_ infos \info -> do
+    copyFromPath info @?= file
+    copyFromColumnNames info @?= ["value"]
+    length (copyFromColumnTypes info) @?= 1
+
+-- | DuckDB keeps the first registration of a format name. A later
+-- registration has no effect, so it does not add a COPY FROM side.
+testCopyFirstRegistration :: Assertion
+testCopyFirstRegistration = withDirectory \directory -> withConnection ":memory:" \conn -> do
+  sinks <- newIORef ([] :: [Text])
+  let file = Text.pack (directory </> "first.txt")
+      register label =
+        registerCopyToFunction
+          conn
+          "typed_first"
+          (\_ -> pure ())
+          (\info -> writeFile (copyInitFilePath info) "")
+          (\_ _ -> modifyIORef' sinks (label :))
+          (\_ -> pure ())
+  register "first"
+  register "second"
+  registerCopyFromFunction conn "typed_first" \_ -> pure [Only (1 :: Int64)]
+  void (execute conn "COPY (SELECT 1) TO ? (FORMAT typed_first)" (Only file))
+  readIORef sinks >>= (@?= ["first"])
+  void (execute_ conn "CREATE TABLE typed_first_rows (value BIGINT)")
+  assertSqlError
+    "COPY FROM is not supported for FORMAT \"typed_first\""
+    (execute conn "COPY typed_first_rows FROM ? (FORMAT typed_first)" (Only file))
+  -- A format with a COPY FROM side only rejects COPY TO.
+  registerCopyFromFunction conn "typed_from_only" \_ -> pure [Only (2 :: Int64)]
+  void (execute conn "COPY typed_first_rows FROM ? (FORMAT typed_from_only)" (Only file))
+  query_ conn "SELECT value FROM typed_first_rows" >>= (@?= [Only (2 :: Int64)])
+  assertSqlError
+    "COPY TO is not supported for FORMAT \"typed_from_only\""
+    (execute conn "COPY (SELECT 1) TO ? (FORMAT typed_from_only)" (Only file))
+  query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+
+-- | Give the reader of COPY FROM the name and the type of each column, in the
+-- order of the table. DuckDB gives the same names and types.
+testCopyFromColumns :: Assertion
+testCopyFromColumns = withDirectory \directory -> withConnection ":memory:" \conn -> do
+  calls <- newIORef ([] :: [CopyFromInfo])
+  registerCopyFromFunction conn "typed_columns" \info -> do
+    modifyIORef' calls (info :)
+    pure [(7 :: Int64, "seven" :: Text, fromGregorian 2026 11 15)]
+  let file = directory </> "columns.txt"
+  writeFile file ""
+  void (execute_ conn "CREATE TABLE typed_three (a BIGINT, b VARCHAR, c DATE)")
+  void (execute conn "COPY typed_three FROM ? (FORMAT typed_columns)" (Only (Text.pack file)))
+  query_ conn "SELECT column_name, data_type FROM information_schema.columns WHERE table_name = 'typed_three' ORDER BY ordinal_position"
+    >>= (@?= [("a" :: Text, "BIGINT" :: Text), ("b", "VARCHAR"), ("c", "DATE")])
+  readIORef calls >>= (@?= [CopyFromInfo file ["a", "b", "c"] [LogicalTypeIdBigInt, LogicalTypeIdVarchar, LogicalTypeIdDate]])
+  query_ conn "SELECT a, b, c FROM typed_three" >>= (@?= [(7 :: Int64, "seven" :: Text, fromGregorian 2026 11 15)])
+
+-- | Raise an error in each COPY TO function, in the COPY FROM function, and in
+-- a lazy row after the first chunk. Each error fails its statement. The next
+-- statement runs.
+testCopyErrors :: Assertion
+testCopyErrors = withDirectory \directory -> withConnection ":memory:" \conn -> do
+  let file = Text.pack (directory </> "errors.txt")
+  void (execute_ conn "CREATE TABLE typed_failed (value BIGINT)")
+  forM_ ["bind", "init", "sink", "finalize"] \phase -> do
+    registerFailingFormat conn phase
+    assertSqlError
+      ("typed_copy_error: " <> phase)
+      (execute conn (Query ("COPY (SELECT 1) TO ? (FORMAT typed_error_" <> phase <> ")")) (Only file))
+    query_ conn "SELECT 42" >>= (@?= [Only (42 :: Int64)])
+  forM_ ["from", "row"] \phase -> do
+    registerFailingFormat conn phase
+    assertSqlError
+      ("typed_copy_error: " <> phase)
+      (execute conn (Query ("COPY typed_failed FROM ? (FORMAT typed_error_" <> phase <> ")")) (Only file))
+    query_ conn "SELECT count(*) FROM typed_failed" >>= (@?= [Only (0 :: Int64)])
+  -- The rows of a format must have one column for each column of the table.
+  void (execute_ conn "CREATE TABLE typed_wide (a BIGINT, b BIGINT)")
+  registerFailingFormat conn "none"
+  assertSqlError
+    "the table of COPY FROM has 2 columns, but a row of typed_error_none has 1"
+    (execute conn "COPY typed_wide FROM ? (FORMAT typed_error_none)" (Only file))
+  void (execute conn "COPY typed_failed FROM ? (FORMAT typed_error_none)" (Only file))
+  query_ conn "SELECT count(*) FROM typed_failed" >>= (@?= [Only (3000 :: Int64)])
+
+-- | Register a format on one connection. Use it from another connection.
+testCopySharedDatabase :: Assertion
+testCopySharedDatabase = withDirectory \directory -> withEnvironment \environment -> withInstance environment [] \instance' -> do
+  -- An instance starts with no database. The case creates a table, so it
+  -- attaches an in-memory database and makes it the default.
+  attachDatabase instance' ":memory:" "typed_shared" []
+  setDefaultDatabase instance' "typed_shared"
+  let file = Text.pack (directory </> "shared.txt")
+  withConnectionOn instance' \first -> withConnectionOn instance' \second -> do
+    registerCopyFunction first "typed_shared_lines" linesTo (readLines . copyFromPath)
+    registerCopyFunction second "typed_shared_lines" linesTo \_ -> ioError (userError "the second registration runs") :: IO [Only Int64]
+    void (execute second "COPY (SELECT i FROM range(5) t(i)) TO ? (FORMAT typed_shared_lines)" (Only file))
+    void (execute_ first "CREATE TABLE typed_shared_rows (value BIGINT)")
+    void (execute second "COPY typed_shared_rows FROM ? (FORMAT typed_shared_lines)" (Only file))
+    void (execute first "COPY typed_shared_rows FROM ? (FORMAT typed_shared_lines)" (Only file))
+    query_ first "SELECT value FROM typed_shared_rows ORDER BY rowid" >>= (@?= map (Only . Just) ([0 .. 4] <> [0 .. 4 :: Int64]))
+
+-- | Raise the input error of an empty format name, also on a closed connection.
+-- The name check comes before the read of the state of the connection.
+testCopyClosedName :: Assertion
+testCopyClosedName = do
+  closed <- open ":memory:"
+  close closed
+  assertInputErrorContaining "invalid copy function name" $
+    registerCopyToFunction closed "" (\_ -> pure ()) (\_ -> pure ()) (\_ _ -> pure ()) (\_ -> pure ())
+  assertInputErrorContaining "invalid copy function name" $
+    registerCopyFunction closed "" linesTo (\_ -> pure [Only (1 :: Int64)])
+
+-- | A COPY TO side that writes one BIGINT column as lines. A NULL is an empty line.
+linesTo :: CopyTo () FilePath
+linesTo =
+  CopyTo
+    { copyToBind = \info -> when (length (copyBindColumnTypes info) /= 1) (ioError (userError "typed_lines writes one column"))
+    , copyToInit = \info -> writeFile (copyInitFilePath info) "" >> pure (copyInitFilePath info)
+    , copyToSink = \info rows -> appendFile (copySinkGlobalState info) (unlines (map line rows))
+    , copyToFinalize = \_ -> pure ()
+    }
+  where
+    line [Field{fieldValue = FieldInt64 value}] = show value
+    line [Field{fieldValue = FieldNull}] = ""
+    line row = error ("typed_lines: unexpected row " <> show (map fieldValue row))
+
+-- | Read a file of 'linesTo'. An empty line is NULL.
+readLines :: FilePath -> IO [Only (Maybe Int64)]
+readLines path = map (Only . parse . Text.unpack) . Text.lines <$> TextIO.readFile path
+  where
+    parse "" = Nothing
+    parse line = Just (read line)
+
+-- | Register the format @typed_error_@ with the phase as suffix. The function
+-- of that phase raises an error. The phase @row@ makes the row at index 2500 raise
+-- an error. That row is in the second chunk.
+registerFailingFormat :: Connection -> Text -> IO ()
+registerFailingFormat conn phase =
+  registerCopyFunction conn ("typed_error_" <> phase) failing \_ -> failIn "from" >> pure rows
+  where
+    failIn name = when (phase == name) (ioError (userError ("typed_copy_error: " <> Text.unpack name)))
+    failing =
+      CopyTo
+        (\_ -> failIn "bind")
+        (\info -> failIn "init" >> writeFile (copyInitFilePath info) "")
+        (\_ _ -> failIn "sink")
+        (\_ -> failIn "finalize")
+    rows = [Only (if phase == "row" && i == 2500 then error "typed_copy_error: row" else i) | i <- [0 .. 2999 :: Int64]]
+
+-- | Read 8 files through a multi-file function over a typed table function.
+-- DuckDB runs exec callbacks of one scan at the same time for a multi-file
+-- function. Each row must come one time. The case sets 4 threads, so that it
+-- does not use the default number of threads of the machine.
+testTableMultiFile :: Assertion
+testTableMultiFile = withDirectory \directory -> withConnection ":memory:" \conn -> do
+  void (execute_ conn "SET threads = 4")
+  createTableFunction conn "typed_numbers" ["value"] \(Only path) ->
+    map (Only . read) . lines <$> readFile (Text.unpack path) :: IO [Only Int64]
+  registerMultiFileFunction conn "typed_all_numbers" "typed_numbers" defaultMultiFileOptions
+  -- A file of 10000 rows needs 5 output chunks. The multi-file function can
+  -- then run more than one exec callback for the scan of one file.
+  let numbers file = [file * 100000 + row | row <- [0 .. 9999]] :: [Int64]
+  forM_ [0 .. 7] \file -> writeFile (directory </> ("numbers" <> show file <> ".txt")) (unlines (map show (numbers file)))
+  forM_ [1 :: Int .. 5] \_ ->
+    query conn "SELECT value FROM typed_all_numbers(?) ORDER BY value" (Only (Text.pack (directory </> "numbers*.txt")))
+      >>= (@?= map Only (concatMap numbers [0 .. 7]))
+  -- count(*) uses no column. The typed table function declares projection
+  -- pushdown, so the multi-file function can run it.
+  query conn "SELECT count(*) FROM typed_all_numbers(?)" (Only (Text.pack (directory </> "numbers*.txt")))
+    >>= (@?= [Only (80000 :: Int64)])
+
+-- | Create and remove a unique directory for the files of a test.
+withDirectory :: (FilePath -> IO a) -> IO a
+withDirectory = bracket create removePathForcibly
+  where
+    create = do
+      root <- getTemporaryDirectory
+      (path, handle) <- openTempFile root "duckdb-typed-copy"
+      hClose handle
+      removeFile path
+      createDirectory path
+      pure path
+
+-- | The registration kinds that have no other check of the release of their
+-- callback closure. Each action registers one callback that reads the token,
+-- runs the callback one time, and closes the database.
+closureKinds :: [(String, IORef Int64 -> IO ())]
+closureKinds =
+  [
+    ( "typed aggregate"
+    , \token -> withConnection ":memory:" \conn -> do
+        createAggregate
+          conn
+          "closure_sum"
+          sumAggregate{aggregateStep = \total (Only value) -> (\factor -> total + factor * value) <$> readIORef token}
+        query_ conn "SELECT closure_sum(i) FROM range(10) t(i)" >>= (@?= [Only (45 :: Int64)])
+    )
+  ,
+    ( "cast"
+    , \token -> withConnection ":memory:" \conn -> do
+        registerCustomType conn "closure_type" (TypeExpression "BIGINT")
+        -- The callback reads the token in each call, so its closure keeps the token.
+        R.registerCast conn (TypeExpression "BIGINT") (TypeExpression "closure_type") Nothing \info _ ->
+          readIORef token >> writeNullRows info
+        query_ conn "SELECT CAST(41::BIGINT AS closure_type) IS NULL" >>= (@?= [Only True])
+    )
+  ,
+    ( "connection replacement scan"
+    , \token -> withConnection ":memory:" \conn -> do
+        registerReplacementScan conn (closureScan token)
+        query_ conn "SELECT value FROM closure_table" >>= (@?= [Only (42 :: Int64)])
+    )
+  ,
+    ( "instance replacement scan"
+    , \token -> withEnvironment \environment -> withInstance environment [] \instance' -> do
+        registerInstanceReplacementScan instance' (closureScan token)
+        withConnectionOn instance' \conn -> query_ conn "SELECT value FROM closure_table" >>= (@?= [Only (42 :: Int64)])
+    )
+  ,
+    ( "custom option update"
+    , \token -> withConnection ":memory:" \conn -> do
+        registerCustomOption conn (customOption "closure_option" (TypeExpression "BIGINT")){customOptionUpdate = Just \_ -> void (readIORef token)}
+        void (execute_ conn "SET closure_option = 5")
+    )
+  ,
+    ( "COPY format"
+    , \token -> withConnection ":memory:" \conn -> do
+        let use = void (readIORef token)
+        registerCopyFunction
+          conn
+          "closure_copy"
+          CopyTo{copyToBind = const use, copyToInit = const use, copyToSink = \_ _ -> use, copyToFinalize = const use}
+          (\_ -> use >> pure [Only (42 :: Int64)])
+        void (execute_ conn "COPY (SELECT 1::BIGINT) TO 'unused' (FORMAT closure_copy)")
+        void (execute_ conn "CREATE TABLE closure_rows (value BIGINT)")
+        void (execute_ conn "COPY closure_rows FROM 'unused' (FORMAT closure_copy)")
+        query_ conn "SELECT value FROM closure_rows" >>= (@?= [Only (42 :: Int64)])
+    )
+  ,
+    ( "typed pragma"
+    , \token -> withConnection ":memory:" \conn -> do
+        registerPragmaFunction conn "closure_pragma" [] (ExecPragma \() -> void (readIORef token))
+        void (execute_ conn "PRAGMA closure_pragma")
+    )
+  ,
+    ( "log sink"
+    , \token -> withConnection ":memory:" \conn -> do
+        Logging.registerLogSink conn "closure_log" (\_ -> void (readIORef token)) (void (readIORef token))
+        void
+          (execute_ conn "CALL enable_logging(); SET logging_storage = 'closure_log'; SELECT write_log('closure'); SET logging_storage = 'memory'")
+    )
+  ]
+
+-- | A replacement scan that reads the token and replaces @closure_table@.
+closureScan :: IORef Int64 -> [Text] -> IO (Maybe Replacement)
+closureScan token parts = do
+  void (readIORef token)
+  pure (if parts == ["closure_table"] then Just (ReplaceWithQuery "SELECT 42::BIGINT AS value") else Nothing)
diff --git a/test/UserCastTests.hs b/test/UserCastTests.hs
new file mode 100644
--- /dev/null
+++ b/test/UserCastTests.hs
@@ -0,0 +1,350 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+
+-- |
+-- Module      : UserCastTests
+-- Description : Check that a cast that a user registers does not change what the library reads.
+--
+-- Each case registers a cast that writes NULL for each row and counts its
+-- calls. Then the case reads a value whose reader uses the built-in cast for
+-- the same pair of types. The value must be correct, and the user cast must
+-- not run. See Note [User casts and the casts of the library] in
+-- "Database.DuckDB.Simple.Materialize".
+module UserCastTests (userCastTests, geometryArgumentTests) where
+
+import Control.Exception (throwIO, try)
+import Control.Monad (void)
+import Data.Array (listArray, (!))
+import qualified Data.ByteString as BS
+import qualified Data.Geometry as G
+import Data.IORef (IORef, atomicModifyIORef', modifyIORef', newIORef, readIORef, writeIORef)
+import Data.Int (Int64)
+import qualified Data.Map.Strict as Map
+import Data.Maybe (fromMaybe)
+import Data.Text (Text)
+import qualified Data.Text as Text
+import Database.DuckDB.Simple
+import qualified Database.DuckDB.Simple.Config as Config
+import qualified Database.DuckDB.Simple.Copy as Copy
+import Database.DuckDB.Simple.FromField (Field (..), FieldValue (..), returnError)
+import Database.DuckDB.Simple.Geometry (RawGeometry (..))
+import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep (..), StructField (..), StructValue (..))
+import Database.DuckDB.Simple.Pragma (PragmaCallback (..), registerPragmaFunction)
+import qualified Database.DuckDB.Simple.Streaming as Streaming
+import Database.DuckDB.Simple.ToField (ToDuckValue (..))
+import qualified Database.DuckDB.Simple.V2.Registration as R
+import Database.DuckDB.Simple.Variant (Variant (..), variantObject)
+import Test.Tasty (TestTree, testGroup)
+import Test.Tasty.HUnit
+import TestUtils (writeNullRows)
+
+-- | Check the readers and binders of the library under user casts.
+userCastTests :: TestTree
+userCastTests =
+  testGroup
+    "user casts"
+    [ testCase "a cast from GEOMETRY to BLOB does not change a GEOMETRY result" $ withConnection ":memory:" \conn -> do
+        calls <- nullCast conn (R.TypeExpression "GEOMETRY") (R.TypeExpression "BLOB")
+        (query_ conn "SELECT 'POINT (1 2)'::GEOMETRY" :: IO [Only (Maybe RawGeometry)]) >>= (@?= [Only (Just point)])
+        (query_ conn "SELECT 'POINT (1 2)'::GEOMETRY" :: IO [Only (Maybe G.Geometry)]) >>= (@?= [Only (Just shape)])
+        (query_ conn "SELECT {'g': 'POINT (1 2)'::GEOMETRY}" :: IO [Only FieldValue])
+          >>= (@?= [Only (FieldStruct (oneField "g" (LogicalTypeGeometry Nothing) (FieldGeometry point)))])
+        Streaming.fold_ conn "SELECT 'POINT (1 2)'::GEOMETRY FROM range(3)" [] (\seen (Only value) -> pure (value : seen))
+          >>= (@?= replicate 3 point)
+        -- A GEOMETRY with a CRS has another type, so this cast is not used for it.
+        (query conn "SELECT ST_SetCRS(ST_GeomFromWKB(?), 'local grid')" (Only pointWKB) :: IO [Only RawGeometry])
+          >>= (@?= [Only point{rawGeometryCRS = Just "local grid"}])
+        readIORef calls >>= (@?= 0)
+    , testCase "a cast from GEOMETRY('OGC:CRS84') to BLOB does not change a GEOMETRY('OGC:CRS84') result" $
+        withConnection ":memory:" \conn -> do
+          calls <- nullCast conn (R.StructuredType (LogicalTypeGeometry (Just "OGC:CRS84"))) (R.TypeExpression "BLOB")
+          (query_ conn "SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84')" :: IO [Only RawGeometry])
+            >>= (@?= [Only point{rawGeometryCRS = Just "OGC:CRS84"}])
+          readIORef calls >>= (@?= 0)
+    , testCase "a cast from GEOMETRY to BLOB does not change the value of a GEOMETRY option" $
+        withConnection ":memory:" \conn -> do
+          Config.registerCustomOption
+            conn
+            (Config.customOption "user_cast_shape" (R.TypeExpression "GEOMETRY")){Config.customOptionDefault = Just (R.defaultValue shape)}
+          calls <- nullCast conn (R.TypeExpression "GEOMETRY") (R.TypeExpression "BLOB")
+          Config.getConfigDefaultValue conn "user_cast_shape" >>= (@?= FieldGeometry point)
+          (fst <$> Config.getConfigValue conn "user_cast_shape") >>= (@?= FieldGeometry point)
+          readIORef calls >>= (@?= 0)
+    , testCase "a cast from GEOMETRY to BLOB does not change a GEOMETRY argument of a table function" $
+        withConnection ":memory:" \conn -> do
+          createTableFunction conn "user_cast_shapes" ["same"] \(Only argument) -> pure [Only (argument == Just shape)]
+          calls <- nullCast conn (R.TypeExpression "GEOMETRY") (R.TypeExpression "BLOB")
+          query_ conn "SELECT same FROM user_cast_shapes('POINT (1 2)'::GEOMETRY)" >>= (@?= [Only True])
+          readIORef calls >>= (@?= 0)
+    , testCase "a cast from GEOMETRY to BLOB does not change a GEOMETRY row of a COPY TO function" $
+        withConnection ":memory:" \conn -> do
+          rows <- newIORef []
+          Copy.registerCopyToFunction conn "user_cast_copy" (\_ -> pure ()) (\_ -> pure ()) (\_ batch -> modifyIORef' rows (<> batch)) (\_ -> pure ())
+          calls <- nullCast conn (R.TypeExpression "GEOMETRY") (R.TypeExpression "BLOB")
+          void (execute_ conn "COPY (SELECT 'POINT (1 2)'::GEOMETRY AS g) TO 'unused' (FORMAT user_cast_copy)")
+          (map (map fieldValue) <$> readIORef rows) >>= (@?= [[FieldGeometry point]])
+          readIORef calls >>= (@?= 0)
+    , testCase "a cast from GEOMETRY to BLOB does not change a GEOMETRY argument of a pragma" $
+        withConnection ":memory:" \conn -> do
+          seen <- newIORef Nothing
+          registerPragmaFunction
+            conn
+            "user_cast_pragma"
+            [R.parameter "shape" (R.TypeExpression "GEOMETRY")]
+            (ExecPragma \(Only argument) -> writeIORef seen argument)
+          calls <- nullCast conn (R.TypeExpression "GEOMETRY") (R.TypeExpression "BLOB")
+          void (execute_ conn "PRAGMA user_cast_pragma('POINT (1 2)')")
+          readIORef seen >>= (@?= Just shape)
+          readIORef calls >>= (@?= 0)
+    , testCase "a cast from GEOMETRY to BLOB does not change the value of a GEOMETRY option update" $
+        withConnection ":memory:" \conn -> do
+          seen <- newIORef []
+          Config.registerCustomOption
+            conn
+            (Config.customOption "user_cast_update" (R.TypeExpression "GEOMETRY"))
+              { Config.customOptionUpdate = Just \value -> modifyIORef' seen (value :)
+              }
+          calls <- nullCast conn (R.TypeExpression "GEOMETRY") (R.TypeExpression "BLOB")
+          void (execute_ conn "SET user_cast_update = 'POINT (1 2)'")
+          readIORef seen >>= (@?= [FieldGeometry point])
+          readIORef calls >>= (@?= 0)
+    , testCase "a cast from VARIANT to BIGINT does not change a BIGINT payload of a VARIANT result" $
+        withConnection ":memory:" \conn -> do
+          calls <- nullCast conn (R.TypeExpression "VARIANT") (R.TypeExpression "BIGINT")
+          createFunction conn "user_cast_variant_arg" ((== Variant (FieldInt64 42)) :: Variant -> Bool)
+          query_ conn "SELECT user_cast_variant_arg(42::BIGINT::VARIANT)" >>= (@?= [Only True])
+          query_ conn "SELECT 42::BIGINT::VARIANT" >>= (@?= [Only (Variant (FieldInt64 42))])
+          query_ conn "SELECT {'n': 42::BIGINT}::VARIANT" >>= (@?= [Only (Variant (variantObject [("n", FieldInt64 42)]))])
+          query_ conn "SELECT [1, 2]::BIGINT[]::VARIANT" >>= (@?= [Only (Variant (FieldList [FieldInt64 1, FieldInt64 2]))])
+          readIORef calls >>= (@?= 0)
+    , testCase "a cast from GEOMETRY to BLOB does not change a GEOMETRY payload of a VARIANT result" $
+        withConnection ":memory:" \conn -> do
+          calls <- nullCast conn (R.TypeExpression "GEOMETRY") (R.TypeExpression "BLOB")
+          query_ conn "SELECT 'POINT (1 2)'::GEOMETRY::VARIANT" >>= (@?= [Only (Variant (FieldGeometry point))])
+          readIORef calls >>= (@?= 0)
+    , testCase "a cast from a VARIANT list to a STRUCT list does not change a VARIANT object" $
+        withConnection ":memory:" \conn -> do
+          let variant = LogicalTypeScalar LogicalTypeIdVariant
+              objects = LogicalTypeList (LogicalTypeStruct (listArray (0, 0) [StructField "a" variant]))
+          calls <- nullCast conn (R.StructuredType (LogicalTypeList variant)) (R.StructuredType objects)
+          query_ conn "SELECT {'a': 1}::VARIANT" >>= (@?= [Only (Variant (variantObject [("a", FieldInt32 1)]))])
+          readIORef calls >>= (@?= 0)
+    , testCase "a cast from VARIANT to BIGINT does not change a VARIANT row of a COPY TO function" $
+        withConnection ":memory:" \conn -> do
+          rows <- newIORef []
+          Copy.registerCopyToFunction
+            conn
+            "user_cast_variant_copy"
+            (\_ -> pure ())
+            (\_ -> pure ())
+            (\_ batch -> modifyIORef' rows (<> batch))
+            (\_ -> pure ())
+          calls <- nullCast conn (R.TypeExpression "VARIANT") (R.TypeExpression "BIGINT")
+          void (execute_ conn "COPY (SELECT 42::BIGINT::VARIANT AS v) TO 'unused' (FORMAT user_cast_variant_copy)")
+          (map (map fieldValue) <$> readIORef rows) >>= (@?= [[FieldInt64 42]])
+          readIORef calls >>= (@?= 0)
+    , testCase "a cast from VARCHAR to GEOMETRY does not run when a custom CRS binds" $
+        withEnvironment \environment -> withInstance environment [] \instance' -> withConnectionOn instance' \conn -> do
+          calls <- nullCast conn (R.TypeExpression "VARCHAR") (R.TypeExpression "GEOMETRY")
+          -- The bind resolves the custom CRS without a VARCHAR cast.
+          withConnectionOn instance' \other -> do
+            let grid = point{rawGeometryCRS = Just "local grid"}
+                struct = oneField "g" (LogicalTypeGeometry (Just "local grid")) (FieldGeometry grid)
+            query other "SELECT ?" (Only struct) >>= (@?= [Only struct])
+            readIORef calls >>= (@?= 0)
+    , testCase "a cast from BLOB to GEOMETRY does not change a bound raw geometry" $ withConnection ":memory:" \conn -> do
+        calls <- nullCast conn (R.TypeExpression "BLOB") (R.TypeExpression "GEOMETRY")
+        let struct = oneField "g" (LogicalTypeGeometry Nothing) (FieldGeometry point)
+        query conn "SELECT ?" (Only point) >>= (@?= [Only point])
+        query conn "SELECT ?" (Only struct) >>= (@?= [Only struct])
+        query conn "SELECT ?" (Only (Variant (FieldGeometry point))) >>= (@?= [Only (Variant (FieldGeometry point))])
+        readIORef calls >>= (@?= 0)
+    , testCase "a cast from BLOB to GEOMETRY('OGC:CRS84') does not change a bound raw geometry with that CRS" $
+        withConnection ":memory:" \conn -> do
+          let crs84 = LogicalTypeGeometry (Just "OGC:CRS84")
+              struct = oneField "g" crs84 (FieldGeometry point{rawGeometryCRS = Just "OGC:CRS84"})
+          calls <- nullCast conn (R.TypeExpression "BLOB") (R.StructuredType crs84)
+          query conn "SELECT ?" (Only struct) >>= (@?= [Only struct])
+          readIORef calls >>= (@?= 0)
+    , testCase "a cast from VARCHAR to GEOMETRY does not change a bound Geometry" $ withConnection ":memory:" \conn -> do
+        calls <- nullCast conn (R.TypeExpression "VARCHAR") (R.TypeExpression "GEOMETRY")
+        query conn "SELECT ?" (Only shape) >>= (@?= [Only shape])
+        query conn "SELECT ?" (Only [shape, shape]) >>= (@?= [Only [shape, shape]])
+        readIORef calls >>= (@?= 0)
+    , testCase "a cast from VARCHAR to an ENUM type does not change a bound ENUM value" $ withConnection ":memory:" \conn -> do
+        let entries = LogicalTypeEnum (listArray (0, 1) ["x", "y"])
+            struct = oneField "e" entries (FieldEnum 1 "y")
+        calls <- nullCast conn (R.TypeExpression "VARCHAR") (R.StructuredType entries)
+        query conn "SELECT ?" (Only struct) >>= (@?= [Only struct])
+        readIORef calls >>= (@?= 0)
+    , testCase "a cast from BIGINT to VARIANT does not change a bound Variant" $ withConnection ":memory:" \conn -> do
+        calls <- nullCast conn (R.TypeExpression "BIGINT") (R.TypeExpression "VARIANT")
+        let list = Variant (FieldList [FieldInt64 1, FieldInt64 2])
+        query conn "SELECT ?" (Only (Variant (FieldInt64 5))) >>= (@?= [Only (Variant (FieldInt64 5))])
+        query conn "SELECT ?" (Only list) >>= (@?= [Only list])
+        readIORef calls >>= (@?= 0)
+    , testCase "a cast from VARCHAR to GEOMETRY does not change a Geometry row of a table function" $
+        withConnection ":memory:" \conn -> do
+          createTableFunction conn "user_cast_rows" ["g"] \() -> pure [Only shape]
+          calls <- nullCast conn (R.TypeExpression "VARCHAR") (R.TypeExpression "GEOMETRY")
+          query_ conn "SELECT g FROM user_cast_rows()" >>= (@?= [Only (Just shape)])
+          readIORef calls >>= (@?= 0)
+    , testCase "a bound raw geometry keeps its typed NULL and its error for bytes that are not WKB" $
+        withConnection ":memory:" \conn -> do
+          let crs84 = LogicalTypeGeometry (Just "OGC:CRS84")
+              struct = oneField "g" crs84 FieldNull
+          query conn "SELECT ?" (Only struct) >>= (@?= [Only struct])
+          try (query conn "SELECT ?" (Only (RawGeometry (BS.pack [1, 2, 3]) Nothing)) :: IO [Only RawGeometry]) >>= \case
+            Left SQLError{sqlErrorMessage} ->
+              assertBool (show sqlErrorMessage) ("Could not convert BLOB to GEOMETRY" `Text.isInfixOf` sqlErrorMessage)
+            Right rows -> assertFailure ("expected an error, got " <> show rows)
+    ]
+
+-- | Check the GEOMETRY arguments of a scalar function and a typed aggregate.
+-- Each case also registers a cast from GEOMETRY to BLOB that writes NULL, and
+-- that cast must not run.
+geometryArgumentTests :: TestTree
+geometryArgumentTests =
+  testGroup
+    "geometry arguments"
+    [ testCase "a scalar function reads a Geometry argument" $ withConnection ":memory:" \conn -> do
+        createFunction conn "hs_point_x" pointX
+        createFunction conn "hs_maybe_x" (fmap pointX :: Maybe G.Geometry -> Maybe Double)
+        createFunction conn "hs_count_shapes" (\(shapes :: [G.Geometry]) -> fromIntegral (length shapes) :: Int64)
+        createFunction conn "hs_placed_x" (\(Placed g) -> pointX g)
+        calls <- nullCast conn (R.TypeExpression "GEOMETRY") (R.TypeExpression "BLOB")
+        query_ conn "SELECT hs_point_x('POINT (1 2)'::GEOMETRY)" >>= (@?= [Only (1 :: Double)])
+        query_ conn "SELECT hs_point_x('POINT (3 4)'::GEOMETRY('OGC:CRS84'))" >>= (@?= [Only (3 :: Double)])
+        query_ conn "SELECT hs_maybe_x(NULL::GEOMETRY)" >>= (@?= [Only (Nothing :: Maybe Double)])
+        query_ conn "SELECT hs_count_shapes(['POINT (1 2)'::GEOMETRY, 'POINT (3 4)'::GEOMETRY])" >>= (@?= [Only (2 :: Int64)])
+        query_ conn "SELECT hs_placed_x({'name': 'a', 'shape': 'POINT (1 2)'::GEOMETRY})" >>= (@?= [Only (1 :: Double)])
+        query_ conn "SELECT sum(hs_point_x(('POINT (' || i || ' 0)')::GEOMETRY)) FROM range(5000) t(i)" >>= (@?= [Only (12497500 :: Double)])
+        readIORef calls >>= (@?= 0)
+        withConnection ":memory:" \grid -> do
+          createFunction grid "hs_point_x" pointX
+          query grid "SELECT hs_point_x(ST_SetCRS(ST_GeomFromWKB(?), 'local grid'))" (Only pointWKB) >>= (@?= [Only (1 :: Double)])
+    , testCase "a scalar function reads its arguments through a selection and from a constant vector" $ withConnection ":memory:" \conn -> do
+        createFunction conn "hs_point_x" pointX
+        createFunction conn "hs_maybe_x" (fmap pointX :: Maybe G.Geometry -> Maybe Double)
+        createFunction conn "hs_count_shapes" (\(shapes :: [G.Geometry]) -> fromIntegral (length shapes) :: Int64)
+        _ <- execute_ conn "CREATE TABLE selected AS SELECT i, ('POINT (' || i || ' 2)')::GEOMETRY AS g FROM range(3000) t(i)"
+        let kept = [i | i <- [0 .. 2999 :: Int64], i `mod` 7 == 0]
+        -- A WHERE filter gives the function a DICTIONARY vector.
+        query_ conn "SELECT count(*), count(DISTINCT hs_point_x(g)), sum(hs_point_x(g)) FROM selected WHERE i % 7 = 0"
+          >>= (@?= [(fromIntegral (length kept) :: Int64, fromIntegral (length kept) :: Int64, fromIntegral (sum kept) :: Double)])
+        query_ conn "SELECT sum(hs_count_shapes([g, g])) FROM selected WHERE i % 7 = 0" >>= (@?= [Only (2 * fromIntegral (length kept) :: Int64)])
+        query_ conn "SELECT count(hs_maybe_x(CASE WHEN i = 7 THEN NULL ELSE g END)) FROM selected WHERE i % 7 = 0"
+          >>= (@?= [Only (fromIntegral (length kept) - 1 :: Int64)])
+        -- A constant argument over FROM gives the function a CONSTANT vector.
+        query_ conn "SELECT hs_point_x('POINT (7 8)'::GEOMETRY) FROM range(3)" >>= (@?= replicate 3 (Only (7 :: Double)))
+    , testCase "a registration cannot declare a custom CRS of the connection" $
+        withConnection ":memory:" \grid -> do
+          try
+            ( R.registerCast grid (R.StructuredType (LogicalTypeGeometry (Just "local grid"))) (R.TypeExpression "BLOB") Nothing \info _ -> writeNullRows info
+            )
+            >>= \case
+              Left SQLError{sqlErrorMessage} ->
+                assertBool (show sqlErrorMessage) ("unrecognized coordinate system 'local grid'" `Text.isInfixOf` sqlErrorMessage)
+              Right () -> assertFailure "expected an error at registration"
+          -- A plain GEOMETRY argument reads the value without its CRS.
+          createFunction grid "hs_crs" (\(PlainGeometry raw) -> fromMaybe "no CRS" (rawGeometryCRS raw) :: Text)
+          query grid "SELECT hs_crs(ST_SetCRS(ST_GeomFromWKB(?), 'local grid'))" (Only pointWKB) >>= (@?= [Only ("no CRS" :: Text)])
+    , testCase "a typed aggregate reads a Geometry argument on four threads" $
+        withConnectionWithConfig ":memory:" [("threads", "4")] \conn -> do
+          _ <-
+            execute_ conn "CREATE TABLE shapes AS SELECT i % 100 AS k, ('POINT (' || i || ' ' || (i + 1) || ')')::GEOMETRY AS g FROM range(200000) t(i)"
+          let total = 19999900000 :: Double
+          createAggregate
+            conn
+            "hs_sum_x"
+            Aggregate
+              { aggregateInitial = 0 :: Double
+              , aggregateStep = \sumX (Only g) -> pure (sumX + pointX g)
+              , aggregateCombine = \a b -> pure (a + b)
+              , aggregateResult = pure
+              }
+          createAggregate
+            conn
+            "hs_sum_placed_x"
+            Aggregate
+              { aggregateInitial = 0 :: Double
+              , aggregateStep = \sumX (Only (Placed g)) -> pure (sumX + pointX g)
+              , aggregateCombine = \a b -> pure (a + b)
+              , aggregateResult = pure
+              }
+          calls <- nullCast conn (R.TypeExpression "GEOMETRY") (R.TypeExpression "BLOB")
+          query_ conn "SELECT hs_sum_x(g) FROM shapes" >>= (@?= [Only total])
+          query_ conn "SELECT hs_sum_placed_x({'name': 'p', 'shape': g}) FROM shapes" >>= (@?= [Only total])
+          query_ conn "SELECT count(*), sum(s) FROM (SELECT k, hs_sum_x(g) AS s FROM shapes GROUP BY k)" >>= (@?= [(100 :: Int64, total)])
+          query_ conn "SELECT DISTINCT hs_sum_x(g) OVER () FROM shapes" >>= (@?= [Only total])
+          query_ conn "SELECT hs_sum_x(DISTINCT g) FROM (SELECT g FROM shapes UNION ALL SELECT g FROM shapes)" >>= (@?= [Only total])
+          query_ conn "SELECT hs_sum_x(g) FROM (VALUES (NULL::GEOMETRY), ('POINT (5 6)'::GEOMETRY)) t(g)" >>= (@?= [Only (5 :: Double)])
+          query_ conn "SELECT hs_sum_x('POINT (7 8)'::GEOMETRY('OGC:CRS84'))" >>= (@?= [Only (7 :: Double)])
+          readIORef calls >>= (@?= 0)
+    ]
+
+-- | The x coordinate of a point, or -1 for another shape.
+pointX :: G.Geometry -> Double
+pointX = \case
+  G.PointGeometry (G.PointXY (G.XY x _)) -> x
+  _ -> -1
+
+-- | A STRUCT argument with a GEOMETRY field. A record through ViaDuckDB cannot
+-- hold a Geometry field, because Geometry has no DuckValue instance. Thus the
+-- instances are written here. The reader reads only the field shape.
+newtype Placed = Placed G.Geometry
+
+instance DuckDBColumnType Placed where
+  duckdbColumnTypeFor _ = "STRUCT(name VARCHAR, shape GEOMETRY)"
+
+instance FromField Placed where
+  fromField f = case fieldValue f of
+    FieldStruct struct
+      | Just index <- Map.lookup "shape" (structValueIndex struct) ->
+          Placed <$> fromField f{fieldValue = structFieldValue (structValueFields struct ! index)}
+    _ -> returnError Incompatible f "expected STRUCT(name VARCHAR, shape GEOMETRY)"
+
+-- | An aggregate gets the SQL type of an argument column from this class. The
+-- cases do not write a Placed value.
+instance ToDuckValue Placed where
+  toDuckValue _ _ = throwIO (userError "a Placed value is only an argument")
+
+-- | A GEOMETRY argument that reads the CRS of the value. RawGeometry has no
+-- DuckDBColumnType instance, so the instances are written here.
+newtype PlainGeometry = PlainGeometry RawGeometry
+
+instance DuckDBColumnType PlainGeometry where
+  duckdbColumnTypeFor _ = "GEOMETRY"
+
+instance FromField PlainGeometry where
+  fromField f = PlainGeometry <$> fromField f
+
+-- | Register a cast that writes NULL for each row, and give its call count.
+nullCast :: Connection -> R.TypeDeclaration -> R.TypeDeclaration -> IO (IORef Int)
+nullCast conn source target = do
+  calls <- newIORef 0
+  R.registerCast conn source target Nothing \info _ -> do
+    atomicModifyIORef' calls (\count -> (count + 1, ()))
+    writeNullRows info
+  pure calls
+
+-- | WKB of POINT (1 2).
+pointWKB :: BS.ByteString
+pointWKB = BS.pack [1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 240, 63, 0, 0, 0, 0, 0, 0, 0, 64]
+
+point :: RawGeometry
+point = RawGeometry pointWKB Nothing
+
+shape :: G.Geometry
+shape = G.PointGeometry (G.PointXY (G.XY 1 2))
+
+oneField :: Text -> LogicalTypeRep -> FieldValue -> StructValue FieldValue
+oneField name rep value =
+  StructValue
+    { structValueFields = listArray (0, 0) [StructField name value]
+    , structValueTypes = listArray (0, 0) [StructField name rep]
+    , structValueIndex = Map.singleton name 0
+    }
diff --git a/test/ValueRegressionTests.hs b/test/ValueRegressionTests.hs
--- a/test/ValueRegressionTests.hs
+++ b/test/ValueRegressionTests.hs
@@ -1,363 +1,2771 @@
 {-# LANGUAGE BlockArguments #-}
-{-# LANGUAGE DeriveGeneric #-}
-{-# LANGUAGE DerivingVia #-}
-{-# LANGUAGE NamedFieldPuns #-}
-{-# LANGUAGE OverloadedStrings #-}
-{-# LANGUAGE ScopedTypeVariables #-}
-
--- | Regression tests for exact values and controlled conversion failures.
-module ValueRegressionTests (main, valueRegressionTests) where
-
-import Control.Exception (IOException, bracket, try)
-import Control.Monad (forM_)
-import Data.Array (Array, listArray)
-import qualified Data.ByteString as BS
-import Data.Int (Int32, Int64, Int8)
-import qualified Data.Map.Strict as Map
-import Data.Ratio ((%))
-import Data.String (fromString)
-import Data.Text (Text)
-import Data.Time.Calendar (Day, addDays, fromGregorian)
-import Data.Time.Clock (UTCTime (..))
-import Data.Time.Clock.POSIX (posixSecondsToUTCTime)
-import Data.Time.LocalTime (LocalTime (..), TimeOfDay (..), minutesToTimeZone, utc, utcToLocalTime)
-import Data.Word (Word16, Word32, Word8)
-import Database.DuckDB.FFI
-import Database.DuckDB.Simple
-import Database.DuckDB.Simple.FromField (BitString (..), DecimalValue (..), FieldValue (..), TimeWithZone (..), bsFromBool)
-import Database.DuckDB.Simple.Generic (ViaDuckDB (..), genericFromFieldValue, genericToStructValue)
-import Database.DuckDB.Simple.Internal (destroyValue, withConnectionHandle)
-import Database.DuckDB.Simple.LogicalRep
-import Database.DuckDB.Simple.Time (Unbounded (..))
-import Database.DuckDB.Simple.ToField (ToDuckValue (..))
-import Foreign.C.String (withCString)
-import Foreign.Marshal.Alloc (alloca)
-import Foreign.Ptr (nullPtr)
-import Foreign.Storable (peek, poke)
-import GHC.Generics (Generic)
-import Test.Tasty (TestTree, defaultMain, testGroup)
-import Test.Tasty.HUnit
-import TestUtils (assertFailureIO)
-
--- | Native timestamps used to test the full storage range.
-data NativeTimestamp = Seconds Int64 | Milliseconds Int64 | Microseconds Int64 | Nanoseconds Int64
-    deriving (Show)
-
-instance DuckDBColumnType NativeTimestamp where
-    duckdbColumnTypeFor _ = "TIMESTAMP"
-
-instance ToDuckValue NativeTimestamp where
-    toDuckValue (Seconds value) = c_duckdb_create_timestamp_s (DuckDBTimestampS value)
-    toDuckValue (Milliseconds value) = c_duckdb_create_timestamp_ms (DuckDBTimestampMs value)
-    toDuckValue (Microseconds value) = c_duckdb_create_timestamp (DuckDBTimestamp value)
-    toDuckValue (Nanoseconds value) = c_duckdb_create_timestamp_ns (DuckDBTimestampNs value)
-
-instance ToField NativeTimestamp
-
--- | An array element with a ToField instance and no ToDuckValue instance.
-newtype DelegatedInteger = DelegatedInteger Int64
-
-instance DuckDBColumnType DelegatedInteger where
-    duckdbColumnTypeFor _ = "BIGINT"
-
-instance ToField DelegatedInteger where
-    toField (DelegatedInteger value) = toField value
-
--- | Bind an array through its connection-free value.
-newtype Scores = Scores (Array Int Int64)
-    deriving (Show)
-
-instance DuckDBColumnType Scores where
-    duckdbColumnTypeFor _ = "BIGINT[]"
-
-instance ToDuckValue Scores where
-    toDuckValue (Scores values) = toDuckValue values
-
-instance ToField Scores
-
--- | Record with identical field types to detect positional decoding.
-data NamedRecord = NamedRecord {firstValue :: Int64, secondValue :: Int64}
-    deriving (Eq, Show, Generic)
-
--- | Sum with a payload to test NULL member handling.
-data NullableSum = EmptyMember | DataMember Int64
-    deriving (Eq, Show, Generic)
-
--- | A generic record for array parameters.
-data Pair = Pair {pairName :: Text, pairValue :: Int64}
-    deriving stock (Eq, Show, Generic)
-    deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB Pair)
-
--- | Generic nullary constructors retain their existing UNION schema.
-data Colour = Red | Blue
-    deriving stock (Eq, Show, Generic)
-    deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB Colour)
-
--- | Run this module without the main integration suite.
-main :: IO ()
-main = defaultMain valueRegressionTests
-
--- | Focused value regressions that also run against the baseline library.
-valueRegressionTests :: TestTree
-valueRegressionTests =
-    testGroup "value regressions" $
-        [ testCase "REAL decodes to Float and Double" $ withConnection ":memory:" \conn -> do
-            (query_ conn "SELECT 1.25::REAL" :: IO [Only Float]) >>= (@?= [Only 1.25])
-            (query_ conn "SELECT 1.25::REAL" :: IO [Only Double]) >>= (@?= [Only 1.25])
-        , testCase "Float parameters still decode as Text" $ withConnection ":memory:" \conn ->
-            (query conn "SELECT ?" (Only (1.25 :: Float)) :: IO [Only Text]) >>= (@?= [Only "1.25"])
-        , testCase "generic nullary UNION constructors round trip through DuckDB" $ withConnection ":memory:" \conn ->
-            forM_ [Red, Blue] \colour ->
-                (query conn "SELECT ?" (Only colour) :: IO [Only Colour]) >>= (@?= [Only colour])
-        , testCase "UNION NULL payload retains its member type" $ withConnection ":memory:" \conn -> do
-            let members = listArray (0, 1) [UnionMemberType "number" (LogicalTypeScalar DuckDBTypeBigInt), UnionMemberType "text" (LogicalTypeScalar DuckDBTypeVarchar)]
-                original = UnionValue 0 "number" FieldNull members
-            (query conn "SELECT ?" (Only original) :: IO [Only (UnionValue FieldValue)]) >>= (@?= [Only original])
-        , testCase "array elements need only a ToField instance" $ withConnection ":memory:" \conn -> do
-            let values = listArray (0 :: Int, 2) [Nothing, Just (DelegatedInteger 41), Just (DelegatedInteger 99)]
-                expected = listArray (0, 2) [Nothing, Just 41, Just 99] :: Array Int (Maybe Int64)
-            (query conn "SELECT ?" (Only values) :: IO [Only (Array Int (Maybe Int64))]) >>= (@?= [Only expected])
-        , testCase "array children use default ToDuckValue instances" $ withConnection ":memory:" \conn -> do
-            let units = [-1, 0, 1234567]
-                values = listArray (0 :: Int, 2) (map Microseconds units)
-                expected = listArray (0, 2) (map (utcToLocalTime utc . posixSecondsToUTCTime . fromRational . (% 1000000) . toInteger) units)
-            (query conn "SELECT ?" (Only values) :: IO [Only (Array Int LocalTime)]) >>= (@?= [Only expected])
-        , testCase "arrays bind through ToDuckValue without a connection" $ withConnection ":memory:" \conn -> do
-            let values = listArray (0, 2) [1, -2, 3]
-            (query conn "SELECT typeof(?), ?" (Scores values, Scores values) :: IO [(Text, Array Int Int64)]) >>= (@?= [("BIGINT[3]", values)])
-        , testCase "arrays of STRUCT, record, and ARRAY elements take the type of a present element" $ withConnection ":memory:" \conn -> do
-            [Only struct] <- query_ conn "SELECT {'a': 1, 'b': 'x'}" :: IO [Only (StructValue FieldValue)]
-            let structs = listArray (0, 1) [struct, struct]
-            (query conn "SELECT typeof(?), ?" (structs, structs) :: IO [(Text, Array Int (StructValue FieldValue))]) >>= (@?= [("STRUCT(a INTEGER, b VARCHAR)[2]", structs)])
-            let pairs = listArray (0, 2) [Nothing, Just (Pair "x" 1), Just (Pair "y" 2)]
-            (query conn "SELECT typeof(?), ?" (pairs, pairs) :: IO [(Text, Array Int (Maybe Pair))]) >>= (@?= [("STRUCT(pairName VARCHAR, pairValue BIGINT)[3]", pairs)])
-            let nested = listArray (0, 1) [listArray (0, 1) [1, 2], listArray (0, 1) [3, 4]] :: Array Int (Array Int Int64)
-            (query conn "SELECT typeof(?), ?" (nested, nested) :: IO [(Text, Array Int (Array Int Int64))]) >>= (@?= [("BIGINT[2][2]", nested)])
-        , testCase "empty arrays of record elements have no element type" $ withConnection ":memory:" \conn ->
-            assertFailureIO (query conn "SELECT ?" (Only (listArray (0, -1) [] :: Array Int Pair)) :: IO [Only Text])
-        , testCase "composite arrays reject schemas that would discard fields or digits" $ withConnection ":memory:" \conn -> do
-            forM_
-                [ ("SELECT {'a': 1::INTEGER}", "SELECT {'a': 2::INTEGER, 'b': 3::INTEGER}")
-                , ("SELECT {'a': 1::INTEGER}", "SELECT {'a': 1.6::DOUBLE}")
-                , ("SELECT {'a': 1.2::DECIMAL(4,1)}", "SELECT {'a': 1.26::DECIMAL(4,2)}")
-                , ("SELECT {'a': [1.2::DECIMAL(4,1)]}", "SELECT {'a': [1.26::DECIMAL(4,2)]}")
-                ]
-                \(firstQuery, secondQuery) -> do
-                    [Only first] <- query_ conn firstQuery :: IO [Only (StructValue FieldValue)]
-                    [Only second] <- query_ conn secondQuery :: IO [Only (StructValue FieldValue)]
-                    forM_ [[Nothing, Just first, Just second], [Just second, Nothing, Just first]] \elements -> do
-                        let values = listArray (0 :: Int, 2) elements
-                        assertFailureIO (query conn "SELECT ?" (Only values) :: IO [Only FieldValue])
-                        assertFailureIO (bracket (toDuckValue values) destroyValue (const (pure ())))
-            (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
-        , testCase "GEOMETRY decodes as well-known binary" $ withConnection ":memory:" \conn -> do
-            [Only bytes] <- query_ conn "SELECT 'POINT(1 2)'::GEOMETRY" :: IO [Only BS.ByteString]
-            BS.length bytes @?= 21
-            (query conn "SELECT ST_AsText(ST_GeomFromWKB(?))" (Only bytes) :: IO [Only Text]) >>= (@?= [Only "POINT (1 2)"])
-        , testCase "Float parameter retains FLOAT type" $ withConnection ":memory:" \conn -> do
-            (query conn "SELECT typeof(?), ?" (1.25 :: Float, 1.25 :: Float) :: IO [(Text, Float)]) >>= (@?= [("FLOAT", 1.25)])
-        , testCase "Float special values survive decoding" $ withConnection ":memory:" \conn -> do
-            [Only value] <- query_ conn "SELECT 'NaN'::REAL" :: IO [Only Float]
-            assertBool "expected NaN" (isNaN value)
-            [Only value'] <- query_ conn "SELECT 'Infinity'::REAL" :: IO [Only Double]
-            assertBool "expected positive infinity" (isInfinite value' && value' > 0)
-        , testCase "finite Double overflow to Float fails" $ withConnection ":memory:" \conn ->
-            assertConversionError (query_ conn "SELECT 1e300::DOUBLE" :: IO [Only Float])
-        , testCase "embedded NUL and Unicode Text round trip" $ withConnection ":memory:" \conn -> do
-            let value = "before\0after íslenska λ 😀" :: Text
-            (query conn "SELECT ?" (Only value) :: IO [Only Text]) >>= (@?= [Only value])
-        , testCase "Int8 rejects both overflow directions" $ withConnection ":memory:" \conn -> do
-            forM_ ["SELECT 128::BIGINT", "SELECT -129::SMALLINT"] \sql ->
-                assertConversionError (query_ conn sql :: IO [Only Int8])
-            (query_ conn "SELECT -128::BIGINT UNION ALL SELECT 127" :: IO [Only Int8]) >>= (@?= [Only (-128), Only 127])
-        , testCase "unsigned narrowing rejects overflow" $ withConnection ":memory:" \conn -> do
-            assertConversionError (query_ conn "SELECT 256::USMALLINT" :: IO [Only Word8])
-            assertConversionError (query_ conn "SELECT 65536::UINTEGER" :: IO [Only Word16])
-            assertConversionError (query_ conn "SELECT 4294967296::UBIGINT" :: IO [Only Word32])
-        , testCase "finite timestamp extrema preserve all units" $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
-            forM_ [(Seconds, 1, "TIMESTAMP_S"), (Milliseconds, 1000, "TIMESTAMP_MS"), (Microseconds, 1000000, "TIMESTAMP"), (Nanoseconds, 1000000000, "TIMESTAMP_NS")] \(constructor, units, dtype) ->
-                forM_ [minBound, negate (maxBound :: Int64) + 1, -1, 0, maxBound - 1] \value -> do
-                    let expected = utcToLocalTime utc (posixSecondsToUTCTime (fromRational (toInteger value % units)))
-                    appendTimestamp conn dtype (toDuckValue (constructor value))
-                    (query_ conn "SELECT value FROM native_timestamp" :: IO [Only LocalTime]) >>= (@?= [Only expected])
-                    [Only original] <- query_ conn "SELECT {'value': value} FROM native_timestamp" :: IO [Only (StructValue FieldValue)]
-                    -- DuckDB needs an explicit parameter type for extreme S/MS values.
-                    query conn (fromString ("SELECT ?::STRUCT(value " <> dtype <> ")")) (Only original) >>= (@?= [Only original])
-                    _ <- execute_ conn "DROP TABLE native_timestamp"
-                    pure ()
-        , testCase "composite timestamps reject infinity and storage overflow" $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
-            forM_ [(DuckDBTypeTimestampS, 1), (DuckDBTypeTimestampMs, 1000), (DuckDBTypeTimestamp, 1000000), (DuckDBTypeTimestampNs, 1000000000)] \(dtype, units) ->
-                forM_ [toInteger (minBound :: Int64) - 1, negate (toInteger (maxBound :: Int64)), toInteger (maxBound :: Int64), toInteger (maxBound :: Int64) + 1] \value -> do
-                    let timestamp = utcToLocalTime utc (posixSecondsToUTCTime (fromRational (value % units)))
-                        struct = singleField (LogicalTypeScalar dtype) (FieldTimestamp (Finite timestamp))
-                    assertIOError (query conn "SELECT ?" (Only struct) :: IO [Only FieldValue])
-        , testCase "composite timestamps floor fractional units before the epoch" $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
-            forM_ [(DuckDBTypeTimestampS, 1), (DuckDBTypeTimestampMs, 1000), (DuckDBTypeTimestamp, 1000000), (DuckDBTypeTimestampNs, 1000000000)] \(dtype, units) -> do
-                let timestamp = utcToLocalTime utc (posixSecondsToUTCTime (fromRational ((-1) % (2 * units))))
-                    expected = utcToLocalTime utc (posixSecondsToUTCTime (fromRational ((-1) % units)))
-                    struct = singleField (LogicalTypeScalar dtype) (FieldTimestamp (Finite timestamp))
-                (query conn "SELECT (?).value" (Only struct) :: IO [Only LocalTime]) >>= (@?= [Only expected])
-        , testCase "composite TIME_NS rejects invalid clock components" $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
-            forM_ [TimeOfDay (-1) 0 0, TimeOfDay 25 0 0, TimeOfDay 0 60 0, TimeOfDay 0 0 (-1), TimeOfDay 24 0 0.000000001, TimeOfDay 23 59 60.000000001] \value ->
-                assertIOError (query conn "SELECT ?" (Only (singleField (LogicalTypeScalar DuckDBTypeTimeNs) (FieldTime value))) :: IO [Only FieldValue])
-        , testCase "microsecond timestamps retain finite extrema" $ withConnection ":memory:" \conn ->
-            forM_ [minBound, negate (maxBound :: Int64) + 1, -1, 0, maxBound - 1] \value -> do
-                let expected = utcToLocalTime utc (posixSecondsToUTCTime (fromRational (toInteger value % 1000000)))
-                _ <- execute_ conn "CREATE TABLE microsecond_timestamp(value TIMESTAMP)"
-                _ <- execute conn "INSERT INTO microsecond_timestamp VALUES (?)" (Only expected)
-                (query_ conn "SELECT value FROM microsecond_timestamp" :: IO [Only LocalTime]) >>= (@?= [Only expected])
-                _ <- execute_ conn "DROP TABLE microsecond_timestamp"
-                pure ()
-        , testCase "out-of-range dates and timestamps fail without abort" $ withConnection ":memory:" \conn -> do
-            let hugeDay = fromGregorian 10000000 1 1
-                local = LocalTime hugeDay (TimeOfDay 0 0 0)
-            assertIOError (query conn "SELECT ?" (Only hugeDay) :: IO [Only Day])
-            assertIOError (query conn "SELECT ?" (Only local) :: IO [Only LocalTime])
-            assertIOError (query conn "SELECT ?" (Only (UTCTime hugeDay 0)) :: IO [Only UTCTime])
-        , testCase "date finite storage extrema round trip" $ withConnection ":memory:" \conn ->
-            forM_ [minBound, negate (maxBound :: Int32) + 1, -1, 0, maxBound - 1] \value -> do
-                let day = addDays (toInteger value) (fromGregorian 1970 1 1)
-                (query conn "SELECT ?" (Only day) :: IO [Only Day]) >>= (@?= [Only day])
-        , testCase "input infinity sentinels are rejected" $ withConnection ":memory:" \conn -> do
-            forM_ [toInteger (maxBound :: Int32), negate (toInteger (maxBound :: Int32))] \days ->
-                assertIOError (query conn "SELECT ?" (Only (addDays days (fromGregorian 1970 1 1))) :: IO [Only Day])
-            forM_ [toInteger (maxBound :: Int64), negate (toInteger (maxBound :: Int64))] \micros -> do
-                let value = utcToLocalTime utc (posixSecondsToUTCTime (fromRational (micros % 1000000)))
-                assertIOError (query conn "SELECT ?" (Only value) :: IO [Only LocalTime])
-        , testCase "UTC binding is TIMESTAMPTZ under a non-UTC zone" $ withConnection ":memory:" \conn -> do
-            _ <- execute_ conn "SET TimeZone = 'Pacific/Auckland'"
-            let value = UTCTime (fromGregorian 2000 1 2) 12345
-            (query conn "SELECT typeof(?), ?" (value, value) :: IO [(Text, UTCTime)]) >>= (@?= [("TIMESTAMP WITH TIME ZONE", value)])
-            _ <- execute_ conn "CREATE TABLE utc_binding(value TIMESTAMPTZ)"
-            _ <- execute conn "INSERT INTO utc_binding VALUES (?)" (Only value)
-            (query_ conn "SELECT value FROM utc_binding" :: IO [Only UTCTime]) >>= (@?= [Only value])
-        , testCase "DECIMAL(38) retains exact integer precision" $ withConnection ":memory:" \conn -> do
-            let decimal = DecimalValue 38 9 12345678901234567890123456789012345678
-                struct = singleField (LogicalTypeDecimal 38 9) (FieldDecimal decimal)
-            [Only result] <- query conn "SELECT ?" (Only struct) :: IO [Only (StructValue FieldValue)]
-            structValueFields result @?= structValueFields struct
-        , testCase "invalid DECIMAL width scale and magnitude are rejected" $ withConnection ":memory:" \conn ->
-            forM_ [DecimalValue 0 0 0, DecimalValue 39 0 0, DecimalValue 2 3 1, DecimalValue 2 0 100, DecimalValue 2 0 (-100)] \decimal ->
-                assertIOError (query conn "SELECT ?" (Only (singleField (LogicalTypeDecimal (decimalWidth decimal) (decimalScale decimal)) (FieldDecimal decimal))) :: IO [Only FieldValue])
-        , testCase "nested conversion failure leaves the connection usable" $ withConnection ":memory:" \conn -> do
-            let days = listArray (0, 1) [fromGregorian 2000 1 1, fromGregorian 10000000 1 1] :: Array Int Day
-            assertIOError (query conn "SELECT ?" (Only days) :: IO [Only FieldValue])
-            (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
-        , testCase "generic NULL product and payload return Left" $ do
-            assertLeft (genericFromFieldValue FieldNull :: Either String NamedRecord)
-            let member = UnionMemberType "DataMember" (LogicalTypeScalar DuckDBTypeBigInt)
-                union = UnionValue 0 "DataMember" FieldNull (listArray (0, 0) [member])
-            assertLeft (genericFromFieldValue (FieldUnion union) :: Either String NullableSum)
-        , testCase "generic records decode by name" $ withConnection ":memory:" \conn -> do
-            [Only struct] <- query_ conn "SELECT {'secondValue': 2::BIGINT, 'firstValue': 1::BIGINT}" :: IO [Only (StructValue FieldValue)]
-            genericFromFieldValue (FieldStruct struct) @?= Right (NamedRecord 1 2)
-        , testCase "generic sums decode by member name" $ withConnection ":memory:" \conn -> do
-            [Only union] <- query_ conn "SELECT union_value(DataMember := {'field1': 42::BIGINT})" :: IO [Only (UnionValue FieldValue)]
-            genericFromFieldValue (FieldUnion union) @?= Right (DataMember 42)
-        , testCase "union binding rejects inconsistent member name" $ withConnection ":memory:" \conn -> do
-            let member = UnionMemberType "right" (LogicalTypeScalar DuckDBTypeBigInt)
-                union = UnionValue 0 "wrong" (FieldInt64 42) (listArray (0, 0) [member])
-            assertIOError (query conn "SELECT ?" (Only union) :: IO [Only FieldValue])
-        , testCase "generic records reject wrong names" $ do
-            case genericToStructValue (NamedRecord 1 2) of
-                Nothing -> assertFailure "missing generic struct"
-                Just struct -> do
-                    let fields = listArray (0, 1) [StructField "wrong" (FieldInt64 1), StructField "secondValue" (FieldInt64 2)]
-                    assertLeft (genericFromFieldValue (FieldStruct struct{structValueFields = fields}) :: Either String NamedRecord)
-        , testCase "logical type Unicode names round trip" $ do
-            let logical = LogicalTypeStruct (listArray (0, 0) [StructField "íslenska_λ_😀" (LogicalTypeScalar DuckDBTypeBigInt)])
-            bracket (logicalTypeFromRep logical) destroyLogicalType \handle ->
-                logicalTypeToRep handle >>= (@?= logical)
-        , testCase "logical type names reject embedded NUL" $ do
-            let logical = LogicalTypeStruct (listArray (0, 0) [StructField "before\0after" (LogicalTypeScalar DuckDBTypeBigInt)])
-            assertIOError (bracket (logicalTypeFromRep logical) destroyLogicalType (const (pure ())))
-        , testCase "invalid native composite constructor returns controlled error" $ withConnection ":memory:" \conn -> do
-            let struct = singleField (LogicalTypeMap (LogicalTypeScalar DuckDBTypeBigInt) (LogicalTypeScalar DuckDBTypeBigInt)) (FieldMap [(FieldNull, FieldInt64 1)])
-            assertIOError (query conn "SELECT ?" (Only struct) :: IO [Only FieldValue])
-        , testCase "BIT padding preserves SQL bit_count" $ withConnection ":memory:" \conn -> do
-            let bits = bsFromBool [True, False, True]
-            (query conn "SELECT bit_count(?), ?" (bits, bits) :: IO [(Int64, BitString)]) >>= (@?= [(2, bits)])
-        , testCase "unsupported BIT input fails before native use" $ withConnection ":memory:" \conn ->
-            forM_ [BitString 0 BS.empty, BitString 8 (BS.singleton 1)] \bits ->
-                assertIOError (query conn "SELECT ?" (Only bits) :: IO [Only BitString])
-        , testCase "TIMETZ second offsets fail without rounding" $ withConnection ":memory:" \conn ->
-            assertIOError (query_ conn "SELECT '12:00:00+01:23:45'::TIMETZ" :: IO [Only TimeWithZone])
-        , testCase "ENUM payload index must be in its dictionary" $ withConnection ":memory:" \conn ->
-            assertIOError (query conn "SELECT ?" (Only (singleField (LogicalTypeEnum (listArray (0, 1) ["a", "b"])) (FieldEnum 2))) :: IO [Only FieldValue])
-        , testCase "TIMETZ input offset overflow fails before native use" $ withConnection ":memory:" \conn -> do
-            let value = TimeWithZone (TimeOfDay 12 0 0) (minutesToTimeZone maxBound)
-                struct = singleField (LogicalTypeScalar DuckDBTypeTimeTz) (FieldTimeTZ value)
-            assertIOError (query conn "SELECT ?" (Only struct) :: IO [Only FieldValue])
-        , testCase "invalid TIME input returns controlled error" $ withConnection ":memory:" \conn ->
-            assertIOError (query conn "SELECT ?" (Only (TimeOfDay 1000000000 0 0)) :: IO [Only TimeOfDay])
-        ]
-            <> [ testCase ("composite temporal round trip: " <> dtype) $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
-                    forM_ ("NULL" : map (\value -> "'" <> value <> "'") values) \value ->
-                        assertTemporalRoundTrip conn dtype (value <> "::" <> dtype)
-               | (dtype, values) <-
-                    [(dtype, ["-infinity", "infinity", "1969-12-31 23:59:59.123456789", "2000-01-01 12:34:56.123456789"]) | dtype <- ["TIMESTAMP", "TIMESTAMP_S", "TIMESTAMP_MS", "TIMESTAMP_NS", "TIMESTAMPTZ"]]
-                        <> [("DATE", ["-infinity", "infinity", "1969-12-31", "2000-01-01"])]
-                        <> [("TIME_NS", ["00:00:00", "12:34:56.123456789", "23:59:59.999999999", "24:00:00"])]
-               ]
-            <> [ testCase (dtype <> " " <> value <> " rejects a finite result type") $ withConnection ":memory:" \conn ->
-                    assertConversionError (query_ conn (fromString ("SELECT '" <> value <> "'::" <> dtype)) :: IO [Only LocalTime])
-               | dtype <- ["DATE", "TIMESTAMP", "TIMESTAMP_S", "TIMESTAMP_MS", "TIMESTAMP_NS", "TIMESTAMPTZ"]
-               , value <- ["infinity", "-infinity"]
-               ]
-
--- | Rebind native temporal values in structs, unions, and nested collections.
-assertTemporalRoundTrip :: Connection -> String -> String -> Assertion
-assertTemporalRoundTrip conn dtype expression = do
-    let sql =
-            "WITH temporal AS (SELECT "
-                <> expression
-                <> " AS value) "
-                <> "SELECT {'scalar': value, 'list': [value, NULL], 'array': [value, NULL]::"
-                <> dtype
-                <> "[2], 'map': map([1], [value])}, union_value(value := value) FROM temporal"
-    [original] <- query_ conn (fromString sql) :: IO [(StructValue FieldValue, UnionValue FieldValue)]
-    query conn "SELECT ?, ?" original >>= (@?= [original])
-
--- | Store raw timestamp units without the prepared-parameter type conversion.
-appendTimestamp :: Connection -> String -> IO DuckDBValue -> IO ()
-appendTimestamp conn dtype createValue = do
-    _ <- execute_ conn (fromString ("CREATE TABLE native_timestamp(value " <> dtype <> ")"))
-    withConnectionHandle conn \handle ->
-        alloca \appenderPtr -> do
-            poke appenderPtr nullPtr
-            withCString "native_timestamp" \table ->
-                c_duckdb_appender_create handle nullPtr table appenderPtr >>= (@?= DuckDBSuccess)
-            bracket (peek appenderPtr) (const (c_duckdb_appender_destroy appenderPtr >> pure ())) \appender -> do
-                bracket createValue (\value -> alloca \ptr -> poke ptr value >> c_duckdb_destroy_value ptr) \value ->
-                    c_duckdb_append_value appender value >>= (@?= DuckDBSuccess)
-                c_duckdb_appender_end_row appender >>= (@?= DuckDBSuccess)
-                c_duckdb_appender_flush appender >>= (@?= DuckDBSuccess)
-
--- | Build a single-field struct for nested binding tests.
-singleField :: LogicalTypeRep -> FieldValue -> StructValue FieldValue
-singleField logical value =
-    StructValue
-        (listArray (0, 0) [StructField "value" value])
-        (listArray (0, 0) [StructField "value" logical])
-        (Map.singleton "value" 0)
-
--- | Assert a controlled input or materialization error.
-assertIOError :: IO a -> Assertion
-assertIOError action = do
-    result <- try action
-    case result of
-        Left (_ :: IOException) -> pure ()
-        Right _ -> assertFailure "expected IOException"
-
--- | Assert a controlled FromField conversion error.
-assertConversionError :: IO a -> Assertion
-assertConversionError action = do
-    result <- try action
-    case result of
-        Left (_ :: SQLError) -> pure ()
-        Right _ -> assertFailure "expected ResultError"
-
--- | Assert rejection without forcing a partial generic value.
-assertLeft :: Either String a -> Assertion
-assertLeft (Left _) = pure ()
-assertLeft (Right _) = assertFailure "expected Left"
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE DeriveGeneric #-}
+{-# LANGUAGE DerivingVia #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE NamedFieldPuns #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications #-}
+
+-- |
+-- Module      : ValueRegressionTests
+-- Description : Regression tests for exact values and controlled conversion failures.
+module ValueRegressionTests (main, valueRegressionTests) where
+
+import Control.Applicative ((<|>))
+import Control.Concurrent (forkIO, killThread, newEmptyMVar, putMVar, readMVar, takeMVar, threadDelay)
+import Control.Exception (
+  AsyncException (ThreadKilled),
+  ErrorCall,
+  MaskingState (..),
+  SomeException,
+  bracket,
+  displayException,
+  fromException,
+  getMaskingState,
+  mask,
+  mask_,
+  throwIO,
+  try,
+  uninterruptibleMask_,
+ )
+import Control.Monad (forM, forM_, replicateM, void, when)
+import Data.Array (elems, listArray)
+import Data.Bits (shiftR, xor)
+import qualified Data.ByteString as BS
+import Data.IORef (atomicModifyIORef', newIORef, readIORef)
+import Data.Int (Int16, Int32, Int64, Int8)
+import qualified Data.Map.Strict as Map
+import Data.Maybe (fromMaybe, isJust)
+import Data.Proxy (Proxy (..), asProxyTypeOf)
+import Data.Ratio ((%))
+import Data.String (fromString)
+import Data.Text (Text)
+import qualified Data.Text as Text
+import qualified Data.Text.Encoding as TextEncoding
+import Data.Time.Calendar (Day, addDays, diffDays, fromGregorian)
+import Data.Time.Clock (UTCTime (..))
+import Data.Time.Clock.POSIX (posixSecondsToUTCTime)
+import Data.Time.LocalTime (LocalTime (..), TimeOfDay (..), hoursToTimeZone, minutesToTimeZone, utc, utcToLocalTime)
+import qualified Data.UUID as UUID
+import Data.Word (Word16, Word32, Word64, Word8)
+import Database.DuckDB.FFI.V2 (
+  DuckDBV2LogicalTypeHandle,
+  c_duckdb_v2_factory_create_common_type,
+  c_duckdb_v2_factory_create_type_from_text,
+  c_duckdb_v2_logical_type_is_equal,
+  c_duckdb_v2_logical_type_to_text,
+  c_duckdb_v2_value_cast,
+  c_duckdb_v2_value_create_null,
+  c_duckdb_v2_vector_set_size,
+  c_duckdb_v2_vector_set_value,
+ )
+import Database.DuckDB.Simple
+import qualified Database.DuckDB.Simple.Catalog as Catalog
+import Database.DuckDB.Simple.Conversion (conversionErrorWith)
+import Database.DuckDB.Simple.FromField (
+  BigNum (..),
+  BitString (..),
+  DecimalValue (..),
+  Field (..),
+  FieldValue (..),
+  IntervalValue (..),
+  TimeWithZone (..),
+  bsFromBool,
+  returnError,
+  timeWithZone,
+  timeWithZoneZone,
+ )
+import Database.DuckDB.Simple.Generic (DuckValue (..), ViaDuckDB (..), genericFromFieldValue, genericToStructValue, typedFromField)
+import Database.DuckDB.Simple.Internal (destroyValue, withConnectionFactory, withConnectionHandle, withOwnedVector)
+import Database.DuckDB.Simple.LogicalRep
+import Database.DuckDB.Simple.Ok (Ok (..))
+import qualified Database.DuckDB.Simple.Streaming as Streaming
+import Database.DuckDB.Simple.Time (Unbounded (..))
+import Database.DuckDB.Simple.ToField (ToDuckValue (..))
+import Database.DuckDB.Simple.V2.LogicalRep (
+  destroyLogicalType,
+  logicalTypeFromRep,
+  logicalTypeToBaseRep,
+  logicalTypeToRep,
+ )
+import qualified Database.DuckDB.Simple.V2.Registration as R
+import Database.DuckDB.Simple.Variant (Variant (..))
+import Foreign.C.ConstPtr (ConstPtr (..))
+import Foreign.Marshal.Alloc (alloca, allocaBytes)
+import Foreign.Marshal.Array (withArray)
+import Foreign.Ptr (castPtr, nullPtr)
+import Foreign.Storable (peek)
+import GHC.Float (castDoubleToWord64, castFloatToWord32)
+import GHC.Generics (Generic)
+import Numeric.Natural (Natural)
+import System.Mem (getAllocationCounter, performMajorGC)
+import System.Timeout (timeout)
+import Test.Tasty (TestTree, defaultMain, testGroup)
+import Test.Tasty.HUnit
+import TestUtils (NativeTimestamp (..), assertInputError, assertRangeError, sized)
+
+-- | The type requested by a field parser.
+data FieldTypeOf = FieldTypeOf LogicalTypeRep
+  deriving (Eq, Show)
+
+instance FromField FieldTypeOf where
+  fromField Field{fieldType} = FieldTypeOf <$> fieldType
+
+-- | An Int64, or else a Text. A read of an ENUM value fails as Int64, and no
+-- one renders that error.
+newtype IntOrText = IntOrText (Either Int64 Text)
+  deriving (Eq, Show)
+
+instance FromField IntOrText where
+  fromField f = IntOrText <$> ((Left <$> fromField f) <|> (Right <$> fromField f))
+
+-- | The text of a native type, from duckdb_v2_logical_type_to_text.
+nativeTypeText :: DuckDBV2LogicalTypeHandle -> IO Text
+nativeTypeText logical = alloca \lengthSlot -> do
+  R.checked (c_duckdb_v2_logical_type_to_text logical nullPtr 0 lengthSlot)
+  size <- peek lengthSlot
+  allocaBytes (fromIntegral size + 1) \buffer -> do
+    R.checked (c_duckdb_v2_logical_type_to_text logical buffer (size + 1) lengthSlot)
+    TextEncoding.decodeUtf8 <$> BS.packCStringLen (castPtr buffer, fromIntegral size)
+
+-- | A value whose read checks the column type, as a user instance can: a
+-- DECIMAL with the scale 2, a TIMESTAMP_NS, an ARRAY of three elements, or
+-- JSON. The value names the accepted kind.
+newtype Checked = Checked Text
+  deriving (Eq, Ord, Show)
+
+instance FromField Checked where
+  fromField f@Field{fieldType} = do
+    logical <- fieldType
+    case logical of
+      LogicalTypeDecimal _ 2 -> pure (Checked "decimal")
+      LogicalTypeScalar LogicalTypeIdTimestampNs -> pure (Checked "timestamp_ns")
+      LogicalTypeArray _ 3 -> pure (Checked "array")
+      LogicalTypeAlias "JSON" _ -> pure (Checked "json")
+      _ -> returnError Incompatible f "expected DECIMAL(_,2), TIMESTAMP_NS, an ARRAY of 3 elements, or JSON"
+
+-- | A record field reads with its type through 'typedFromField'.
+instance DuckValue Checked where
+  duckToField (Checked text) = FieldText text
+  duckLogicalType _ = LogicalTypeScalar LogicalTypeIdVarchar
+  duckFromTypedField = typedFromField
+
+-- | A record with a field that checks its type.
+newtype Priced = Priced {price :: Checked}
+  deriving (Eq, Show, Generic)
+  deriving (FromField) via (ViaDuckDB Priced)
+
+-- | An array element with a ToField instance and no ToDuckValue instance.
+newtype DelegatedInteger = DelegatedInteger Int64
+
+instance DuckDBColumnType DelegatedInteger where
+  duckdbColumnTypeFor _ = "BIGINT"
+
+instance ToField DelegatedInteger where
+  toField (DelegatedInteger value) = toField value
+
+-- | Bind an array through a value built with the explicit factory.
+newtype Scores = Scores (SizedArray 3 Int64)
+  deriving (Show)
+
+instance DuckDBColumnType Scores where
+  duckdbColumnTypeFor _ = "BIGINT[]"
+
+instance ToDuckValue Scores where
+  toDuckValue factory (Scores values) = toDuckValue factory values
+
+instance ToField Scores
+
+-- | Bind declared child types without adapting them to a parameter target.
+data UnadaptedStruct
+  = UnadaptedStruct (StructValue FieldValue)
+  | TypedStructNull LogicalTypeRep
+  deriving (Show)
+
+instance DuckDBColumnType UnadaptedStruct where
+  duckdbColumnTypeFor _ = "STRUCT"
+  duckdbTypeDeclaration _ = Left "the fields depend on the value"
+
+instance ToDuckValue UnadaptedStruct where
+  toDuckValue factory (UnadaptedStruct value) = toDuckValue factory value
+  toDuckValue factory (TypedStructNull rep) =
+    bracket (logicalTypeFromRep factory rep) destroyLogicalType \logical ->
+      R.output (c_duckdb_v2_value_create_null factory logical)
+
+instance ToField UnadaptedStruct
+
+-- | Record with identical field types to detect positional decoding.
+data NamedRecord = NamedRecord {firstValue :: Int64, secondValue :: Int64}
+  deriving (Eq, Show, Generic)
+
+-- | Sum with a payload to test NULL member handling.
+data NullableSum = EmptyMember | DataMember Int64
+  deriving (Eq, Show, Generic)
+
+-- | A generic record with a UTCTime field.
+newtype Stamped = Stamped {stampedAt :: UTCTime}
+  deriving stock (Eq, Show, Generic)
+  deriving (FromField) via (ViaDuckDB Stamped)
+
+-- | A generic record with a LIST, an ARRAY, and a MAP field.
+data Holder = Holder {listField :: [Int32], arrayField :: SizedArray 2 Int32, mapField :: Map.Map Text Int32}
+  deriving stock (Eq, Show, Generic)
+  deriving (FromField) via (ViaDuckDB Holder)
+
+-- | A generic record for array parameters.
+data Pair = Pair {pairName :: Text, pairValue :: Int64}
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB Pair)
+
+-- | A generic record with an ARRAY field.
+data Scored = Scored {scoredName :: Text, scoredValues :: SizedArray 3 Int32}
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB Scored)
+
+-- | Generic nullary constructors retain their existing UNION schema.
+data Colour = Red | Blue
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB Colour)
+
+-- | Run this module without the main integration suite.
+main :: IO ()
+main = defaultMain valueRegressionTests
+
+-- | Focused value regressions that also run against the baseline library.
+valueRegressionTests :: TestTree
+valueRegressionTests =
+  testGroup "value regressions" $
+    [ testCase "REAL decodes to Float and Double" $ withConnection ":memory:" \conn -> do
+        (query_ conn "SELECT 1.25::REAL" :: IO [Only Float]) >>= (@?= [Only 1.25])
+        (query_ conn "SELECT 1.25::REAL" :: IO [Only Double]) >>= (@?= [Only 1.25])
+    , testCase "a Float parameter does not read as Text, and its cast to VARCHAR does" $ withConnection ":memory:" \conn -> do
+        assertIncompatible conn "?::FLOAT" (Only (1.25 :: Float)) "FLOAT" (Proxy @Text) "Text"
+        (query conn "SELECT ?::VARCHAR" (Only (1.25 :: Float)) :: IO [Only Text]) >>= (@?= [Only "1.25"])
+    , testCase "BOOLEAN read as Text and String gives the cast to VARCHAR" $ withConnection ":memory:" \conn ->
+        (query_ conn "SELECT b, b::VARCHAR, b FROM (VALUES (true), (false)) t(b)" :: IO [(Text, Text, String)])
+          >>= (@?= [("true", "true", "true"), ("false", "false", "false")])
+    , testCase "generic nullary UNION constructors round trip through DuckDB" $ withConnection ":memory:" \conn ->
+        forM_ [Red, Blue] \colour ->
+          (query conn "SELECT ?" (Only colour) :: IO [Only Colour]) >>= (@?= [Only colour])
+    , testCase "UNION NULL payload retains its member type" $ withConnection ":memory:" \conn -> do
+        let members =
+              listArray
+                (0, 1)
+                [UnionMemberType "number" (LogicalTypeScalar LogicalTypeIdBigInt), UnionMemberType "text" (LogicalTypeScalar LogicalTypeIdVarchar)]
+            original = UnionValue 0 "number" FieldNull members
+        (query conn "SELECT ?" (Only original) :: IO [Only (UnionValue FieldValue)]) >>= (@?= [Only original])
+    , testCase "a UNION value binds the member of its tag up to the member limit of DuckDB" $ withConnection ":memory:" \conn -> do
+        let lastMember :: Int -> UnionValue FieldValue
+            lastMember count =
+              let name index = "m" <> Text.pack (show index)
+                  members = listArray (0, count - 1) [UnionMemberType (name index) (LogicalTypeScalar LogicalTypeIdInteger) | index <- [0 .. count - 1]]
+              in  UnionValue (fromIntegral (count - 1)) (name (count - 1)) (FieldInt32 7) members
+            accepted = lastMember 255
+        (query conn "SELECT union_tag(?)::VARCHAR, ?" (accepted, accepted) :: IO [(Text, UnionValue FieldValue)]) >>= (@?= [("m254", accepted)])
+        -- DuckDB 2.0.0 permits at most 255 members in a UNION type.
+        forM_ [256, 300] \count ->
+          try (query conn "SELECT ?" (Only (lastMember count)) :: IO [Only (UnionValue FieldValue)]) >>= \case
+            Left SQLError{sqlErrorMessage, sqlErrorType} -> do
+              sqlErrorMessage @?= "Binder Error: UNION type supports at most 255 type modifiers"
+              sqlErrorType @?= Just ErrorQueryBinder
+            Right rows -> assertFailure (show count <> " members: expected the DuckDB member limit error, got " <> show rows)
+    , testCase "array elements need only a ToField instance" $ withConnection ":memory:" \conn -> do
+        let values = sized [Nothing, Just (DelegatedInteger 41), Just (DelegatedInteger 99)] :: SizedArray 3 (Maybe DelegatedInteger)
+            expected = sized [Nothing, Just 41, Just 99] :: SizedArray 3 (Maybe Int64)
+        (query conn "SELECT ?" (Only values) :: IO [Only (SizedArray 3 (Maybe Int64))]) >>= (@?= [Only expected])
+    , testCase "array children use default ToDuckValue instances" $ withConnection ":memory:" \conn -> do
+        let units = [-1, 0, 1234567]
+            values = sized (map Microseconds units) :: SizedArray 3 NativeTimestamp
+            expected = sized (map (utcToLocalTime utc . posixSecondsToUTCTime . fromRational . (% 1000000) . toInteger) units)
+        (query conn "SELECT ?" (Only values) :: IO [Only (SizedArray 3 LocalTime)]) >>= (@?= [Only expected])
+    , testCase "arrays bind through ToDuckValue with an explicit connection" $ withConnection ":memory:" \conn -> do
+        let values = sized [1, -2, 3]
+        (query conn "SELECT typeof(?), ?" (Scores values, Scores values) :: IO [(Text, SizedArray 3 Int64)]) >>= (@?= [("BIGINT[3]", values)])
+    , testCase "arrays of STRUCT, record, and ARRAY elements take the type of a present element" $ withConnection ":memory:" \conn -> do
+        [Only struct] <- query_ conn "SELECT {'a': 1, 'b': 'x'}" :: IO [Only (StructValue FieldValue)]
+        let structs = sized [struct, struct]
+        (query conn "SELECT typeof(?), ?" (structs, structs) :: IO [(Text, SizedArray 2 (StructValue FieldValue))])
+          >>= (@?= [("STRUCT(a INTEGER, b VARCHAR)[2]", structs)])
+        let pairs = sized [Nothing, Just (Pair "x" 1), Just (Pair "y" 2)]
+        (query conn "SELECT typeof(?), ?" (pairs, pairs) :: IO [(Text, SizedArray 3 (Maybe Pair))])
+          >>= (@?= [("STRUCT(pairName VARCHAR, pairValue BIGINT)[3]", pairs)])
+        let nested = sized [sized [1, 2], sized [3, 4]] :: SizedArray 2 (SizedArray 2 Int64)
+        (query conn "SELECT typeof(?), ?" (nested, nested) :: IO [(Text, SizedArray 2 (SizedArray 2 Int64))]) >>= (@?= [("BIGINT[2][2]", nested)])
+    , testCase "generic records with ARRAY fields bind with the size of the type" $ withConnection ":memory:" \conn -> do
+        let first = Scored "x" (sized [1, 2, 3])
+            second = Scored "y" (sized [4, 5, 6])
+            rowType = "STRUCT(scoredName VARCHAR, scoredValues INTEGER[3])"
+        (query conn "SELECT typeof(?), ?" (first, first) :: IO [(Text, Scored)]) >>= (@?= [(rowType, first)])
+        _ <- execute_ conn "CREATE TABLE scored (s STRUCT(scoredName VARCHAR, scoredValues INTEGER[3]))"
+        _ <- executeMany conn "INSERT INTO scored VALUES (?)" [Only first, Only second]
+        (query_ conn "SELECT s FROM scored ORDER BY s.scoredName" :: IO [Only Scored]) >>= (@?= [Only first, Only second])
+        let records = sized [first, second] :: SizedArray 2 Scored
+        (query conn "SELECT typeof(?), ?" (records, records) :: IO [(Text, SizedArray 2 Scored)]) >>= (@?= [(rowType <> "[2]", records)])
+    , testCase "empty arrays of record elements raise the empty ARRAY error" $ withConnection ":memory:" \conn -> do
+        result <- try (query conn "SELECT ?" (Only (sized [] :: SizedArray 0 Pair)))
+        case result of
+          Left SQLError{sqlErrorMessage, sqlErrorType} -> do
+            assertBool (Text.unpack sqlErrorMessage) ("duckdb-simple: an empty ARRAY parameter is not possible" `Text.isInfixOf` sqlErrorMessage)
+            sqlErrorType @?= Just ErrorInputInvalid
+          Right (_ :: [Only Text]) -> assertFailure "expected the empty ARRAY error"
+    , testCase "composite arrays with different element types take the type of array_value" $ withConnection ":memory:" \conn -> do
+        forM_
+          [ ("{'a': 1::INTEGER}", "{'a': 2::INTEGER, 'b': 3::INTEGER}", "STRUCT(a INTEGER, b INTEGER)[3]")
+          , ("{'a': 1::INTEGER}", "{'a': 1.6::DOUBLE}", "STRUCT(a DOUBLE)[3]")
+          , ("{'a': 1.2::DECIMAL(4,1)}", "{'a': 1.26::DECIMAL(4,2)}", "STRUCT(a DECIMAL(5,2))[3]")
+          , ("{'a': [1.2::DECIMAL(4,1)]}", "{'a': [1.26::DECIMAL(4,2)]}", "STRUCT(a DECIMAL(5,2)[])[3]")
+          ]
+          \(firstSql, secondSql, typeName) -> do
+            [Only first] <- query_ conn (Query ("SELECT " <> firstSql)) :: IO [Only (StructValue FieldValue)]
+            [Only second] <- query_ conn (Query ("SELECT " <> secondSql)) :: IO [Only (StructValue FieldValue)]
+            forM_
+              [([Nothing, Just first, Just second], ["NULL", firstSql, secondSql]), ([Just second, Nothing, Just first], [secondSql, "NULL", firstSql])]
+              \(elements, sqls) -> do
+                let values = sized elements :: SizedArray 3 (Maybe (StructValue FieldValue))
+                    literal = "array_value(" <> Text.intercalate ", " sqls <> ")"
+                (query conn (Query ("SELECT typeof(?), ?::VARCHAR, (" <> literal <> ")::VARCHAR")) (values, values) :: IO [(Text, Text, Text)]) >>= \case
+                  [(actualType, text, literalText)] -> do
+                    actualType @?= typeName
+                    text @?= literalText
+                  rows -> assertFailure (show rows)
+                withConnectionHandle conn \native -> withConnectionFactory native \factory -> bracket (toDuckValue factory values) destroyValue (const (pure ()))
+        (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+    , testCase "a FieldValue binds back as the value that it was read from" $ withConnection ":memory:" \conn -> do
+        -- The third item is the type of the bound value for SELECT ?, when it
+        -- is not the type of the source.
+        forM_
+          [ ("BOOLEAN", "true", Nothing)
+          , ("TINYINT", "-7", Nothing)
+          , ("SMALLINT", "-300", Nothing)
+          , ("INTEGER", "-70000", Nothing)
+          , ("BIGINT", "-9007199254740993", Nothing)
+          , ("UTINYINT", "200", Nothing)
+          , ("USMALLINT", "60000", Nothing)
+          , ("UINTEGER", "4000000000", Nothing)
+          , ("UBIGINT", "18446744073709551615", Nothing)
+          , ("HUGEINT", "-170141183460469231731687303715884105728", Nothing)
+          , ("UHUGEINT", "5", Nothing)
+          , ("UHUGEINT", "340282366920938463463374607431768211455", Nothing)
+          , ("FLOAT", "1.25", Nothing)
+          , ("DOUBLE", "0.1", Nothing)
+          , ("DECIMAL(4,1)", "123.4", Nothing)
+          , ("DECIMAL(18,3)", "123456789012345.678", Nothing)
+          , ("DECIMAL(38,10)", "1234567890123456789012345678.0123456789", Nothing)
+          , ("VARCHAR", "'text'", Nothing)
+          , ("VARCHAR COLLATE NOCASE", "'Text'", Nothing)
+          , ("JSON", "'{\"a\": 1}'", Just "VARCHAR")
+          , ("BLOB", "'\\x00\\xFF'::BLOB", Nothing)
+          , ("UUID", "'00112233-4455-6677-8899-aabbccddeeff'", Nothing)
+          , ("BIT", "'10110'", Nothing)
+          , ("DATE", "'2026-01-02'", Nothing)
+          , ("DATE", "'infinity'", Nothing)
+          , ("TIME", "'03:04:05.123456'", Nothing)
+          , ("TIME_NS", "'03:04:05.123456789'", Just "TIME")
+          , ("TIMETZ", "'03:04:05+01:30:15'", Nothing)
+          , ("TIMESTAMP", "'2026-01-02 03:04:05.123456'", Nothing)
+          , ("TIMESTAMP", "'-infinity'", Nothing)
+          , ("TIMESTAMP_S", "'2026-01-02 03:04:05'", Just "TIMESTAMP")
+          , ("TIMESTAMP_MS", "'2026-01-02 03:04:05.123'", Just "TIMESTAMP")
+          , ("TIMESTAMP_NS", "'2026-01-02 03:04:05.123456789'", Just "TIMESTAMP")
+          , ("TIMESTAMPTZ", "'2026-01-02 03:04:05.123456+00'", Nothing)
+          , ("TIMESTAMPTZ_NS", "'2026-01-02 03:04:05.123456789+00'", Just "TIMESTAMP WITH TIME ZONE")
+          , ("INTERVAL", "INTERVAL '1 month 2 days 3 microseconds'", Nothing)
+          , ("BIGNUM", "'123456789012345678901234567890123456789012345678901234567890'", Nothing)
+          , ("GEOMETRY", "'POINT (1 2)'", Nothing)
+          , ("GEOMETRY('OGC:CRS84')", "'POINT (1 2)'", Nothing)
+          , ("VARIANT", "42::BIGINT", Just "BIGINT")
+          , ("VARIANT", "{'k': 1}", Just "STRUCT(k VARIANT)")
+          , ("INTEGER", "NULL", Just "\"NULL\"")
+          , ("INTEGER[]", "[1, NULL, 3]", Nothing)
+          , ("TIMESTAMP_NS[]", "['2026-01-02 03:04:05.123456789', '2026-01-02 03:04:05']", Just "TIMESTAMP[]")
+          , ("TIME_NS[]", "['03:04:05.123456789', '03:04:05']", Just "TIME[]")
+          , ("TIMESTAMPTZ_NS[]", "['2026-01-02 03:04:05.123456789+00', '2026-01-02 03:04:05+00']", Just "TIMESTAMP WITH TIME ZONE[]")
+          , ("DECIMAL(4,1)[]", "[1.5, 2.5]", Nothing)
+          , ("INTEGER[2]", "[1, 2]", Nothing)
+          , ("VARCHAR[2][]", "[['a', 'b'], ['c', NULL]]", Nothing)
+          , ("MAP(VARCHAR, INTEGER)", "MAP {'a': 1, 'b': NULL}", Nothing)
+          , ("MAP(INTEGER[], STRUCT(x DOUBLE))", "MAP {[1]: {'x': 1.5}}", Nothing)
+          , ("STRUCT(a INTEGER, b VARCHAR)", "{'a': 1, 'b': 'x'}", Nothing)
+          , ("STRUCT(e ENUM('a', 'b'), n INTEGER[])", "{'e': 'b', 'n': []}", Nothing)
+          , ("ENUM('a', 'b')", "'b'", Just "VARCHAR")
+          , ("ENUM('a', 'b')[]", "['a', NULL, 'b']", Just "VARCHAR[]")
+          , ("TUPLE(INTEGER, VARCHAR)", "(1, 'x')", Nothing)
+          , ("UNION(a INTEGER, b VARCHAR)", "union_value(b := 'x')", Nothing)
+          , ("STRUCT(a INTEGER)[]", "[{'a': 1}, NULL]", Nothing)
+          , ("VARIANT", "'2026-01-02 03:04:05.123456789'::TIMESTAMP_NS", Just "TIMESTAMP")
+          , ("VARIANT", "'03:04:05.123456789'::TIME_NS", Just "TIME")
+          , ("VARIANT", "123.4::DECIMAL(4,1)", Just "DECIMAL(4,1)")
+          , ("VARIANT", "'00112233-4455-6677-8899-aabbccddeeff'::UUID", Just "UUID")
+          , ("VARIANT", "'\\x00\\xFF'::BLOB", Just "BLOB")
+          , ("VARIANT", "'03:04:05+01:30'::TIMETZ", Just "TIME WITH TIME ZONE")
+          , ("VARIANT", "INTERVAL '1 month 2 days 3 microseconds'", Just "INTERVAL")
+          , ("GEOMETRY('OGC:CRS84')[]", "['POINT (1 2)', NULL]", Nothing)
+          , ("STRUCT(g GEOMETRY('OGC:CRS84'))", "{'g': 'POINT (1 2)'}", Nothing)
+          , ("TIMESTAMPTZ", "'infinity'", Nothing)
+          , ("TIME", "'24:00:00'", Nothing)
+          , ("DOUBLE", "'NaN'", Nothing)
+          , ("DOUBLE", "'-Infinity'", Nothing)
+          , ("FLOAT", "'NaN'", Nothing)
+          , ("FLOAT", "'Infinity'", Nothing)
+          , ("UNION(a INTEGER, b VARCHAR)", "union_value(a := NULL::INTEGER)", Nothing)
+          , ("INTEGER[][2]", "[[1, 2], [3]]", Nothing)
+          , ("MAP(STRUCT(k INTEGER), VARCHAR)", "MAP {{'k': 1}: 'a'}", Nothing)
+          , ("MAP(VARCHAR, INTEGER)", "MAP {}", Just "MAP(\"NULL\", \"NULL\")")
+          , ("INTEGER[]", "[]", Just "\"NULL\"[]")
+          , ("INTEGER[]", "[NULL, NULL]", Just "\"NULL\"[]")
+          , ("BIT[]", "['101', '0']", Nothing)
+          , ("TIMETZ[]", "['03:04:05+01:30']", Nothing)
+          , ("UUID[]", "['00112233-4455-6677-8899-aabbccddeeff']", Nothing)
+          , ("TIME_NS[][]", "[['03:04:05.123456789', '03:04:05']]", Just "TIME[][]")
+          ]
+          \(sqlType, literal, boundType) -> do
+            let source = "(" <> literal <> ")::" <> sqlType
+                label = Text.unpack source
+            [Only value] <- query_ conn (Query ("SELECT " <> source)) :: IO [Only FieldValue]
+            rows <- query conn (Query ("SELECT typeof(?), typeof(" <> source <> "), ? IS NOT DISTINCT FROM " <> source)) (value, value)
+            case (rows, boundType) of
+              ([(actual, expected, same)], Nothing) -> do
+                assertEqual label expected actual
+                assertBool (label <> ": SELECT ? gives another value") same
+              ([(actual, _, _ :: Bool)], Just expected) -> assertEqual label expected (actual :: Text)
+              _ -> assertFailure (label <> ": " <> show rows)
+            _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE back (v " <> sqlType <> ")"))
+            _ <- execute conn "INSERT INTO back VALUES (?)" (Only value)
+            (query_ conn (Query ("SELECT v IS NOT DISTINCT FROM " <> source <> " FROM back")) :: IO [Only Bool]) >>= assertEqual label [Only True]
+        -- ST_SetCRS supplies the custom CRS in the result type.
+        withConnection ":memory:" \custom -> do
+          _ <- execute_ custom "CREATE TABLE shapes AS SELECT ST_SetCRS('POINT (1 2)'::GEOMETRY, 'local grid') AS v"
+          [Only shape] <- query_ custom "SELECT v FROM shapes" :: IO [Only FieldValue]
+          ( query custom "SELECT typeof(?), (SELECT typeof(v) FROM shapes), ? IS NOT DISTINCT FROM (SELECT v FROM shapes)" (shape, shape)
+              :: IO [(Text, Text, Bool)]
+            )
+            >>= \case
+              [(actual, expected, same)] -> do
+                actual @?= expected
+                assertBool "custom CRS: SELECT ? gives another value" same
+              rows -> assertFailure (show rows)
+          _ <- execute custom "INSERT INTO shapes VALUES (?)" (Only shape)
+          (query_ custom "SELECT count(*) FROM shapes WHERE v IS NOT DISTINCT FROM (SELECT v FROM shapes LIMIT 1)" :: IO [Only Int64])
+            >>= (@?= [Only 2])
+        -- A row read as a list of FieldValue binds back as a row.
+        _ <-
+          execute_
+            conn
+            "CREATE TABLE source_row (i INTEGER, t VARCHAR, s STRUCT(a INTEGER), l DOUBLE[]); INSERT INTO source_row VALUES (1, 'x', {'a': 2}, [1.5, NULL]); CREATE TABLE copied AS FROM source_row LIMIT 0"
+        [row] <- query_ conn "SELECT * FROM source_row" :: IO [[FieldValue]]
+        _ <- execute conn "INSERT INTO copied VALUES (?, ?, ?, ?)" row
+        (query_ conn "SELECT (SELECT count(*) FROM copied), (SELECT count(*) FROM (FROM source_row EXCEPT FROM copied))" :: IO [(Int64, Int64)])
+          >>= (@?= [(1, 0)])
+    , testCase "a FieldValue with no known type raises an error" $ withConnection ":memory:" \conn -> do
+        let untyped :: String -> FieldValue -> Text -> IO ()
+            untyped label value part =
+              try (query conn "SELECT ?" (Only value) :: IO [Only FieldValue]) >>= \case
+                Left SQLError{sqlErrorType, sqlErrorMessage} -> do
+                  assertEqual label (Just ErrorInputInvalid) sqlErrorType
+                  assertBool (Text.unpack sqlErrorMessage) (part `Text.isInfixOf` sqlErrorMessage)
+                Right rows -> assertFailure (label <> ": " <> show rows)
+        untyped "empty array" (FieldArray (listArray (0, -1) [])) "an empty ARRAY parameter is not possible"
+        -- Empty values and NULL elements bind as the SQL literal does.
+        forM_
+          [ ("empty list", FieldList [], "\"NULL\"[]", "[]")
+          , ("empty inner list", FieldList [FieldList [FieldInt32 1], FieldList []], "INTEGER[][]", "[[1], []]")
+          , ("empty map", FieldMap [], "MAP(\"NULL\", \"NULL\")", "{}")
+          , ("NULL list", FieldList [FieldNull, FieldNull], "\"NULL\"[]", "[NULL, NULL]")
+          , ("NULL array", FieldArray (listArray (0, 1) [FieldNull, FieldNull]), "\"NULL\"[2]", "[NULL, NULL]")
+          , ("NULL map values", FieldMap [(FieldText "a", FieldNull)], "MAP(VARCHAR, \"NULL\")", "{a=NULL}")
+          ]
+          \(label, value, typeName, text) ->
+            (query conn "SELECT typeof(?), ?::VARCHAR" (value, value) :: IO [(Text, Text)]) >>= assertEqual label [(typeName, text)]
+        forM_
+          [ ("STRUCT(a INTEGER)[]", FieldList [], "[]")
+          , ("STRUCT(a INTEGER)[]", FieldList [FieldNull], "[NULL]")
+          , ("INTEGER[][]", FieldList [FieldList [FieldInt32 1], FieldList []], "[[1], []]")
+          , ("MAP(VARCHAR, STRUCT(a INTEGER))", FieldMap [], "{}")
+          , ("MAP(VARCHAR, STRUCT(a INTEGER))", FieldMap [(FieldText "k", FieldNull)], "{k=NULL}")
+          ]
+          \(sqlType, value, text) -> do
+            _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE typed (v " <> sqlType <> ")"))
+            _ <- execute conn "INSERT INTO typed VALUES (?)" (Only value)
+            (query_ conn "SELECT v::VARCHAR FROM typed" :: IO [Only Text]) >>= assertEqual (Text.unpack sqlType) [Only text]
+        (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+    , testCase "a FieldList of scalar values with different types follows the SQL list literal" $ withConnection ":memory:" \conn -> do
+        forM_
+          [ ([FieldInt32 1, FieldInt64 2], "[1::INTEGER, 2::BIGINT]", "BIGINT[]")
+          , ([FieldInt64 9007199254740993, FieldDouble 1.5], "[9007199254740993::BIGINT, 1.5::DOUBLE]", "DOUBLE[]")
+          , ([FieldList [FieldInt32 1], FieldList [FieldInt64 2]], "[[1::INTEGER], [2::BIGINT]]", "BIGINT[][]")
+          ]
+          \(items, literal, typeName) ->
+            ( query conn (Query ("SELECT typeof(?), ?::VARCHAR, (" <> literal <> ")::VARCHAR")) (FieldList items, FieldList items)
+                :: IO [(Text, Text, Text)]
+            )
+              >>= \case
+                [(actualType, text, literalText)] -> do
+                  assertEqual (Text.unpack literal) typeName actualType
+                  assertEqual (Text.unpack literal) literalText text
+                rows -> assertFailure (show rows)
+        (query conn "SELECT ?::VARCHAR" (Only (FieldList [FieldInt64 9007199254740993, FieldDouble 1.5])) :: IO [Only Text])
+          >>= (@?= [Only "[9007199254740992.0, 1.5]"])
+        [Only mixedVariant] <- query_ conn "SELECT [1::VARIANT, 'x'::VARIANT]::VARIANT" :: IO [Only FieldValue]
+        forM_
+          [ ("scalars", FieldList [FieldInt32 1, FieldText "a"], "Cannot combine types INTEGER and VARCHAR")
+          , ("lists", FieldList [FieldList [FieldInt32 1], FieldList [FieldText "a"]], "Cannot combine types INTEGER[] and VARCHAR[]")
+          , ("array", FieldArray (listArray (0, 1) [FieldInt32 1, FieldText "a"]), "Cannot combine types INTEGER and VARCHAR")
+          , ("VARIANT array", mixedVariant, "Cannot combine types INTEGER and VARCHAR")
+          ]
+          \(label, value, part) ->
+            try (query conn "SELECT ?" (Only value) :: IO [Only FieldValue]) >>= \case
+              Left SQLError{sqlErrorType, sqlErrorMessage} -> do
+                assertEqual label (Just ErrorQueryNotImplemented) sqlErrorType
+                assertBool (Text.unpack sqlErrorMessage) (part `Text.isInfixOf` sqlErrorMessage)
+              Right rows -> assertFailure (label <> ": " <> show rows)
+    , testCase "a list or a FieldArray of composite elements with different types follows the SQL list literal" $ withConnection ":memory:" \conn -> do
+        let elementOf :: Text -> IO (Maybe (StructValue FieldValue))
+            elementOf "NULL" = pure Nothing
+            elementOf sql = do
+              [Only value] <- query_ conn (Query ("SELECT " <> sql))
+              pure (Just value)
+            sameAs :: (ToField a) => a -> Text -> Text -> IO ()
+            sameAs value literal typeName =
+              (query conn (Query ("SELECT typeof(?), ?::VARCHAR, (" <> literal <> ")::VARCHAR")) (value, value) :: IO [(Text, Text, Text)]) >>= \case
+                [(actualType, text, literalText)] -> do
+                  assertEqual (Text.unpack literal) typeName actualType
+                  assertEqual (Text.unpack literal) literalText text
+                rows -> assertFailure (show rows)
+            duckdbError :: (ToField a) => String -> a -> ErrorType -> Text -> IO ()
+            duckdbError label value errorType part =
+              try (query conn "SELECT ?" (Only value) :: IO [Only FieldValue]) >>= \case
+                Left SQLError{sqlErrorType, sqlErrorMessage} -> do
+                  assertEqual label (Just errorType) sqlErrorType
+                  assertBool (Text.unpack sqlErrorMessage) (part `Text.isInfixOf` sqlErrorMessage)
+                Right rows -> assertFailure (label <> ": " <> show rows)
+        forM_
+          [ (["{'a': 1}", "{'b': 2}"], "STRUCT(a INTEGER, b INTEGER)")
+          , (["{'a': 1::INTEGER}", "{'a': 2::BIGINT}"], "STRUCT(a BIGINT)")
+          , (["{'a': 9007199254740993::BIGINT}", "{'a': 1.5::DOUBLE}"], "STRUCT(a DOUBLE)")
+          , (["{'a': [1::INTEGER]}", "{'a': [2::BIGINT]}"], "STRUCT(a BIGINT[])")
+          , (["{'a': 1}", "NULL"], "STRUCT(a INTEGER)")
+          , (["NULL", "{'a': 1}", "{'b': 2}"], "STRUCT(a INTEGER, b INTEGER)")
+          ]
+          \(sqls, elementType) -> do
+            elements <- mapM elementOf sqls
+            let literal = Text.intercalate ", " sqls
+                count = length elements
+            sameAs elements ("[" <> literal <> "]") (elementType <> "[]")
+            sameAs
+              (FieldArray (listArray (0, count - 1) (map (maybe FieldNull FieldStruct) elements)))
+              ("array_value(" <> literal <> ")")
+              (elementType <> "[" <> Text.pack (show count) <> "]")
+        -- The rule can round, as in SQL.
+        large <- mapM elementOf ["{'a': 9007199254740993::BIGINT}", "{'a': 1.5::DOUBLE}"]
+        (query conn "SELECT ?::VARCHAR" (Only large) :: IO [Only Text]) >>= (@?= [Only "[{'a': 9007199254740992.0}, {'a': 1.5}]"])
+        mismatch <- mapM elementOf ["{'a': 1}", "{'a': 'x'}"]
+        duckdbError "list" mismatch ErrorQueryNotImplemented "Cannot combine types STRUCT(a INTEGER) and STRUCT(a VARCHAR)"
+        duckdbError
+          "SizedArray"
+          (sized mismatch :: SizedArray 2 (Maybe (StructValue FieldValue)))
+          ErrorQueryNotImplemented
+          "Cannot combine types"
+        unions <-
+          mapM
+            (\sql -> query_ conn sql :: IO [Only (UnionValue FieldValue)])
+            ["SELECT union_value(a := 1)::UNION(a INTEGER)", "SELECT union_value(b := 'x')::UNION(b VARCHAR)"]
+        duckdbError "UNION list" (map fromOnly (concat unions)) ErrorTypeConversion "is not present in target union"
+        duckdbError
+          "ARRAY sizes"
+          ( FieldList
+              [FieldArray (listArray (0, 1) [FieldInt32 1, FieldInt32 2]), FieldArray (listArray (0, 2) [FieldInt32 1, FieldInt32 2, FieldInt32 3])]
+          )
+          ErrorInputInvalid
+          "Cannot cast array of size 2 to array of size 3"
+        [Just first, Just second] <- mapM elementOf ["{'a': 1}", "{'b': 2}"]
+        let mapped = Map.fromList [("k1" :: Text, first), ("k2", second)]
+        (query conn "SELECT typeof(?), ?::VARCHAR" (mapped, mapped) :: IO [(Text, Text)])
+          >>= (@?= [("MAP(VARCHAR, STRUCT(a INTEGER, b INTEGER))", "{k1={'a': 1, 'b': NULL}, k2={'a': NULL, 'b': 2}}")])
+        -- The column type does not change the type of the list, as in SQL.
+        _ <- execute_ conn "CREATE TABLE wide (v STRUCT(a BIGINT, b BIGINT)[]); CREATE TABLE named (v STRUCT(a VARCHAR)[])"
+        _ <- execute conn "INSERT INTO wide VALUES (?)" (Only [first, second])
+        (query_ conn "SELECT v::VARCHAR FROM wide" :: IO [Only Text]) >>= (@?= [Only "[{'a': 1, 'b': NULL}, {'a': NULL, 'b': 2}]"])
+        try (execute conn "INSERT INTO named VALUES (?)" (Only mismatch)) >>= \case
+          Left SQLError{sqlErrorType} -> sqlErrorType @?= Just ErrorQueryNotImplemented
+          Right count -> assertFailure ("expected the error of DuckDB, stored " <> show count)
+        (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+    , testCase "collection inference keeps aliases and collations as native common types do" $ withConnection ":memory:" \conn -> do
+        let check :: (ToField a) => String -> a -> Text -> Assertion
+            check label value literal =
+              (query conn (Query ("SELECT ?, " <> literal)) (Only value) :: IO [(FieldValue, FieldValue)]) >>= \case
+                [(actual, expected)] -> assertEqual label expected actual
+                rows -> assertFailure (show rows)
+        forM_
+          [ ("{'k': '{\"n\":1}'::VARCHAR}", "{'k': '{\"n\":2}'::JSON}", True)
+          , ("{'k': 'A'::VARCHAR}", "{'k': 'B' COLLATE nocase}", False)
+          ]
+          \(plainSql, annotatedSql, compareSQL) -> do
+            [Only plain] <- query_ conn (Query ("SELECT " <> plainSql)) :: IO [Only (StructValue FieldValue)]
+            [Only annotated] <- query_ conn (Query ("SELECT " <> annotatedSql)) :: IO [Only (StructValue FieldValue)]
+            forM_ [(plain, annotated, plainSql, annotatedSql), (annotated, plain, annotatedSql, plainSql)] \(first, second, firstSql, secondSql) -> do
+              let items = firstSql <> ", " <> secondSql
+                  array = FieldArray (listArray (0, 1) [FieldStruct first, FieldStruct second])
+                  mapping = Map.fromList [("a" :: Text, first), ("b", second)]
+              when compareSQL do
+                check "LIST" [first, second] ("[" <> items <> "]")
+                check "ARRAY" array ("array_value(" <> items <> ")")
+                check "MAP" mapping ("map(['a', 'b'], [" <> items <> "])")
+              -- SQL expression binding can discard collations before common
+              -- type inference. Compare the preserved input types directly.
+              common <- withConnectionHandle conn \native -> withConnectionFactory native \factory ->
+                bracket (logicalTypeFromRep factory (structValueTypeRep first)) destroyLogicalType \left ->
+                  bracket (logicalTypeFromRep factory (structValueTypeRep second)) destroyLogicalType \right ->
+                    withArray [left, right] \types ->
+                      bracket (R.output (c_duckdb_v2_factory_create_common_type factory (ConstPtr types) 2)) destroyLogicalType (logicalTypeToRep factory)
+              let checkType :: (ToField a) => a -> LogicalTypeRep -> Assertion
+                  checkType value expected =
+                    (query conn "SELECT ?" (Only value) :: IO [Only FieldTypeOf]) >>= (@?= [Only (FieldTypeOf expected)])
+              checkType [first, second] (LogicalTypeList common)
+              checkType array (LogicalTypeArray common 2)
+              checkType mapping (LogicalTypeMap (LogicalTypeScalar LogicalTypeIdVarchar) common)
+    , testCase "collection inference preserves exact metadata at native equality boundaries" $ withConnection ":memory:" \conn -> do
+        let integer = LogicalTypeScalar LogicalTypeIdInteger
+            varchar = LogicalTypeScalar LogicalTypeIdVarchar
+            record name = LogicalTypeStruct (listArray (0, 0) [StructField name integer])
+            member name rep = LogicalTypeUnion (listArray (0, 0) [UnionMemberType name rep])
+            tuple rep = LogicalTypeTuple (listArray (0, 0) [rep])
+            enum labels = LogicalTypeEnum (listArray (0, length labels - 1) labels)
+            wkt =
+              "ENGCRS[\"Local grid\",EDATUM[\"Local datum\"],CS[Cartesian,2],AXIS[\"x\",east,ORDER[1],LENGTHUNIT[\"metre\",1]],AXIS[\"y\",north,ORDER[2],LENGTHUNIT[\"metre\",1]]]"
+            geometry = LogicalTypeGeometry . Just
+            wrappers =
+              [ ("STRUCT", id)
+              , ("LIST", LogicalTypeList)
+              , ("ARRAY", \rep -> LogicalTypeArray rep 1)
+              , ("MAP key", \rep -> LogicalTypeMap rep integer)
+              , ("MAP value", LogicalTypeMap varchar)
+              , ("TUPLE", tuple)
+              , ("UNION", member "value")
+              , ("alias", LogicalTypeAlias "nested_alias")
+              ]
+            cases =
+              [(label <> " field spelling", wrap (record "a"), wrap (record "A"), True, False) | (label, wrap) <- wrappers]
+                <> [ ("collation", tuple varchar, tuple (LogicalTypeCollatedVarchar "nocase"), True, False)
+                   , ("UNION spelling", member "a" integer, member "A" integer, True, False)
+                   , ("CRS definition", geometry wkt, geometry (Text.replace ",EDATUM" ", EDATUM" wkt), True, False)
+                   , ("ENUM label", enum ["A", "b"], enum ["a", "b"], False, False)
+                   , ("ENUM order", enum ["a", "b"], enum ["b", "a"], False, False)
+                   , ("same ENUM", enum ["a", "b"], enum ["a", "b"], True, True)
+                   , ("alias spelling", LogicalTypeAlias "alias" integer, LogicalTypeAlias "Alias" integer, False, True)
+                   , ("empty STRUCT", LogicalTypeStruct (listArray (0, -1) []), LogicalTypeStruct (listArray (0, -1) []), True, True)
+                   , ("empty TUPLE", LogicalTypeTuple (listArray (0, -1) []), LogicalTypeTuple (listArray (0, -1) []), True, True)
+                   ]
+            check :: (ToField a) => String -> a -> LogicalTypeRep -> Assertion
+            check label value expected =
+              (query conn "SELECT ?" (Only value) :: IO [Only FieldTypeOf]) >>= assertEqual label [Only (FieldTypeOf expected)]
+        forM_ cases \(label, first, second, nativeEqual, baseEqual) ->
+          forM_ [(first, second), (second, first)] \(leftRep, rightRep) -> do
+            expected <- withConnectionHandle conn \native -> withConnectionFactory native \factory ->
+              bracket (logicalTypeFromRep factory leftRep) destroyLogicalType \left ->
+                bracket (logicalTypeFromRep factory rightRep) destroyLogicalType \right -> do
+                  same <- (/= 0) <$> R.output (c_duckdb_v2_logical_type_is_equal left right)
+                  assertEqual (label <> " native equality") nativeEqual same
+                  sameBase <- (==) <$> logicalTypeToBaseRep left <*> logicalTypeToBaseRep right
+                  assertEqual (label <> " base equality") baseEqual sameBase
+                  -- Equal native types retain their exact metadata. Other types use native inference.
+                  if same && sameBase
+                    then logicalTypeToRep factory left
+                    else withArray [left, right] \types ->
+                      bracket (R.output (c_duckdb_v2_factory_create_common_type factory (ConstPtr types) 2)) destroyLogicalType (logicalTypeToRep factory)
+            let items = [TypedStructNull leftRep, TypedStructNull rightRep]
+            check label items (LogicalTypeList expected)
+            check label (sized items :: SizedArray 2 UnadaptedStruct) (LogicalTypeArray expected 2)
+            check label (Map.fromList (zip ["a" :: Text, "b"] items)) (LogicalTypeMap varchar expected)
+    , testCase "collection inference keeps typed NULL aliases and collations" $ withConnection ":memory:" \conn -> do
+        let varchar = LogicalTypeScalar LogicalTypeIdVarchar
+            plain = singleField varchar (FieldText "{}")
+            plainRep = structValueTypeRep plain
+            check :: (ToField a) => a -> LogicalTypeRep -> Assertion
+            check value expected =
+              (query conn "SELECT ?" (Only value) :: IO [Only FieldTypeOf]) >>= (@?= [Only (FieldTypeOf expected)])
+        cases <- withConnectionHandle conn \native -> withConnectionFactory native \factory ->
+          bracket (logicalTypeFromRep factory plainRep) destroyLogicalType \left ->
+            fmap concat $ forM
+              [ structValueTypeRep (singleField (LogicalTypeAlias "JSON" varchar) FieldNull)
+              , structValueTypeRep (singleField (LogicalTypeCollatedVarchar "nocase") FieldNull)
+              , LogicalTypeAlias "STRUCT" plainRep
+              ]
+              \rep -> bracket (logicalTypeFromRep factory rep) destroyLogicalType \right ->
+                forM
+                  [ ([UnadaptedStruct plain, TypedStructNull rep], [left, right])
+                  , ([TypedStructNull rep, UnadaptedStruct plain], [right, left])
+                  , ([TypedStructNull plainRep, TypedStructNull rep], [left, right])
+                  , ([TypedStructNull rep, TypedStructNull plainRep], [right, left])
+                  , ([TypedStructNull rep], [right])
+                  ]
+                  \(items, types) -> do
+                    common <- withArray types \nativeTypes ->
+                      bracket
+                        (R.output (c_duckdb_v2_factory_create_common_type factory (ConstPtr nativeTypes) (fromIntegral (length types))))
+                        destroyLogicalType
+                        (logicalTypeToRep factory)
+                    pure (items, common)
+        forM_ cases \(items, common) -> do
+          check items (LogicalTypeList common)
+          if length items == 2
+            then check (sized items :: SizedArray 2 UnadaptedStruct) (LogicalTypeArray common 2)
+            else check (sized items :: SizedArray 1 UnadaptedStruct) (LogicalTypeArray common 1)
+          check (Map.fromList (zip ["a" :: Text, "b"] items)) (LogicalTypeMap varchar common)
+        -- SQLNULL can itself have its canonical name as an alias. It must not
+        -- be discarded with an ordinary untyped NULL.
+        let canonicalNull = LogicalTypeAlias "NULL" (LogicalTypeScalar LogicalTypeIdSQLNull)
+        check [Just (TypedStructNull canonicalNull), Nothing] (LogicalTypeList canonicalNull)
+    , testCase "collection inference keeps canonical aliases in both element orders" $ withConnection ":memory:" \conn -> do
+        let integer = LogicalTypeScalar LogicalTypeIdInteger
+            canonical = LogicalTypeAlias "INTEGER" integer
+            plain = singleField integer (FieldInt32 7)
+            annotated = singleField canonical (FieldInt32 7)
+            element = structValueTypeRep annotated
+            check :: (ToField a) => a -> LogicalTypeRep -> Assertion
+            check value expected = do
+              [Only actual] <- query conn "SELECT ?" (Only value) :: IO [Only FieldTypeOf]
+              actual @?= FieldTypeOf expected
+        forM_ [[plain, annotated], [annotated, plain]] \items -> do
+          check items (LogicalTypeList element)
+          check (FieldArray (listArray (0, 1) (map FieldStruct items))) (LogicalTypeArray element 2)
+          check (Map.fromList (zip ["a" :: Text, "b"] items)) (LogicalTypeMap (LogicalTypeScalar LogicalTypeIdVarchar) element)
+    , testCase "mixed temporal inference preserves aliases on unchanged nested leaves" $ withConnection ":memory:" \conn -> do
+        let varchar = LogicalTypeScalar LogicalTypeIdVarchar
+            json = LogicalTypeAlias "JSON" varchar
+            time = LogicalTypeScalar LogicalTypeIdTime
+            nanos = LogicalTypeScalar LogicalTypeIdTimeNs
+            structure textType timeType value =
+              structOf [("k", FieldText "{}", textType), ("t", FieldTime value, timeType)]
+            coarse textType = structure textType time (TimeOfDay 3 4 5)
+            precise textType = structure textType nanos (TimeOfDay 3 4 5.123456789)
+            aliasedCoarse = structure json (LogicalTypeAlias "TIME" time) (TimeOfDay 3 4 5)
+            target = "STRUCT(k JSON, t TIME_NS)[]"
+            check items =
+              (query conn (Query ("SELECT ?::" <> target)) (Only (map UnadaptedStruct items)) :: IO [Only [StructValue FieldValue]])
+        forM_
+          [ ([coarse json], [structure json nanos (TimeOfDay 3 4 5)])
+          , ([precise json], [precise json])
+          , ([coarse json, coarse json], replicate 2 (structure json nanos (TimeOfDay 3 4 5)))
+          , ([precise json, precise json], [precise json, precise json])
+          , ([coarse json, precise json], [structure json nanos (TimeOfDay 3 4 5), precise json])
+          , ([precise json, coarse json], [precise json, structure json nanos (TimeOfDay 3 4 5)])
+          ]
+          \(items, expected) -> check items >>= (@?= [Only expected])
+        -- Keep the native cast failure as a control for public vector writes.
+        nativeAlias <- try $ withConnectionHandle conn \native -> withConnectionFactory native \factory ->
+          bracket (logicalTypeFromRep factory (LogicalTypeAlias "TIME" time)) destroyLogicalType \logical ->
+            withOwnedVector factory logical \vector -> do
+              R.checked (c_duckdb_v2_vector_set_size vector 1)
+              bracket (toDuckValue factory (TimeOfDay 3 4 5)) destroyValue \value ->
+                R.checked (c_duckdb_v2_vector_set_value vector 0 value)
+        let rejectsAlias :: Either SQLError a -> Assertion
+            rejectsAlias result = case result of
+              Left SQLError{sqlErrorMessage, sqlErrorType} -> do
+                sqlErrorType @?= Just ErrorInputInvalid
+                assertBool (Text.unpack sqlErrorMessage) ("Unimplemented type for cast (TIME -> TIME)" `Text.isInfixOf` sqlErrorMessage)
+              Right _ -> assertFailure "expected the native TIME alias cast limit"
+        rejectsAlias nativeAlias
+        nativeCast <- try $ withConnectionHandle conn \native -> withConnectionFactory native \factory ->
+          bracket (logicalTypeFromRep factory (LogicalTypeAlias "TIME" time)) destroyLogicalType \logical ->
+            bracket (toDuckValue factory (TimeOfDay 3 4 5)) destroyValue \value ->
+              bracket (R.output (c_duckdb_v2_value_cast factory value logical)) destroyValue (const (pure ()))
+        rejectsAlias nativeCast
+        check [aliasedCoarse, precise json] >>= (@?= [Only [structure json nanos (TimeOfDay 3 4 5), precise json]])
+        check [precise json, aliasedCoarse] >>= (@?= [Only [precise json, structure json nanos (TimeOfDay 3 4 5)]])
+        let plainSql = "{'k': '{}'::VARCHAR, 't': TIME '03:04:05'}"
+            annotatedSql = "{'k': '{}'::JSON, 't': '03:04:05.123456789'::TIME_NS}"
+        forM_
+          [ ([coarse varchar, precise json], plainSql <> ", " <> annotatedSql)
+          , ([precise json, coarse varchar], annotatedSql <> ", " <> plainSql)
+          ]
+          \(items, sqls) -> do
+            native <- try (query_ conn (Query ("SELECT array_value(" <> sqls <> ")")) :: IO [Only FieldValue])
+            bound <- try (check items)
+            let rejected label result = case result of
+                  Left SQLError{sqlErrorMessage} ->
+                    assertBool (label <> ": " <> Text.unpack sqlErrorMessage) ("Cannot combine types" `Text.isInfixOf` sqlErrorMessage)
+                  Right _ -> assertFailure (label <> ": expected the native common-type error")
+            rejected "native SQL" native
+            rejected "bound list" bound
+    , testCase "TIME aliases bind exact scalar and nested payloads under session settings" $ withConnection ":memory:" \conn -> do
+        let time = LogicalTypeScalar LogicalTypeIdTime
+            varchar = LogicalTypeScalar LogicalTypeIdVarchar
+            check rep payload = do
+              let original = singleField rep payload
+              (query conn "SELECT ?" (Only original) :: IO [Only (StructValue FieldValue)]) >>= (@?= [Only original])
+        forM_ ["UTC", "Europe/Stockholm", "America/New_York"] \zone -> do
+          _ <- execute conn "SET TimeZone = ?" (Only (zone :: Text))
+          forM_ ["TIME", "clock_alias"] \name -> do
+            let alias = LogicalTypeAlias name time
+                members = listArray (0, 0) [UnionMemberType "t" alias]
+            forM_
+              [ FieldNull
+              , FieldTime (TimeOfDay 0 0 0)
+              , FieldTime (TimeOfDay 0 0 0.000001)
+              , FieldTime (TimeOfDay 12 34 56.123456)
+              , FieldTime (TimeOfDay 23 59 59.999999)
+              , FieldTime (TimeOfDay 24 0 0)
+              ]
+              \payload -> do
+                check alias payload
+                check (LogicalTypeList alias) (FieldList [payload, FieldNull])
+                check (LogicalTypeArray alias 2) (FieldArray (listArray (0, 1) [payload, FieldNull]))
+                check (LogicalTypeMap varchar alias) (FieldMap [(FieldText "t", payload)])
+                let nested = singleField alias payload
+                check (structValueTypeRep nested) (FieldStruct nested)
+                let union = UnionValue 0 "t" payload members
+                check (unionValueTypeRep union) (FieldUnion union)
+            let precise = singleField alias (FieldTime (TimeOfDay 12 34 56.123456789))
+                truncated = singleField alias (FieldTime (TimeOfDay 12 34 56.123456))
+            (query conn "SELECT ?" (Only precise) :: IO [Only (StructValue FieldValue)]) >>= (@?= [Only truncated])
+            forM_ [TimeOfDay 25 0 0, TimeOfDay 24 0 0.000001, TimeOfDay 12 60 0] \invalid ->
+              assertRangeError (query conn "SELECT ?" (Only (singleField alias (FieldTime invalid))) :: IO [Only FieldValue])
+    , testCase "a LIST parameter fails at an element of the wrong type after earlier elements" $ withConnection ":memory:" \conn -> do
+        let struct =
+              singleField (LogicalTypeList (LogicalTypeScalar LogicalTypeIdBigInt)) (FieldList [FieldInt64 1, FieldInt64 2, FieldText "x", FieldInt64 4])
+        result <- try (query conn "SELECT ?" (Only struct) :: IO [Only FieldValue])
+        case result of
+          Left SQLError{sqlErrorType, sqlErrorMessage} -> do
+            sqlErrorType @?= Just ErrorInputInvalid
+            assertBool
+              (Text.unpack sqlErrorMessage)
+              ("unsupported scalar conversion for BIGINT from a value of type VARCHAR" `Text.isInfixOf` sqlErrorMessage)
+          Right _ -> assertFailure "expected a conversion error for the third element"
+        -- A value of another kind than the declared type names its SQL type.
+        try
+          (query conn "SELECT ?" (Only (singleField (LogicalTypeList (LogicalTypeScalar LogicalTypeIdBigInt)) (FieldInt32 7))) :: IO [Only FieldValue])
+          >>= \case
+            Left SQLError{sqlErrorType, sqlErrorMessage} -> do
+              sqlErrorType @?= Just ErrorInputInvalid
+              assertBool (Text.unpack sqlErrorMessage) ("cannot encode a value of type INTEGER as BIGINT[]" `Text.isSuffixOf` sqlErrorMessage)
+            Right rows -> assertFailure ("expected the encode error, got " <> show rows)
+        (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+    , testCase "a declared NULL type binds NULL and rejects a value that is not NULL" $ withConnection ":memory:" \conn -> do
+        let sqlNull = LogicalTypeScalar LogicalTypeIdSQLNull
+            nullStruct = singleField sqlNull FieldNull
+        (query conn "SELECT typeof(?), CAST(? AS VARCHAR)" (nullStruct, nullStruct) :: IO [(Text, Text)])
+          >>= (@?= [("STRUCT(\"value\" \"NULL\")", "{'value': NULL}")])
+        result <- try (query conn "SELECT ?" (Only (singleField sqlNull (FieldInt32 7))) :: IO [Only FieldValue])
+        case result of
+          Left SQLError{sqlErrorType, sqlErrorMessage} -> do
+            sqlErrorType @?= Just ErrorInputInvalid
+            assertBool
+              (Text.unpack sqlErrorMessage)
+              ("unsupported scalar conversion for \"NULL\" from a value of type INTEGER" `Text.isInfixOf` sqlErrorMessage)
+          Right _ -> assertFailure "expected a conversion error for a value that is not NULL"
+    , testCase "GEOMETRY decodes as well-known binary" $ withConnection ":memory:" \conn -> do
+        [Only bytes] <- query_ conn "SELECT 'POINT(1 2)'::GEOMETRY" :: IO [Only BS.ByteString]
+        BS.length bytes @?= 21
+        (query conn "SELECT ST_AsText(ST_GeomFromWKB(?))" (Only bytes) :: IO [Only Text]) >>= (@?= [Only "POINT (1 2)"])
+    , testCase "Float parameter retains FLOAT type" $ withConnection ":memory:" \conn -> do
+        (query conn "SELECT typeof(?), ?" (1.25 :: Float, 1.25 :: Float) :: IO [(Text, Float)]) >>= (@?= [("FLOAT", 1.25)])
+    , testCase "Float special values survive decoding" $ withConnection ":memory:" \conn -> do
+        [Only value] <- query_ conn "SELECT 'NaN'::REAL" :: IO [Only Float]
+        assertBool "expected NaN" (isNaN value)
+        [Only value'] <- query_ conn "SELECT 'Infinity'::REAL" :: IO [Only Double]
+        assertBool "expected positive infinity" (isInfinite value' && value' > 0)
+    , testCase "finite Double overflow to Float fails" $ withConnection ":memory:" \conn ->
+        assertConversionError (query_ conn "SELECT 1e300::DOUBLE" :: IO [Only Float])
+    , testCase "embedded NUL and Unicode Text round trip" $ withConnection ":memory:" \conn -> do
+        let value = "before\0after íslenska λ 😀" :: Text
+        (query conn "SELECT ?" (Only value) :: IO [Only Text]) >>= (@?= [Only value])
+    , testCase "VARCHAR, BLOB, and BIT values on both sides of the inline length read back" $ withConnection ":memory:" \conn -> do
+        -- DuckDB keeps a value of at most 12 bytes inline and a longer value
+        -- behind a pointer. A BIT value has one more byte for its padding count.
+        let lengths = [0, 1, 11, 12, 13, 64]
+            texts = [Text.pack (take n (cycle ['a' .. 'z'])) | n <- lengths]
+            blobs = [BS.pack (take n (cycle [0, 255, 1, 128])) | n <- lengths]
+            bits = [bsFromBool (take n (cycle [True, False, False])) | n <- [1, 8, 87, 88, 89, 200]]
+            present = [(Just text, Just blob, Just bit) | (text, blob, bit) <- zip3 texts blobs bits]
+            -- The NULL row is between the values of 11 and 12 bytes.
+            rows = take 3 present <> [(Nothing, Nothing, Nothing)] <> drop 3 present
+        _ <- execute_ conn "CREATE TABLE inline_boundary (i INTEGER, t VARCHAR, b BLOB, bits BIT)"
+        _ <-
+          executeMany
+            conn
+            "INSERT INTO inline_boundary VALUES (?, ?, ?, ?)"
+            [(i, text, blob, bit) | (i, (text, blob, bit)) <- zip [0 :: Int32 ..] rows]
+        (query_ conn "SELECT t, b, bits FROM inline_boundary ORDER BY i" :: IO [(Maybe Text, Maybe BS.ByteString, Maybe BitString)])
+          >>= (@?= rows)
+        (query_ conn "SELECT list(t ORDER BY i) FROM inline_boundary" :: IO [Only [Maybe Text]])
+          >>= (@?= [Only [text | (text, _, _) <- rows]])
+    , testCase "Int8 rejects both overflow directions" $ withConnection ":memory:" \conn -> do
+        forM_ ["SELECT 128::BIGINT", "SELECT -129::SMALLINT"] \sql ->
+          assertConversionError (query_ conn sql :: IO [Only Int8])
+        (query_ conn "SELECT -128::BIGINT UNION ALL SELECT 127" :: IO [Only Int8]) >>= (@?= [Only (-128), Only 127])
+    , testCase "unsigned narrowing rejects overflow" $ withConnection ":memory:" \conn -> do
+        assertConversionError (query_ conn "SELECT 256::USMALLINT" :: IO [Only Word8])
+        assertConversionError (query_ conn "SELECT 65536::UINTEGER" :: IO [Only Word16])
+        assertConversionError (query_ conn "SELECT 4294967296::UBIGINT" :: IO [Only Word32])
+    , testCase "a parameter for a column of a type from CREATE TYPE follows the base type" $ withConnection ":memory:" \conn -> do
+        _ <- execute_ conn "CREATE TYPE tsns AS TIMESTAMP_NS; CREATE TYPE wide AS UHUGEINT; CREATE TABLE aliased (t tsns, w wide)"
+        let precise = LocalTime (fromGregorian 2024 1 2) (TimeOfDay 3 4 5.123456789)
+        _ <- execute conn "INSERT INTO aliased VALUES (?, ?)" (precise, 2 ^ (127 :: Int) + 5 :: Integer)
+        (query_ conn "SELECT t::VARCHAR, w::VARCHAR FROM aliased" :: IO [(Text, Text)])
+          >>= (@?= [("2024-01-02 03:04:05.123456789", "170141183460469231731687303715884105733")])
+    , testCase "Integer and Natural parameters store exact values for each numeric target" $ withConnection ":memory:" \conn -> do
+        let store :: (Show a, ToField a) => Text -> a -> Text -> Assertion
+            store dtype value expected = do
+              let label = Text.unpack dtype <> " " <> show value
+              _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE exact_value (v " <> dtype <> ")"))
+              _ <- execute conn "INSERT INTO exact_value VALUES (?)" (Only value)
+              (query_ conn "SELECT v::VARCHAR FROM exact_value" :: IO [Only Text]) >>= assertEqual label [Only expected]
+              (query conn "SELECT count(*) FROM exact_value WHERE v = ?" (Only value) :: IO [Only Int64]) >>= assertEqual label [Only 1]
+            huge = 2 ^ (128 :: Int) + 5 :: Integer
+        forM_ ["TINYINT", "SMALLINT", "INTEGER", "BIGINT", "UBIGINT", "HUGEINT", "UHUGEINT", "DECIMAL(38,0)", "DOUBLE", "VARCHAR", "BIGNUM"] \dtype -> do
+          let expected = if dtype == "DOUBLE" then "5.0" else "5"
+          store dtype (5 :: Integer) expected
+          store dtype (5 :: Natural) expected
+        forM_ ["TINYINT", "SMALLINT", "INTEGER", "BIGINT", "HUGEINT", "DECIMAL(38,0)", "DOUBLE", "VARCHAR", "BIGNUM"] \dtype ->
+          store dtype (-5 :: Integer) (if dtype == "DOUBLE" then "-5.0" else "-5")
+        forM_ ["HUGEINT", "UHUGEINT", "DECIMAL(38,0)", "BIGNUM", "VARCHAR"] \dtype ->
+          store dtype (2 ^ (100 :: Int) :: Integer) "1267650600228229401496703205376"
+        store "HUGEINT" (negate (2 ^ (127 :: Int)) :: Integer) "-170141183460469231731687303715884105728"
+        store "HUGEINT" (2 ^ (127 :: Int) - 1 :: Integer) "170141183460469231731687303715884105727"
+        forM_ ["UHUGEINT", "BIGNUM"] \dtype -> do
+          store dtype (2 ^ (127 :: Int) :: Integer) "170141183460469231731687303715884105728"
+          store dtype (2 ^ (127 :: Int) :: Natural) "170141183460469231731687303715884105728"
+          store dtype (2 ^ (128 :: Int) - 1 :: Integer) "340282366920938463463374607431768211455"
+          store dtype (2 ^ (128 :: Int) - 1 :: Natural) "340282366920938463463374607431768211455"
+        forM_ ["BIGNUM", "VARCHAR"] \dtype -> forM_ [huge, negate huge] \value ->
+          store dtype value (Text.pack (show value))
+    , testCase "an Integer parameter that its target cannot hold raises an error and stores no row" $ withConnection ":memory:" \conn -> do
+        let insertValue :: (Show a, ToField a) => Text -> a -> IO (Either SQLError Int)
+            insertValue dtype value = do
+              _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE rejected_value (v " <> dtype <> ")"))
+              result <- try (execute conn "INSERT INTO rejected_value VALUES (?)" (Only value))
+              (query_ conn "SELECT count(*) FROM rejected_value" :: IO [Only Int64]) >>= assertEqual (Text.unpack dtype <> " " <> show value) [Only 0]
+              pure result
+            insert :: Text -> Integer -> IO (Either SQLError Int)
+            insert = insertValue
+            huge = 2 ^ (128 :: Int) + 5 :: Integer
+        -- DuckDB checks the range of a cast from HUGEINT.
+        forM_
+          ( [(dtype, -5) | dtype <- ["UTINYINT", "USMALLINT", "UINTEGER", "UBIGINT", "UHUGEINT"]]
+              <> [("BIGINT", 2 ^ (70 :: Int)), ("DECIMAL(10,0)", 2 ^ (100 :: Int))]
+          )
+          \(dtype, value) ->
+            insert dtype value >>= \case
+              Left SQLError{sqlErrorMessage, sqlErrorType} -> do
+                assertBool (Text.unpack sqlErrorMessage) (not ("duckdb-simple:" `Text.isPrefixOf` sqlErrorMessage))
+                sqlErrorType @?= Just ErrorTypeConversion
+              Right _ -> assertFailure ("expected a DuckDB error for " <> Text.unpack dtype <> " " <> show value)
+        -- duckdb-simple checks the range of a value outside the HUGEINT range.
+        forM_
+          ( [("HUGEINT", 2 ^ (127 :: Int)), ("BIGINT", 2 ^ (127 :: Int)), ("UHUGEINT", 2 ^ (128 :: Int))]
+              <> [(dtype, value) | dtype <- ["TINYINT", "BIGINT", "UBIGINT", "HUGEINT", "UHUGEINT", "DECIMAL(38,0)"], value <- [huge, negate huge]]
+          )
+          \(dtype, value) ->
+            insert dtype value >>= \case
+              Left SQLError{sqlErrorMessage, sqlErrorType} -> do
+                sqlErrorType @?= Just ErrorTypeConversion
+                sqlErrorMessage @?= "duckdb-simple: the value " <> Text.pack (show value) <> " is out of range for a parameter of the type " <> dtype
+              Right _ -> assertFailure ("expected the duckdb-simple range error for " <> Text.unpack dtype <> " " <> show value)
+        insertValue "BIGINT" (2 ^ (128 :: Int) + 5 :: Natural) >>= \case
+          Left SQLError{sqlErrorMessage, sqlErrorType} -> do
+            sqlErrorType @?= Just ErrorTypeConversion
+            sqlErrorMessage @?= "duckdb-simple: the value 340282366920938463463374607431768211461 is out of range for a parameter of the type BIGINT"
+          Right _ -> assertFailure "expected the duckdb-simple range error for a Natural BIGINT value"
+        _ <- execute_ conn "CREATE TABLE wrapped_value (v UBIGINT)"
+        _ <- execute_ conn "INSERT INTO wrapped_value VALUES (18446744073709551611), (5)"
+        (query conn "SELECT count(*) FROM wrapped_value WHERE v = ?" (Only (-5 :: Integer)) :: IO [Only Int64]) >>= (@?= [Only 0])
+    , testCase "the SQL type of an Integer parameter follows its range" $ withConnection ":memory:" \conn -> do
+        let typed :: (ToField a) => a -> Integer -> Text -> Assertion
+            typed value expected dtype = (query conn "SELECT typeof(?), ?" (value, value) :: IO [(Text, Integer)]) >>= (@?= [(dtype, expected)])
+        typed (5 :: Integer) 5 "HUGEINT"
+        typed (negate (2 ^ (127 :: Int)) :: Integer) (negate (2 ^ (127 :: Int))) "HUGEINT"
+        typed (5 :: Natural) 5 "HUGEINT"
+        typed (2 ^ (127 :: Int) :: Integer) (2 ^ (127 :: Int)) "BIGNUM"
+        typed (2 ^ (130 :: Int) :: Integer) (2 ^ (130 :: Int)) "BIGNUM"
+        typed (BigNum 5) 5 "BIGNUM"
+    , testCase "executeMany stores Integer rows of each range" $ withConnection ":memory:" \conn ->
+        forM_ [("BIGNUM", [5, 2 ^ (127 :: Int), 2 ^ (130 :: Int)]), ("HUGEINT", [5, 2 ^ (100 :: Int)])] \(dtype, values :: [Integer]) -> do
+          _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE many_values (v " <> dtype <> ")"))
+          _ <- executeMany conn "INSERT INTO many_values VALUES (?)" (map Only values)
+          (query_ conn "SELECT v FROM many_values ORDER BY rowid" :: IO [Only Integer]) >>= (@?= map Only values)
+    , testCase "an array of Integer values takes the type that its elements give" $ withConnection ":memory:" \conn ->
+        -- See Note [Integer parameters] in "Database.DuckDB.Simple.ToField".
+        forM_ [(sized [5, 2 ^ (130 :: Int)], "BIGNUM[2]"), (sized [5, 6], "HUGEINT[2]")] \(values :: SizedArray 2 Integer, dtype) ->
+          (query conn "SELECT typeof(?), ?" (values, values) :: IO [(Text, SizedArray 2 Integer)]) >>= (@?= [(dtype, values)])
+    , testCase "an array of Integer values takes the element type of its target" $ withConnection ":memory:" \conn -> do
+        let store :: (Show a, ToField a) => Text -> a -> Text -> Assertion
+            store dtype value expected = do
+              _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE array_value (v " <> dtype <> ")"))
+              _ <- execute conn "INSERT INTO array_value VALUES (?)" (Only value)
+              (query_ conn "SELECT v::VARCHAR FROM array_value" :: IO [Only Text])
+                >>= assertEqual (Text.unpack dtype <> " " <> show value) [Only expected]
+            pair :: Integer -> Integer -> SizedArray 2 Integer
+            pair first second = sized [first, second]
+            huge = 2 ^ (128 :: Int) + 7 :: Integer
+        forM_ ["BIGINT[2]", "UBIGINT[2]", "HUGEINT[2]", "UHUGEINT[2]", "DECIMAL(38,0)[2]", "BIGNUM[2]", "VARCHAR[2]"] \dtype ->
+          store dtype (pair 5 6) "[5, 6]"
+        forM_ ["BIGINT[2]", "HUGEINT[2]", "BIGNUM[2]"] \dtype ->
+          store dtype (pair 5 (-6)) "[5, -6]"
+        store "UHUGEINT[2]" (sized [5, 2 ^ (127 :: Int)] :: SizedArray 2 Natural) "[5, 170141183460469231731687303715884105728]"
+        forM_ ["BIGNUM[2]", "VARCHAR[2]"] \dtype ->
+          store dtype (pair 5 huge) "[5, 340282366920938463463374607431768211463]"
+        store "BIGINT[2][2]" (sized [pair 1 2, pair 3 (-4)] :: SizedArray 2 (SizedArray 2 Integer)) "[[1, 2], [3, -4]]"
+        store "BIGINT[]" (pair 5 6) "[5, 6]"
+    , testCase "an array of Integer values with an element that its target cannot hold raises an error and stores no row" $ withConnection ":memory:" \conn -> do
+        let insert :: Text -> Integer -> IO SQLError
+            insert dtype second = do
+              let label = Text.unpack dtype <> " [5, " <> show second <> "]"
+              _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE rejected_array (v " <> dtype <> ")"))
+              result <- try (execute conn "INSERT INTO rejected_array VALUES (?)" (Only (sized [5, second] :: SizedArray 2 Integer)))
+              (query_ conn "SELECT count(*) FROM rejected_array" :: IO [Only Int64]) >>= assertEqual label [Only 0]
+              either pure (\_ -> assertFailure ("expected an error for " <> label)) result
+            huge = 2 ^ (128 :: Int) + 7 :: Integer
+        -- DuckDB checks the range of each element when it builds the array.
+        forM_ ([(dtype, -6) | dtype <- ["UTINYINT[2]", "UBIGINT[2]", "UHUGEINT[2]", "UBIGINT[]"]] <> [("TINYINT[2]", 300)]) \(dtype, second) -> do
+          SQLError{sqlErrorMessage, sqlErrorType} <- insert dtype second
+          assertBool (Text.unpack sqlErrorMessage) ("is out of range for the destination type" `Text.isInfixOf` sqlErrorMessage)
+          sqlErrorType @?= Just ErrorInputInvalid
+        -- duckdb-simple checks the range of an element outside the HUGEINT range.
+        forM_ [(dtype, second) | dtype <- ["BIGINT[2]", "UBIGINT[2]", "HUGEINT[2]", "DECIMAL(38,0)[2]"], second <- [huge, negate huge]] \(dtype, second) -> do
+          SQLError{sqlErrorType} <- insert dtype second
+          sqlErrorType @?= Just ErrorTypeConversion
+    , testCase "a list binds as a LIST parameter in each SQL form" $ withConnection ":memory:" \conn -> do
+        let ints = [1, 2, 3] :: [Int64]
+            none = [] :: [Int64]
+            count :: (ToRow p) => Query -> p -> IO [Only Int64]
+            count = query conn
+        forM_ [ints, none] \values ->
+          (query conn "SELECT typeof(?), ?" (values, values) :: IO [(Text, [Int64])]) >>= (@?= [("BIGINT[]", values)])
+        _ <- execute_ conn "CREATE TABLE list_value (i BIGINT, v BIGINT[])"
+        _ <- executeMany conn "INSERT INTO list_value VALUES (?, ?)" [(0 :: Int64, ints), (1, none)]
+        (query_ conn "SELECT v FROM list_value ORDER BY i" :: IO [Only [Int64]]) >>= (@?= [Only ints, Only none])
+        count "SELECT count(*) FROM list_value WHERE v = ?" (Only ints) >>= (@?= [Only 1])
+        count "SELECT count(*) FROM list_value WHERE v = ?" (Only none) >>= (@?= [Only 1])
+        -- DuckDB casts a LIST to an ARRAY of the same length only.
+        _ <- execute_ conn "CREATE TABLE array_column (v BIGINT[3])"
+        _ <- execute conn "INSERT INTO array_column VALUES (?)" (Only ints)
+        (query_ conn "SELECT v FROM array_column" :: IO [Only [Int64]]) >>= (@?= [Only ints])
+        count "SELECT count(*) FROM array_column WHERE v = ?" (Only ints) >>= (@?= [Only 1])
+        forM_ [[1, 2], none] \values -> do
+          result <- try (execute conn "INSERT INTO array_column VALUES (?)" (Only values))
+          case result of
+            Left SQLError{sqlErrorMessage, sqlErrorType} -> do
+              assertBool (Text.unpack sqlErrorMessage) ("Conversion Error: Cannot cast list with length " `Text.isPrefixOf` sqlErrorMessage)
+              sqlErrorType @?= Just ErrorTypeConversion
+            Right (_ :: Int) -> assertFailure ("expected the DuckDB length error for " <> show values)
+        (query_ conn "SELECT count(*) FROM array_column" :: IO [Only Int64]) >>= (@?= [Only 1])
+        _ <- execute_ conn "CREATE TABLE searched (v BIGINT)"
+        _ <- execute_ conn "INSERT INTO searched VALUES (1), (2), (5)"
+        forM_
+          [ "SELECT count(*) FROM searched WHERE v = ANY(?)"
+          , "SELECT count(*) FROM searched WHERE v IN (SELECT unnest(?))"
+          , "SELECT count(*) FROM searched WHERE list_contains(?, v)"
+          ]
+          \sql -> do
+            count sql (Only ([1, 5] :: [Int64])) >>= (@?= [Only 2])
+            count sql (Only none) >>= (@?= [Only 0])
+    , testCase "a list binds Maybe, nested, Text, String, and UTC elements" $ withConnection ":memory:" \conn -> do
+        (query conn "SELECT typeof(?), (?)::VARCHAR" ([Just 1, Nothing] :: [Maybe Int64], [Just 1, Nothing] :: [Maybe Int64]) :: IO [(Text, Text)])
+          >>= (@?= [("BIGINT[]", "[1, NULL]")])
+        let nested = [[1, 2], [], [3]] :: [[Int64]]
+        (query conn "SELECT typeof(?), ?" (nested, nested) :: IO [(Text, [[Int64]])]) >>= (@?= [("BIGINT[][]", nested)])
+        -- A String stays one VARCHAR parameter next to a list of Text.
+        let labels = ["a", "b"] :: [Text]
+            label = "ab" :: String
+        (query conn "SELECT typeof(?), ?, typeof(?), ?" (labels, labels, label, label) :: IO [(Text, [Text], Text, String)])
+          >>= (@?= [("VARCHAR[]", labels, "VARCHAR", label)])
+        (query conn "SELECT typeof(?), typeof(?)" (["x"] :: [String], [] :: [String]) :: IO [(Text, Text)]) >>= (@?= [("VARCHAR[]", "VARCHAR[]")])
+        -- A UTC element keeps its nanoseconds for a nanosecond target.
+        let precise = posixSecondsToUTCTime 0.123456789
+        (query conn "SELECT ?::TIMESTAMPTZ_NS[]" (Only [Just precise, Nothing]) :: IO [Only [Maybe UTCTime]])
+          >>= (@?= [Only [Just precise, Nothing]])
+    , testCase "a list of Integer values takes the element type of its target" $ withConnection ":memory:" \conn -> do
+        let insert :: Text -> [Integer] -> IO (Either SQLError Int)
+            insert dtype values = do
+              _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE integer_list (v " <> dtype <> ")"))
+              try (execute conn "INSERT INTO integer_list VALUES (?)" (Only values))
+            stored = query_ conn "SELECT v::VARCHAR FROM integer_list" :: IO [Only Text]
+        insert "UBIGINT[]" [5, 6] >>= either (assertFailure . show) (const (pure ()))
+        stored >>= (@?= [Only "[5, 6]"])
+        insert "UBIGINT[]" [5, -6] >>= \case
+          Left SQLError{sqlErrorType} -> sqlErrorType @?= Just ErrorInputInvalid
+          Right _ -> assertFailure "expected the DuckDB range error for -6"
+        insert "UBIGINT[]" [5, 2 ^ (130 :: Int)] >>= \case
+          Left SQLError{sqlErrorType} -> sqlErrorType @?= Just ErrorTypeConversion
+          Right _ -> assertFailure "expected the duckdb-simple range error for 2^130"
+        stored >>= (@?= [])
+        -- With no integer target, a list takes the type that its elements give,
+        -- as a SQL list literal of the HUGEINT and BIGNUM values. A list with
+        -- no element, or with only NULL elements, gets the type NULL. See
+        -- Note [Integer parameters] in "Database.DuckDB.Simple.ToField".
+        let typeOf :: (ToField a) => a -> IO [Only Text]
+            typeOf value = query conn "SELECT typeof(?)" (Only value)
+        typeOf ([5, 6] :: [Integer]) >>= (@?= [Only "HUGEINT[]"])
+        typeOf ([5, 2 ^ (130 :: Int)] :: [Integer]) >>= (@?= [Only "BIGNUM[]"])
+        typeOf ([] :: [Integer]) >>= (@?= [Only "\"NULL\"[]"])
+        typeOf ([Nothing] :: [Maybe Integer]) >>= (@?= [Only "\"NULL\"[]"])
+        typeOf ([5, 2 ^ (64 :: Int)] :: [Natural]) >>= (@?= [Only "HUGEINT[]"])
+        typeOf (Map.fromList [(5, "a")] :: Map.Map Integer Text) >>= (@?= [Only "MAP(HUGEINT, VARCHAR)"])
+        typeOf ([[1], []] :: [[Integer]]) >>= (@?= [Only "HUGEINT[][]"])
+        typeOf ([[]] :: [[Integer]]) >>= (@?= [Only "\"NULL\"[][]"])
+        -- BigNum has the same column type name. Its elements are BIGNUM values.
+        typeOf [BigNum 5, BigNum 6] >>= (@?= [Only "BIGNUM[]"])
+        typeOf ([Nothing] :: [Maybe BigNum]) >>= (@?= [Only "\"NULL\"[]"])
+        -- An empty list for an integer target takes the element type of the target.
+        _ <- execute_ conn "CREATE OR REPLACE TABLE empty_integers (v INTEGER[])"
+        _ <- execute conn "INSERT INTO empty_integers VALUES (?)" (Only ([] :: [Integer]))
+        (query_ conn "SELECT typeof(v), v::VARCHAR FROM empty_integers" :: IO [(Text, Text)]) >>= (@?= [("INTEGER[]", "[]")])
+        -- In a VARIANT, the elements keep the HUGEINT values, so a cast to an
+        -- unsigned type checks their range. A BIGNUM element gave
+        -- 18446744073709551611 for -5 with no error.
+        let variantCast :: (ToField a) => String -> a -> Text -> Assertion
+            variantCast label value target = do
+              _ <- execute_ conn "CREATE OR REPLACE TABLE variant_integers (v VARIANT)"
+              _ <- execute conn "INSERT INTO variant_integers VALUES (?)" (Only value)
+              try (query_ conn (Query ("SELECT (v::" <> target <> ")::VARCHAR FROM variant_integers")) :: IO [Only Text]) >>= \case
+                Left SQLError{sqlErrorType} -> assertEqual label (Just ErrorTypeConversion) sqlErrorType
+                Right rows -> assertFailure (label <> ": expected the error of the cast, got " <> show rows)
+        variantCast "[-5]" ([-5] :: [Integer]) "UBIGINT[]"
+        variantCast "Map {a: -5}" (Map.fromList [("a", -5)] :: Map.Map Text Integer) "MAP(VARCHAR, UBIGINT)"
+        variantCast "[[-5], []]" ([[-5], []] :: [[Integer]]) "UBIGINT[][]"
+    , testCase "a list and a SizedArray with the same elements store the same LIST value" $ withConnection ":memory:" \conn -> do
+        let ints = [1, 2, 3] :: [Int64]
+            arr = sized ints :: SizedArray 3 Int64
+        (query conn "SELECT typeof(?), typeof(?)" (ints, arr) :: IO [(Text, Text)]) >>= (@?= [("BIGINT[]", "BIGINT[3]")])
+        _ <- execute_ conn "CREATE TABLE same_value (i BIGINT, v BIGINT[])"
+        _ <- execute conn "INSERT INTO same_value VALUES (0, ?), (1, ?)" (ints, arr)
+        (query_ conn "SELECT v FROM same_value ORDER BY i" :: IO [Only [Int64]]) >>= (@?= [Only ints, Only ints])
+        (query_ conn "SELECT count(DISTINCT v) FROM same_value" :: IO [Only Int64]) >>= (@?= [Only 1])
+    , testCase "an empty list of composite elements binds as the SQL literal []" $ withConnection ":memory:" \conn -> do
+        let literal :: (ToField a) => String -> a -> Assertion
+            literal label value =
+              (query conn "SELECT typeof(?), ?::VARCHAR, typeof([])" (value, value) :: IO [(Text, Text, Text)])
+                >>= assertEqual label [("\"NULL\"[]", "[]", "\"NULL\"[]")]
+        literal "STRUCT" ([] :: [StructValue FieldValue])
+        literal "BIGINT[]" ([] :: [[Int64]])
+        -- A StructValue has no declaration, so a list of NULL elements and an
+        -- empty MAP of them get the type of the SQL literal. See
+        -- Note [Element types of a list] in "Database.DuckDB.Simple.ToField".
+        (query conn "SELECT typeof(?)" (Only [Nothing :: Maybe (StructValue FieldValue)]) :: IO [Only Text]) >>= (@?= [Only "\"NULL\"[]"])
+        (query conn "SELECT typeof(?)" (Only (Map.empty :: Map.Map Text (StructValue FieldValue))) :: IO [Only Text])
+          >>= (@?= [Only "MAP(VARCHAR, \"NULL\")"])
+        -- A SizedArray of NULL STRUCT values gets the type of array_value(NULL).
+        let nullArray = sized [Nothing] :: SizedArray 1 (Maybe (StructValue FieldValue))
+        (query conn "SELECT typeof(?), ?::VARCHAR" (nullArray, nullArray) :: IO [(Text, Text)]) >>= (@?= [("\"NULL\"[1]", "[NULL]")])
+    , testCase "a list of NULL composite elements takes the element type of a typed column" $ withConnection ":memory:" \conn -> do
+        let nulls = [Nothing, Nothing] :: [Maybe (StructValue FieldValue)]
+        _ <- execute_ conn "CREATE TABLE null_list (v STRUCT(a INTEGER)[]); CREATE TABLE null_array (v STRUCT(a INTEGER)[2])"
+        _ <- execute conn "INSERT INTO null_list VALUES (?)" (Only nulls)
+        _ <- execute conn "INSERT INTO null_array VALUES (?)" (Only (sized nulls :: SizedArray 2 (Maybe (StructValue FieldValue))))
+        (query_ conn "SELECT typeof(v), v::VARCHAR FROM null_list UNION ALL SELECT typeof(v), v::VARCHAR FROM null_array" :: IO [(Text, Text)])
+          >>= (@?= [("STRUCT(a INTEGER)[]", "[NULL, NULL]"), ("STRUCT(a INTEGER)[2]", "[NULL, NULL]")])
+        (query conn "SELECT typeof(?::STRUCT(a INTEGER)[])" (Only nulls) :: IO [Only Text]) >>= (@?= [Only "STRUCT(a INTEGER)[]"])
+        -- An empty list takes the element type of a typed column too.
+        _ <- execute_ conn "DELETE FROM null_list"
+        _ <- execute conn "INSERT INTO null_list VALUES (?)" (Only ([] :: [StructValue FieldValue]))
+        (query_ conn "SELECT v::VARCHAR FROM null_list" :: IO [Only Text]) >>= (@?= [Only "[]"])
+        -- With no known type, a list of NULL elements gets the type of the SQL literal [NULL, NULL].
+        (query conn "SELECT typeof(?)" (Only nulls) :: IO [Only Text]) >>= (@?= [Only "\"NULL\"[]"])
+    , testCase "an IntervalValue binds as an INTERVAL and keeps its three fields" $ withConnection ":memory:" \conn -> do
+        let value = IntervalValue 1 2 3
+            negative = IntervalValue (-1) (-2) (-3)
+            month = IntervalValue 1 0 0
+            days30 = IntervalValue 0 30 0
+        forM_ [value, negative] \interval ->
+          (query conn "SELECT typeof(?), ?" (interval, interval) :: IO [(Text, IntervalValue)]) >>= (@?= [("INTERVAL", interval)])
+        _ <- execute_ conn "CREATE TABLE intervals (i BIGINT, v INTERVAL)"
+        _ <- executeMany conn "INSERT INTO intervals VALUES (?, ?)" [(0 :: Int64, days30), (1, month), (2, negative)]
+        (query_ conn "SELECT v FROM intervals ORDER BY i" :: IO [Only IntervalValue]) >>= (@?= map Only [days30, month, negative])
+        -- DuckDB compares intervals with 30 days for each month.
+        (query conn "SELECT count(*) FROM intervals WHERE v = ?" (Only days30) :: IO [Only Int64]) >>= (@?= [Only 2])
+        (query conn "SELECT count(*) FROM intervals WHERE v < ?" (Only (IntervalValue 0 31 0)) :: IO [Only Int64]) >>= (@?= [Only 3])
+        (query conn "SELECT typeof(TIMESTAMP '2026-01-31' + ?), TIMESTAMP '2026-01-31' + ?" (month, month) :: IO [(Text, LocalTime)])
+          >>= (@?= [("TIMESTAMP", LocalTime (fromGregorian 2026 2 28) (TimeOfDay 0 0 0))])
+        (query conn "SELECT ?" (Only (Nothing :: Maybe IntervalValue)) :: IO [Only (Maybe IntervalValue)]) >>= (@?= [Only Nothing])
+        (query conn "SELECT typeof(?), ?" ([value, negative], [value, negative]) :: IO [(Text, [IntervalValue])])
+          >>= (@?= [("INTERVAL[]", [value, negative])])
+        let array = sized [value, negative] :: SizedArray 2 IntervalValue
+        (query conn "SELECT typeof(?), ?" (array, array) :: IO [(Text, [IntervalValue])]) >>= (@?= [("INTERVAL[2]", [value, negative])])
+    , testCase "MAP keys must remain distinct in field and generic decoding" $ withConnection ":memory:" \conn -> do
+        let genericKeyMap entry = fieldType entry >>= \logical -> duckFromTypedField logical (fieldValue entry)
+            check parser = do
+              let get sql = queryWith_ (fieldWith parser) conn sql :: IO [Map.Map Bool Int]
+              get "SELECT MAP {0:10, 1:20}" >>= (@?= [Map.fromList [(False, 10), (True, 20)]])
+              try (get "SELECT MAP {1:10, 2:20}") >>= \case
+                Left SQLError{sqlErrorMessage} -> assertBool (Text.unpack sqlErrorMessage) ("duplicate MAP key after conversion" `Text.isInfixOf` sqlErrorMessage)
+                Right rows -> assertFailure ("expected duplicate MAP key error, got " <> show rows)
+        check fromField
+        check genericKeyMap
+    , testCase "a JSON alias on an INTEGER reads as a VARIANT integer" $ withConnection ":memory:" \conn -> do
+        let value = singleField (LogicalTypeAlias "JSON" (LogicalTypeScalar LogicalTypeIdInteger)) (FieldInt32 17)
+        (query conn "SELECT (?).value, (?).value::VARIANT" (value, value) :: IO [(Variant, Variant)])
+          >>= (@?= [(Variant (FieldInt32 17), Variant (FieldInt32 17))])
+    , testCase "a TimeWithZone from a Data.Time zone reads back with that zone" $ withConnection ":memory:" \conn -> do
+        let zone = hoursToTimeZone 2
+            value = timeWithZone (TimeOfDay 12 34 0) zone
+        timeWithZoneOffsetSeconds value @?= 7200
+        [Only stored] <- query conn "SELECT ?" (Only value)
+        stored @?= value
+        timeWithZoneZone stored @?= zone
+        -- A TimeZone holds whole minutes, so the seconds of an offset go.
+        [Only withSeconds] <- query_ conn "SELECT '12:00:00+01:00:30'::TIMETZ"
+        timeWithZoneOffsetSeconds withSeconds @?= 3630
+        timeWithZoneZone withSeconds @?= hoursToTimeZone 1
+    , testCase "a TimeWithZone binds as a TIMETZ with its time and offset in seconds" $ withConnection ":memory:" \conn -> do
+        let at hours minutes offset = TimeWithZone (TimeOfDay hours minutes 0) offset
+            value = at 12 34 19800
+            -- The offset +01:00:30.
+            seconds = at 12 0 3630
+            roundTrip time = (query conn "SELECT ?" (Only time) :: IO [Only TimeWithZone]) >>= (@?= [Only time])
+        (query conn "SELECT typeof(?), ?" (value, value) :: IO [(Text, TimeWithZone)]) >>= (@?= [("TIME WITH TIME ZONE", value)])
+        -- An offset with seconds reads, binds, and prints exactly.
+        ( query_ conn "SELECT '12:00:00+01:00:30'::TIMETZ, '12:00:00-15:59:59'::TIMETZ, '24:00:00+15:59:59'::TIMETZ"
+            :: IO [(TimeWithZone, TimeWithZone, TimeWithZone)]
+          )
+          >>= (@?= [(seconds, at 12 0 (-57599), TimeWithZone (TimeOfDay 24 0 0) 57599)])
+        (query conn "SELECT ?::VARCHAR" (Only seconds) :: IO [Only Text]) >>= (@?= [Only "12:00:00+01:00:30"])
+        mapM_
+          roundTrip
+          [seconds, at 12 0 57599, at 12 0 (-57599), TimeWithZone (TimeOfDay 24 0 0) 0, TimeWithZone (TimeOfDay 23 59 59.999999) (-3630)]
+        -- DuckDB stores an offset from -15:59:59 to +15:59:59.
+        forM_ [57600, -57600] \offset ->
+          try (query conn "SELECT ?" (Only (at 12 0 offset)) :: IO [Only TimeWithZone]) >>= \case
+            Left SQLError{sqlErrorType, sqlErrorMessage} -> do
+              sqlErrorType @?= Just ErrorTypeConversion
+              assertBool
+                (Text.unpack sqlErrorMessage)
+                (("duckdb-simple: the TIMETZ offset " <> Text.pack (show offset) <> " seconds is out of range") `Text.isInfixOf` sqlErrorMessage)
+            Right rows -> assertFailure ("expected the offset error, got " <> show rows)
+        -- A TIME column removes the offset and keeps the local time.
+        _ <- execute_ conn "CREATE TABLE times (a TIMETZ, b TIME)"
+        _ <- execute conn "INSERT INTO times VALUES (?, ?)" (seconds, seconds)
+        (query_ conn "SELECT a, b FROM times" :: IO [(TimeWithZone, TimeOfDay)]) >>= (@?= [(seconds, TimeOfDay 12 0 0)])
+        -- DuckDB compares the instant first, and then the offset.
+        (query conn "SELECT count(*) FROM times WHERE a = ?" (Only seconds) :: IO [Only Int64]) >>= (@?= [Only 1])
+        (query conn "SELECT count(*) FROM times WHERE a = ?" (Only (at 12 0 3631)) :: IO [Only Int64]) >>= (@?= [Only 0])
+        (query conn "SELECT count(*) FROM times WHERE ? < a" (Only (at 12 0 3631)) :: IO [Only Int64]) >>= (@?= [Only 1])
+        (query conn "SELECT count(*) FROM times WHERE a = ?" (Only (TimeWithZone (TimeOfDay 10 59 30) 0)) :: IO [Only Int64]) >>= (@?= [Only 0])
+        -- The digits below one microsecond go away, as in SQL text.
+        (query conn "SELECT ?" (Only seconds{timeWithZoneTime = TimeOfDay 1 2 3.0000005}) :: IO [Only TimeWithZone])
+          >>= (@?= [Only seconds{timeWithZoneTime = TimeOfDay 1 2 3}])
+        (query conn "SELECT ?" (Only (Nothing :: Maybe TimeWithZone)) :: IO [Only (Maybe TimeWithZone)]) >>= (@?= [Only Nothing])
+        let times = [value, seconds, at 0 0 (-57599)]
+        (query conn "SELECT typeof(?), ?" (times, times) :: IO [(Text, [TimeWithZone])]) >>= (@?= [("TIME WITH TIME ZONE[]", times)])
+        let array = sized times :: SizedArray 3 TimeWithZone
+        (query conn "SELECT typeof(?), ?" (array, array) :: IO [(Text, [TimeWithZone])]) >>= (@?= [("TIME WITH TIME ZONE[3]", times)])
+        let nested = singleField (LogicalTypeScalar LogicalTypeIdTimeTz) (FieldTimeTZ seconds)
+        (query conn "SELECT ?, (?).value::VARCHAR" (nested, nested) :: IO [(StructValue FieldValue, Text)])
+          >>= (@?= [(nested, "12:00:00+01:00:30")])
+    , testCase "a DecimalValue binds as a DECIMAL with its own width and scale" $ withConnection ":memory:" \conn -> do
+        let value = DecimalValue 5 3 2125
+            roundTrip decimal = (query conn "SELECT ?" (Only decimal) :: IO [Only DecimalValue]) >>= (@?= [Only decimal])
+            stored column decimal = do
+              _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE decimals (v " <> column <> ")"))
+              _ <- execute conn "INSERT INTO decimals VALUES (?)" (Only decimal)
+              query_ conn "SELECT v FROM decimals" :: IO [Only DecimalValue]
+        (query conn "SELECT typeof(?), ?" (value, value) :: IO [(Text, DecimalValue)]) >>= (@?= [("DECIMAL(5,3)", value)])
+        -- A column of another width and scale gives its own type. DuckDB rounds
+        -- half away from zero.
+        stored "DECIMAL(4,2)" value >>= (@?= [Only (DecimalValue 4 2 213)])
+        stored "DECIMAL(4,2)" (DecimalValue 5 3 2135) >>= (@?= [Only (DecimalValue 4 2 214)])
+        stored "DECIMAL(4,2)" (DecimalValue 5 3 (-2125)) >>= (@?= [Only (DecimalValue 4 2 (-213))])
+        stored "DECIMAL(10,4)" value >>= (@?= [Only (DecimalValue 10 4 21250)])
+        try (stored "DECIMAL(4,2)" (DecimalValue 8 3 12345678)) >>= \case
+          Left SQLError{sqlErrorMessage, sqlErrorType} -> do
+            assertBool
+              (Text.unpack sqlErrorMessage)
+              ("Casting value \"12345.678\" to type DECIMAL(4,2) failed: value is out of range!" `Text.isInfixOf` sqlErrorMessage)
+            sqlErrorType @?= Just ErrorTypeConversion
+          Right rows -> assertFailure ("expected the DECIMAL range error, got " <> show rows)
+        stored "DECIMAL(3,2)" (DecimalValue 3 2 210) >>= (@?= [Only (DecimalValue 3 2 210)])
+        (query conn "SELECT count(*) FROM decimals WHERE v = ?" (Only (DecimalValue 2 1 21)) :: IO [Only Int64]) >>= (@?= [Only 1])
+        (query conn "SELECT count(*) FROM decimals WHERE v < ?" (Only (DecimalValue 5 2 211)) :: IO [Only Int64]) >>= (@?= [Only 1])
+        (query conn "SELECT typeof(? * 2), ? * 2" (value, value) :: IO [(Text, DecimalValue)]) >>= (@?= [("DECIMAL(15,3)", DecimalValue 15 3 4250)])
+        mapM_
+          roundTrip
+          [ DecimalValue 38 0 (10 ^ (38 :: Int) - 1)
+          , DecimalValue 38 0 (negate (10 ^ (38 :: Int) - 1))
+          , DecimalValue 38 38 1
+          , DecimalValue 2 1 (-15)
+          , DecimalValue 1 0 7
+          ]
+        -- The encoder raises an error for a value that it cannot encode.
+        assertRangeError (query conn "SELECT ?" (Only (DecimalValue 2 1 100)) :: IO [Only DecimalValue])
+        forM_ [DecimalValue 39 0 1, DecimalValue 2 3 1, DecimalValue 0 0 0] \decimal ->
+          assertInputError (query conn "SELECT ?" (Only decimal) :: IO [Only DecimalValue])
+        (query conn "SELECT ?" (Only (Nothing :: Maybe DecimalValue)) :: IO [Only (Maybe DecimalValue)]) >>= (@?= [Only Nothing])
+    , testCase "a Map binds as a MAP parameter in each SQL form" $ withConnection ":memory:" \conn -> do
+        let pairs = Map.fromList [("a", 1), ("b", 2)] :: Map.Map Text Int64
+            none = Map.empty :: Map.Map Text Int64
+            rejected :: (ToField a) => Text -> a -> Assertion
+            rejected message value =
+              try (query conn "SELECT ?::VARCHAR" (Only value) :: IO [Only Text]) >>= \case
+                Left SQLError{sqlErrorMessage, sqlErrorType} -> do
+                  sqlErrorMessage @?= message
+                  sqlErrorType @?= Just ErrorInputInvalid
+                Right rows -> assertFailure ("expected " <> Text.unpack message <> ", got " <> show rows)
+        forM_ [pairs, none] \value ->
+          (query conn "SELECT typeof(?), ?" (value, value) :: IO [(Text, Map.Map Text Int64)]) >>= (@?= [("MAP(VARCHAR, BIGINT)", value)])
+        -- DuckDB casts the keys and the values to the types of the column.
+        forM_ ["MAP(VARCHAR, BIGINT)", "MAP(VARCHAR, INTEGER)"] \dtype -> do
+          _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE map_value (i BIGINT, m " <> dtype <> ")"))
+          _ <- executeMany conn "INSERT INTO map_value VALUES (?, ?)" [(0 :: Int64, pairs), (1, none)]
+          (query_ conn "SELECT m FROM map_value ORDER BY i" :: IO [Only (Map.Map Text Int64)])
+            >>= assertEqual (Text.unpack dtype) [Only pairs, Only none]
+        _ <- execute_ conn "CREATE TABLE integer_keys (m MAP(INTEGER, BIGINT))"
+        _ <- execute conn "INSERT INTO integer_keys VALUES (?)" (Only (Map.fromList [("1", 1)] :: Map.Map Text Int64))
+        (query_ conn "SELECT m FROM integer_keys" :: IO [Only (Map.Map Int32 Int64)]) >>= (@?= [Only (Map.fromList [(1, 1)])])
+        try (execute conn "INSERT INTO integer_keys VALUES (?)" (Only pairs)) >>= \case
+          Left SQLError{sqlErrorMessage, sqlErrorType} -> do
+            assertBool (Text.unpack sqlErrorMessage) ("Conversion Error: Could not convert string 'a' to INT32" `Text.isPrefixOf` sqlErrorMessage)
+            sqlErrorType @?= Just ErrorTypeConversion
+          Right (_ :: Int) -> assertFailure "expected the DuckDB key conversion error"
+        -- DuckDB compares two MAP values pair by pair in their order. A map binds
+        -- its pairs in ascending key order.
+        _ <- execute_ conn "CREATE TABLE ordered_maps (m MAP(VARCHAR, BIGINT))"
+        _ <- execute_ conn "INSERT INTO ordered_maps VALUES (MAP {'b': 2, 'a': 1}), (MAP {'a': 1, 'b': 2})"
+        (query conn "SELECT count(*) FROM ordered_maps WHERE m = ?" (Only pairs) :: IO [Only Int64]) >>= (@?= [Only 1])
+        (query_ conn "SELECT m FROM ordered_maps" :: IO [Only (Map.Map Text Int64)]) >>= (@?= [Only pairs, Only pairs])
+        ( query conn "SELECT map_extract(?, 'a'), (?)['a'], map_keys(?), element_at(?, 'b')" (pairs, pairs, pairs, pairs)
+            :: IO [([Int64], Int64, [Text], [Int64])]
+          )
+          >>= (@?= [([1], 1, ["a", "b"], [2])])
+        -- A Haskell map can hold two NaN keys. DuckDB rejects them and a NULL key.
+        let nan = 0 / 0 :: Double
+        rejected "Invalid Input Error: Map keys must be unique." (Map.insert nan 2 (Map.fromList [(nan, 1)]) :: Map.Map Double Int64)
+        rejected "Invalid Input Error: Map keys can not be NULL." (Map.fromList [(Nothing, 1), (Just "a", 2)] :: Map.Map (Maybe Text) Int64)
+    , testCase "a Map binds NULL, nested, Integer, and UTC values" $ withConnection ":memory:" \conn -> do
+        let withNull = Map.fromList [("a", Just 1), ("b", Nothing)] :: Map.Map Text (Maybe Int64)
+            nested = Map.fromList [("a", [1, 2]), ("b", [])] :: Map.Map Text [Int64]
+            pairs = Map.fromList [("a", 1)] :: Map.Map Text Int64
+        (query conn "SELECT typeof(?), ?" (withNull, withNull) :: IO [(Text, Map.Map Text (Maybe Int64))])
+          >>= (@?= [("MAP(VARCHAR, BIGINT)", withNull)])
+        (query conn "SELECT typeof(?), ?" (nested, nested) :: IO [(Text, Map.Map Text [Int64])]) >>= (@?= [("MAP(VARCHAR, BIGINT[])", nested)])
+        (query conn "SELECT ?" (Only (Nothing :: Maybe (Map.Map Text Int64))) :: IO [Only (Maybe (Map.Map Text Int64))]) >>= (@?= [Only Nothing])
+        (query conn "SELECT typeof(?), ?" ([pairs, Map.empty], [pairs, Map.empty]) :: IO [(Text, [Map.Map Text Int64])])
+          >>= (@?= [("MAP(VARCHAR, BIGINT)[]", [pairs, Map.empty])])
+        -- An Integer value takes the value type of its target.
+        let insert :: Map.Map Text Integer -> IO (Either SQLError Int)
+            insert value = do
+              _ <- execute_ conn "CREATE OR REPLACE TABLE unsigned_map (m MAP(VARCHAR, UBIGINT))"
+              try (execute conn "INSERT INTO unsigned_map VALUES (?)" (Only value))
+        insert (Map.fromList [("a", 5), ("b", 6)]) >>= either (assertFailure . show) (const (pure ()))
+        (query_ conn "SELECT m::VARCHAR FROM unsigned_map" :: IO [Only Text]) >>= (@?= [Only "{a=5, b=6}"])
+        insert (Map.fromList [("a", -5)]) >>= \case
+          Left SQLError{sqlErrorType} -> sqlErrorType @?= Just ErrorInputInvalid
+          Right _ -> assertFailure "expected the DuckDB range error for -5"
+        insert (Map.fromList [("a", 2 ^ (130 :: Int))]) >>= \case
+          Left SQLError{sqlErrorType} -> sqlErrorType @?= Just ErrorTypeConversion
+          Right _ -> assertFailure "expected the duckdb-simple range error for 2^130"
+        (query conn "SELECT typeof(?)" (Only (Map.fromList [("a", 5)] :: Map.Map Text Integer)) :: IO [Only Text])
+          >>= (@?= [Only "MAP(VARCHAR, HUGEINT)"])
+        -- A UTC value keeps its nanoseconds for a nanosecond target.
+        let times = Map.fromList [("t", posixSecondsToUTCTime 0.123456789)] :: Map.Map Text UTCTime
+        (query conn "SELECT ?::MAP(VARCHAR, TIMESTAMPTZ_NS)" (Only times) :: IO [Only (Map.Map Text UTCTime)]) >>= (@?= [Only times])
+        -- An empty map of nested values has the value type NULL, as in MAP {}.
+        (query conn "SELECT typeof(?), ?::VARCHAR" (Map.empty :: Map.Map Text [Int64], Map.empty :: Map.Map Text [Int64]) :: IO [(Text, Text)])
+          >>= (@?= [("MAP(VARCHAR, \"NULL\")", "{}")])
+    , testCase "an array of BigNum values keeps the BIGNUM casts of DuckDB" $ withConnection ":memory:" \conn -> do
+        -- DuckDB 2.0.0 casts the BIGNUM -6 to UBIGINT as a wrapped value with no
+        -- error. See Note [Integer parameters] in "Database.DuckDB.Simple.ToField".
+        forM_
+          [ ("BIGINT[2]", [BigNum 5, BigNum 6], "[5, 6]")
+          , ("BIGNUM[2]", [BigNum 5, BigNum 6], "[5, 6]")
+          , ("UBIGINT[2]", [BigNum 5, BigNum (-6)], "[5, 18446744073709551610]")
+          ]
+          \(dtype, values, expected) -> do
+            _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE bignum_array (v " <> dtype <> ")"))
+            _ <- execute conn "INSERT INTO bignum_array VALUES (?)" (Only (sized values :: SizedArray 2 BigNum))
+            (query_ conn "SELECT v::VARCHAR FROM bignum_array" :: IO [Only Text]) >>= assertEqual (Text.unpack dtype) [Only expected]
+    , testCase "native timestamp extrema read back in all units, and bind back only in the range of DuckDB" $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+        let checkTemporalFailure :: forall a. (FromField a) => Query -> Proxy a -> Text -> IO ()
+            checkTemporalFailure sql _ target = do
+              assertConversionError (query_ conn sql :: IO [Only a])
+              results <- queryWith_ (fieldWith (liftConversion . runConversion . (fromField :: Field -> Conversion a))) conn sql
+              case results of
+                [Errors [failure]] -> case fromException failure of
+                  Just ConversionFailed{errHaskellType} -> errHaskellType @?= target
+                  _ -> assertFailure ("expected ConversionFailed, got " <> show failure)
+                _ -> assertFailure ("expected one conversion failure for " <> Text.unpack target)
+        let epoch = fromGregorian 1970 1 1
+            lowerDay = toInteger (minBound :: Int64) `div` 86400000000
+            upperDay = toInteger (maxBound :: Int64) `div` 86400000000
+            dates =
+              [fromGregorian 2000 1 2, fromGregorian (-500000) 1 1, fromGregorian 500000 1 1]
+                <> map (`addDays` epoch) [-2147483646, 2147483646, lowerDay, lowerDay + 1, upperDay, upperDay + 1]
+        -- DATE itself has a wider range than the intermediate of a timestamp cast.
+        _ <- execute_ conn "CREATE TABLE native_date(value DATE)"
+        forM_ dates \day -> do
+          _ <- execute conn "INSERT INTO native_date VALUES (?)" (Only day)
+          (query_ conn "SELECT value FROM native_date" :: IO [Only Day]) >>= (@?= [Only day])
+          (query_ conn "SELECT value FROM native_date" :: IO [Only (Unbounded Day)]) >>= (@?= [Only (Finite day)])
+          let expected = LocalTime day (TimeOfDay 0 0 0)
+              micros = diffDays day epoch * 86400000000
+          if micros >= toInteger (minBound :: Int64) && micros <= toInteger (maxBound :: Int64)
+            then do
+              (query_ conn "SELECT value::TIMESTAMP FROM native_date" :: IO [Only LocalTime]) >>= (@?= [Only expected])
+              (query_ conn "SELECT value FROM native_date" :: IO [Only LocalTime]) >>= (@?= [Only expected])
+              (query_ conn "SELECT value FROM native_date" :: IO [Only (Unbounded LocalTime)]) >>= (@?= [Only (Finite expected)])
+            else do
+              checkTemporalFailure "SELECT value FROM native_date" (Proxy @LocalTime) "LocalTime"
+              checkTemporalFailure "SELECT value FROM native_date" (Proxy @(Unbounded LocalTime)) "Unbounded LocalTime"
+              forM_ ["TIMESTAMP", "TIMESTAMP_S", "TIMESTAMP_MS", "TIMESTAMP_NS"] \dtype ->
+                try (query_ conn (fromString ("SELECT value::" <> dtype <> " FROM native_date")) :: IO [Only LocalTime]) >>= \case
+                  Left SQLError{sqlErrorType} -> sqlErrorType @?= Just ErrorTypeConversion
+                  Right rows -> assertFailure ("expected the native timestamp cast to fail, got " <> show rows)
+              (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+          _ <- execute_ conn "DELETE FROM native_date"
+          pure ()
+        _ <- execute_ conn "DROP TABLE native_date"
+        forM_ [("-infinity", NegInfinity), ("infinity", PosInfinity)] \(literal, expected) -> do
+          let sql = fromString ("SELECT '" <> literal <> "'::DATE")
+              cast = fromString ("SELECT '" <> literal <> "'::DATE::TIMESTAMP")
+          assertConversionError (query_ conn sql :: IO [Only LocalTime])
+          (query_ conn sql :: IO [Only (Unbounded LocalTime)]) >>= (@?= [Only expected])
+          (query_ conn cast :: IO [Only (Unbounded LocalTime)]) >>= (@?= [Only expected])
+        forM_
+          [ (Seconds, 1, "TIMESTAMP_S")
+          , (Milliseconds, 1000, "TIMESTAMP_MS")
+          , (Microseconds, 1000000, "TIMESTAMP")
+          , (Nanoseconds, 1000000000, "TIMESTAMP_NS")
+          ]
+          \(constructor, units, dtype) -> do
+            let extraValues
+                  | units <= 1000 =
+                      let limit = toInteger (maxBound :: Int64) `div` (1000000 `div` units)
+                      in  map
+                            fromInteger
+                            ( [-limit - 1, -limit, limit, limit + 1]
+                                <> [days * 86400 * units | days <- [-2147483648, -2147483647, -2147483646, 2147483646, 2147483647, 2147483648]]
+                            )
+                  | units == 1000000000 =
+                      let day = 86400000000000
+                      in  [-1, -499, -500, -501, day - 1, day - 499, day - 500, day - 501]
+                  | otherwise = []
+            forM_ ([minBound, negate (maxBound :: Int64) + 1, -1, 0, maxBound - 1] <> extraValues) \value -> do
+              let expected = utcToLocalTime utc (posixSecondsToUTCTime (fromRational (toInteger value % units)))
+                  micros = toInteger value * 1000000 `div` units
+              appendTimestamp conn dtype (constructor value)
+              (query_ conn "SELECT value FROM native_timestamp" :: IO [Only LocalTime]) >>= (@?= [Only expected])
+              (query_ conn "SELECT value FROM native_timestamp" :: IO [Only (Unbounded LocalTime)]) >>= (@?= [Only (Finite expected)])
+              -- S/MS casts check a microsecond intermediate. NS casts round it
+              -- to the nearest microsecond before they extract the date.
+              if micros >= toInteger (minBound :: Int64) && micros <= toInteger (maxBound :: Int64)
+                then do
+                  [Only day] <- query_ conn "SELECT value::DATE FROM native_timestamp" :: IO [Only Day]
+                  (query_ conn "SELECT value FROM native_timestamp" :: IO [Only Day]) >>= (@?= [Only day])
+                  (query_ conn "SELECT value FROM native_timestamp" :: IO [Only (Unbounded Day)]) >>= (@?= [Only (Finite day)])
+                  let timeType = if units == 1000000000 then "TIME_NS" else "TIME"
+                  [Only clock] <- query_ conn (fromString ("SELECT value::" <> timeType <> " FROM native_timestamp")) :: IO [Only TimeOfDay]
+                  (query_ conn "SELECT value FROM native_timestamp" :: IO [Only TimeOfDay]) >>= (@?= [Only clock])
+                else do
+                  checkTemporalFailure "SELECT value FROM native_timestamp" (Proxy @Day) "Day"
+                  checkTemporalFailure "SELECT value FROM native_timestamp" (Proxy @(Unbounded Day)) "Unbounded Day"
+                  checkTemporalFailure "SELECT value FROM native_timestamp" (Proxy @TimeOfDay) "TimeOfDay"
+                  try (query_ conn "SELECT value::DATE FROM native_timestamp" :: IO [Only Day]) >>= \case
+                    Left SQLError{sqlErrorType} -> sqlErrorType @?= Just ErrorTypeConversion
+                    Right rows -> assertFailure ("expected the native DATE cast to fail, got " <> show rows)
+                  try (query_ conn "SELECT value::TIME FROM native_timestamp" :: IO [Only TimeOfDay]) >>= \case
+                    Left SQLError{sqlErrorType} -> sqlErrorType @?= Just ErrorTypeConversion
+                    Right rows -> assertFailure ("expected the native TIME cast to fail, got " <> show rows)
+                  (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+              [Only original] <- query_ conn "SELECT {'value': value} FROM native_timestamp" :: IO [Only (StructValue FieldValue)]
+              -- DuckDB needs an explicit parameter type for extreme S/MS values.
+              let rebind = query conn (fromString ("SELECT ?::STRUCT(value " <> dtype <> ")")) (Only original)
+              -- A second, millisecond, or microsecond value outside the range of
+              -- DuckDB raises an error. See Note [Time ranges] in
+              -- "Database.DuckDB.Simple.ToField".
+              if units == 1000000000 || (micros >= -9223372022400000000 && micros <= 9223372036854775806)
+                then rebind >>= (@?= [Only original])
+                else assertOutsideTimeRange rebind
+              _ <- execute_ conn "DROP TABLE native_timestamp"
+              pure ()
+            forM_ [("-infinity", NegInfinity), ("infinity", PosInfinity)] \(literal, expected) -> do
+              let sql = fromString ("SELECT '" <> literal <> "'::" <> dtype)
+                  cast = fromString ("SELECT '" <> literal <> "'::" <> dtype <> "::DATE")
+              assertConversionError (query_ conn sql :: IO [Only Day])
+              (query_ conn sql :: IO [Only (Unbounded Day)]) >>= (@?= [Only expected])
+              (query_ conn cast :: IO [Only (Unbounded Day)]) >>= (@?= [Only expected])
+    , testCase "composite timestamps reject infinity and storage overflow" $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
+        -- Only a nanosecond value has the range of its storage. See
+        -- Note [Time ranges] in "Database.DuckDB.Simple.ToField".
+        forM_
+          [ (LogicalTypeIdTimestampSec, 1, assertOutsideTimeRange)
+          , (LogicalTypeIdTimestampMs, 1000, assertOutsideTimeRange)
+          , (LogicalTypeIdTimestamp, 1000000, assertOutsideTimeRange)
+          , (LogicalTypeIdTimestampNs, 1000000000, assertRangeError)
+          ]
+          \(dtype, units, rejected) ->
+            forM_
+              [ toInteger (minBound :: Int64) - 1
+              , negate (toInteger (maxBound :: Int64))
+              , toInteger (maxBound :: Int64)
+              , toInteger (maxBound :: Int64) + 1
+              ]
+              \value -> do
+                let timestamp = utcToLocalTime utc (posixSecondsToUTCTime (fromRational (value % units)))
+                    struct = singleField (LogicalTypeScalar dtype) (FieldTimestamp (Finite timestamp))
+                rejected (query conn "SELECT ?" (Only struct) :: IO [Only FieldValue])
+    , testCase "composite timestamps floor fractional units before the epoch" $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
+        forM_
+          [ (LogicalTypeIdTimestampSec, 1)
+          , (LogicalTypeIdTimestampMs, 1000)
+          , (LogicalTypeIdTimestamp, 1000000)
+          , (LogicalTypeIdTimestampNs, 1000000000)
+          ]
+          \(dtype, units) -> do
+            let timestamp = utcToLocalTime utc (posixSecondsToUTCTime (fromRational ((-1) % (2 * units))))
+                expected = utcToLocalTime utc (posixSecondsToUTCTime (fromRational ((-1) % units)))
+                struct = singleField (LogicalTypeScalar dtype) (FieldTimestamp (Finite timestamp))
+            (query conn "SELECT (?).value" (Only struct) :: IO [Only LocalTime]) >>= (@?= [Only expected])
+    , testCase "composite TIME_NS rejects invalid clock components" $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
+        -- A field outside its own range and a time with valid fields after
+        -- 24:00:00 are both outside the range of TIME_NS.
+        forM_
+          [ TimeOfDay (-1) 0 0
+          , TimeOfDay 0 60 0
+          , TimeOfDay 0 0 (-1)
+          , TimeOfDay 25 0 0
+          , TimeOfDay 24 0 0.000000001
+          , TimeOfDay 23 59 60.000000001
+          ]
+          \value ->
+            assertRangeError
+              (query conn "SELECT ?" (Only (singleField (LogicalTypeScalar LogicalTypeIdTimeNs) (FieldTime value))) :: IO [Only FieldValue])
+    , testCase "microsecond timestamps round trip at the ends of the range of DuckDB" $ withConnection ":memory:" \conn -> do
+        let local (micros :: Int64) = utcToLocalTime utc (posixSecondsToUTCTime (fromRational (toInteger micros % 1000000)))
+        forM_ [-9223372022400000000, -1, 0, maxBound - 1] \value -> do
+          _ <- execute_ conn "CREATE TABLE microsecond_timestamp(value TIMESTAMP)"
+          _ <- execute conn "INSERT INTO microsecond_timestamp VALUES (?)" (Only (local value))
+          (query_ conn "SELECT value FROM microsecond_timestamp" :: IO [Only LocalTime]) >>= (@?= [Only (local value)])
+          _ <- execute_ conn "DROP TABLE microsecond_timestamp"
+          pure ()
+        -- The INT64 storage also holds the four hours before the range, but
+        -- DuckDB does not accept them.
+        forM_ [minBound, negate (maxBound :: Int64) + 1, -9223372022400000001] \value ->
+          assertOutsideTimeRange (query conn "SELECT ?" (Only (local value)) :: IO [Only LocalTime])
+    , testCase "out-of-range dates and timestamps fail without abort" $ withConnection ":memory:" \conn -> do
+        let hugeDay = fromGregorian 10000000 1 1
+            local = LocalTime hugeDay (TimeOfDay 0 0 0)
+        assertOutsideTimeRange (query conn "SELECT ?" (Only hugeDay) :: IO [Only Day])
+        assertOutsideTimeRange (query conn "SELECT ?" (Only local) :: IO [Only LocalTime])
+        assertOutsideTimeRange (query conn "SELECT ?" (Only (UTCTime hugeDay 0)) :: IO [Only UTCTime])
+    , testCase "dates round trip at the ends of the range of DuckDB" $ withConnection ":memory:" \conn -> do
+        forM_ [negate (maxBound :: Int32) + 1, -1, 0, maxBound - 1] \value -> do
+          let day = addDays (toInteger value) (fromGregorian 1970 1 1)
+          (query conn "SELECT ?" (Only day) :: IO [Only Day]) >>= (@?= [Only day])
+        -- The INT32 storage also holds day -2147483648, but DuckDB does not accept it.
+        assertOutsideTimeRange (query conn "SELECT ?" (Only (addDays (toInteger (minBound :: Int32)) (fromGregorian 1970 1 1))) :: IO [Only Day])
+    , testCase "input infinity sentinels are rejected" $ withConnection ":memory:" \conn -> do
+        forM_ [toInteger (maxBound :: Int32), negate (toInteger (maxBound :: Int32))] \days ->
+          assertOutsideTimeRange (query conn "SELECT ?" (Only (addDays days (fromGregorian 1970 1 1))) :: IO [Only Day])
+        forM_ [toInteger (maxBound :: Int64), negate (toInteger (maxBound :: Int64))] \micros -> do
+          let value = utcToLocalTime utc (posixSecondsToUTCTime (fromRational (micros % 1000000)))
+          assertOutsideTimeRange (query conn "SELECT ?" (Only value) :: IO [Only LocalTime])
+    , testCase "UTC binding is TIMESTAMPTZ under a non-UTC zone" $ withConnection ":memory:" \conn -> do
+        _ <- execute_ conn "SET TimeZone = 'Pacific/Auckland'"
+        let value = UTCTime (fromGregorian 2000 1 2) 12345
+        (query conn "SELECT typeof(?), ?" (value, value) :: IO [(Text, UTCTime)]) >>= (@?= [("TIMESTAMP WITH TIME ZONE", value)])
+        _ <- execute_ conn "CREATE TABLE utc_binding(value TIMESTAMPTZ)"
+        _ <- execute conn "INSERT INTO utc_binding VALUES (?)" (Only value)
+        (query_ conn "SELECT value FROM utc_binding" :: IO [Only UTCTime]) >>= (@?= [Only value])
+    , testCase "DECIMAL(38) retains exact integer precision" $ withConnection ":memory:" \conn -> do
+        let decimal = DecimalValue 38 9 12345678901234567890123456789012345678
+            struct = singleField (LogicalTypeDecimal 38 9) (FieldDecimal decimal)
+        [Only result] <- query conn "SELECT ?" (Only struct) :: IO [Only (StructValue FieldValue)]
+        structValueFields result @?= structValueFields struct
+    , testCase "DECIMAL and ENUM columns decode at each storage width" $ withConnection ":memory:" \conn -> do
+        -- Each column has a NULL between values, so one reader serves valid and invalid rows.
+        forM_ [(4, 1), (9, 3), (18, 3), (38, 9)] \(width, scale) -> do
+          let dtype = "DECIMAL(" <> Text.pack (show width) <> "," <> Text.pack (show scale) <> ")"
+              decimal units = FieldDecimal (DecimalValue width scale (units * 10 ^ scale))
+          rows <-
+            query_ conn (Query ("SELECT CASE WHEN i = 1 THEN NULL ELSE (i - 2)::" <> dtype <> " END FROM range(4) t(i)")) :: IO [Only FieldValue]
+          rows @?= map Only [decimal (-2), FieldNull, decimal 0, decimal 1]
+        forM_ [200, 300, 70000 :: Int] \size -> do
+          let label index = "v" <> Text.pack (show index)
+              dtype = "enum_width_" <> Text.pack (show size)
+          _ <-
+            execute_
+              conn
+              (Query ("CREATE TYPE " <> dtype <> " AS ENUM (" <> Text.intercalate "," ["'" <> label index <> "'" | index <- [0 .. size - 1]] <> ")"))
+          rows <-
+            query_ conn (Query ("SELECT x::" <> dtype <> " FROM (VALUES ('v0'), (NULL), ('" <> label (size - 1) <> "')) t(x)")) :: IO [Only FieldValue]
+          rows @?= map Only [FieldEnum 0 (label (0 :: Int)), FieldNull, FieldEnum (fromIntegral (size - 1)) (label (size - 1))]
+    , testCase "DECIMAL and BIGINT values read as Double and Float give the casts of DuckDB" $ withConnection ":memory:" \conn -> do
+        -- Each row has the read of v as Double and Float, and the casts of v
+        -- to DOUBLE and FLOAT read at their own types. The value lists are
+        -- fixed. See Note [DECIMAL as DOUBLE and FLOAT] in
+        -- "Database.DuckDB.Simple.FromField". For scale 0 and a width of 19
+        -- to 38, the library copies the cast of DuckDB 2.0.0, which is not
+        -- always the nearest value. If a later DuckDB version changes the
+        -- rounding of that cast, the first assertion fails and shows the new
+        -- values of DuckDB. DuckDB 2.0.0 gives these values. The nearest values
+        -- are -9007199254740994 and 3.3569516755834854e36.
+        query_ conn "SELECT (-9007199254740994)::DECIMAL(19,0)::DOUBLE, 3356951675583485076575379654993209529::DECIMAL(38,0)::DOUBLE"
+          >>= (@?= [(-9007199254740992 :: Double, 3.356951675583485e36 :: Double)])
+        let bigints =
+              filter (\v -> v >= toInteger (minBound :: Int64) && v <= toInteger (maxBound :: Int64)) (toInteger (minBound :: Int64) : decimalIntegers 19)
+            kinds =
+              [ ("DECIMAL(" <> show width <> "," <> show scale <> ")", map (decimalText scale) (decimalIntegers width <> roundingTies width scale))
+              | (width, scale) <- decimalKinds
+              ]
+                <> [("BIGINT", map (Text.pack . show) bigints)]
+        forM_ kinds \(sqlType, texts) -> do
+          rows <-
+            query
+              conn
+              (fromString ("SELECT s, v, v::DOUBLE, v, v::FLOAT FROM (SELECT s, s::" <> sqlType <> " AS v FROM unnest(?::VARCHAR[]) t(s))"))
+              (Only texts)
+              :: IO [(Text, Double, Double, Float, Float)]
+          length rows @?= length texts
+          [(sqlType, text, value, cast) | (text, value, cast, _, _) <- rows, castDoubleToWord64 value /= castDoubleToWord64 cast] @?= []
+          if sqlType /= "BIGINT"
+            then [(sqlType, text, value, cast) | (text, _, _, value, cast) <- rows, castFloatToWord32 value /= castFloatToWord32 cast] @?= []
+            else do
+              -- CI on macOS (Apple Silicon) showed a cast of DuckDB 2.0.0 from
+              -- BIGINT to FLOAT that rounds two times, through DOUBLE, for some
+              -- values above 2^53: 9007199791611905 gave 9.007199e15, and the
+              -- nearest FLOAT is 9.0072e15. On Linux x86-64 and aarch64 the cast
+              -- gave the nearest value. The read of the library is the nearest
+              -- value on each platform. The cast of DuckDB is one of the two.
+              let integer text = read (Text.unpack text) :: Integer
+                  nearest text = fromRational (toRational (integer text)) :: Float
+                  throughDouble text = realToFrac (fromInteger (integer text) :: Double) :: Float
+                  bits = castFloatToWord32
+              [(text, value) | (text, _, _, value, _) <- rows, bits value /= bits (nearest text)] @?= []
+              [(text, cast) | (text, _, _, _, cast) <- rows, bits cast `notElem` [bits (nearest text), bits (throughDouble text)]] @?= []
+    , testCase "a read of another SQL type gives the value of the cast of DuckDB" $ withConnection ":memory:" \conn -> do
+        -- Each value reads as the Haskell type, next to its cast to the SQL
+        -- type of the Haskell type in the same row. See
+        -- Note [Reads of another SQL type] in "Database.DuckDB.Simple.FromField".
+        let signedValues = ["-100", "0", "7", "100"]
+            unsignedValues = ["0", "7", "100"]
+            signedSources = ["TINYINT", "SMALLINT", "INTEGER", "BIGINT", "HUGEINT"]
+            unsignedSources = ["UTINYINT", "USMALLINT", "UINTEGER", "UBIGINT", "UHUGEINT"]
+            signedTarget :: (FromField a, Eq a, Show a) => Proxy a -> Text -> Assertion
+            signedTarget proxy target = do
+              forM_ signedSources \source -> assertReadsAsCast conn proxy source target signedValues
+              assertReadsAsCast conn proxy "UHUGEINT" target unsignedValues
+            unsignedTarget :: (FromField a, Eq a, Show a) => Proxy a -> Text -> Assertion
+            unsignedTarget proxy target = forM_ (signedSources <> unsignedSources) \source -> assertReadsAsCast conn proxy source target unsignedValues
+            timestamps = ["2024-01-02 03:04:05", "1969-12-31 23:59:59"]
+            timePairs = do
+              forM_ ["TIMESTAMP", "TIMESTAMP_S", "TIMESTAMP_MS", "TIMESTAMP_NS"] \source -> do
+                assertReadsAsCast conn (Proxy @Day) source "DATE" timestamps
+                assertReadsAsCast conn (Proxy @(Unbounded Day)) source "DATE" timestamps
+              assertReadsAsCast conn (Proxy @(Unbounded Day)) "TIMESTAMP" "DATE" ["infinity", "-infinity"]
+              forM_ ["TIMESTAMP", "TIMESTAMP_S", "TIMESTAMP_MS"] \source -> assertReadsAsCast conn (Proxy @TimeOfDay) source "TIME" timestamps
+              assertReadsAsCast conn (Proxy @TimeOfDay) "TIMESTAMP" "TIME" ["2024-01-02 03:04:05.123456"]
+              assertReadsAsCast
+                conn
+                (Proxy @TimeOfDay)
+                "TIMESTAMP_NS"
+                "TIME_NS"
+                ["2024-01-02 03:04:05.123456789", "1969-12-31 23:59:59.999999999"]
+              forM_ [("DATE", ["2024-01-02", "1969-12-31"]), ("TIMESTAMP_S", timestamps), ("TIMESTAMP_MS", timestamps)] \(source, values) -> do
+                assertReadsAsCast conn (Proxy @LocalTime) source "TIMESTAMP" values
+                assertReadsAsCast conn (Proxy @(Unbounded LocalTime)) source "TIMESTAMP" values
+              assertReadsAsCast conn (Proxy @(Unbounded LocalTime)) "DATE" "TIMESTAMP" ["infinity", "-infinity"]
+        signedTarget (Proxy @Int8) "TINYINT"
+        signedTarget (Proxy @Int16) "SMALLINT"
+        signedTarget (Proxy @Int32) "INTEGER"
+        signedTarget (Proxy @Int64) "BIGINT"
+        signedTarget (Proxy @Int) "BIGINT"
+        signedTarget (Proxy @Integer) "BIGNUM"
+        forM_ unsignedSources \source -> assertReadsAsCast conn (Proxy @Integer) source "BIGNUM" unsignedValues
+        unsignedTarget (Proxy @Natural) "BIGNUM"
+        unsignedTarget (Proxy @Word8) "UTINYINT"
+        unsignedTarget (Proxy @Word16) "USMALLINT"
+        unsignedTarget (Proxy @Word32) "UINTEGER"
+        unsignedTarget (Proxy @Word64) "UBIGINT"
+        unsignedTarget (Proxy @Word) "UBIGINT"
+        forM_ (take 4 signedSources) \source -> do
+          assertReadsAsCast conn (Proxy @Bool) source "BOOLEAN" ["-2", "0", "1", "7"]
+          assertReadsAsCast conn (Proxy @Double) source "DOUBLE" signedValues
+          assertReadsAsCast conn (Proxy @Float) source "FLOAT" signedValues
+          assertReadsAsCast conn (Proxy @Text) source "VARCHAR" signedValues
+          assertReadsAsCast conn (Proxy @String) source "VARCHAR" signedValues
+        assertReadsAsCast conn (Proxy @Double) "BIGINT" "DOUBLE" ["9007199254740993", "-9223372036854775808"]
+        assertReadsAsCast conn (Proxy @Double) "FLOAT" "DOUBLE" ["1.25", "0.1", "-3.5"]
+        assertReadsAsCast conn (Proxy @Float) "DOUBLE" "FLOAT" ["1.25", "0.1", "16777217"]
+        assertReadsAsCast conn (Proxy @Text) "BOOLEAN" "VARCHAR" ["true", "false"]
+        assertReadsAsCast conn (Proxy @String) "BOOLEAN" "VARCHAR" ["true", "false"]
+        assertReadsAsCast conn (Proxy @BS.ByteString) "BIT" "BLOB" ["101", "10110011101", "00000000"]
+        assertReadsAsCast conn (Proxy @BS.ByteString) "GEOMETRY" "BLOB" ["POINT (1 2)", "LINESTRING (0 0, 1 1)"]
+        assertReadsAsCast
+          conn
+          (Proxy @UUID.UUID)
+          "VARCHAR"
+          "UUID"
+          ["00000000-0000-0000-0000-000000000000", "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"]
+        assertReadsAsCast conn (Proxy @[Int32]) "INTEGER[3]" "INTEGER[]" ["[1, 2, 3]", "[-1, 2, 0]"]
+        -- An ENUM value reads as its label, the text of the cast to VARCHAR.
+        assertReadsAsCast conn (Proxy @Text) "ENUM('10', 'beta')" "VARCHAR" ["10", "beta"]
+        assertReadsAsCast conn (Proxy @String) "ENUM('10', 'beta')" "VARCHAR" ["10", "beta"]
+        -- The time pairs do not use the session time zone.
+        timePairs
+        _ <- execute_ conn "SET TimeZone = 'Pacific/Auckland'"
+        timePairs
+    , testCase "a field of a generic record reads the SQL types of the top-level read" $ withConnection ":memory:" \conn -> do
+        -- See Note [Reads of another SQL type] in "Database.DuckDB.Simple.FromField".
+        [Only column] <- query_ conn "SELECT [1, 2, 3]::INTEGER[3]" :: IO [Only [Int32]]
+        let holder list array map' = "SELECT {'listField': " <> list <> ", 'arrayField': " <> array <> ", 'mapField': " <> map' <> "}"
+        (query_ conn (Query (holder "[1, 2, 3]::INTEGER[3]" "[4, 5]::INTEGER[2]" "MAP {'k': 6}")) :: IO [Only Holder])
+          >>= (@?= [Only (Holder column (sized [4, 5]) (Map.singleton "k" 6))])
+        -- The error of a value that a decoder does not read names its SQL type.
+        let refused :: forall a. (FromField a, Show a) => Proxy a -> Text -> Text -> Assertion
+            refused _ sql expected =
+              try (query_ conn (Query sql) :: IO [Only a]) >>= \case
+                Left SQLError{sqlErrorMessage} -> sqlErrorMessage @?= expected
+                Right rows -> assertFailure ("expected an error for " <> Text.unpack sql <> ", got " <> show rows)
+        refused
+          (Proxy @Holder)
+          (holder "MAP {'k': 1}" "[4, 5]::INTEGER[2]" "MAP {'k': 6}")
+          "duckdb-simple: field listField: a value has type MAP(VARCHAR, INTEGER) but expected LIST or ARRAY"
+        refused
+          (Proxy @Holder)
+          (holder "[1]" "[4, 5, 6]" "MAP {'k': 6}")
+          "duckdb-simple: field arrayField: a value has type INTEGER[] but expected SizedArray 2: the value has 3 elements"
+        refused
+          (Proxy @Holder)
+          (holder "[1]" "[4, 5]::INTEGER[2]" "[6]")
+          "duckdb-simple: field mapField: a value has type INTEGER[] but expected MAP"
+        refused (Proxy @Holder) "SELECT 7" "duckdb-simple: a value has type INTEGER but expected STRUCT for a product type"
+        refused (Proxy @Colour) "SELECT {'a': 1}" "duckdb-simple: a value has type STRUCT but expected UNION for a sum type"
+        refused
+          (Proxy @Colour)
+          "SELECT union_value(Red := 1)::UNION(Red INTEGER, Blue INTEGER)"
+          "duckdb-simple: a value has type INTEGER but expected STRUCT for a member of a sum type"
+    , testCase "a refused field of a generic record names the field and the two types" $ withConnection ":memory:" \conn -> do
+        try (query_ conn "SELECT {'stampedAt': TIMESTAMP '2024-01-02 03:04:05'} AS s" :: IO [Only Stamped]) >>= \case
+          Left SQLError{sqlErrorMessage} -> sqlErrorMessage @?= "duckdb-simple: field stampedAt: a value has type TIMESTAMP but expected UTCTime"
+          Right rows -> assertFailure ("expected the error of the field, got " <> show rows)
+        (query_ conn "SELECT {'stampedAt': TIMESTAMPTZ '2024-01-02 03:04:05+00'} AS s" :: IO [Only Stamped])
+          >>= (@?= [Only (Stamped (UTCTime (fromGregorian 2024 1 2) 11045))])
+    , testCase "a read of another SQL type that needs the time zone or another text raises Incompatible" $ withConnection ":memory:" \conn -> do
+        -- See Note [Reads of another SQL type] in "Database.DuckDB.Simple.FromField".
+        let refusedPairs = do
+              forM_ ["TIMESTAMP", "TIMESTAMP_S", "TIMESTAMP_MS", "TIMESTAMP_NS"] \source -> do
+                assertIncompatible conn ("'2024-01-02 03:04:05'::" <> source) () source (Proxy @UTCTime) "UTCTime"
+                assertIncompatible conn ("'2024-01-02 03:04:05'::" <> source) () source (Proxy @(Unbounded UTCTime)) "Unbounded UTCTime"
+              assertIncompatible conn "DATE '2024-01-02'" () "DATE" (Proxy @UTCTime) "UTCTime"
+              assertIncompatible conn "DATE '2024-01-02'" () "DATE" (Proxy @(Unbounded UTCTime)) "Unbounded UTCTime"
+              forM_ [("TIMESTAMPTZ", "TIMESTAMP WITH TIME ZONE"), ("TIMESTAMPTZ_NS", "TIMESTAMPTZ_NS")] \(source, sqlName) -> do
+                assertIncompatible conn ("'2024-01-02 03:04:05+00'::" <> source) () sqlName (Proxy @LocalTime) "LocalTime"
+                assertIncompatible
+                  conn
+                  ("'2024-01-02 03:04:05+00'::" <> source)
+                  ()
+                  sqlName
+                  (Proxy @(Unbounded LocalTime))
+                  "Unbounded LocalTime"
+              forM_ [("FLOAT", "0.01::FLOAT"), ("DOUBLE", "0.01::DOUBLE")] \(sqlName, expression) -> do
+                assertIncompatible conn expression () sqlName (Proxy @Text) "Text"
+                assertIncompatible conn expression () sqlName (Proxy @String) "Text"
+              assertIncompatible conn "'a\\x41'::VARCHAR" () "VARCHAR" (Proxy @BS.ByteString) "ByteString"
+              -- An integer type does not read an ENUM value. The cast of DuckDB
+              -- parses the label, and enum_code gives the index.
+              let enumAs :: (FromField a, Show a) => Proxy a -> Text -> Assertion
+                  enumAs = assertIncompatible conn "'10'::ENUM('10', '20')" () "ENUM('10', '20')"
+              enumAs (Proxy @Int8) "Int8"
+              enumAs (Proxy @Int16) "Int16"
+              enumAs (Proxy @Int32) "Int32"
+              enumAs (Proxy @Int64) "Int64"
+              enumAs (Proxy @Int) "Int"
+              enumAs (Proxy @Integer) "Integer"
+              enumAs (Proxy @Natural) "Natural"
+              enumAs (Proxy @Word8) "Word8"
+              enumAs (Proxy @Word16) "Word16"
+              enumAs (Proxy @Word32) "Word32"
+              enumAs (Proxy @Word64) "Word64"
+              enumAs (Proxy @Word) "Word"
+              -- The SQL in place of the refused read: enum_code(c)::BIGINT gives
+              -- the index, and c::INTEGER parses the label.
+              ( query_
+                  conn
+                  "SELECT enum_code(c)::BIGINT, enum_code(c)::BIGINT, enum_code(c)::BIGINT, c::INTEGER FROM (VALUES ('20'::ENUM('10', '20'))) t(c)"
+                  :: IO [(Int8, Word8, Natural, Int32)]
+                )
+                >>= (@?= [(1, 1, 1, 20)])
+              -- The SQL in place of each refused read, also for the year 1500,
+              -- which a nanosecond value cannot hold.
+              forM_ [2024, 1500] \year -> do
+                let day = fromGregorian year 1 2
+                    text = Text.pack (show day)
+                (query_ conn (Query ("SELECT c::TIMESTAMP AT TIME ZONE 'UTC' FROM (VALUES (TIMESTAMP '" <> text <> " 03:04:05')) t(c)")) :: IO [Only UTCTime])
+                  >>= (@?= [Only (UTCTime day 11045)])
+                forM_ ["TIMESTAMP_S", "TIMESTAMP_MS"] \source ->
+                  ( query_ conn (Query ("SELECT c::TIMESTAMP AT TIME ZONE 'UTC' FROM (VALUES ('" <> text <> " 03:04:05'::" <> source <> ")) t(c)"))
+                      :: IO [Only UTCTime]
+                  )
+                    >>= (@?= [Only (UTCTime day 11045)])
+                (query_ conn (Query ("SELECT c::TIMESTAMP AT TIME ZONE 'UTC' FROM (VALUES (DATE '" <> text <> "')) t(c)")) :: IO [Only UTCTime])
+                  >>= (@?= [Only (UTCTime day 0)])
+                (query_ conn (Query ("SELECT c AT TIME ZONE 'UTC' FROM (VALUES (TIMESTAMPTZ '" <> text <> " 03:04:05+00')) t(c)")) :: IO [Only LocalTime])
+                  >>= (@?= [Only (LocalTime day (TimeOfDay 3 4 5))])
+              (query_ conn "SELECT c AT TIME ZONE 'UTC' FROM (VALUES ('2024-01-02 03:04:05.123456789'::TIMESTAMP_NS)) t(c)" :: IO [Only UTCTime])
+                >>= (@?= [Only (UTCTime (fromGregorian 2024 1 2) 11045.123456789)])
+              (query_ conn "SELECT 0.01::DOUBLE::VARCHAR, encode('a\\x41')" :: IO [(Text, BS.ByteString)]) >>= (@?= [("0.01", "a\\x41")])
+        refusedPairs
+        _ <- execute_ conn "SET TimeZone = 'Pacific/Auckland'"
+        refusedPairs
+    , testCase "invalid DECIMAL width scale and magnitude are rejected" $ withConnection ":memory:" \conn ->
+        forM_
+          [ (DecimalValue 0 0 0, assertInputError)
+          , (DecimalValue 39 0 0, assertInputError)
+          , (DecimalValue 2 3 1, assertInputError)
+          , (DecimalValue 2 0 100, assertRangeError)
+          , (DecimalValue 2 0 (-100), assertRangeError)
+          ]
+          \(decimal, rejected) ->
+            rejected
+              ( query conn "SELECT ?" (Only (singleField (LogicalTypeDecimal (decimalWidth decimal) (decimalScale decimal)) (FieldDecimal decimal)))
+                  :: IO [Only FieldValue]
+              )
+    , testCase "nested conversion failure leaves the connection usable" $ withConnection ":memory:" \conn -> do
+        let days = sized [fromGregorian 2000 1 1, fromGregorian 10000000 1 1] :: SizedArray 2 Day
+        assertOutsideTimeRange (query conn "SELECT ?" (Only days) :: IO [Only FieldValue])
+        (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+    , testCase "generic NULL product and payload fail conversion" $ do
+        assertConversionFails (genericFromFieldValue FieldNull :: Conversion NamedRecord)
+        let member = UnionMemberType "DataMember" (LogicalTypeScalar LogicalTypeIdBigInt)
+            union = UnionValue 0 "DataMember" FieldNull (listArray (0, 0) [member])
+        assertConversionFails (genericFromFieldValue (FieldUnion union) :: Conversion NullableSum)
+    , testCase "generic records decode by name" $ withConnection ":memory:" \conn -> do
+        [Only struct] <- query_ conn "SELECT {'secondValue': 2::BIGINT, 'firstValue': 1::BIGINT}" :: IO [Only (StructValue FieldValue)]
+        runConversion (genericFromFieldValue (FieldStruct struct)) >>= (@?= Ok (NamedRecord 1 2))
+    , testCase "generic sums decode by member name" $ withConnection ":memory:" \conn -> do
+        [Only union] <- query_ conn "SELECT union_value(DataMember := {'field1': 42::BIGINT})" :: IO [Only (UnionValue FieldValue)]
+        runConversion (genericFromFieldValue (FieldUnion union)) >>= (@?= Ok (DataMember 42))
+    , testCase "union binding rejects inconsistent member name" $ withConnection ":memory:" \conn -> do
+        let member = UnionMemberType "right" (LogicalTypeScalar LogicalTypeIdBigInt)
+            union = UnionValue 0 "wrong" (FieldInt64 42) (listArray (0, 0) [member])
+        assertInputError (query conn "SELECT ?" (Only union) :: IO [Only FieldValue])
+    , testCase "union binding rejects a tag out of range" $ withConnection ":memory:" \conn -> do
+        let member = UnionMemberType "only" (LogicalTypeScalar LogicalTypeIdBigInt)
+            union = UnionValue 1 "only" (FieldInt64 42) (listArray (0, 0) [member])
+        try (query conn "SELECT ?" (Only union) :: IO [Only FieldValue]) >>= \case
+          Left SQLError{sqlErrorType, sqlErrorMessage} -> do
+            sqlErrorType @?= Just ErrorInputInvalid
+            sqlErrorMessage @?= "duckdb-simple: union value tag out of range"
+          Right rows -> assertFailure ("expected the tag error, got " <> show rows)
+        (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+    , testCase "generic records reject wrong names" $ do
+        case genericToStructValue (NamedRecord 1 2) of
+          Nothing -> assertFailure "missing generic struct"
+          Just struct -> do
+            let fields = listArray (0, 1) [StructField "wrong" (FieldInt64 1), StructField "secondValue" (FieldInt64 2)]
+            assertConversionFails (genericFromFieldValue (FieldStruct struct{structValueFields = fields}) :: Conversion NamedRecord)
+    , testCase "unnamed tuples preserve scalar and nested fields on round trip" $ withConnection ":memory:" \conn -> do
+        let tuple =
+              TupleValue
+                (listArray (0, 1) [FieldInt64 42, FieldText "λ"])
+                (listArray (0, 1) [LogicalTypeScalar LogicalTypeIdBigInt, LogicalTypeScalar LogicalTypeIdVarchar])
+        (query_ conn "SELECT row(42::BIGINT, 'λ')" :: IO [Only (TupleValue FieldValue)]) >>= (@?= [Only tuple])
+        (query_ conn "SELECT [row(42::BIGINT, 'λ')]" :: IO [Only [TupleValue FieldValue]]) >>= (@?= [Only [tuple]])
+        (query conn "SELECT ?" (Only tuple) :: IO [Only (TupleValue FieldValue)]) >>= (@?= [Only tuple])
+    , testCase "empty tuples retain their type independently of empty structs" $ withConnection ":memory:" \conn -> do
+        let tuple = TupleValue (listArray (0, -1) []) (listArray (0, -1) []) :: TupleValue FieldValue
+            struct = StructValue (listArray (0, -1) []) (listArray (0, -1) []) Map.empty :: StructValue FieldValue
+        (query_ conn "SELECT row(), [row()]" :: IO [(TupleValue FieldValue, [TupleValue FieldValue])]) >>= (@?= [(tuple, [tuple])])
+        (query conn "SELECT typeof(?), ?" (tuple, tuple) :: IO [(Text, TupleValue FieldValue)]) >>= (@?= [("TUPLE", tuple)])
+        (query conn "SELECT typeof(?), ?" (struct, struct) :: IO [(Text, StructValue FieldValue)]) >>= (@?= [("STRUCT", struct)])
+        withConnectionHandle conn \native -> withConnectionFactory native \factory ->
+          forM_ [tupleValueTypeRep tuple, structValueTypeRep struct] \rep ->
+            bracket (logicalTypeFromRep factory rep) destroyLogicalType \logical -> do
+              logicalTypeToRep factory logical >>= (@?= rep)
+              nativeTypeText logical >>= (@?= logicalTypeSQL rep)
+        assertInputError (query conn "SELECT ?" (Only tuple{tupleValueFields = listArray (4, 4) [FieldNull]}) :: IO [Only FieldValue])
+    , testCase "filtered tuple cursors retain positional fields" $ withConnection ":memory:" \conn -> do
+        rows <- Streaming.fold_ conn "SELECT row(i::BIGINT, 'λ') FROM range(6) t(i) WHERE i % 2 = 1" [] $ \values (Only tuple) ->
+          pure (values <> [elems (tupleValueFields tuple)])
+        rows @?= [[FieldInt64 value, FieldText "λ"] | value <- [1, 3, 5]]
+    , testCase "composite VARCHAR collations retain native comparison semantics" $ withConnection ":memory:" \conn -> do
+        let collated = LogicalTypeCollatedVarchar "nocase"
+        [Only original] <-
+          query_ conn "SELECT {'text':'A' COLLATE nocase,'items':['B' COLLATE nocase], 'optional':NULL::VARCHAR COLLATE nocase}"
+            :: IO [Only (StructValue FieldValue)]
+        map structFieldValue (elems (structValueTypes original)) @?= [collated, LogicalTypeList collated, collated]
+        ( query conn "SELECT value.text='a', value.items[1]='b', value.optional IS NULL FROM (SELECT ? AS value)" (Only original)
+            :: IO [(Bool, Bool, Bool)]
+          )
+          >>= (@?= [(True, True, True)])
+        (query conn "SELECT ?" (Only original) :: IO [Only (StructValue FieldValue)]) >>= (@?= [Only original])
+        [Only tuple] <- query_ conn "SELECT row('A' COLLATE nocase)" :: IO [Only (TupleValue FieldValue)]
+        (query conn "SELECT value[1]='a' FROM (SELECT ? AS value)" (Only tuple) :: IO [Only Bool]) >>= (@?= [Only True])
+        withConnectionHandle conn \native -> withConnectionFactory native \factory ->
+          bracket (logicalTypeFromRep factory collated) destroyLogicalType \logical -> logicalTypeToRep factory logical >>= (@?= collated)
+    , testCase "logical type Unicode names round trip" $ withConnection ":memory:" \conn -> withConnectionHandle conn \native -> withConnectionFactory native \factory -> do
+        let logical = LogicalTypeStruct (listArray (0, 0) [StructField "íslenska_λ_😀" (LogicalTypeScalar LogicalTypeIdBigInt)])
+        bracket (logicalTypeFromRep factory logical) destroyLogicalType \handle ->
+          logicalTypeToRep factory handle >>= (@?= logical)
+    , testCase "a column type keeps the alias JSON at each depth, and reads as its base type" $ withConnection ":memory:" \conn -> do
+        let json = LogicalTypeAlias "JSON" (LogicalTypeScalar LogicalTypeIdVarchar)
+            varchar = LogicalTypeScalar LogicalTypeIdVarchar
+            structType =
+              LogicalTypeStruct
+                (listArray (0, 2) [StructField "k" json, StructField "js" (LogicalTypeList json), StructField "m" (LogicalTypeMap varchar json)])
+        _ <- execute_ conn "CREATE TABLE aliased (j JSON, js JSON[], s STRUCT(k JSON, js JSON[], m MAP(VARCHAR, JSON)), m MAP(VARCHAR, JSON))"
+        description <- Catalog.describeTable conn "aliased"
+        map Catalog.columnDescriptionType (Catalog.tableDescriptionColumns description)
+          @?= [json, LogicalTypeList json, structType, LogicalTypeMap varchar json]
+        _ <- execute_ conn "INSERT INTO aliased VALUES ('{\"a\": 1}', ['[1]'], {'k': '2', 'js': ['[3]'], 'm': MAP {'y': '4'}}, MAP {'x': '3'})"
+        query_ conn "SELECT j, js, m FROM aliased"
+          >>= (@?= [("{\"a\": 1}" :: Text, ["[1]"] :: [Text], Map.fromList [("x" :: Text, "3" :: Text)])])
+        -- The type fields of a STRUCT value keep the alias, so the value binds
+        -- again with its type.
+        [Only struct] <- query_ conn "SELECT s FROM aliased" :: IO [Only (StructValue FieldValue)]
+        structValueTypeRep struct @?= structType
+        map structFieldValue (elems (structValueFields struct))
+          @?= [FieldText "2", FieldList [FieldText "[3]"], FieldMap [(FieldText "y", FieldText "4")]]
+        query conn "SELECT typeof(?), ?" (struct, struct)
+          >>= (@?= [("STRUCT(k JSON, js JSON[], m MAP(VARCHAR, JSON))" :: Text, struct)])
+    , testCase "a column of a type from CREATE TYPE has the base type and no name" $ withConnection ":memory:" \conn -> do
+        _ <- execute_ conn "CREATE TYPE meters AS BIGINT"
+        _ <- execute_ conn "CREATE TYPE mood AS ENUM ('sad', 'happy')"
+        _ <- execute_ conn "CREATE TABLE created (m meters, mo mood)"
+        description <- Catalog.describeTable conn "created"
+        map Catalog.columnDescriptionType (Catalog.tableDescriptionColumns description)
+          @?= [LogicalTypeScalar LogicalTypeIdBigInt, LogicalTypeEnum (listArray (0, 1) ["sad", "happy"])]
+    , testCase "a registered custom type keeps its name, and reads and binds as its base type" $ withConnection ":memory:" \conn -> do
+        let decimal = LogicalTypeDecimal 9 2
+            point =
+              LogicalTypeStruct
+                (listArray (0, 1) [StructField "x" (LogicalTypeScalar LogicalTypeIdInteger), StructField "label" (LogicalTypeScalar LogicalTypeIdVarchar)])
+            custom =
+              [ ("money", decimal)
+              , ("point", point)
+              , ("tags", LogicalTypeList (LogicalTypeScalar LogicalTypeIdVarchar))
+              , ("level", LogicalTypeEnum (listArray (0, 1) ["low", "high"]))
+              , ("meters", LogicalTypeScalar LogicalTypeIdBigInt)
+              ]
+        forM_ custom \(name, base) -> R.registerCustomType conn name (StructuredType base)
+        _ <- execute_ conn "CREATE TABLE custom (a money, b point, c tags, d level, e meters, f money[])"
+        description <- Catalog.describeTable conn "custom"
+        map Catalog.columnDescriptionType (Catalog.tableDescriptionColumns description)
+          @?= [LogicalTypeAlias name base | (name, base) <- custom] <> [LogicalTypeList (LogicalTypeAlias "money" decimal)]
+        _ <- execute_ conn "INSERT INTO custom VALUES (1.25, {'x': 1, 'label': 'a'}, ['t'], 'high', 7, [2.5])"
+        query_ conn "SELECT a, c, d, e, f FROM custom"
+          >>= (@?= [(DecimalValue 9 2 125, ["t"] :: [Text], "high" :: Text, 7 :: Int64, [DecimalValue 9 2 250])])
+        [Only struct] <- query_ conn "SELECT b FROM custom" :: IO [Only (StructValue FieldValue)]
+        map structFieldValue (elems (structValueFields struct)) @?= [FieldInt32 1, FieldText "a"]
+        -- The binding uses the range of the base type.
+        try (execute conn "INSERT INTO custom (e) VALUES (?)" (Only (2 ^ (127 :: Int) :: Integer))) >>= \case
+          Left SQLError{sqlErrorMessage, sqlErrorType} -> do
+            sqlErrorType @?= Just ErrorTypeConversion
+            sqlErrorMessage @?= "duckdb-simple: the value 170141183460469231731687303715884105728 is out of range for a parameter of the type BIGINT"
+          Right _ -> assertFailure "expected the duckdb-simple range error for a custom type over BIGINT"
+    , testCase "an alias type round trips through a native type" $ withConnection ":memory:" \conn -> do
+        let json = LogicalTypeAlias "JSON" (LogicalTypeScalar LogicalTypeIdVarchar)
+            money = LogicalTypeAlias "money" (LogicalTypeDecimal 9 2)
+        R.registerCustomType conn "money" (StructuredType (LogicalTypeDecimal 9 2))
+        withConnectionHandle conn \native -> withConnectionFactory native \factory ->
+          forM_ [(json, "JSON"), (money, "money"), (LogicalTypeList json, "JSON[]")] \(logical, text) ->
+            bracket (logicalTypeFromRep factory logical) destroyLogicalType \handle -> do
+              logicalTypeToRep factory handle >>= (@?= logical)
+              -- The type is the type that DuckDB gives for the type text.
+              bracket (R.withText text (R.output . c_duckdb_v2_factory_create_type_from_text factory)) destroyLogicalType \parsed ->
+                R.output (c_duckdb_v2_logical_type_is_equal handle parsed) >>= (@?= 1)
+    , testCase "aliases equal to their type id names retain native type identity" $ withConnection ":memory:" \conn ->
+        withConnectionHandle conn \native -> withConnectionFactory native \factory -> do
+          let integer = LogicalTypeScalar LogicalTypeIdInteger
+              decimal = LogicalTypeDecimal 9 2
+              struct = LogicalTypeStruct (listArray (0, 0) [StructField "a" integer])
+              integerAlias = LogicalTypeAlias "INTEGER" integer
+              decimalAlias = LogicalTypeAlias "DECIMAL" decimal
+              structAlias = LogicalTypeAlias "STRUCT" struct
+              nested =
+                LogicalTypeStruct
+                  (listArray (0, 2) [StructField "i" integerAlias, StructField "d" decimalAlias, StructField "s" structAlias])
+          forM_
+            [ integerAlias
+            , decimalAlias
+            , structAlias
+            , LogicalTypeAlias "STRUCT" (LogicalTypeStruct (listArray (0, -1) []))
+            , LogicalTypeAlias "TUPLE" (LogicalTypeTuple (listArray (0, -1) []))
+            , LogicalTypeAlias "ENUM" (LogicalTypeEnum (listArray (0, 1) ["first", "it's second"]))
+            , LogicalTypeAlias "VARCHAR" (LogicalTypeCollatedVarchar "nocase")
+            , LogicalTypeList integerAlias
+            , nested
+            ]
+            \rep -> bracket (logicalTypeFromRep factory rep) destroyLogicalType \logical -> do
+              copied <- logicalTypeToRep factory logical
+              copied @?= rep
+              logicalTypeToBaseRep logical >>= (@?= withoutAliases rep)
+              nativeTypeText logical >>= (@?= logicalTypeSQL copied)
+              bracket (logicalTypeFromRep factory copied) destroyLogicalType \rebuilt ->
+                R.output (c_duckdb_v2_logical_type_is_equal logical rebuilt) >>= (@?= 1)
+    , testCase "logicalTypeSQL gives the type text of DuckDB for each kind, and a read error names that text" $ withConnection ":memory:" \conn -> do
+        R.registerCustomType conn "money" (StructuredType (LogicalTypeDecimal 9 2))
+        keywords <- map fromOnly <$> (query_ conn "SELECT DISTINCT keyword_name FROM duckdb_keywords() ORDER BY 1" :: IO [Only Text])
+        let keywordStruct = "STRUCT(" <> Text.intercalate ", " ["\"" <> keyword <> "\" INTEGER" | keyword <- keywords] <> ")"
+        withConnectionHandle conn \native -> withConnectionFactory native \factory ->
+          forM_
+            [ "DECIMAL(18,3)"
+            , "TIMESTAMP_NS"
+            , "TIMESTAMPTZ"
+            , "TIMETZ"
+            , "\"NULL\""
+            , "ENUM('sad', 'it''s')"
+            , "BIGINT[]"
+            , "INTEGER[3]"
+            , "INTEGER[3][]"
+            , "MAP(VARCHAR, BIGINT)"
+            , "STRUCT(a INTEGER, B VARCHAR, \"c d\" BIGINT[], \"x\"\"y\" DOUBLE, \"1a\" INTEGER, \"Name\" INTEGER, \"_1\" INTEGER, _a INTEGER)"
+            , "UNION(n INTEGER, s VARCHAR)"
+            , "TUPLE(INTEGER, VARCHAR)"
+            , "GEOMETRY"
+            , "GEOMETRY('OGC:CRS84')"
+            , "VARCHAR COLLATE nocase"
+            , "VARIANT"
+            , "JSON"
+            , "JSON[]"
+            , "STRUCT(k JSON)"
+            , "money"
+            , keywordStruct
+            ]
+            \text ->
+              bracket (R.withText text (R.output . c_duckdb_v2_factory_create_type_from_text factory)) destroyLogicalType \logical -> do
+                expected <- nativeTypeText logical
+                rep <- logicalTypeToRep factory logical
+                assertEqual (Text.unpack (Text.take 80 text)) expected (logicalTypeSQL rep)
+        -- A read error names the column type. Under VARIANT it names the type of
+        -- the stored value, in the same text.
+        assertIncompatible conn "1.5::DECIMAL(18,3)" () "DECIMAL(18,3)" (Proxy @Text) "Text"
+        assertIncompatible conn "(1.5::DECIMAL(18,3))::VARIANT" () "DECIMAL(18,3)" (Proxy @Text) "Text"
+        assertIncompatible conn "(TIMESTAMPTZ '2024-01-02 03:04:05+00')::VARIANT" () "TIMESTAMP WITH TIME ZONE" (Proxy @Text) "Text"
+    , testCase "logicalTypeSQL quotes an empty named STRUCT field" $ do
+        let integer = LogicalTypeScalar LogicalTypeIdInteger
+            rep = LogicalTypeStruct (listArray (0, 1) [StructField "" integer, StructField "normal" integer])
+        logicalTypeSQL rep @?= "STRUCT(\"\" INTEGER, normal INTEGER)"
+    , testCase "a user FromField checks the type of a column, an element, a MAP key and value, and a record field" $ withConnection ":memory:" \conn -> do
+        query_ conn "SELECT 1.25::DECIMAL(9,2), TIMESTAMP_NS '2024-01-02 03:04:05.123456789', [1, 2, 3]::INTEGER[3], '{\"a\": 1}'::JSON"
+          >>= (@?= [(Checked "decimal", Checked "timestamp_ns", Checked "array", Checked "json")])
+        forM_ ["1.25::DECIMAL(9,3)", "TIMESTAMP '2024-01-02 03:04:05'", "[1, 2]::INTEGER[2]", "'{}'::VARCHAR"] \value ->
+          try (query_ conn (Query ("SELECT " <> value)) :: IO [Only Checked]) >>= \case
+            Left SQLError{sqlErrorMessage} -> assertBool (Text.unpack sqlErrorMessage) ("expected DECIMAL(_,2)" `Text.isInfixOf` sqlErrorMessage)
+            Right rows -> assertFailure (Text.unpack value <> " reads as " <> show rows)
+        query_ conn "SELECT [1.25::DECIMAL(9,2)], MAP {TIMESTAMP_NS '2024-01-02': '{}'::JSON}, {'price': 2.5::DECIMAL(9,2)}"
+          >>= (@?= [([Checked "decimal"], Map.fromList [(Checked "timestamp_ns", Checked "json")], Priced (Checked "decimal"))])
+    , testCase "an element and a MAP value have the child type, and a value in a VARIANT has the type VARIANT" $ withConnection ":memory:" \conn -> do
+        let decimal = LogicalTypeDecimal 4 1
+            json = LogicalTypeAlias "JSON" (LogicalTypeScalar LogicalTypeIdVarchar)
+            variant = LogicalTypeScalar LogicalTypeIdVariant
+        query_ conn "SELECT [1.5::DECIMAL(4,1)], [1.5::DECIMAL(4,1)], MAP {'k': '{}'::JSON}, [1, 2]::VARIANT"
+          >>= ( @?=
+                  [
+                    ( FieldTypeOf (LogicalTypeList decimal)
+                    , [FieldTypeOf decimal]
+                    , Map.fromList [("k" :: Text, FieldTypeOf json)]
+                    , [FieldTypeOf variant, FieldTypeOf variant]
+                    )
+                  ]
+              )
+    , testCase "a column whose type no read forces converts no ENUM dictionary" $ withConnection ":memory:" \conn -> do
+        _ <- execute_ conn "CREATE TYPE wide AS ENUM (SELECT 'label' || i FROM range(100000) t(i))"
+        let readLabel = query_ conn "SELECT 'label7'::wide" :: IO [Only Text]
+            allocation action = do
+              before <- getAllocationCounter
+              result <- action
+              after <- getAllocationCounter
+              -- The counter counts down.
+              pure (result, before - after)
+        _ <- readLabel
+        (labels, withoutType) <- allocation readLabel
+        labels @?= [Only "label7"]
+        -- A failed read whose error no one renders converts no type.
+        (alternative, withoutRender) <- allocation (query_ conn "SELECT 'label7'::wide" :: IO [Only IntOrText])
+        alternative @?= [Only (IntOrText (Right "label7"))]
+        assertBool ("the read with a failed alternative allocated " <> show withoutRender <> " bytes") (withoutRender < 1000000)
+        [(size, conversion)] <-
+          queryWith_
+            (fieldWith (\entry -> liftConversion (allocation (runConversion (enumSize <$> fieldType entry)))))
+            conn
+            "SELECT 'label7'::wide"
+        size @?= Ok 100000
+        -- Each of the 100,000 labels is a Text of at least 32 bytes.
+        assertBool ("the read without the type allocated " <> show withoutType <> " bytes") (withoutType < 1000000)
+        assertBool ("the conversion allocated " <> show conversion <> " bytes") (conversion > 3200000)
+    , testCase "a pure column type snapshot survives all database scopes" $ do
+        snapshot <- withEnumType runConversion
+        performMajorGC
+        snapshot @?= Ok (LogicalTypeEnum (listArray (0, 99999) ["label" <> Text.pack (show index) | index <- [0 .. 99999 :: Int]]))
+    , testCase "unused and cached native type actions reject after the query returns" $
+        forM_ [False, True] \cached -> do
+          logical <- withEnumType \action -> do
+            when cached (runConversion (enumSize <$> action) >>= (@?= Ok 100000))
+            pure action
+          performMajorGC
+          assertClosedMetadata logical
+    , testCase "a parser can read metadata around a nested query on its connection" $ withConnection ":memory:" \conn -> do
+        rows <-
+          queryWith_
+            ( fieldWith \entry -> do
+                before <- fieldType entry
+                liftConversion (query_ conn "SELECT 7::INTEGER" :: IO [Only Int32]) >>= liftConversion . (@?= [Only 7])
+                after <- fieldType entry
+                pure (before, after)
+            )
+            conn
+            "SELECT 1.5::DECIMAL(4,1)"
+        rows @?= [(LogicalTypeDecimal 4 1, LogicalTypeDecimal 4 1)]
+    , testCase "a cursor keeps metadata until exhaustion reset or statement close" $ withEnumConnection \conn ->
+        forM_ [False, True] \cached ->
+          forM_ (["exhaustion", "reset", "close"] :: [String]) \end ->
+            withStatement conn "SELECT 'label7'::scoped_wide FROM range(2)" \stmt -> do
+              Just logical <- nextRowWith (fieldWith (pure . fieldType)) stmt
+              when cached (runConversion (enumSize <$> logical) >>= (@?= Ok 100000))
+              case end of
+                "exhaustion" -> do
+                  Just (Only label) <- nextRow stmt
+                  (label :: Text) @?= "label7"
+                  -- The first field's metadata is still valid after another row.
+                  when cached (runConversion (enumSize <$> logical) >>= (@?= Ok 100000))
+                  nextRow stmt >>= (@?= (Nothing :: Maybe (Only Text)))
+                "reset" -> clearStatementBindings stmt
+                _ -> closeStatement stmt
+              assertClosedMetadata logical
+    , testCase "an ENUM type retries cancellation while its query scope remains open" $
+        forM_ [1 .. 3 :: Int] \_ -> withEnumType \logical -> do
+          started <- newEmptyMVar
+          finished <- newEmptyMVar
+          worker <- forkIO $ mask \restore -> do
+            outcome <- try $ restore $ do
+              putMVar started ()
+              runConversion (enumSize <$> logical)
+            putMVar finished (outcome :: Either SomeException (Ok Int))
+          awaitMetadata "metadata worker did not start" (takeMVar started)
+          -- Completion can win this cancellation race.
+          threadDelay 1000
+          awaitMetadata "metadata worker did not finish" (killThread worker >> takeMVar finished) >>= \case
+            Left failure -> fromException failure @?= Just ThreadKilled
+            Right result -> result @?= Ok 100000
+          runConversion (enumSize <$> logical) >>= (@?= Ok 100000)
+    , testCase "conversion steps force successful values inside IO" $ do
+        let marker = "conversion result failure"
+            bad = error marker :: Int
+            expectFailure conversion = do
+              outcome <- try (runConversion conversion)
+              -- Match the outcome after try has left the IO exception boundary.
+              case outcome of
+                Left (failure :: ErrorCall) -> assertBool (displayException failure) (Text.pack marker `Text.isInfixOf` Text.pack (displayException failure))
+                Right _ -> assertFailure "the result exception escaped the conversion boundary"
+        expectFailure (pure bad)
+        expectFailure ((,) <$> pure (1 :: Int) <*> pure bad)
+        expectFailure ((,) <$> pure (1 :: Int) <*> fmap (const bad) (pure ()))
+        expectFailure ((,) <$> pure (1 :: Int) <*> liftConversion (pure bad))
+        expectFailure (pure bad >> pure ())
+    , testCase "a conversion propagates cancellation and retries its explicit IO" $ withEnumType \logical -> do
+        attempts <- newIORef (0 :: Int)
+        let conversion = do
+              attempt <- liftConversion (atomicModifyIORef' attempts (\count -> (count + 1, count)))
+              if attempt == 0
+                then liftConversion (throwIO ThreadKilled)
+                else enumSize <$> logical
+        try (runConversion conversion) >>= \case
+          Left failure -> (failure :: AsyncException) @?= ThreadKilled
+          Right result -> assertFailure ("expected cancellation, got " <> show result)
+        runConversion conversion >>= (@?= Ok 100000)
+        readIORef attempts >>= (@?= 2)
+    , testCase "concurrent demands share an ENUM snapshot within its query scope" $ withEnumType \logical -> do
+        start <- newEmptyMVar
+        completed <- replicateM 8 newEmptyMVar
+        forM_ completed \done -> void $ forkIO $ mask \restore -> do
+          outcome <- try $ restore $ readMVar start >> runConversion logical
+          putMVar done (outcome :: Either SomeException (Ok LogicalTypeRep))
+        putMVar start ()
+        outcomes <- awaitMetadata "concurrent metadata workers did not finish" (mapM takeMVar completed)
+        forM_ outcomes \case
+          Left failure -> throwIO failure
+          Right result -> result @?= Ok (LogicalTypeEnum (listArray (0, 99999) ["label" <> Text.pack (show index) | index <- [0 .. 99999 :: Int]]))
+        case outcomes of
+          Right first : rest -> forM_ rest \case
+            Right result -> result @?= first
+            Left failure -> throwIO failure
+          _ -> assertFailure "expected completed metadata demands"
+    , testCase "concurrent type demand and cursor closure complete without deadlock" $ withEnumConnection \conn ->
+        forM_ [1 .. 3 :: Int] \_ -> withStatement conn "SELECT 'label7'::scoped_wide" \stmt -> do
+          Just logical <- nextRowWith (fieldWith (pure . fieldType)) stmt
+          started <- newEmptyMVar
+          readFinished <- newEmptyMVar
+          closeFinished <- newEmptyMVar
+          void $ forkIO $ mask \restore -> do
+            outcome <- try $ restore (putMVar started () >> runConversion (enumSize <$> logical))
+            putMVar readFinished (outcome :: Either SQLError (Ok Int))
+          awaitMetadata "metadata reader did not start" (takeMVar started)
+          void $ forkIO $ do
+            outcome <- try (closeStatement stmt)
+            putMVar closeFinished (outcome :: Either SomeException ())
+          awaitMetadata "cursor closure blocked on metadata" (takeMVar closeFinished) >>= either throwIO pure
+          awaitMetadata "metadata reader blocked on cursor closure" (takeMVar readFinished) >>= \case
+            Left failure -> sqlErrorMessage failure @?= "duckdb-simple: field type scope is closed"
+            Right result -> result @?= Ok 100000
+          assertClosedMetadata logical
+    , testCase "conversion actions preserve the caller's masking state" $ do
+        let check expected = withEnumType \logical -> do
+              runConversion (liftConversion getMaskingState) >>= (@?= Ok expected)
+              runConversion (logical >> liftConversion getMaskingState) >>= (@?= Ok expected)
+              getMaskingState >>= (@?= expected)
+        initialState <- getMaskingState
+        check initialState
+        mask_ (check MaskedInterruptible)
+        uninterruptibleMask_ (check MaskedUninterruptible)
+    , testCase "a discarded diagnostic performs no metadata read or diagnostic IO" $ withEnumType \logical -> do
+        diagnosticReads <- newIORef (0 :: Int)
+        let failure :: Conversion Int
+            failure = conversionErrorWith $ do
+              liftConversion (atomicModifyIORef' diagnosticReads (\count -> (count + 1, ())))
+              size <- enumSize <$> logical
+              pure (userError ("ENUM dictionary size " <> show size))
+        runConversion (failure <|> pure 42) >>= (@?= Ok 42)
+        readIORef diagnosticReads >>= (@?= 0)
+        runConversion failure >>= \case
+          Errors [problem] -> assertBool (show problem) ("ENUM dictionary size 100000" `Text.isInfixOf` Text.pack (show problem))
+          other -> assertFailure ("expected the final diagnostic, got " <> show other)
+        readIORef diagnosticReads >>= (@?= 1)
+    , testCase "logical type names reject embedded NUL" $ withConnection ":memory:" \conn -> withConnectionHandle conn \native -> withConnectionFactory native \factory -> do
+        let logical = LogicalTypeStruct (listArray (0, 0) [StructField "before\0after" (LogicalTypeScalar LogicalTypeIdBigInt)])
+        assertInputError (bracket (logicalTypeFromRep factory logical) destroyLogicalType (const (pure ())))
+    , testCase "invalid native composite constructor returns controlled error" $ withConnection ":memory:" \conn -> do
+        let struct =
+              singleField
+                (LogicalTypeMap (LogicalTypeScalar LogicalTypeIdBigInt) (LogicalTypeScalar LogicalTypeIdBigInt))
+                (FieldMap [(FieldNull, FieldInt64 1)])
+        result <- try (query conn "SELECT ?" (Only struct) :: IO [Only FieldValue])
+        case result of
+          Left SQLError{sqlErrorType} -> sqlErrorType @?= Just ErrorInputInvalid
+          Right _ -> assertFailure "expected a V2 native constructor error"
+    , testCase "BIT padding preserves SQL bit_count" $ withConnection ":memory:" \conn -> do
+        let bits = bsFromBool [True, False, True]
+        (query conn "SELECT bit_count(?), ?" (bits, bits) :: IO [(Int64, BitString)]) >>= (@?= [(2, bits)])
+    , testCase "unsupported BIT input fails before native use" $ withConnection ":memory:" \conn ->
+        forM_ [BitString 0 BS.empty, BitString 8 (BS.singleton 1)] \bits ->
+          assertInputError (query conn "SELECT ?" (Only bits) :: IO [Only BitString])
+    , testCase "TIMETZ offsets with seconds read without rounding" $ withConnection ":memory:" \conn ->
+        (query_ conn "SELECT '12:00:00+01:23:45'::TIMETZ" :: IO [Only TimeWithZone]) >>= (@?= [Only (TimeWithZone (TimeOfDay 12 0 0) 5025)])
+    , testCase "a failure of the reader of a chunk gives the error of DuckDB and releases each chunk" $ withConnection ":memory:" \conn -> do
+        -- The VARIANT reader runs its metadata query on a helper connection, and
+        -- that query needs an expression depth of 11. A GLOBAL depth of 10 thus
+        -- fails the reader at the bind of that query, and the SESSION depth of
+        -- the caller lets the query of the case run.
+        _ <- execute_ conn "SET GLOBAL max_expression_depth = 10"
+        _ <- execute_ conn "SET SESSION max_expression_depth = 1000"
+        let rows = "SELECT 42::BIGINT::VARIANT FROM range(10000)"
+        try (query_ conn rows :: IO [Only FieldValue]) >>= \case
+          Left SQLError{sqlErrorMessage, sqlErrorType} -> do
+            assertBool (Text.unpack sqlErrorMessage) ("expression depth" `Text.isInfixOf` sqlErrorMessage)
+            sqlErrorType @?= Just ErrorQueryBinder
+          Right result -> assertFailure ("expected the error of the VARIANT reader, got " <> show (length result) <> " rows")
+        (query_ conn "SELECT 42" :: IO [Only Int]) >>= (@?= [Only 42])
+        _ <- execute_ conn "SET GLOBAL max_expression_depth = 1000"
+        (length <$> (query_ conn rows :: IO [Only FieldValue])) >>= (@?= 10000)
+    , testCase "a failure of the reader of a later chunk of a stream gives the error of DuckDB" $
+        withEnvironment \environment -> withInstance environment [] \instance' ->
+          withConnectionOn instance' \conn -> withConnectionOn instance' \other -> do
+            _ <- execute_ conn "SET SESSION max_expression_depth = 1000"
+            -- Metadata reuses its prepared plan. The unusual key needs the
+            -- extraction query, which binds again for each chunk. A lower
+            -- GLOBAL depth fails that bind after the first chunk.
+            let step count (Only (_ :: FieldValue)) = do
+                  when (count == 0) $ do
+                    _ <- execute_ other "SET GLOBAL max_expression_depth = 3"
+                    pure ()
+                  pure (count + 1)
+            let rows = "SELECT json_object('', i)::VARIANT FROM range(10000) t(i)"
+            try (Streaming.fold_ conn rows (0 :: Int) step) >>= \case
+              Left SQLError{sqlErrorMessage} -> assertBool (Text.unpack sqlErrorMessage) ("expression depth" `Text.isInfixOf` sqlErrorMessage)
+              Right count -> assertFailure ("expected the error of the VARIANT reader, got " <> show count <> " rows")
+            (query_ conn "SELECT 42" :: IO [Only Int]) >>= (@?= [Only 42])
+            _ <- execute_ conn "SET GLOBAL max_expression_depth = 1000"
+            (length <$> (query_ conn rows :: IO [Only FieldValue])) >>= (@?= 10000)
+    , testCase "ENUM labels read as the cast to VARCHAR in each chunk, execution, list, and map key" $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
+        -- 5000 rows are three chunks. Each row has another label of a
+        -- dictionary of 16-bit or 32-bit indexes. See Note [ENUM labels] in
+        -- "Database.DuckDB.Simple.Materialize".
+        forM_ [300, 70000 :: Int] \size -> do
+          let dtype = "labels_" <> Text.pack (show size)
+              count = Text.pack (show size)
+          _ <- execute_ conn (Query ("CREATE TYPE " <> dtype <> " AS ENUM (SELECT 'v' || i FROM range(" <> count <> ") t(i))"))
+          let sql =
+                Query
+                  ( "SELECT e, [e, NULL], map([coalesce(e, 'v1'::"
+                      <> dtype
+                      <> ")], [i]), e::VARCHAR, [e, NULL]::VARCHAR[] FROM (SELECT i, CASE WHEN i % 1000 = 999 THEN NULL ELSE ('v' || ((i * 7) % "
+                      <> count
+                      <> "))::"
+                      <> dtype
+                      <> " END AS e FROM range(5000) t(i))"
+                  )
+              check :: [(Maybe Text, [Maybe Text], Map.Map Text Int64, Maybe Text, [Maybe Text])] -> Assertion
+              check rows = do
+                length rows @?= 5000
+                forM_ rows \(label, list, keys, cast, castList) -> do
+                  label @?= cast
+                  list @?= castList
+                  Map.keys keys @?= [fromMaybe "v1" cast]
+          forM_ [1 :: Int, 2] \_ ->
+            query_ conn sql >>= check
+          withStatement conn sql (readAllRows Streaming.nextRow) >>= check
+    , testCase "a prepared statement reads the labels of an ENUM type that DROP TYPE and CREATE TYPE replaced" $ withConnection ":memory:" \conn -> do
+        _ <- execute_ conn "CREATE TYPE swapped AS ENUM ('a', 'b')"
+        withStatement conn "SELECT ?::swapped, (?::swapped)::VARCHAR" \stmt -> do
+          let run label = do
+                bind stmt [toField (label :: Text), toField label]
+                readAllRows nextRow stmt
+          run "b" >>= (@?= [(FieldEnum 1 "b", "b" :: Text)])
+          _ <- execute_ conn "DROP TYPE swapped"
+          _ <- execute_ conn "CREATE TYPE swapped AS ENUM ('x', 'y', 'b')"
+          -- Index 1 is 'y' in the new type. A cache of the first execution
+          -- would give 'b'.
+          run "y" >>= (@?= [(FieldEnum 1 "y", "y" :: Text)])
+    , testCase "ENUM members of a UNION and the key and value of a MAP read the labels of their own dictionaries" $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+        _ <- execute_ conn "CREATE TYPE first_labels AS ENUM ('x', 'y'); CREATE TYPE second_labels AS ENUM ('p', 'q', 'r')"
+        -- 3000 rows are two chunks.
+        rows <-
+          query_
+            conn
+            "SELECT CASE WHEN i % 2 = 0 THEN union_value(a := (['x', 'y'])[i % 4 // 2 + 1]::first_labels)::UNION(a first_labels, b second_labels) \
+            \ELSE union_value(b := (['p', 'q', 'r'])[i % 3 + 1]::second_labels)::UNION(a first_labels, b second_labels) END, \
+            \map([(['x', 'y'])[i % 2 + 1]::first_labels], [(['p', 'q', 'r'])[i % 3 + 1]::second_labels]), \
+            \(['x', 'y'])[i % 4 // 2 + 1], (['p', 'q', 'r'])[i % 3 + 1], (['x', 'y'])[i % 2 + 1] \
+            \FROM range(3000) t(i)"
+            :: IO [(UnionValue FieldValue, Map.Map Text Text, Text, Text, Text)]
+        length rows @?= 3000
+        forM_ (zip [0 :: Int ..] rows) \(i, (union, pairs, first, second, key)) -> do
+          unionValuePayload union
+            @?= if even i
+              then FieldEnum (if first == "x" then 0 else 1) first
+              else FieldEnum (if second == "p" then 0 else if second == "q" then 1 else 2) second
+          pairs @?= Map.singleton key second
+    , testCase "ENUM payload label must be in its dictionary" $ withConnection ":memory:" \conn -> do
+        try (query conn "SELECT ?" (Only (singleField (LogicalTypeEnum (listArray (0, 1) ["a", "b"])) (FieldEnum 0 "c"))) :: IO [Only FieldValue]) >>= \case
+          Left SQLError{sqlErrorMessage, sqlErrorType} -> do
+            sqlErrorType @?= Just ErrorTypeConversion
+            sqlErrorMessage @?= "duckdb-simple: the ENUM label 'c' is not in the dictionary of the type"
+          Right rows -> assertFailure ("expected the label error, got " <> show rows)
+        -- DuckDB gives the same type for the same label in SQL.
+        try (query_ conn "SELECT {'value': 'c'}::STRUCT(value ENUM('a', 'b'))" :: IO [Only FieldValue]) >>= \case
+          Left SQLError{sqlErrorType} -> sqlErrorType @?= Just ErrorTypeConversion
+          Right rows -> assertFailure ("expected the cast error of DuckDB, got " <> show rows)
+        -- A label with a single quote prints as it is, as in the cast error of DuckDB.
+        try
+          (query conn "SELECT ?" (Only (singleField (LogicalTypeEnum (listArray (0, 1) ["a", "b"])) (FieldEnum 0 "it's"))) :: IO [Only FieldValue])
+          >>= \case
+            Left SQLError{sqlErrorMessage} -> sqlErrorMessage @?= "duckdb-simple: the ENUM label 'it's' is not in the dictionary of the type"
+            Right rows -> assertFailure ("expected the label error, got " <> show rows)
+        try (query_ conn "SELECT {'value': 'it''s'}::STRUCT(value ENUM('a', 'b'))" :: IO [Only FieldValue]) >>= \case
+          Left SQLError{sqlErrorMessage} -> Text.takeWhile (/= '\n') sqlErrorMessage @?= "Conversion Error: Could not convert string 'it's' to ENUM('a', 'b')"
+          Right rows -> assertFailure ("expected the cast error of DuckDB, got " <> show rows)
+    , testCase "ENUM payload binds its label, not its index" $ withConnection ":memory:" \conn -> do
+        let struct = singleField (LogicalTypeEnum (listArray (0, 2) ["a", "b", "c"])) (FieldEnum 1 "b")
+        (query conn "SELECT typeof((?).value), (?).value::VARCHAR, ?" (struct, struct, struct) :: IO [(Text, Text, StructValue FieldValue)])
+          >>= (@?= [("ENUM('a', 'b', 'c')", "b", struct)])
+        -- The index of another dictionary does not change the value.
+        let other = singleField (LogicalTypeEnum (listArray (0, 2) ["a", "b", "c"])) (FieldEnum 0 "c")
+        (query conn "SELECT (?).value::VARCHAR, ?" (other, other) :: IO [(Text, StructValue FieldValue)])
+          >>= (@?= [("c", singleField (LogicalTypeEnum (listArray (0, 2) ["a", "b", "c"])) (FieldEnum 2 "c"))])
+    , testCase "ENUM values of each dictionary size bind their labels" $ withConnection ":memory:" \conn ->
+        -- DuckDB stores the index of a dictionary of 200, 300, and 70000 entries
+        -- in 8, 16, and 32 bits.
+        forM_ [200, 300, 70000 :: Int] \size -> do
+          let label index = "v" <> Text.pack (show index)
+              entries = listArray (0, size - 1) (map label [0 .. size - 1])
+          forM_ [0, size - 1] \index -> do
+            let struct = singleField (LogicalTypeEnum entries) (FieldEnum (fromIntegral index) (label index))
+            (query conn "SELECT (?).value::VARCHAR, ?" (struct, struct) :: IO [(Text, StructValue FieldValue)])
+              >>= assertEqual (show size <> " " <> show index) [(label index, struct)]
+    , testCase "TIMETZ input offset overflow fails before native use" $ withConnection ":memory:" \conn -> do
+        let value = TimeWithZone (TimeOfDay 12 0 0) maxBound
+            struct = singleField (LogicalTypeScalar LogicalTypeIdTimeTz) (FieldTimeTZ value)
+        assertRangeError (query conn "SELECT ?" (Only struct) :: IO [Only FieldValue])
+        forM_ [71582789, -71582789, minBound, maxBound] \minutes ->
+          assertRangeError
+            (query conn "SELECT ?::TIMETZ" (Only (timeWithZone (TimeOfDay 12 0 0) (minutesToTimeZone minutes))) :: IO [Only TimeWithZone])
+    , testCase "invalid TIME input returns controlled error" $ withConnection ":memory:" \conn ->
+        assertRangeError (query conn "SELECT ?" (Only (TimeOfDay 1000000000 0 0)) :: IO [Only TimeOfDay])
+    , testCase "nested types decode the same in each chunk and each read mode" $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+        _ <- execute_ conn "CREATE TYPE mood AS ENUM ('calm', 'busy', 'tired')"
+        let sql =
+              "SELECT st, [st, st] AS l, [st, st]::STRUCT(n BIGINT, e mood)[2] AS a, tiers, [tiers, tiers] AS tl, \
+              \CASE WHEN i % 2 = 0 THEN union_value(d := ((i % 1000) / 10)::DECIMAL(9, 2))::UNION(d DECIMAL(9, 2), s STRUCT(n BIGINT, e mood)) \
+              \ELSE union_value(s := st)::UNION(d DECIMAL(9, 2), s STRUCT(n BIGINT, e mood)) END AS u, \
+              \map([st.e], [((i % 1000) / 10)::DECIMAL(9, 2)]) AS m, i::DECIMAL(18, 3) AS d \
+              \FROM (SELECT i, {'n': i, 'e': (['calm', 'busy', 'tired'])[i % 3 + 1]::mood} AS st, \
+              \{'small': ((i % 1000) / 10)::DECIMAL(4, 1), 'large': (i * 1000 + 7)::DECIMAL(18, 3)} AS tiers FROM range(5000) r(i))"
+            mood = LogicalTypeEnum (listArray (0, 2) ["calm", "busy", "tired"])
+            bigint = LogicalTypeScalar LogicalTypeIdBigInt
+            stType = LogicalTypeStruct (listArray (0, 1) [StructField "n" bigint, StructField "e" mood])
+            members = listArray (0, 1) [UnionMemberType "d" (LogicalTypeDecimal 9 2), UnionMemberType "s" stType]
+            decimal width scale integer = FieldDecimal (DecimalValue width scale integer)
+            moodValue i = FieldEnum (fromIntegral (i `mod` 3)) (["calm", "busy", "tired"] !! fromIntegral (i `mod` 3))
+            expected :: Int64 -> [FieldValue]
+            expected i =
+              let st = FieldStruct (structOf [("n", FieldInt64 i, bigint), ("e", moodValue i, mood)])
+                  tenths = toInteger (i `mod` 1000)
+                  tiers =
+                    FieldStruct
+                      ( structOf
+                          [ ("small", decimal 4 1 tenths, LogicalTypeDecimal 4 1)
+                          , ("large", decimal 18 3 ((toInteger i * 1000 + 7) * 1000), LogicalTypeDecimal 18 3)
+                          ]
+                      )
+                  union
+                    | even i = UnionValue 0 "d" (decimal 9 2 (tenths * 10)) members
+                    | otherwise = UnionValue 1 "s" st members
+              in  [ st
+                  , FieldList [st, st]
+                  , FieldArray (listArray (0, 1) [st, st])
+                  , tiers
+                  , FieldList [tiers, tiers]
+                  , FieldUnion union
+                  , FieldMap [(moodValue i, decimal 9 2 (tenths * 10))]
+                  , decimal 18 3 (toInteger i * 1000)
+                  ]
+        materialized <- query_ conn sql :: IO [[FieldValue]]
+        cursor <- withStatement conn sql (readAllRows nextRow)
+        streamed <- withStatement conn sql (readAllRows Streaming.nextRow)
+        length materialized @?= 5000
+        cursor @?= materialized
+        streamed @?= materialized
+        forM_ [0, 2047, 2048, 4095, 4999 :: Int] \i -> (materialized !! i) @?= expected (fromIntegral i)
+    , testCase "a statement that runs again with another type reads the new type" $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
+        withStatement conn "SELECT ? AS s FROM range(3000) r(i)" \stmt ->
+          forM_ ([nextRow, Streaming.nextRow] :: [Statement -> IO (Maybe (Only (StructValue FieldValue)))]) \next ->
+            forM_ [DecimalValue 4 1 123, DecimalValue 18 3 123456789012, DecimalValue 4 1 (-45)] \value -> do
+              let struct = singleField (LogicalTypeDecimal (decimalWidth value) (decimalScale value)) (FieldDecimal value)
+              bind stmt [toField struct]
+              readAllRows next stmt >>= (@?= replicate 3000 (Only struct))
+    , testCase "an Integer outside the HUGEINT range raises the range error for each integer type" $ withConnection ":memory:" \conn -> do
+        -- A BIGNUM value for these types stores a wrong value with no error.
+        -- See Note [Integer parameters] in "Database.DuckDB.Simple.ToField".
+        let huge = 2 ^ (128 :: Int) + 5 :: Integer
+            insert :: Text -> Integer -> IO (Either SQLError Int)
+            insert dtype value = do
+              _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE wide_integer (v " <> dtype <> ")"))
+              result <- try (execute conn "INSERT INTO wide_integer VALUES (?)" (Only value))
+              (query_ conn "SELECT count(*) FROM wide_integer" :: IO [Only Int64]) >>= assertEqual (Text.unpack dtype <> " " <> show value) [Only 0]
+              pure result
+        forM_ ["TINYINT", "SMALLINT", "INTEGER", "BIGINT", "HUGEINT", "UTINYINT", "USMALLINT", "UINTEGER", "UBIGINT", "UHUGEINT"] \dtype -> do
+          -- DuckDB also rejects the value for the type.
+          try (query_ conn (Query ("SELECT '" <> Text.pack (show huge) <> "'::" <> dtype)) :: IO [Only Text]) >>= \case
+            Left SQLError{sqlErrorMessage} ->
+              assertBool (Text.unpack sqlErrorMessage) ("Conversion Error: Could not convert string" `Text.isPrefixOf` sqlErrorMessage)
+            Right rows -> assertFailure ("DuckDB accepts " <> show huge <> " as " <> Text.unpack dtype <> ": " <> show rows)
+          forM_ [huge, negate huge] \value ->
+            insert dtype value >>= \case
+              Left SQLError{sqlErrorMessage, sqlErrorType} -> do
+                sqlErrorType @?= Just ErrorTypeConversion
+                sqlErrorMessage @?= "duckdb-simple: the value " <> Text.pack (show value) <> " is out of range for a parameter of the type " <> dtype
+              Right _ -> assertFailure ("expected the duckdb-simple range error for " <> Text.unpack dtype <> " " <> show value)
+        -- An element of an array takes the element type of its target. DuckDB
+        -- then checks the range of each element.
+        forM_ ["UTINYINT[2]", "USMALLINT[2]", "UINTEGER[2]", "UBIGINT[2]"] \dtype -> do
+          _ <- execute_ conn (Query ("CREATE OR REPLACE TABLE wide_integer (v " <> dtype <> ")"))
+          result <- try (execute conn "INSERT INTO wide_integer VALUES (?)" (Only (sized [5, -6] :: SizedArray 2 Integer)))
+          (query_ conn "SELECT count(*) FROM wide_integer" :: IO [Only Int64]) >>= assertEqual (Text.unpack dtype) [Only 0]
+          case result of
+            Left SQLError{sqlErrorMessage, sqlErrorType} -> do
+              assertBool
+                (Text.unpack sqlErrorMessage)
+                ("-6 can't be cast because the value is out of range for the destination type" `Text.isInfixOf` sqlErrorMessage)
+              sqlErrorType @?= Just ErrorInputInvalid
+            Right _ -> assertFailure ("expected the DuckDB range error for " <> Text.unpack dtype)
+    , testCase "DECIMAL columns decode the largest value at each storage boundary" $ withConnection ":memory:" \conn ->
+        -- DuckDB stores a DECIMAL of the width 1 to 4 in 16 bits, 5 to 9 in 32 bits,
+        -- 10 to 18 in 64 bits, and 19 to 38 in 128 bits. The text comes from DuckDB.
+        forM_ [4, 5, 9, 10, 18, 19, 38] \width -> do
+          let largest = 10 ^ width - 1 :: Integer
+              dtype = "DECIMAL(" <> Text.pack (show width) <> ",0)"
+              sql =
+                "SELECT x::"
+                  <> dtype
+                  <> ", x::"
+                  <> dtype
+                  <> "::VARCHAR FROM (VALUES ("
+                  <> Text.pack (show (negate largest))
+                  <> "), (NULL), ("
+                  <> Text.pack (show largest)
+                  <> ")) t(x)"
+          rows <- query_ conn (Query sql) :: IO [(FieldValue, Maybe Text)]
+          assertEqual
+            (Text.unpack dtype)
+            [ (FieldDecimal (DecimalValue width 0 (negate largest)), Just (Text.pack (show (negate largest))))
+            , (FieldNull, Nothing)
+            , (FieldDecimal (DecimalValue width 0 largest), Just (Text.pack (show largest)))
+            ]
+            rows
+    , testCase "ENUM columns decode the last label at each storage boundary" $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
+        -- DuckDB stores the index of an ENUM with at most 255 labels in 8 bits, with
+        -- at most 65535 labels in 16 bits, and with more labels in 32 bits.
+        forM_ [255, 256, 65535, 65536 :: Int] \size -> do
+          let dtype = "enum_boundary_" <> Text.pack (show size)
+              lastLabel = "v" <> Text.pack (show (size - 1))
+          _ <- execute_ conn (Query ("CREATE TYPE " <> dtype <> " AS ENUM (SELECT 'v' || i FROM range(" <> Text.pack (show size) <> ") t(i))"))
+          rows <-
+            query_
+              conn
+              ( Query
+                  ( "SELECT x::"
+                      <> dtype
+                      <> ", enum_code(x::"
+                      <> dtype
+                      <> ")::BIGINT, x::"
+                      <> dtype
+                      <> "::VARCHAR FROM (VALUES ('v0'), (NULL), ('"
+                      <> lastLabel
+                      <> "')) t(x)"
+                  )
+              )
+              :: IO [(FieldValue, Maybe Int64, Maybe Text)]
+          -- DuckDB gives the index and the label of each row.
+          assertEqual
+            (Text.unpack dtype)
+            [(Just 0, Just "v0"), (Nothing, Nothing), (Just (fromIntegral (size - 1)), Just lastLabel)]
+            [(index, label) | (_, index, label) <- rows]
+          forM_ rows \(value, index, label) -> assertEqual (Text.unpack dtype) (enumField index label) value
+    , testCase "NULL TUPLE and UNION rows decode as NULL in each chunk" $ withConnection ":memory:" \conn -> do
+        rows <-
+          query_
+            conn
+            "SELECT t, u, t IS NULL, u IS NULL FROM (SELECT CASE WHEN i % 7 = 1 THEN NULL ELSE row(i, 'x') END AS t, CASE WHEN i % 7 = 2 THEN NULL ELSE union_value(n := i)::UNION(n BIGINT, s VARCHAR) END AS u FROM range(3000) r(i))"
+            :: IO [(FieldValue, FieldValue, Bool, Bool)]
+        length rows @?= 3000
+        -- DuckDB gives the NULL rows in the last two columns.
+        forM_ (zip [0 :: Int ..] rows) \(row, (tuple, member, tupleIsNull, memberIsNull)) -> do
+          assertEqual ("TUPLE row " <> show row) tupleIsNull (tuple == FieldNull)
+          assertEqual ("UNION row " <> show row) memberIsNull (member == FieldNull)
+    , testCase "narrowing reads reject the values that DuckDB rejects for the type" $ withConnection ":memory:" \conn -> do
+        let rejects :: forall a. (FromField a, Show a) => Proxy a -> Text -> Text -> Assertion
+            rejects _ value sqlType = do
+              -- DuckDB raises an error for the same cast.
+              try (query_ conn (Query ("SELECT (" <> value <> ")::" <> sqlType)) :: IO [Only Text]) >>= \case
+                Left SQLError{sqlErrorMessage} ->
+                  assertBool
+                    (Text.unpack sqlErrorMessage)
+                    ("can't be cast because the value is out of range for the destination type" `Text.isInfixOf` sqlErrorMessage)
+                Right rows -> assertFailure ("DuckDB accepts " <> Text.unpack value <> " as " <> Text.unpack sqlType <> ": " <> show rows)
+              -- The read raises the conversion error of the query.
+              let sql = Query ("SELECT " <> value)
+              try (query_ conn sql :: IO [Only a]) >>= \case
+                Left SQLError{sqlErrorType, sqlErrorQuery} -> do
+                  assertEqual (Text.unpack value) Nothing sqlErrorType
+                  assertEqual (Text.unpack value) (Just sql) sqlErrorQuery
+                Right rows -> assertFailure (Text.unpack value <> " decodes as " <> show rows)
+              -- The cause of that error is a ResultError.
+              [Only native] <- query_ conn sql :: IO [Only FieldValue]
+              runConversion
+                ( fromField Field{fieldName = "value", fieldIndex = 0, fieldValue = native, fieldType = pure (LogicalTypeScalar LogicalTypeIdVariant)}
+                    :: Conversion a
+                )
+                >>= \case
+                  Errors errors ->
+                    assertBool ("expected a ResultError, got " <> show errors) (not (null errors) && all isResultError errors)
+                  Ok decoded -> assertFailure (Text.unpack value <> " converts to " <> show decoded)
+            isResultError failure = isJust (fromException failure :: Maybe ResultError)
+        rejects (Proxy @Word64) "-1::BIGINT" "UBIGINT"
+        rejects (Proxy @Word) "-1::BIGINT" "UBIGINT"
+        rejects (Proxy @Word32) "-1::INTEGER" "UINTEGER"
+        rejects (Proxy @Int16) "32768::INTEGER" "SMALLINT"
+        rejects (Proxy @Int32) "2147483648::BIGINT" "INTEGER"
+        rejects (Proxy @Int64) "1180591620717411303424::HUGEINT" "BIGINT"
+    ]
+      <> [ testCase ("composite temporal round trip: " <> dtype) $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn ->
+             forM_ ("NULL" : map (\value -> "'" <> value <> "'") values) \value ->
+               assertTemporalRoundTrip conn dtype (value <> "::" <> dtype)
+         | (dtype, values) <-
+             [ (dtype, ["-infinity", "infinity", "1969-12-31 23:59:59.123456789", "2000-01-01 12:34:56.123456789"])
+             | dtype <- ["TIMESTAMP", "TIMESTAMP_S", "TIMESTAMP_MS", "TIMESTAMP_NS", "TIMESTAMPTZ"]
+             ]
+               <> [("DATE", ["-infinity", "infinity", "1969-12-31", "2000-01-01"])]
+               <> [("TIME_NS", ["00:00:00", "12:34:56.123456789", "23:59:59.999999999", "24:00:00"])]
+         ]
+      <> [ testCase (dtype <> " " <> value <> " rejects a finite result type") $ withConnection ":memory:" \conn ->
+             assertConversionError (query_ conn (fromString ("SELECT '" <> value <> "'::" <> dtype)) :: IO [Only LocalTime])
+         | dtype <- ["DATE", "TIMESTAMP", "TIMESTAMP_S", "TIMESTAMP_MS", "TIMESTAMP_NS", "TIMESTAMPTZ"]
+         , value <- ["infinity", "-infinity"]
+         ]
+
+-- | Rebind native temporal values in structs, unions, and nested collections.
+assertTemporalRoundTrip :: Connection -> String -> String -> Assertion
+assertTemporalRoundTrip conn dtype expression = do
+  let sql =
+        "WITH temporal AS (SELECT "
+          <> expression
+          <> " AS value) "
+          <> "SELECT {'scalar': value, 'list': [value, NULL], 'array': [value, NULL]::"
+          <> dtype
+          <> "[2], 'map': map([1], [value])}, union_value(value := value) FROM temporal"
+  [original] <- query_ conn (fromString sql) :: IO [(StructValue FieldValue, UnionValue FieldValue)]
+  query conn "SELECT ?, ?" original >>= (@?= [original])
+
+-- | Store raw V2 timestamp units through the parameter API.
+appendTimestamp :: Connection -> String -> NativeTimestamp -> IO ()
+appendTimestamp conn dtype value = do
+  _ <- execute_ conn (fromString ("CREATE TABLE native_timestamp(value " <> dtype <> ")"))
+  _ <- execute conn "INSERT INTO native_timestamp VALUES (?)" (Only value)
+  pure ()
+
+-- | Build a struct from the name, the value, and the type of each field.
+structOf :: [(Text, FieldValue, LogicalTypeRep)] -> StructValue FieldValue
+structOf fields =
+  StructValue
+    (listArray (0, length fields - 1) [StructField name value | (name, value, _) <- fields])
+    (listArray (0, length fields - 1) [StructField name logical | (name, _, logical) <- fields])
+    (Map.fromList (zip [name | (name, _, _) <- fields] [0 ..]))
+
+-- | Read the rows of a statement until the cursor gives no row.
+readAllRows :: (Statement -> IO (Maybe row)) -> Statement -> IO [row]
+readAllRows next stmt = go []
+  where
+    go rows = next stmt >>= maybe (pure (reverse rows)) (\row -> go (row : rows))
+
+-- | Build a single-field struct for nested binding tests.
+singleField :: LogicalTypeRep -> FieldValue -> StructValue FieldValue
+singleField logical value =
+  StructValue
+    (listArray (0, 0) [StructField "value" value])
+    (listArray (0, 0) [StructField "value" logical])
+    (Map.singleton "value" 0)
+
+-- | The field of an ENUM row with the index and the label that DuckDB gives.
+enumField :: Maybe Int64 -> Maybe Text -> FieldValue
+enumField (Just index) (Just label) = FieldEnum (fromIntegral index) label
+enumField _ _ = FieldNull
+
+-- | Require the range error of the library for a date or a timestamp outside
+-- the range of DuckDB. See Note [Time ranges] in "Database.DuckDB.Simple.ToField".
+assertOutsideTimeRange :: IO a -> Assertion
+assertOutsideTimeRange action =
+  try action >>= \case
+    Left SQLError{sqlErrorMessage, sqlErrorType} -> do
+      sqlErrorType @?= Just ErrorTypeConversion
+      assertBool (Text.unpack sqlErrorMessage) ("of DuckDB" `Text.isInfixOf` sqlErrorMessage)
+    Right _ -> assertFailure "expected the range error of the library"
+
+-- | Assert a controlled FromField conversion error.
+assertConversionError :: IO a -> Assertion
+assertConversionError action = do
+  result <- try action
+  case result of
+    Left (_ :: SQLError) -> pure ()
+    Right _ -> assertFailure "expected ResultError"
+
+-- | The DECIMAL widths and scales of the case on Double and Float reads. They
+-- have each storage type of a DECIMAL, each path of
+-- Note [DECIMAL as DOUBLE and FLOAT] in "Database.DuckDB.Simple.FromField",
+-- and the scales on both sides of the limits 10 and 22 of path 2.
+decimalKinds :: [(Int, Int)]
+decimalKinds =
+  [(4, 0), (4, 2), (4, 4), (9, 0), (9, 2), (9, 5), (9, 9), (18, 0), (18, 2), (18, 6), (18, 12), (18, 18)]
+    <> [(19, 0), (19, 4), (38, 0), (38, 2), (38, 5), (38, 10), (38, 11), (38, 20), (38, 22), (38, 23), (38, 30), (38, 38)]
+
+-- | A fixed sequence of 64-bit words: SplitMix64 with seed 1.
+splitMix64 :: [Word64]
+splitMix64 = map mix (drop 1 (iterate (+ 0x9e3779b97f4a7c15) 1))
+  where
+    mix z0 =
+      let z1 = (z0 `xor` (z0 `shiftR` 30)) * 0xbf58476d1ce4e5b9
+          z2 = (z1 `xor` (z1 `shiftR` 27)) * 0x94d049bb133111eb
+      in  z2 `xor` (z2 `shiftR` 31)
+
+-- | Unscaled integers that a DECIMAL of a width holds, with both signs: zero
+-- and the extremes; two values that DuckDB 2.0.0 does not cast to the nearest
+-- DOUBLE at scale 0; a value that two roundings change at scale 2; values next
+-- to each power of two and next to the DOUBLE and FLOAT midpoints above it; and
+-- 400 values of 'splitMix64' with 1 to width digits.
+decimalIntegers :: Int -> [Integer]
+decimalIntegers width = filter (\v -> abs v <= limit) (special <> near <> spread)
+  where
+    limit = 10 ^ width - 1
+    special = [0, limit, negate limit, -9007199254740994, 270628455292663770, 3356951675583485076575379654993209529]
+    near =
+      [ sign * (2 ^ k + base + delta)
+      | k <- [0 .. 127 :: Int]
+      , base <- 0 : [m * 2 ^ (k - 53) | k >= 53, m <- [1, 3]] <> [m * 2 ^ (k - 24) | k >= 24, m <- [1, 3]]
+      , delta <- [-1, 0, 1]
+      , sign <- [1, -1]
+      ]
+    spread =
+      [ (if odd n then negate else id) ((toInteger high * 2 ^ (64 :: Int) + toInteger low) `mod` (10 ^ (1 + n `mod` width)))
+      | (n, high, low) <- zip3 [0 .. 399 :: Int] (everyOther splitMix64) (everyOther (drop 1 splitMix64))
+      ]
+    everyOther (a : _ : rest) = a : everyOther rest
+    everyOther rest = rest
+
+-- | Unscaled integers of path 3 in Note [DECIMAL as DOUBLE and FLOAT] whose
+-- value is a midpoint of two DOUBLE values (scale 5) or of two FLOAT values
+-- (scale 11), and the integers next to them, with both signs. A midpoint rounds
+-- to the even value.
+roundingTies :: Int -> Int -> [Integer]
+roundingTies 38 5 = [sign * ((2 ^ (100 :: Int) + 2 ^ (47 :: Int)) * 10 ^ (5 :: Int) + delta) | delta <- [-1, 0, 1], sign <- [1, -1]]
+roundingTies 38 11 = [sign * ((2 ^ (60 :: Int) + 2 ^ (36 :: Int)) * 10 ^ (11 :: Int) + delta) | delta <- [-1, 0, 1], sign <- [1, -1]]
+roundingTies _ _ = []
+
+-- | The text of an unscaled DECIMAL integer with a scale.
+decimalText :: Int -> Integer -> Text
+decimalText 0 v = Text.pack (show v)
+decimalText scale v = Text.pack ((if v < 0 then "-" else "") <> whole <> "." <> fraction)
+  where
+    digits = show (abs v)
+    padded = replicate (scale + 1 - length digits) '0' <> digits
+    (whole, fraction) = splitAt (length padded - scale) padded
+
+-- | Assert that each text value, cast to the source type, reads as @a@ with the
+-- value of its cast from the source type to the target type. The target type is
+-- the SQL type of @a@. The two reads are in the same row.
+assertReadsAsCast :: (FromField a, Eq a, Show a) => Connection -> Proxy a -> Text -> Text -> [Text] -> Assertion
+assertReadsAsCast conn proxy source target values = do
+  rows <-
+    query conn (Query ("SELECT v, v::" <> source <> ", v::" <> source <> "::" <> target <> " FROM unnest(?::VARCHAR[]) t(v)")) (Only values)
+  length rows @?= length values
+  forM_ rows \(value, actual, cast) ->
+    assertEqual (Text.unpack ("'" <> value <> "'::" <> source <> " as " <> target)) (cast `asProxyTypeOf` proxy) actual
+
+-- | Assert that a read of an expression as @a@ raises Incompatible with the SQL
+-- type name and the Haskell type name. A String reads through Text, so its
+-- error names Text.
+assertIncompatible :: forall a q. (FromField a, Show a, ToRow q) => Connection -> Text -> q -> Text -> Proxy a -> Text -> Assertion
+assertIncompatible conn expression parameters sqlName _ haskellName =
+  try (query conn (Query ("SELECT " <> expression <> " AS c")) parameters :: IO [Only a]) >>= \case
+    Left SQLError{sqlErrorMessage} ->
+      sqlErrorMessage @?= "duckdb-simple: column c has type " <> sqlName <> " but expected " <> haskellName
+    Right rows -> assertFailure ("expected Incompatible for " <> Text.unpack expression <> ", got " <> show rows)
+
+-- | Assert rejection without forcing a partial generic value.
+assertConversionFails :: Conversion a -> Assertion
+assertConversionFails conversion =
+  runConversion conversion >>= \case
+    Errors _ -> pure ()
+    Ok _ -> assertFailure "expected a conversion failure"
+
+-- | Run a parser action while the ENUM column's metadata scope is open.
+withEnumType :: (Conversion LogicalTypeRep -> IO a) -> IO a
+withEnumType action = withEnumConnection \connection -> do
+  [result] <- queryWith_ (fieldWith (liftConversion . action . fieldType)) connection "SELECT 'label7'::scoped_wide"
+  pure result
+
+-- | Create an ENUM in an explicitly attached in-memory database.
+withEnumConnection :: (Connection -> IO a) -> IO a
+withEnumConnection action = withEnvironment \environment -> withInstance environment [] \instance_ ->
+  withConnectionOn instance_ \connection -> do
+    _ <- execute_ connection "ATTACH ':memory:' AS metadata"
+    _ <- execute_ connection "USE metadata"
+    _ <- execute_ connection "CREATE TYPE scoped_wide AS ENUM (SELECT 'label' || i FROM range(100000) t(i) ORDER BY i)"
+    action connection
+
+-- | Reject native metadata reads after their query or callback scope closes.
+assertClosedMetadata :: Conversion a -> Assertion
+assertClosedMetadata conversion =
+  try (runConversion conversion) >>= \case
+    Left SQLError{sqlErrorMessage} -> sqlErrorMessage @?= "duckdb-simple: field type scope is closed"
+    Right _ -> assertFailure "metadata read succeeded after its scope closed"
+
+-- | Read the size of an ENUM dictionary.
+enumSize :: LogicalTypeRep -> Int
+enumSize (LogicalTypeEnum entries) = length (elems entries)
+enumSize other = error ("expected an ENUM type, got " <> take 100 (show other))
+
+-- | Bound waits for metadata workers, including a worker that fails.
+awaitMetadata :: String -> IO a -> IO a
+awaitMetadata message action =
+  timeout 60000000 action >>= \case
+    Just result -> pure result
+    Nothing -> assertFailure message >> fail message
diff --git a/test/VariantRegressionTests.hs b/test/VariantRegressionTests.hs
--- a/test/VariantRegressionTests.hs
+++ b/test/VariantRegressionTests.hs
@@ -1,282 +1,645 @@
 {-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE DataKinds #-}
 {-# LANGUAGE DeriveGeneric #-}
 {-# LANGUAGE DerivingVia #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE NamedFieldPuns #-}
 {-# LANGUAGE OverloadedStrings #-}
-{-# LANGUAGE PatternSynonyms #-}
-{-# OPTIONS_GHC -Wno-deprecations #-}
+{-# LANGUAGE ScopedTypeVariables #-}
 
+-- |
+-- Module      : VariantRegressionTests
+-- Description : Lossless VARIANT binding and result conversion through the V2 API.
 module VariantRegressionTests (tests) where
 
-import Control.Exception (SomeException, bracket, displayException, try)
-import Control.Monad (forM_, void, when)
-import Data.Array (Array, listArray)
+import Control.Concurrent (forkFinally, killThread, myThreadId, newEmptyMVar, putMVar, readMVar, takeMVar, throwTo)
+import Control.Exception (AsyncException (..), bracket, finally, throwIO, try)
+import Control.Monad (forM, forM_, void, when)
+import Data.Array (elems, listArray)
 import qualified Data.ByteString as BS
 import qualified Data.Geometry as G
 import Data.Int (Int64)
-import Data.List (isInfixOf)
 import Data.Text (Text)
 import qualified Data.Text as Text
 import qualified Data.Vector as V
-import Database.DuckDB.FFI
 import Database.DuckDB.Simple
-import qualified Database.DuckDB.Simple.Deprecated.Streaming as Streaming
-import Database.DuckDB.Simple.FromField (BitString (..), DecimalValue (..), FieldValue (..), StructValue (..), UnionValue)
+import Database.DuckDB.Simple.FromField (BitString (..), DecimalValue (..), FieldValue (..), StructValue (..), UnionValue (..))
 import Database.DuckDB.Simple.Generic (ViaDuckDB (..))
 import Database.DuckDB.Simple.Geometry (RawGeometry (..), toRawGeometry)
-import Database.DuckDB.Simple.Internal (destroyValue, withConnectionHandle)
-import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep (..), destroyLogicalType, logicalTypeFromRep)
+import Database.DuckDB.Simple.Internal (withConnectionFactory, withConnectionHandle)
+import Database.DuckDB.Simple.LogicalRep (LogicalTypeRep (..), StructField (..), UnionMemberType (..))
+import qualified Database.DuckDB.Simple.Streaming as Streaming
+import Database.DuckDB.Simple.V2.LogicalRep (destroyLogicalType, logicalTypeFromRep, logicalTypeToRep)
 import Database.DuckDB.Simple.Variant
-import Foreign.C.String (withCString)
-import Foreign.Marshal.Alloc (alloca)
-import Foreign.Ptr (nullPtr)
-import Foreign.Storable (peek, poke)
 import GHC.Float (castDoubleToWord64, castFloatToWord32, castWord64ToDouble)
 import GHC.Generics (Generic)
 import System.Directory (doesFileExist, getTemporaryDirectory, removeFile)
 import System.IO (hClose, openBinaryTempFile)
+import System.Timeout (timeout)
 import Test.Tasty (TestTree, testGroup)
 import Test.Tasty.HUnit
-import TestUtils (assertFailureIO)
+import TestUtils (NativeTimestamp (..), assertFailureIO, nativeLocalTime, sized)
 
 -- | A generic record checks the bridge to composite type metadata.
 newtype VariantRecord = VariantRecord {payload :: Variant}
-    deriving stock (Eq, Show, Generic)
-    deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB VariantRecord)
+  deriving stock (Eq, Show, Generic)
+  deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB VariantRecord)
 
 -- | Check VARIANT payloads against native decoding and parameter round trips.
 tests :: TestTree
 tests =
-    testGroup
-        "variant integration"
-        [ testGroup
-            "scalar payloads decode like native values"
-            [ testCase (Text.unpack sql) $ withConnection ":memory:" \conn -> do
-                [(Variant actual, native)] <- query_ conn (Query ("SELECT (" <> sql <> ")::VARIANT, " <> sql)) :: IO [(Variant, FieldValue)]
-                actual @?= native
-                roundTrip conn native
-            | sql <- scalarCases
-            ]
-        , testCase "explicit casts bind plain parameters" $ withConnection ":memory:" \conn -> do
-            [Only record] <- query_ conn "SELECT {'a': 1, 'b': 'x'}" :: IO [Only (StructValue FieldValue)]
-            (query conn "SELECT ?::VARIANT, ?::VARIANT, ?::VARIANT, ?::VARIANT" (42 :: Int64, "two" :: Text, record, listArray (0, 1) [1, 2] :: Array Int Int64) :: IO [(Variant, Variant, Variant, Variant)])
-                >>= (@?= [(Variant (FieldInt64 42), Variant (FieldText "two"), Variant (variantObject [("a", FieldInt32 1), ("b", FieldText "x")]), Variant (FieldList [FieldInt64 1, FieldInt64 2]))])
-            (query conn "SELECT [NULL::VARIANT, ?::VARIANT, ?::VARIANT]" (42 :: Int64, "two" :: Text) :: IO [Only [Variant]])
-                >>= (@?= [Only [Variant FieldNull, Variant (FieldInt64 42), Variant (FieldText "two")]])
-            _ <- execute_ conn "CREATE TABLE variants (v VARIANT)"
-            _ <- executeMany conn "INSERT INTO variants VALUES (?)" [Only (7 :: Int64), Only 8]
-            _ <- execute conn "INSERT INTO variants VALUES (?)" (Only record)
-            (query_ conn "SELECT v FROM variants" :: IO [Only Variant])
-                >>= (@?= [Only (Variant (FieldInt64 7)), Only (Variant (FieldInt64 8)), Only (Variant (variantObject [("a", FieldInt32 1), ("b", FieldText "x")]))])
-        , testCase "existing FromField instances read VARIANT payloads" $ withConnection ":memory:" \conn -> do
-            (query_ conn "SELECT 42::BIGINT::VARIANT, 'x'::VARIANT, [1, 2, 3]::VARIANT" :: IO [(Int64, Text, [Int64])])
-                >>= (@?= [(42, "x", [1, 2, 3])])
-            (query_ conn "SELECT {'payload': {'x': 18446744073709551615::UBIGINT}::VARIANT}" :: IO [Only VariantRecord])
-                >>= (@?= [Only (VariantRecord (Variant (variantObject [("x", FieldWord64 maxBound)])))])
-        , testCase "bound payloads keep integer widths and decimal scale" $ withConnection ":memory:" \conn ->
-            forM_ [("'-128'::TINYINT", FieldInt8 minBound), ("12.34::DECIMAL(4,2)", FieldDecimal (DecimalValue 4 2 1234)), ("255::UTINYINT", FieldWord8 maxBound)] \(sql, value) ->
-                (query conn (Query ("SELECT variant_typeof(?) = variant_typeof((" <> sql <> ")::VARIANT)")) (Only (Variant value)) :: IO [Only Bool])
-                    >>= (@?= [Only True])
-        , testCase "floating special values retain type and bits" $ withConnection ":memory:" \conn -> do
-            forM_ [0, -0.0, 1 / 0, -1 / 0, 0 / 0] \value -> do
-                [Only (Variant actual)] <- query conn "SELECT ?" (Only (Variant (FieldDouble value)))
-                case actual of
-                    FieldDouble decoded
-                        | isNaN value -> assertBool "expected Double NaN" (isNaN decoded)
-                        | otherwise -> castDoubleToWord64 decoded @?= castDoubleToWord64 value
-                    _ -> assertFailure (show actual)
-            forM_ [0, -0.0, 1 / 0, -1 / 0, 0 / 0] \value -> do
-                [Only (Variant actual)] <- query conn "SELECT ?" (Only (Variant (FieldFloat value)))
-                case actual of
-                    FieldFloat decoded
-                        | isNaN value -> assertBool "expected Float NaN" (isNaN decoded)
-                        | otherwise -> castFloatToWord32 decoded @?= castFloatToWord32 value
-                    _ -> assertFailure (show actual)
-        , testCase "TIMETZ offsets decode like native values" $ withConnection ":memory:" \conn -> do
-            forM_ ["'12:00:00+01:23'::TIMETZ", "'23:59:59.999999-15:59'::TIMETZ", "'00:00:00+00'::TIMETZ"] \sql -> do
-                [(Variant actual, native)] <- query_ conn (Query ("SELECT (" <> sql <> ")::VARIANT, " <> sql)) :: IO [(Variant, FieldValue)]
-                actual @?= native
-                roundTrip conn native
-            assertFailureIO (query_ conn "SELECT '12:00:00+01:23:45'::TIMETZ::VARIANT" :: IO [Only Variant])
-        , testCase "wide finite timestamp payloads round trip without losing digits" $ withConnection ":memory:" \conn -> do
-            void (execute_ conn "CREATE TABLE wide_timestamps (seconds TIMESTAMP_S, millis TIMESTAMP_MS)")
-            appendWideTimestamps conn [(30000000000000, 30000000000000001), (-30000000000000, -30000000000000001), (maxBound - 1, maxBound - 1), (minBound, minBound)]
-            rows <- query_ conn "SELECT seconds::VARIANT, seconds, millis::VARIANT, millis FROM wide_timestamps" :: IO [(Variant, FieldValue, Variant, FieldValue)]
-            length rows @?= 4
-            forM_ rows \(seconds, nativeSeconds, millis, nativeMillis) ->
-                forM_ [(seconds, nativeSeconds), (millis, nativeMillis)] \(Variant actual, native) -> do
-                    actual @?= native
-                    roundTrip conn actual
-        , testCase "text and binary values preserve embedded NUL" $ withConnection ":memory:" \conn -> do
-            roundTrip conn (FieldText "before\0after íslenska λ 😀")
-            roundTrip conn (FieldBlob (BS.pack [0, 1, 127, 128, 255, 0]))
-        , testCase "objects preserve case-sensitive names and heterogeneous children" $ withConnection ":memory:" \conn -> do
-            let value =
-                    variantObject
-                        [ ("Case", FieldInt64 9007199254740993)
-                        , ("case", FieldDecimal (DecimalValue 38 9 1234567890123456789))
-                        , ("quote' íslenska λ", FieldList [FieldNull, FieldText "x", FieldList [], variantObject []])
-                        ]
-            roundTrip conn value
-            (query conn "SELECT variant_extract(?, 'Case')::BIGINT, variant_extract(?, 'case')::DECIMAL(38,9)::VARCHAR" (Variant value, Variant value) :: IO [(Int64, Text)])
-                >>= (@?= [(9007199254740993, "1234567890.123456789")])
-        , testCase "empty containers and NULL stay distinct" $ withConnection ":memory:" \conn -> do
-            forM_ [FieldNull, FieldList [], variantObject [], FieldList [FieldNull], variantObject [("x", FieldNull)]] (roundTrip conn)
-            (query_ conn "SELECT NULL::VARIANT" :: IO [Only (Maybe Variant)]) >>= (@?= [Only Nothing])
-            (query conn "SELECT ?" (Only (Variant FieldNull)) :: IO [Only FieldValue]) >>= (@?= [Only FieldNull])
-        , testCase "deep native arrays decode without a library depth limit" $ withConnection ":memory:" \conn ->
-            forM_ [128, 256 :: Int] \depth -> do
-                let expected = Variant (foldr (const (FieldList . pure)) (FieldWord64 7) [1 .. depth])
-                (query conn "SELECT (repeat('[', ?) || '7' || repeat(']', ?))::JSON::VARIANT" (depth, depth) :: IO [Only Variant])
-                    >>= (@?= [Only expected])
-        , testCase "ARRAY parameters and generic records contain VARIANT" $ withConnection ":memory:" \conn -> do
-            let array = listArray (0, 2) [Variant (FieldInt8 1), Variant (FieldText "two"), Variant FieldNull]
-            (query conn "SELECT ?" (Only array) :: IO [Only (Array Int Variant)]) >>= (@?= [Only array])
-            let record = VariantRecord (Variant (variantObject [("x", FieldWord64 maxBound)]))
-            (query conn "SELECT ?" (Only record) :: IO [Only VariantRecord]) >>= (@?= [Only record])
-        , testCase "nullable ARRAY parameters preserve heterogeneous VARIANT values" $ withConnection ":memory:" \conn -> do
-            let values = listArray (0, 3) [Nothing, Just (Variant (FieldInt64 42)), Just (Variant (FieldText "two")), Just (Variant (variantObject [("xs", FieldList [FieldNull, FieldBool True])]))]
-            (query conn "SELECT typeof(?), ?" (values, values) :: IO [(Text, Array Int (Maybe Variant))]) >>= (@?= [("VARIANT[4]", values)])
-        , testCase "empty ARRAY parameters retain VARIANT element type" $ withConnection ":memory:" \conn -> do
-            let values = listArray (0, -1) [] :: Array Int (Maybe Variant)
-            (query conn "SELECT typeof(?)" (Only values) :: IO [Only Text]) >>= (@?= [Only "VARIANT[ANY]"])
-        , testCase "parameter binding supplies a complete VARIANT type" $ withConnection ":memory:" \conn -> do
-            let value = variantObject [("xs", FieldList [FieldNull, FieldInt64 42])]
-            roundTrip conn value
-            (query conn "SELECT typeof(?)" (Only (Variant value)) :: IO [Only Text]) >>= (@?= [Only "VARIANT"])
-        , testCase "the first VARIANT parameter does not end a streaming result" $ withConnection ":memory:" \conn ->
-            withStatement conn "SELECT ?" \stmt -> do
-                total <- Streaming.fold_ conn "SELECT i FROM range(100000) t(i)" 0 \acc (Only i) -> do
-                    when (i == 0) (bind stmt [toField (Variant (FieldInt64 42))])
-                    pure (acc + i)
-                total @?= (sum [0 .. 99999] :: Int64)
-        , testCase "VARIANT type construction raises an error" $ do
-            result <- try (bracket (logicalTypeFromRep (LogicalTypeScalar DuckDBTypeVariant)) destroyLogicalType (const (pure ())))
+  testGroup
+    "variant integration"
+    [ testCase "separate connections decode VARIANT concurrently" $
+        withEnvironment \env -> withInstance env [] \inst ->
+          withConnectionOn inst \left -> withConnectionOn inst \right -> do
+            start <- newEmptyMVar
+            let worker conn input = do
+                  readMVar start
+                  forM_ [1 .. 20 :: Int] \_ -> roundTrip conn input
+            completions <- forM [(left, FieldList [FieldInt64 42, FieldNull]), (right, variantObject [("", FieldText "right"), ("n", FieldInt64 7)])] \(conn, input) -> do
+              done <- newEmptyMVar
+              thread <- forkFinally (worker conn input) (putMVar done)
+              pure (thread, done)
+            putMVar start ()
+            result <- timeout 10000000 (mapM (takeMVar . snd) completions) `finally` mapM_ (killThread . fst) completions
             case result of
-                Left err -> assertBool (displayException (err :: SomeException)) ("?::VARIANT" `isInfixOf` displayException err)
-                Right () -> assertFailure "expected VARIANT type rejection"
-        , testCase "VARIANT payloads and GEOMETRY CRS metadata bind together" $ withConnection ":memory:" \conn -> do
-            [Only value] <- query_ conn "SELECT {'payload': 42::VARIANT, 'shape': NULL::GEOMETRY('OGC:CRS84')}" :: IO [Only (StructValue FieldValue)]
-            (query conn "SELECT typeof(?)" (Only value) :: IO [Only Text]) >>= (@?= [Only "STRUCT(payload VARIANT, shape GEOMETRY('OGC:CRS84'))"])
-            (query conn "SELECT ?" (Only value) :: IO [Only (StructValue FieldValue)]) >>= (@?= [Only value])
-        , testCase "inactive VARIANT UNION members have complete types" $ withConnection ":memory:" \conn -> do
-            [Only value] <- query_ conn "SELECT union_value(number := 42::BIGINT)::UNION(number BIGINT, payload VARIANT)" :: IO [Only (UnionValue FieldValue)]
-            (query conn "SELECT ?" (Only value) :: IO [Only (UnionValue FieldValue)]) >>= (@?= [Only value])
-        , testCase "native LIST, ARRAY, MAP and STRUCT metadata round trip" $ withConnection ":memory:" \conn -> do
-            [Only value] <-
-                query_
-                    conn
-                    "SELECT {'xs': [1::VARIANT, 'two'::VARIANT, NULL], 'fixed': [42::VARIANT]::VARIANT[1], 'map': MAP {'x': {'a': 9}::VARIANT}}" ::
-                    IO [Only (StructValue FieldValue)]
-            (query conn "SELECT ?" (Only value) :: IO [Only (StructValue FieldValue)]) >>= (@?= [Only value])
-        , testCase "UNION payloads retain VARIANT type, including NULL" $ withConnection ":memory:" \conn ->
-            forM_ ["SELECT union_value(v := {'a': 42}::VARIANT)", "SELECT union_value(v := NULL::VARIANT)"] \sql -> do
-                [Only value] <- query_ conn sql :: IO [Only (UnionValue FieldValue)]
-                (query conn "SELECT ?" (Only value) :: IO [Only (UnionValue FieldValue)]) >>= (@?= [Only value])
-        , testGroup
-            "heterogeneous folds cross chunk boundaries"
-            [ testCase mode $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
-                count <- foldRows
-                    conn
-                    "SELECT CASE WHEN i % 3 = 0 THEN i::VARIANT WHEN i % 3 = 1 THEN 'text'::VARIANT ELSE {'n': i, 'xs': [NULL, i]}::VARIANT END FROM range(5000) t(i)"
-                    (0 :: Int64)
-                    \n (Only (Variant actual)) -> do
-                        let expected = case n `mod` 3 of
-                                0 -> FieldInt64 n
-                                1 -> FieldText "text"
-                                _ -> variantObject [("n", FieldInt64 n), ("xs", FieldList [FieldNull, FieldInt64 n])]
-                        actual @?= expected
-                        pure (n + 1)
-                count @?= 5000
-            | (mode, foldRows) <- [("materialized", fold_), ("deprecated streaming", Streaming.fold_)]
-            ]
-        , testCase "filtered and reordered rows use the right child offsets" $ withConnection ":memory:" \conn -> do
-            rows <- query_ conn "SELECT {'n': i, 'xs': [i, i + 1]}::VARIANT FROM range(10000) t(i) WHERE i % 97 = 0 ORDER BY i DESC LIMIT 40"
-            let expected = [Only (Variant (variantObject [("n", FieldInt64 n), ("xs", FieldList [FieldInt64 n, FieldInt64 (n + 1)])])) | n <- take 40 (reverse [0, 97 .. 9999])]
-            rows @?= expected
-        , testCase "file-backed values survive checkpoint and reopen" $
-            bracket newDatabase removeDatabase \path -> do
-                withConnectionWithConfig path [("storage_compatibility_version", "v1.5.0")] \conn -> do
-                    void (execute_ conn "CREATE TABLE stored AS SELECT i, {'n': i, 'xs': [i, NULL], 'text': i::VARCHAR}::VARIANT AS value, 'POINT (1 2)'::GEOMETRY('OGC:CRS84') AS geometry FROM range(10000) t(i)")
-                    void (execute_ conn "CHECKPOINT")
-                withConnectionWithConfig path [("storage_compatibility_version", "v1.5.0")] \conn -> do
-                    rows <- query_ conn "SELECT value FROM stored WHERE i % 97 = 0 ORDER BY i DESC LIMIT 40" :: IO [Only Variant]
-                    let expected =
-                            [ Only (Variant (variantObject [("n", FieldInt64 n), ("xs", FieldList [FieldInt64 n, FieldNull]), ("text", FieldText (Text.pack (show n)))]))
-                            | n <- take 40 (reverse [0, 97 .. 9999])
-                            ]
-                    rows @?= expected
-                    [Only geometry] <- query_ conn "SELECT geometry FROM stored LIMIT 1" :: IO [Only RawGeometry]
-                    rawGeometryCRS geometry @?= Just "OGC:CRS84"
-                    BS.length (rawGeometryWKB geometry) @?= 21
-        , testCase "geometry payload keeps WKB; native VARIANT does not retain CRS" $ withConnection ":memory:" \conn -> do
-            [Only geometry] <- query_ conn "SELECT 'POINT ZM (1 2 3 4)'::GEOMETRY('OGC:CRS84')" :: IO [Only RawGeometry]
-            [Only value] <- query_ conn "SELECT 'POINT ZM (1 2 3 4)'::GEOMETRY('OGC:CRS84')::VARIANT" :: IO [Only Variant]
-            value @?= geometryPayload (rawGeometryWKB geometry)
-            (query conn "SELECT system.main.ST_GeomFromWKB(?)::VARIANT" (Only (rawGeometryWKB geometry)) :: IO [Only Variant]) >>= (@?= [Only value])
-            (query conn "SELECT system.main.ST_CRS((system.main.ST_GeomFromWKB(?)::VARIANT)::GEOMETRY)" (Only (rawGeometryWKB geometry)) :: IO [Only (Maybe Text)]) >>= (@?= [Only Nothing])
-            forM_ [variantPayload value, FieldList [variantPayload value], variantObject [("shape", variantPayload value)]] \input -> do
-                result <- try (query conn "SELECT ?" (Only (Variant input)) :: IO [Only Variant]) :: IO (Either SomeException [Only Variant])
-                case result of
-                    Left err -> assertBool (displayException err) ("raw GEOMETRY binding requires explicit" `isInfixOf` displayException err)
-                    Right _ -> assertFailure "expected raw geometry binding rejection"
-            (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
-        , testCase "geometry payload retains empty layout tags and native NaN points" $ withConnection ":memory:" \conn ->
-            forM_ ["GEOMETRYCOLLECTION ZM EMPTY", "MULTIPOLYGON M EMPTY", "POINT Z (NaN NaN 7)"] \wkt -> do
-                [Only geometry] <- query conn "SELECT ?::GEOMETRY" (Only (wkt :: Text)) :: IO [Only RawGeometry]
-                (query conn "SELECT system.main.ST_GeomFromWKB(?)::VARIANT" (Only (rawGeometryWKB geometry)) :: IO [Only Variant]) >>= (@?= [Only (geometryPayload (rawGeometryWKB geometry))])
-        , testCase "geometry payload conversion ignores user macros with built-in names" $ withConnection ":memory:" \conn -> do
-            [Only geometry] <- query_ conn "SELECT 'POINT (1 2)'::GEOMETRY" :: IO [Only RawGeometry]
-            _ <- execute_ conn "CREATE MACRO ST_AsText(x) AS 42"
-            _ <- execute_ conn "CREATE MACRO ST_GeomFromWKB(x) AS 'POINT (9 9)'::GEOMETRY"
-            (query conn "SELECT system.main.ST_GeomFromWKB(?)::VARIANT" (Only (rawGeometryWKB geometry)) :: IO [Only Variant]) >>= (@?= [Only (geometryPayload (rawGeometryWKB geometry))])
-        , testCase "binary geometry payloads retain NaN bits and mixed member layouts" $ withConnection ":memory:" \conn ->
-            forM_
-                [ G.PointGeometry (G.PointXYZ (G.XYZ (castWord64ToDouble 0x7ff8000000000001) (castWord64ToDouble 0x7ff8000000000002) 7))
-                , G.GeometryCollection (V.fromList [G.PointGeometry (G.PointXY (G.XY 1 2)), G.PointGeometry (G.PointXYZ (G.XYZ 3 4 5))])
+              Nothing -> assertFailure "concurrent VARIANT decoding timed out"
+              Just outcomes -> mapM_ (either throwIO pure) outcomes
+    , testGroup
+        "scalar payloads decode like native values"
+        [ testCase (Text.unpack sql) $ withConnection ":memory:" \conn -> do
+            -- Two rows with one tag use the list cast. The round trip uses the cast of one value.
+            rows <-
+              query_ conn (Query ("SELECT (" <> sql <> ")::VARIANT, {'v': " <> sql <> "}::VARIANT, " <> sql <> " FROM range(2)"))
+                :: IO [(Variant, Variant, FieldValue)]
+            length rows @?= 2
+            forM_ rows \(Variant actual, Variant object, native) -> do
+              actual @?= native
+              object @?= variantObject [("v", native)]
+              roundTrip conn native
+        | sql <- scalarCases
+        ]
+    , testCase "explicit casts bind plain parameters" $ withConnection ":memory:" \conn -> do
+        [Only record] <- query_ conn "SELECT {'a': 1, 'b': 'x'}" :: IO [Only (StructValue FieldValue)]
+        ( query
+            conn
+            "SELECT ?::VARIANT, ?::VARIANT, ?::VARIANT, ?::VARIANT"
+            (42 :: Int64, "two" :: Text, record, sized [1, 2] :: SizedArray 2 Int64)
+            :: IO [(Variant, Variant, Variant, Variant)]
+          )
+          >>= ( @?=
+                  [
+                    ( Variant (FieldInt64 42)
+                    , Variant (FieldText "two")
+                    , Variant (variantObject [("a", FieldInt32 1), ("b", FieldText "x")])
+                    , Variant (FieldList [FieldInt64 1, FieldInt64 2])
+                    )
+                  ]
+              )
+        (query conn "SELECT [NULL::VARIANT, ?::VARIANT, ?::VARIANT]" (42 :: Int64, "two" :: Text) :: IO [Only [Variant]])
+          >>= (@?= [Only [Variant FieldNull, Variant (FieldInt64 42), Variant (FieldText "two")]])
+        _ <- execute_ conn "CREATE TABLE variants (v VARIANT)"
+        _ <- executeMany conn "INSERT INTO variants VALUES (?)" [Only (7 :: Int64), Only 8]
+        _ <- execute conn "INSERT INTO variants VALUES (?)" (Only record)
+        (query_ conn "SELECT v FROM variants" :: IO [Only Variant])
+          >>= ( @?=
+                  [Only (Variant (FieldInt64 7)), Only (Variant (FieldInt64 8)), Only (Variant (variantObject [("a", FieldInt32 1), ("b", FieldText "x")]))]
+              )
+    , testCase "existing FromField instances read VARIANT payloads" $ withConnection ":memory:" \conn -> do
+        (query_ conn "SELECT 42::BIGINT::VARIANT, 'x'::VARIANT, [1, 2, 3]::VARIANT" :: IO [(Int64, Text, [Int64])])
+          >>= (@?= [(42, "x", [1, 2, 3])])
+        (query_ conn "SELECT {'payload': {'x': 18446744073709551615::UBIGINT}::VARIANT}" :: IO [Only VariantRecord])
+          >>= (@?= [Only (VariantRecord (Variant (variantObject [("x", FieldWord64 maxBound)])))])
+    , testCase "bound payloads keep integer widths and decimal scale" $ withConnection ":memory:" \conn ->
+        forM_
+          [ ("'-128'::TINYINT", FieldInt8 minBound)
+          , ("12.34::DECIMAL(4,2)", FieldDecimal (DecimalValue 4 2 1234))
+          , ("255::UTINYINT", FieldWord8 maxBound)
+          ]
+          \(sql, value) ->
+            (query conn (Query ("SELECT variant_typeof(?) = variant_typeof((" <> sql <> ")::VARIANT)")) (Only (Variant value)) :: IO [Only Bool])
+              >>= (@?= [Only True])
+    , testCase "floating special values retain type and bits" $ withConnection ":memory:" \conn -> do
+        forM_ [0, -0.0, 1 / 0, -1 / 0, 0 / 0] \value -> do
+          [Only (Variant actual)] <- query conn "SELECT ?" (Only (Variant (FieldDouble value)))
+          case actual of
+            FieldDouble decoded
+              | isNaN value -> assertBool "expected Double NaN" (isNaN decoded)
+              | otherwise -> castDoubleToWord64 decoded @?= castDoubleToWord64 value
+            _ -> assertFailure (show actual)
+        forM_ [0, -0.0, 1 / 0, -1 / 0, 0 / 0] \value -> do
+          [Only (Variant actual)] <- query conn "SELECT ?" (Only (Variant (FieldFloat value)))
+          case actual of
+            FieldFloat decoded
+              | isNaN value -> assertBool "expected Float NaN" (isNaN decoded)
+              | otherwise -> castFloatToWord32 decoded @?= castFloatToWord32 value
+            _ -> assertFailure (show actual)
+    , testCase "TIMETZ offsets decode like native values" $ withConnection ":memory:" \conn -> do
+        forM_
+          [ "'12:00:00+01:23'::TIMETZ"
+          , "'23:59:59.999999-15:59'::TIMETZ"
+          , "'00:00:00+00'::TIMETZ"
+          , "'12:00:00+01:23:45'::TIMETZ"
+          , "'00:00:00-15:59:59'::TIMETZ"
+          ]
+          \sql -> do
+            rows <- query_ conn (Query ("SELECT (" <> sql <> ")::VARIANT, " <> sql <> " FROM range(2)")) :: IO [(Variant, FieldValue)]
+            length rows @?= 2
+            forM_ rows \(Variant actual, native) -> do
+              actual @?= native
+              roundTrip conn native
+    , testCase "wide finite timestamp payloads read without losing digits, and do not bind" $ withConnection ":memory:" \conn -> do
+        void (execute_ conn "CREATE TABLE wide_timestamps (seconds TIMESTAMP_S, millis TIMESTAMP_MS)")
+        let units =
+              [(30000000000000, 30000000000000001), (-30000000000000, -30000000000000001), (maxBound - 1, maxBound - 1), (minBound, minBound)]
+                :: [(Int64, Int64)]
+        void (executeMany conn "INSERT INTO wide_timestamps VALUES (?, ?)" [(Seconds seconds, Milliseconds millis) | (seconds, millis) <- units])
+        -- DuckDB sorts the raw values. A cast of these values to VARCHAR gives an
+        -- internal error in DuckDB 2.0.0, so the case does not read their text.
+        forM_ ["seconds", "millis"] \column ->
+          query_ conn (Query ("SELECT rowid FROM wide_timestamps ORDER BY " <> column)) >>= (@?= map Only [3, 1, 0, 2 :: Int64])
+        query_ conn "SELECT seconds, millis FROM wide_timestamps ORDER BY rowid"
+          >>= (@?= [(nativeLocalTime (Seconds seconds), nativeLocalTime (Milliseconds millis)) | (seconds, millis) <- units])
+        rows <-
+          query_ conn "SELECT seconds::VARIANT, seconds, millis::VARIANT, millis FROM wide_timestamps"
+            :: IO [(Variant, FieldValue, Variant, FieldValue)]
+        length rows @?= 4
+        forM_ rows \(seconds, nativeSeconds, millis, nativeMillis) ->
+          forM_ [(seconds, nativeSeconds), (millis, nativeMillis)] \(Variant actual, native) -> do
+            actual @?= native
+            -- The value is outside the range of TIMESTAMP. See
+            -- Note [Time ranges] in "Database.DuckDB.Simple.ToField".
+            outcome <- try (query conn "SELECT ?" (Only (Variant actual)) :: IO [Only Variant])
+            case outcome of
+              Left (err :: SQLError) -> do
+                sqlErrorType err @?= Just ErrorTypeConversion
+                assertBool (show err) ("TIMESTAMP of DuckDB" `Text.isInfixOf` sqlErrorMessage err)
+              Right bound -> assertFailure ("expected the range error, got " <> show bound)
+    , testCase "text and binary values preserve embedded NUL" $ withConnection ":memory:" \conn -> do
+        roundTrip conn (FieldText "before\0after íslenska λ 😀")
+        roundTrip conn (FieldBlob (BS.pack [0, 1, 127, 128, 255, 0]))
+    , testCase "objects preserve case-sensitive names and heterogeneous children" $ withConnection ":memory:" \conn -> do
+        let value =
+              variantObject
+                [ ("Case", FieldInt64 9007199254740993)
+                , ("case", FieldDecimal (DecimalValue 38 9 1234567890123456789))
+                , ("quote' íslenska λ", FieldList [FieldNull, FieldText "x", FieldList [], variantObject []])
                 ]
-                \shape -> do
-                    raw <- either assertFailure pure (toRawGeometry shape)
-                    (query conn "SELECT system.main.ST_GeomFromWKB(?)::VARIANT" (Only (rawGeometryWKB raw)) :: IO [Only Variant]) >>= (@?= [Only (geometryPayload (rawGeometryWKB raw))])
-        , testCase "invalid values fail before binding and connection reuse succeeds" $ withConnection ":memory:" \conn -> do
-            forM_
-                [ FieldHugeInt (2 ^ (127 :: Int))
-                , FieldUHugeInt (-1)
-                , FieldUHugeInt (2 ^ (128 :: Int))
-                , FieldDecimal (DecimalValue 0 0 0)
-                , FieldDecimal (DecimalValue 5 6 1)
-                , FieldDecimal (DecimalValue 3 0 1000)
-                , FieldBit (BitString 8 (BS.singleton 0))
-                , variantObject [("same", FieldNull), ("same", FieldBool True)]
-                , variantObject [("", FieldBool True)]
-                , variantObject [("first", FieldBool False), ("", FieldBool True)]
-                , variantObject [("before\0after", FieldNull)]
+        roundTrip conn value
+        ( query conn "SELECT variant_extract(?, 'Case')::BIGINT, variant_extract(?, 'case')::DECIMAL(38,9)::VARCHAR" (Variant value, Variant value)
+            :: IO [(Int64, Text)]
+          )
+          >>= (@?= [(9007199254740993, "1234567890.123456789")])
+    , testCase "native objects use lexical key order and arrays retain element order" $ withConnection ":memory:" \conn ->
+        (query_ conn "SELECT {'z':1, 'a':2, 'm':[3,1,2]}::VARIANT" :: IO [Only Variant])
+          >>= (@?= [Only (Variant (variantObject [("a", FieldInt32 2), ("m", FieldList [FieldInt32 3, FieldInt32 1, FieldInt32 2]), ("z", FieldInt32 1)]))])
+    , testCase "empty containers and NULL stay distinct" $ withConnection ":memory:" \conn -> do
+        forM_ [FieldNull, FieldList [], variantObject [], FieldList [FieldNull], variantObject [("x", FieldNull)]] (roundTrip conn)
+        (query_ conn "SELECT NULL::VARIANT" :: IO [Only (Maybe Variant)]) >>= (@?= [Only Nothing])
+        (query conn "SELECT ?" (Only (Variant FieldNull)) :: IO [Only FieldValue]) >>= (@?= [Only FieldNull])
+    , testCase "native objects preserve empty and embedded NUL keys" $ withConnection ":memory:" \conn -> do
+        (query_ conn "SELECT '{\"\":42}'::JSON::VARIANT" :: IO [Only Variant])
+          >>= (@?= [Only (Variant (variantObject [("", FieldWord64 42)]))])
+        (query_ conn "SELECT '{\"A\":1,\"a\":2,\"a\\u0000b\":3}'::JSON::VARIANT" :: IO [Only Variant])
+          >>= (@?= [Only (Variant (variantObject [("A", FieldWord64 1), ("a", FieldWord64 2), ("a\0b", FieldWord64 3)]))])
+    , testCase "empty object keys survive parameter binding" $ withConnection ":memory:" \conn -> do
+        [Only value] <- query_ conn "SELECT '{\"named\": 1, \"\": 42}'::JSON::VARIANT" :: IO [Only Variant]
+        query conn "SELECT ?" (Only value) >>= (@?= [Only value])
+        -- Decoded objects list their keys in DuckDB's lexicographic order.
+        roundTrip
+          conn
+          (variantObject [("", FieldList [FieldNull, variantObject [("", FieldText "λ"), ("named", FieldInt64 1)]]), ("named", FieldBool True)])
+        sole <- try (query conn "SELECT ?" (Only (Variant (variantObject [("", FieldInt64 42)])))) :: IO (Either SQLError [Only Variant])
+        case sole of
+          Left err -> do
+            sqlErrorType err @?= Just ErrorInputInvalid
+            assertBool (Text.unpack (sqlErrorMessage err)) ("only an empty key" `Text.isInfixOf` sqlErrorMessage err)
+          Right _ -> assertFailure "expected the native constructor limit for an object with only an empty key"
+    , testCase "objects with two empty keys fail the unique key check" $ withConnection ":memory:" \conn -> do
+        result <-
+          try (query conn "SELECT ?" (Only (Variant (variantObject [("", FieldInt64 1), ("", FieldInt64 2)]))))
+            :: IO (Either SQLError [Only Variant])
+        case result of
+          Left err -> do
+            sqlErrorType err @?= Just ErrorInputInvalid
+            sqlErrorMessage err @?= "duckdb-simple: VARIANT objects need unique keys"
+          Right _ -> assertFailure "expected the unique key check to reject two empty keys"
+    , testCase "metadata conversion recovers after preparation failure and ignores shadowing macros" $ withConnection ":memory:" \conn -> do
+        void (execute_ conn "SET GLOBAL max_expression_depth = 10")
+        failed <- try (query_ conn "SELECT 42::VARIANT" :: IO [Only Variant])
+        void (execute_ conn "SET GLOBAL max_expression_depth = 1000")
+        case failed of
+          Left SQLError{sqlErrorType} -> sqlErrorType @?= Just ErrorQueryBinder
+          Right _ -> assertFailure "expected the metadata preparation depth error"
+        -- The connection keeps the prepared metadata statement of the first successful decode.
+        (query_ conn "SELECT {'a': 42::TINYINT}::VARIANT" :: IO [Only Variant]) >>= (@?= [Only (Variant (variantObject [("a", FieldInt8 42)]))])
+        void (execute_ conn "CREATE MACRO variant_typeof(x) AS 'VARCHAR'")
+        void (execute_ conn "CREATE MACRO list_transform(x,y) AS [42]")
+        void (execute_ conn "CREATE MACRO variant_keys(x) AS ['wrong']")
+        (query_ conn "SELECT [42::TINYINT::VARIANT, 'two'::VARIANT]::VARIANT" :: IO [Only Variant])
+          >>= (@?= [Only (Variant (FieldList [FieldInt8 42, FieldText "two"]))])
+        (query_ conn "SELECT {'a': 42::TINYINT}::VARIANT" :: IO [Only Variant]) >>= (@?= [Only (Variant (variantObject [("a", FieldInt8 42)]))])
+    , testCase "deep native arrays decode without a library depth limit" $ withConnection ":memory:" \conn ->
+        forM_ [128, 256 :: Int] \depth -> do
+          let expected = Variant (foldr (const (FieldList . pure)) (FieldWord64 7) [1 .. depth])
+          (query conn "SELECT (repeat('[', ?) || '7' || repeat(']', ?))::JSON::VARIANT AS payload" (depth, depth) :: IO [Only Variant])
+            >>= (@?= [Only expected])
+          let object = Variant (variantObject [("nested", variantPayload expected)])
+          ( query conn "SELECT ('{\"nested\":' || repeat('[', ?) || '7' || repeat(']', ?) || '}')::JSON::VARIANT AS payload" (depth, depth)
+              :: IO [Only Variant]
+            )
+            >>= (@?= [Only object])
+    , testCase "ARRAY parameters and generic records contain VARIANT" $ withConnection ":memory:" \conn -> do
+        let array = sized [Variant (FieldInt8 1), Variant (FieldText "two"), Variant FieldNull] :: SizedArray 3 Variant
+        (query conn "SELECT ?" (Only array) :: IO [Only (SizedArray 3 Variant)]) >>= (@?= [Only array])
+        let record = VariantRecord (Variant (variantObject [("x", FieldWord64 maxBound)]))
+        (query conn "SELECT ?" (Only record) :: IO [Only VariantRecord]) >>= (@?= [Only record])
+    , testCase "nullable ARRAY parameters preserve heterogeneous VARIANT values" $ withConnection ":memory:" \conn -> do
+        let values =
+              sized
+                [ Nothing
+                , Just (Variant (FieldInt64 42))
+                , Just (Variant (FieldText "two"))
+                , Just (Variant (variantObject [("xs", FieldList [FieldNull, FieldBool True])]))
                 ]
-                \value -> assertFailureIO (query conn "SELECT ?" (Only (Variant value)) :: IO [Only Variant])
-            (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+        (query conn "SELECT typeof(?), ?" (values, values) :: IO [(Text, SizedArray 4 (Maybe Variant))]) >>= (@?= [("VARIANT[4]", values)])
+    , testCase "empty ARRAY parameters raise an error" $ withConnection ":memory:" \conn -> do
+        let values = sized [] :: SizedArray 0 (Maybe Variant)
+        result <- try (query conn "SELECT typeof(?)" (Only values))
+        case result of
+          Left SQLError{sqlErrorMessage, sqlErrorType} -> do
+            assertBool "must identify empty ARRAY" ("empty ARRAY" `Text.isInfixOf` sqlErrorMessage)
+            sqlErrorType @?= Just ErrorInputInvalid
+          Right (_ :: [Only Text]) -> assertFailure "expected the empty ARRAY error"
+    , testCase "parameter binding supplies a complete VARIANT type" $ withConnection ":memory:" \conn -> do
+        let value = variantObject [("xs", FieldList [FieldNull, FieldInt64 42])]
+        roundTrip conn value
+        (query conn "SELECT typeof(?)" (Only (Variant value)) :: IO [Only Text]) >>= (@?= [Only "VARIANT"])
+    , testCase "the first VARIANT parameter does not end a streaming result" $ withConnection ":memory:" \conn ->
+        withStatement conn "SELECT ?" \stmt -> do
+          total <- Streaming.fold_ conn "SELECT i FROM range(100000) t(i)" 0 \acc (Only i) -> do
+            when (i == 0) (bind stmt [toField (Variant (FieldInt64 42))])
+            pure (acc + i)
+          total @?= (sum [0 .. 99999] :: Int64)
+    , testCase "VARIANT type construction uses the supplied factory" $ withConnection ":memory:" \conn ->
+        withConnectionHandle conn \native -> withConnectionFactory native \factory ->
+          bracket (logicalTypeFromRep factory (LogicalTypeScalar LogicalTypeIdVariant)) destroyLogicalType \logical ->
+            logicalTypeToRep factory logical >>= (@?= LogicalTypeScalar LogicalTypeIdVariant)
+    , testCase "VARIANT payloads and GEOMETRY CRS metadata bind together" $ withConnection ":memory:" \conn -> do
+        [Only value] <- query_ conn "SELECT {'payload': 42::VARIANT, 'shape': NULL::GEOMETRY('OGC:CRS84')}" :: IO [Only (StructValue FieldValue)]
+        (query conn "SELECT typeof(?)" (Only value) :: IO [Only Text]) >>= (@?= [Only "STRUCT(payload VARIANT, shape GEOMETRY('OGC:CRS84'))"])
+        (query conn "SELECT ?" (Only value) :: IO [Only (StructValue FieldValue)]) >>= (@?= [Only value])
+    , testCase "inactive VARIANT UNION members have complete types" $ withConnection ":memory:" \conn -> do
+        [Only value] <-
+          query_ conn "SELECT union_value(number := 42::BIGINT)::UNION(number BIGINT, payload VARIANT)" :: IO [Only (UnionValue FieldValue)]
+        (query conn "SELECT ?" (Only value) :: IO [Only (UnionValue FieldValue)]) >>= (@?= [Only value])
+    , testCase "native LIST, ARRAY, MAP and STRUCT metadata round trip" $ withConnection ":memory:" \conn -> do
+        [Only value] <-
+          query_
+            conn
+            "SELECT {'xs': [1::VARIANT, 'two'::VARIANT, NULL], 'fixed': [42::VARIANT]::VARIANT[1], 'map': MAP {'x': {'a': 9}::VARIANT}}"
+            :: IO [Only (StructValue FieldValue)]
+        (query conn "SELECT ?" (Only value) :: IO [Only (StructValue FieldValue)]) >>= (@?= [Only value])
+    , testCase "UNION payloads retain VARIANT type, including NULL" $ withConnection ":memory:" \conn ->
+        forM_ ["SELECT union_value(v := {'a': 42}::VARIANT)", "SELECT union_value(v := NULL::VARIANT)"] \sql -> do
+          [Only value] <- query_ conn sql :: IO [Only (UnionValue FieldValue)]
+          (query conn "SELECT ?" (Only value) :: IO [Only (UnionValue FieldValue)]) >>= (@?= [Only value])
+    , testGroup
+        "heterogeneous folds cross chunk boundaries"
+        [ testCase mode $ withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+            -- Cancel after metadata and the first chunk have been decoded.
+            cancelled <- try $ foldRows conn "SELECT i::VARIANT FROM range(5000) t(i)" (0 :: Int64) \n (Only (Variant actual)) -> do
+              actual @?= FieldInt64 0
+              self <- myThreadId
+              throwTo self UserInterrupt
+              pure n
+            (cancelled :: Either AsyncException Int64) @?= Left UserInterrupt
+            count <- foldRows
+              conn
+              "SELECT CASE WHEN i % 3 = 0 THEN i::VARIANT WHEN i % 3 = 1 THEN 'text'::VARIANT ELSE {'n': i, 'xs': [NULL, i]}::VARIANT END FROM range(5000) t(i)"
+              (0 :: Int64)
+              \n (Only (Variant actual)) -> do
+                let expected = case n `mod` 3 of
+                      0 -> FieldInt64 n
+                      1 -> FieldText "text"
+                      _ -> variantObject [("n", FieldInt64 n), ("xs", FieldList [FieldNull, FieldInt64 n])]
+                actual @?= expected
+                pure (n + 1)
+            count @?= 5000
+        | (mode, foldRows) <- [("materialized", fold_), ("native streaming", Streaming.fold_)]
         ]
+    , testCase "one column with many payload tags decodes each row exactly" $ withConnection ":memory:" \conn -> do
+        rows <-
+          query_
+            conn
+            "SELECT i, CASE i % 12 WHEN 0 THEN NULL WHEN 1 THEN (i % 24 = 1)::VARIANT WHEN 2 THEN (i % 100)::TINYINT::VARIANT WHEN 3 THEN i::VARIANT WHEN 4 THEN (i * 0.5)::DOUBLE::VARIANT WHEN 5 THEN i::DECIMAL(9,2)::VARIANT WHEN 6 THEN ('t' || i)::VARIANT WHEN 7 THEN [i, NULL, i + 1]::VARIANT WHEN 8 THEN {'n': i, 'xs': [i]}::VARIANT WHEN 9 THEN {'k': {'deep': 't' || i}}::VARIANT WHEN 10 THEN []::VARIANT ELSE i::UBIGINT::VARIANT END FROM range(5000) t(i)"
+            :: IO [(Int64, Maybe Variant)]
+        let text n = FieldText ("t" <> Text.pack (show n))
+            expected n = case n `mod` 12 of
+              0 -> Nothing
+              1 -> Just (FieldBool (n `mod` 24 == 1))
+              2 -> Just (FieldInt8 (fromIntegral (n `mod` 100)))
+              3 -> Just (FieldInt64 n)
+              4 -> Just (FieldDouble (fromIntegral n * 0.5))
+              5 -> Just (FieldDecimal (DecimalValue 9 2 (toInteger n * 100)))
+              6 -> Just (text n)
+              7 -> Just (FieldList [FieldInt64 n, FieldNull, FieldInt64 (n + 1)])
+              8 -> Just (variantObject [("n", FieldInt64 n), ("xs", FieldList [FieldInt64 n])])
+              9 -> Just (variantObject [("k", variantObject [("deep", text n)])])
+              10 -> Just (FieldList [])
+              _ -> Just (FieldWord64 (fromIntegral n))
+        length rows @?= 5000
+        forM_ rows \(n, actual) -> fmap variantPayload actual @?= expected n
+    , testCase "GEOMETRY, BLOB and BIGNUM payloads in one column decode like native values" $ withConnection ":memory:" \conn -> do
+        rows <-
+          query_
+            conn
+            "SELECT i, CASE i % 3 WHEN 0 THEN g::VARIANT WHEN 1 THEN b::VARIANT ELSE n::VARIANT END, g, b, n FROM (SELECT i, ('POINT (' || i || ' ' || (i + 1) || ')')::GEOMETRY AS g, encode('b' || i) AS b, (i::VARCHAR || '12345678901234567890')::BIGNUM AS n FROM range(5000) t(i))"
+            :: IO [(Int64, Variant, FieldValue, FieldValue, FieldValue)]
+        length rows @?= 5000
+        forM_ rows \(n, Variant actual, geometry, blob, bignum) ->
+          actual @?= case n `mod` 3 of
+            0 -> geometry
+            1 -> blob
+            _ -> bignum
+    , testCase "objects with many key layouts and many keys decode exactly" $ withConnection ":memory:" \conn -> do
+        let digits = Text.pack . show :: Int64 -> Text
+        layouts <- query_ conn "SELECT i, json_object('k' || i::VARCHAR, i)::VARIANT FROM range(3000) t(i)" :: IO [(Int64, Variant)]
+        length layouts @?= 3000
+        forM_ layouts \(n, Variant actual) -> actual @?= variantObject [("k" <> digits n, FieldWord64 (fromIntegral n))]
+        (query_ conn "SELECT json_group_object('k' || lpad(i::VARCHAR, 3, '0'), i)::VARIANT FROM range(300) t(i)" :: IO [Only Variant])
+          >>= (@?= [Only (Variant (variantObject [("k" <> Text.justifyRight 3 '0' (digits n), FieldWord64 (fromIntegral n)) | n <- [0 .. 299]]))])
+    , testCase "one column mixes object layouts with special keys" $ withConnection ":memory:" \conn -> do
+        rows <-
+          query_
+            conn
+            "SELECT i, CASE i % 4 WHEN 0 THEN json_object('A', i, 'a', i + 1)::VARIANT WHEN 1 THEN json_object('', i, 'n', i + 1)::VARIANT WHEN 2 THEN json_object('É', i, 'é', i + 1, 'a\"b', i + 2, 'it''s λ', i + 3)::VARIANT ELSE json_object('n', i, 'a', i + 1)::VARIANT END FROM range(3000) t(i)"
+            :: IO [(Int64, Variant)]
+        -- Decoded objects list their keys in DuckDB's lexicographic order.
+        let expected n = variantObject [(key, FieldWord64 (fromIntegral (n + offset))) | (key, offset) <- layout]
+              where
+                layout = case n `mod` 4 of
+                  0 -> [("A", 0), ("a", 1)]
+                  1 -> [("", 0), ("n", 1)]
+                  2 -> [("a\"b", 2), ("it's λ", 3), ("É", 0), ("é", 1)]
+                  _ -> [("a", 1), ("n", 0)]
+        length rows @?= 3000
+        forM_ rows \(n, Variant actual) -> actual @?= expected n
+    , testCase "VARIANT objects with keys that a STRUCT cannot name decode in each chunk" $
+        withConnectionWithConfig ":memory:" [("threads", "1")] \conn -> do
+          -- The empty key needs the extraction query. The result has three chunks.
+          let sql = "SELECT i, json_object('', i, 'n', i + 1)::VARIANT FROM range(5000) t(i)" :: Query
+              expected n = variantObject [("", FieldWord64 (fromIntegral n)), ("n", FieldWord64 (fromIntegral (n + 1)))]
+          rows <- query_ conn sql :: IO [(Int64, Variant)]
+          rows @?= [(n, Variant (expected n)) | n <- [0 .. 4999]]
+          count <- fold_ conn sql (0 :: Int64) \n (i, Variant actual) -> do
+            (i, actual) @?= (n, expected n)
+            pure (n + 1)
+          count @?= 5000
+    , testCase "VARIANT objects with different key counts decode after each other" $ withConnection ":memory:" \conn -> do
+        -- Each object has an empty key, so each object group uses the extraction
+        -- query. The key count changes between the queries and in the last query.
+        let two n = variantObject [("", FieldWord64 n), ("n", FieldWord64 (n + 1))]
+            three n = variantObject [("", FieldWord64 n), ("a", FieldWord64 (n + 1)), ("b", FieldWord64 (n + 2))]
+            twoKeys = "SELECT json_object('', i, 'n', i + 1)::VARIANT FROM range(3) t(i)"
+            threeKeys = "SELECT json_object('', i, 'a', i + 1, 'b', i + 2)::VARIANT FROM range(3) t(i)"
+            check sql expected = (query_ conn sql :: IO [Only Variant]) >>= (@?= map (Only . Variant) expected)
+        check twoKeys (map two [0 .. 2])
+        check threeKeys (map three [0 .. 2])
+        check twoKeys (map two [0 .. 2])
+        check
+          "SELECT CASE WHEN i % 2 = 0 THEN json_object('', i, 'n', i + 1) ELSE json_object('', i, 'a', i + 1, 'b', i + 2) END::VARIANT FROM range(4) t(i)"
+          [two 0, three 1, two 2, three 3]
+        forM_
+          [ []
+          , [FieldNull, FieldInt8 3, FieldText "two"]
+          , [FieldList [], variantObject []]
+          , [FieldList [FieldInt64 7, FieldNull], three 4]
+          , []
+          , [FieldInt64 9]
+          ]
+          \payloads ->
+            (query conn "SELECT unnest(?::VARIANT[])" (Only (map Variant payloads)) :: IO [Only Variant])
+              >>= (@?= map (Only . Variant) payloads)
+    , testCase "filtered and reordered rows use the right child offsets" $ withConnection ":memory:" \conn -> do
+        rows <- query_ conn "SELECT {'n': i, 'xs': [i, i + 1]}::VARIANT FROM range(10000) t(i) WHERE i % 97 = 0 ORDER BY i DESC LIMIT 40"
+        let expected =
+              [ Only (Variant (variantObject [("n", FieldInt64 n), ("xs", FieldList [FieldInt64 n, FieldInt64 (n + 1)])]))
+              | n <- take 40 (reverse [0, 97 .. 9999])
+              ]
+        rows @?= expected
+    , testCase "file-backed values survive checkpoint and reopen" $
+        bracket newDatabase removeDatabase \path -> do
+          withConnectionWithConfig path [("storage_compatibility_version", "v1.5.0")] \conn -> do
+            void
+              ( execute_
+                  conn
+                  "CREATE TABLE stored AS SELECT i, {'n': i, 'xs': [i, NULL], 'text': i::VARCHAR}::VARIANT AS value, 'POINT (1 2)'::GEOMETRY('OGC:CRS84') AS geometry FROM range(10000) t(i)"
+              )
+            void (execute_ conn "CHECKPOINT")
+          withConnectionWithConfig path [("storage_compatibility_version", "v1.5.0")] \conn -> do
+            rows <- query_ conn "SELECT value FROM stored WHERE i % 97 = 0 ORDER BY i DESC LIMIT 40" :: IO [Only Variant]
+            let expected =
+                  [ Only (Variant (variantObject [("n", FieldInt64 n), ("text", FieldText (Text.pack (show n))), ("xs", FieldList [FieldInt64 n, FieldNull])]))
+                  | n <- take 40 (reverse [0, 97 .. 9999])
+                  ]
+            rows @?= expected
+            [Only nativeKeys] <- query_ conn "SELECT system.main.variant_keys(value) FROM stored LIMIT 1" :: IO [Only [Text]]
+            nativeKeys @?= ["n", "text", "xs"]
+            forM_ rows \(Only (Variant payloadValue)) -> case payloadValue of
+              FieldStruct object -> map structFieldName (elems (structValueFields object)) @?= nativeKeys
+              other -> assertFailure (show other)
+            [Only geometry] <- query_ conn "SELECT geometry FROM stored LIMIT 1" :: IO [Only RawGeometry]
+            rawGeometryCRS geometry @?= Just "OGC:CRS84"
+            BS.length (rawGeometryWKB geometry) @?= 21
+    , testCase "geometry payload keeps WKB; native VARIANT does not retain CRS" $ withConnection ":memory:" \conn -> do
+        [Only geometry] <- query_ conn "SELECT 'POINT ZM (1 2 3 4)'::GEOMETRY('OGC:CRS84')" :: IO [Only RawGeometry]
+        [Only value] <- query_ conn "SELECT 'POINT ZM (1 2 3 4)'::GEOMETRY('OGC:CRS84')::VARIANT" :: IO [Only Variant]
+        value @?= geometryPayload (rawGeometryWKB geometry)
+        (query conn "SELECT system.main.ST_GeomFromWKB(?)::VARIANT" (Only (rawGeometryWKB geometry)) :: IO [Only Variant]) >>= (@?= [Only value])
+        ( query conn "SELECT system.main.ST_CRS((system.main.ST_GeomFromWKB(?)::VARIANT)::GEOMETRY)" (Only (rawGeometryWKB geometry))
+            :: IO [Only (Maybe Text)]
+          )
+          >>= (@?= [Only Nothing])
+        forM_ [variantPayload value, FieldList [variantPayload value], variantObject [("shape", variantPayload value)]] (roundTrip conn)
+    , testCase "raw geometry without a CRS binds in a VARIANT, and a CRS raises an error" $ withConnection ":memory:" \conn -> do
+        nanPoint <-
+          either assertFailure pure $
+            toRawGeometry (G.PointGeometry (G.PointXYZ (G.XYZ (castWord64ToDouble 0x7ff8000000000001) (castWord64ToDouble 0x7ff8000000000002) 7)))
+        native <- forM ["GEOMETRYCOLLECTION ZM EMPTY", "MULTIPOLYGON M EMPTY", "POINT Z (NaN NaN 7)", "POLYGON ((0 0, 1 0, 1 1, 0 0))"] \wkt -> do
+          [Only geometry] <- query conn "SELECT ?::GEOMETRY" (Only (wkt :: Text)) :: IO [Only RawGeometry]
+          pure geometry
+        forM_ (map rawGeometryWKB (nanPoint : native)) \wkb -> do
+          let value = geometryPayload wkb
+          roundTrip conn (variantPayload value)
+          (query conn "SELECT variant_typeof(?), (?)::GEOMETRY::BLOB" (value, value) :: IO [(Text, BS.ByteString)]) >>= (@?= [("GEOMETRY", wkb)])
+        [Only withCRS] <- query_ conn "SELECT 'POINT (1 2)'::GEOMETRY('OGC:CRS84')" :: IO [Only RawGeometry]
+        forM_ [FieldGeometry withCRS, FieldList [FieldGeometry withCRS], variantObject [("shape", FieldGeometry withCRS)]] \input -> do
+          result <- try (query conn "SELECT ?" (Only (Variant input)) :: IO [Only Variant])
+          case result of
+            Left err -> do
+              sqlErrorMessage err
+                @?= "duckdb-simple: a VARIANT does not keep the CRS of a GEOMETRY, so the GEOMETRY value with the CRS 'OGC:CRS84' cannot bind as a VARIANT"
+              sqlErrorType err @?= Just ErrorInputInvalid
+            Right _ -> assertFailure "expected a VARIANT CRS error"
+        (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+    , testCase "UNION, MAP, and ENUM payloads raise an error at each depth" $ withConnection ":memory:" \conn -> do
+        let members =
+              listArray
+                (0, 1)
+                [UnionMemberType "a" (LogicalTypeScalar LogicalTypeIdInteger), UnionMemberType "b" (LogicalTypeScalar LogicalTypeIdVarchar)]
+            depths payload = [payload, FieldList [payload], variantObject [("u", payload)], variantObject [("u", FieldList [payload])]]
+            bindPayload input = try (query conn "SELECT ?" (Only (Variant input)) :: IO [Only Variant])
+        forM_ [FieldInt32 1, FieldNull] \member ->
+          forM_ (depths (FieldUnion (UnionValue 0 "a" member members))) \input ->
+            bindPayload input >>= \result -> case result of
+              Left err -> do
+                sqlErrorType err @?= Just ErrorInputInvalid
+                assertBool (Text.unpack (sqlErrorMessage err)) ("a VARIANT keeps only the member value of a UNION" `Text.isInfixOf` sqlErrorMessage err)
+              Right rows -> assertFailure ("expected the UNION error, got " <> show rows)
+        forM_
+          [ (FieldMap [(FieldText "k", FieldInt32 1)], "a VARIANT stores a MAP as a list of key and value objects")
+          , (FieldEnum 0 "a", "a VARIANT stores an ENUM as its text")
+          ]
+          \(payload, reason) -> forM_ (depths payload) \input -> do
+            result <- try (query conn "SELECT ?" (Only (Variant input)) :: IO [Only Variant])
+            case result of
+              Left SQLError{sqlErrorType, sqlErrorMessage} -> do
+                sqlErrorType @?= Just ErrorInputInvalid
+                assertBool (Text.unpack sqlErrorMessage) (Text.pack reason `Text.isInfixOf` sqlErrorMessage)
+              Right rows -> assertFailure ("expected the " <> reason <> " error, got " <> show rows)
+        (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+    , testCase "a Variant read of a JSON type raises an error at each depth, and the cast reads the parsed value" $ withConnection ":memory:" \conn -> do
+        let refused column expression sqlName =
+              try (query_ conn (Query ("SELECT " <> expression <> " AS " <> column)) :: IO [Only Variant]) >>= \case
+                Left SQLError{sqlErrorMessage} ->
+                  sqlErrorMessage
+                    @?= "duckdb-simple: column "
+                      <> column
+                      <> " has type "
+                      <> sqlName
+                      <> " but expected Variant: DuckDB casts JSON to VARIANT by parsing the text; write "
+                      <> column
+                      <> "::VARIANT"
+                Right rows -> assertFailure ("expected Incompatible for " <> Text.unpack expression <> ", got " <> show rows)
+        refused "j" "'{\"a\": 1}'::JSON" "JSON"
+        refused "l" "['{\"a\": 1}']::JSON[]" "JSON[]"
+        refused "s" "{'k': '{\"a\": 1}'::JSON}" "STRUCT(k JSON)"
+        refused "m" "MAP {'k': '{\"a\": 1}'::JSON}" "MAP(VARCHAR, JSON)"
+        (query_ conn "SELECT j::VARIANT FROM (SELECT '{\"a\": 1}'::JSON AS j)" :: IO [Only Variant])
+          >>= (@?= [Only (Variant (variantObject [("a", FieldWord64 1)]))])
+        (query_ conn "SELECT l::VARIANT FROM (SELECT ['{\"a\": 1}']::JSON[] AS l)" :: IO [Only Variant])
+          >>= (@?= [Only (Variant (FieldList [variantObject [("a", FieldWord64 1)]]))])
+    , testCase "a Variant reads only a value that a VARIANT can hold" $ withConnection ":memory:" \conn -> do
+        -- The cast to VARIANT changes a value of another shape, so the read
+        -- raises the error of an incompatible column at each depth. The cast in
+        -- SQL reads.
+        forM_
+          [ ("'a'::ENUM('a', 'b')", "ENUM('a', 'b')")
+          , ("MAP {'k': 1}", "MAP(VARCHAR, INTEGER)")
+          , ("union_value(n := 1)", "UNION(n INTEGER)")
+          , ("{'b': 1, 'a': 2}", "STRUCT(b INTEGER, a INTEGER)")
+          , ("[1, 2]::INTEGER[2]", "INTEGER[2]")
+          , ("row(1, 'x')", "TUPLE(INTEGER, VARCHAR)")
+          , ("'POINT (1 2)'::GEOMETRY('OGC:CRS84')", "GEOMETRY('OGC:CRS84')")
+          , ("['a'::ENUM('a', 'b')]", "ENUM('a', 'b')[]")
+          , ("[{'a': 1}]", "STRUCT(a INTEGER)[]")
+          , ("{'v': 1::VARIANT, 'm': MAP {'k': 1}}", "STRUCT(v VARIANT, m MAP(VARCHAR, INTEGER))")
+          , ("{'b': 1::VARIANT, 'a': 2::VARIANT}", "STRUCT(b VARIANT, a VARIANT)")
+          , ("{'é': 1::VARIANT, 'z': 2::VARIANT}", "STRUCT(\"é\" VARIANT, z VARIANT)")
+          ]
+          \(expression, sqlName) -> do
+            result <- try (query_ conn (Query ("SELECT " <> expression <> " AS c")) :: IO [Only Variant])
+            case result of
+              Left SQLError{sqlErrorMessage} ->
+                sqlErrorMessage
+                  @?= "duckdb-simple: column c has type "
+                    <> sqlName
+                    <> " but expected Variant: a VARIANT does not hold a value of this shape; write c::VARIANT"
+              Right rows -> assertFailure ("expected Incompatible for " <> Text.unpack expression <> ", got " <> show rows)
+            (query_ conn (Query ("SELECT (" <> expression <> ")::VARIANT")) :: IO [Only Variant]) >>= \rows -> length rows @?= 1
+        ( query_ conn "SELECT ('a'::ENUM('a', 'b'))::VARIANT, (MAP {'k': 1})::VARIANT, {'b': 1, 'a': 2}::VARIANT, ([1, 2]::INTEGER[2])::VARIANT"
+            :: IO [(Variant, Variant, Variant, Variant)]
+          )
+          >>= ( @?=
+                  [
+                    ( Variant (FieldText "a")
+                    , Variant (FieldList [variantObject [("key", FieldText "k"), ("value", FieldInt32 1)]])
+                    , Variant (variantObject [("a", FieldInt32 2), ("b", FieldInt32 1)])
+                    , Variant (FieldList [FieldInt32 1, FieldInt32 2])
+                    )
+                  ]
+              )
+        -- A value of the VARIANT shape reads: a scalar, a LIST, a VARIANT in a
+        -- LIST or in a STRUCT field, a STRUCT with VARIANT fields and keys in
+        -- byte order, and a VARIANT object whose keys were given out of order.
+        -- Each equals its cast.
+        forM_
+          [ "7::INTEGER"
+          , "[1, 2]"
+          , "[1::VARIANT, 'x'::VARIANT]"
+          , "{'v': 1::VARIANT}"
+          , "{'a': 1::VARIANT, 'b': 2::VARIANT}"
+          , "{'B': 1::VARIANT, 'a': NULL::VARIANT, 'z': 2::VARIANT, 'é': 3::VARIANT}"
+          , "{'é': 3, 'b': 1, 'Z': 2}::VARIANT"
+          , "{'a': [1, 2]}::VARIANT"
+          , "'POINT (1 2)'::GEOMETRY"
+          ]
+          \expression ->
+            (query_ conn (Query ("SELECT " <> expression <> ", (" <> expression <> ")::VARIANT")) :: IO [(Variant, Variant)])
+              >>= \case
+                [(value, cast)] -> assertEqual (Text.unpack expression) cast value
+                rows -> assertFailure (show rows)
+        -- The cast of a GEOMETRY with a CRS drops the CRS.
+        [(withCrs, wkb)] <-
+          query_ conn "SELECT ('POINT (1 2)'::GEOMETRY('OGC:CRS84'))::VARIANT, ST_AsWKB('POINT (1 2)'::GEOMETRY)" :: IO [(Variant, BS.ByteString)]
+        withCrs @?= geometryPayload wkb
+    , testCase "geometry payload retains empty layout tags and native NaN points" $ withConnection ":memory:" \conn ->
+        forM_ ["GEOMETRYCOLLECTION ZM EMPTY", "MULTIPOLYGON M EMPTY", "POINT Z (NaN NaN 7)"] \wkt -> do
+          [Only geometry] <- query conn "SELECT ?::GEOMETRY" (Only (wkt :: Text)) :: IO [Only RawGeometry]
+          (query conn "SELECT system.main.ST_GeomFromWKB(?)::VARIANT" (Only (rawGeometryWKB geometry)) :: IO [Only Variant])
+            >>= (@?= [Only (geometryPayload (rawGeometryWKB geometry))])
+    , testCase "geometry payload conversion ignores user macros with built-in names" $ withConnection ":memory:" \conn -> do
+        [Only geometry] <- query_ conn "SELECT 'POINT (1 2)'::GEOMETRY" :: IO [Only RawGeometry]
+        _ <- execute_ conn "CREATE MACRO ST_AsText(x) AS 42"
+        _ <- execute_ conn "CREATE MACRO ST_GeomFromWKB(x) AS 'POINT (9 9)'::GEOMETRY"
+        (query conn "SELECT system.main.ST_GeomFromWKB(?)::VARIANT" (Only (rawGeometryWKB geometry)) :: IO [Only Variant])
+          >>= (@?= [Only (geometryPayload (rawGeometryWKB geometry))])
+    , testCase "binary geometry preserves NaN bits and rejects mixed member layouts" $ withConnection ":memory:" \conn -> do
+        let nanPoint = G.PointGeometry (G.PointXYZ (G.XYZ (castWord64ToDouble 0x7ff8000000000001) (castWord64ToDouble 0x7ff8000000000002) 7))
+        raw <- either assertFailure pure (toRawGeometry nanPoint)
+        (query conn "SELECT system.main.ST_GeomFromWKB(?)::VARIANT" (Only (rawGeometryWKB raw)) :: IO [Only Variant])
+          >>= (@?= [Only (geometryPayload (rawGeometryWKB raw))])
+        let mixed = G.GeometryCollection (V.fromList [G.PointGeometry (G.PointXY (G.XY 1 2)), G.PointGeometry (G.PointXYZ (G.XYZ 3 4 5))])
+        mixedRaw <- either assertFailure pure (toRawGeometry mixed)
+        outcome <- try (query conn "SELECT system.main.ST_GeomFromWKB(?)::VARIANT" (Only (rawGeometryWKB mixedRaw)) :: IO [Only Variant])
+        case outcome of
+          Left (err :: SQLError) -> sqlErrorType err @?= Just ErrorInputInvalid
+          Right _ -> assertFailure "native GEOMETRY must reject mixed Z/M dimensions"
+        (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+    , testCase "invalid values fail before binding and connection reuse succeeds" $ withConnection ":memory:" \conn -> do
+        forM_
+          [ FieldHugeInt (2 ^ (127 :: Int))
+          , FieldUHugeInt (-1)
+          , FieldUHugeInt (2 ^ (128 :: Int))
+          , FieldDecimal (DecimalValue 0 0 0)
+          , FieldDecimal (DecimalValue 5 6 1)
+          , FieldDecimal (DecimalValue 3 0 1000)
+          , FieldBit (BitString 8 (BS.singleton 0))
+          , variantObject [("same", FieldNull), ("same", FieldBool True)]
+          , variantObject [("", FieldBool True)]
+          , variantObject [("before\0after", FieldNull)]
+          ]
+          \value -> assertFailureIO (query conn "SELECT ?" (Only (Variant value)) :: IO [Only Variant])
+        (query_ conn "SELECT 42" :: IO [Only Int64]) >>= (@?= [Only 42])
+    ]
 
 -- | Bind a payload as VARIANT without a cast and read it back.
 roundTrip :: Connection -> FieldValue -> Assertion
 roundTrip conn expected =
-    (query conn "SELECT typeof(?) AS kind, ? AS value" (Variant expected, Variant expected) :: IO [(Text, Variant)]) >>= (@?= [("VARIANT", Variant expected)])
-
-{- | Insert native timestamp units without the parameter API, which converts
-TIMESTAMP_S and TIMESTAMP_MS parameters to microseconds before execution.
--}
-appendWideTimestamps :: Connection -> [(Int64, Int64)] -> IO ()
-appendWideTimestamps conn rows =
-    withConnectionHandle conn \native ->
-        withCString "wide_timestamps" \table ->
-            alloca \appenderPtr -> do
-                poke appenderPtr nullPtr
-                bracket (c_duckdb_appender_create native nullPtr table appenderPtr) (const (void (c_duckdb_appender_destroy appenderPtr))) \created -> do
-                    created @?= DuckDBSuccess
-                    appender <- peek appenderPtr
-                    forM_ rows \(seconds, millis) -> do
-                        bracket (c_duckdb_create_timestamp_s (DuckDBTimestampS seconds)) destroyValue (c_duckdb_append_value appender) >>= (@?= DuckDBSuccess)
-                        bracket (c_duckdb_create_timestamp_ms (DuckDBTimestampMs millis)) destroyValue (c_duckdb_append_value appender) >>= (@?= DuckDBSuccess)
-                        c_duckdb_appender_end_row appender >>= (@?= DuckDBSuccess)
-                    c_duckdb_appender_flush appender >>= (@?= DuckDBSuccess)
+  (query conn "SELECT typeof(?) AS kind, ? AS value" (Variant expected, Variant expected) :: IO [(Text, Variant)])
+    >>= (@?= [("VARIANT", Variant expected)])
 
 -- | A raw geometry payload has no CRS inside a VARIANT.
 geometryPayload :: BS.ByteString -> Variant
@@ -285,58 +648,61 @@
 -- | SQL constructors for each scalar payload tag.
 scalarCases :: [Text]
 scalarCases =
-    [ "NULL"
-    , "TRUE"
-    , "FALSE"
-    , "'-128'::TINYINT"
-    , "'-32768'::SMALLINT"
-    , "'-2147483648'::INTEGER"
-    , "9007199254740993::BIGINT"
-    , "'-170141183460469231731687303715884105728'::HUGEINT"
-    , "255::UTINYINT"
-    , "65535::USMALLINT"
-    , "4294967295::UINTEGER"
-    , "18446744073709551615::UBIGINT"
-    , "'340282366920938463463374607431768211455'::UHUGEINT"
-    , "1.25::FLOAT"
-    , "1.25::DOUBLE"
-    , "12.34::DECIMAL(4,2)"
-    , "-1234.56::DECIMAL(9,2)"
-    , "123456789012.345::DECIMAL(18,3)"
-    , "1234567890.123456789::DECIMAL(38,9)"
-    , "'text λ'::VARCHAR"
-    , "'\\x00\\xFF'::BLOB"
-    , "'01234567-89ab-cdef-fedc-ba9876543210'::UUID"
-    , "DATE '1970-01-02'"
-    , "DATE 'infinity'"
-    , "DATE '-infinity'"
-    , "TIME '01:02:03.456789'"
-    , "'01:02:03.456789012'::TIME_NS"
-    , "'1970-01-01 00:00:01'::TIMESTAMP_S"
-    , "'1969-12-31 23:59:59.999'::TIMESTAMP_MS"
-    , "'1970-01-01 00:00:01.234567'::TIMESTAMP"
-    , "'1970-01-01 00:00:01.234567891'::TIMESTAMP_NS"
-    , "'infinity'::TIMESTAMP_NS"
-    , "'1970-01-01 00:00:01.234567+00'::TIMESTAMPTZ"
-    , "INTERVAL '-4 MONTHS 8 DAYS 123456789 MICROSECONDS'"
-    , "'12345678901234567890123456789012345678901234567890'::BIGNUM"
-    , "'-12345678901234567890123456789012345678901234567890'::BIGNUM"
-    , "0::BIGNUM"
-    , "'10101'::BIT"
-    ]
+  [ "NULL"
+  , "TRUE"
+  , "FALSE"
+  , "'-128'::TINYINT"
+  , "'-32768'::SMALLINT"
+  , "'-2147483648'::INTEGER"
+  , "9007199254740993::BIGINT"
+  , "'-9223372036854775808'::BIGINT"
+  , "'9223372036854775807'::BIGINT"
+  , "'-170141183460469231731687303715884105728'::HUGEINT"
+  , "255::UTINYINT"
+  , "65535::USMALLINT"
+  , "4294967295::UINTEGER"
+  , "18446744073709551615::UBIGINT"
+  , "'340282366920938463463374607431768211455'::UHUGEINT"
+  , "1.25::FLOAT"
+  , "1.25::DOUBLE"
+  , "12.34::DECIMAL(4,2)"
+  , "-1234.56::DECIMAL(9,2)"
+  , "123456789012.345::DECIMAL(18,3)"
+  , "1234567890.123456789::DECIMAL(38,9)"
+  , "'text λ'::VARCHAR"
+  , "'\\x00\\xFF'::BLOB"
+  , "'01234567-89ab-cdef-fedc-ba9876543210'::UUID"
+  , "DATE '1970-01-02'"
+  , "DATE 'infinity'"
+  , "DATE '-infinity'"
+  , "TIME '01:02:03.456789'"
+  , "'01:02:03.456789012'::TIME_NS"
+  , "'1970-01-01 00:00:01'::TIMESTAMP_S"
+  , "'1969-12-31 23:59:59.999'::TIMESTAMP_MS"
+  , "'1970-01-01 00:00:01.234567'::TIMESTAMP"
+  , "'1970-01-01 00:00:01.234567891'::TIMESTAMP_NS"
+  , "'infinity'::TIMESTAMP_NS"
+  , "'1970-01-01 00:00:01.234567+00'::TIMESTAMPTZ"
+  , "'1970-01-01 00:00:01.234567891+00'::TIMESTAMPTZ_NS"
+  , "INTERVAL '-4 MONTHS 8 DAYS 123456789 MICROSECONDS'"
+  , "'12345678901234567890123456789012345678901234567890'::BIGNUM"
+  , "'-12345678901234567890123456789012345678901234567890'::BIGNUM"
+  , "0::BIGNUM"
+  , "'10101'::BIT"
+  ]
 
 -- | Reserve a unique path and let DuckDB create its file.
 newDatabase :: IO FilePath
 newDatabase = do
-    directory <- getTemporaryDirectory
-    (path, handle) <- openBinaryTempFile directory "duckdb-variant"
-    hClose handle
-    removeFile path
-    pure path
+  directory <- getTemporaryDirectory
+  (path, handle) <- openBinaryTempFile directory "duckdb-variant"
+  hClose handle
+  removeFile path
+  pure path
 
 -- | Remove files created by this test after DuckDB closes them.
 removeDatabase :: FilePath -> IO ()
 removeDatabase path =
-    forM_ [path, path <> ".wal"] \file -> do
-        exists <- doesFileExist file
-        when exists (removeFile file)
+  forM_ [path, path <> ".wal"] \file -> do
+    exists <- doesFileExist file
+    when exists (removeFile file)
