Quack protocol coverage

Copy Markdown View Source

QuackDB is intentionally protocol-first, but it does not claim full DuckDB Quack protocol coverage yet. It speaks Quack protocol version 3, the version DuckDB 2.0 serves, and refuses servers that select another version. This matrix tracks the implemented surface, unsupported gaps, and the test style expected before a feature is treated as covered.

Message coverage

Quack messageStatusCoverage
Connection requestSupportedVersion 3 range, client id, and heartbeat lease; codec tests and connection integration
Connection responseSupportedNegotiated lease; DuckDB 2.0 fixture and integration
Prepare requestSupportedQuery UUID and inline row limit; query, prepare, and stream integration
Prepare responseSupportedDuckDB 2.0 fixtures and integration
Fetch requestSupportedDense batch and acknowledged-prefix indexes; retried after lost connections
Fetch responseSupportedChunk blob after the body and terminal batch count; DuckDB 2.0 fixtures
Send-data requestSupportedNative appends into scan_data_from_quack_client; codec tests and integration
Send-data responseSupportedNative append integration
Cancel requestSupportedQuackDB.cancel/3, timeouts, and disconnects; integration
AcknowledgementSupportedSent with acknowledge_results: true
Heartbeat requestSupportedDBConnection idle pings; integration
Success responseSupportedHeartbeat, cancel, and disconnect paths
Error responseSupportedMessage, exception type, extra info, and invalidation flag; DuckDB 2.0 fixture
DisconnectSupportedDBConnection disconnect cleanup

Vector encoding coverage

Vector encodingDecodeEncodeNotes
FlatSupportedSupportedPrimary query and append path; strings use DuckDB 2.0's lengths-and-bytes layout and the pre-2.0 list layout still decodes
ConstantSupportedNot emittedDecode expands constants to row values
DictionarySupportedNot emittedDecode validates selection indexes
SequenceSupportedNot emittedDecode materializes generated values
ShreddedSupportedNot emittedVARIANT columns read from storage; typed fields merge with unshredded leftovers
FSSTUnsupportedUnsupportedRaises explicit :unsupported_vector_type; QuackDB has an internal optional :fsst bridge, but current real-server probes with repeated long strings still return flat VARCHAR chunks over Quack, so the compressed wire payload shape is not exposed by current DuckDB releases
Unknown vector idsUnsupportedUnsupportedRaises explicit :unknown_vector_type

Logical type coverage

DuckDB logical type familyDecodeAppend encodeNotes
BooleansSupportedSupported
Signed/unsigned integersSupportedSupportedIncludes hugeint/uhugeint
Floating pointSupportedSupported
DecimalSupportedSupportedWidth-dependent physical storage
VARCHAR/CHARSupportedSupportedInvalid UTF-8 raises explicit errors
BLOBSupportedSupportedRaw bytes
UUIDSupportedPartialDecode supported; append can encode integer storage but public UUID append ergonomics are not finalized
ENUMSupportedPartialDecode supported; append requires encoded enum index today
BITSupportedPartialDecode to bit string; append expects DuckDB bit payload bytes
BIGNUMSupportedSupportedElixir integers; fixture covers zero, positive, and negative large values
DATE/TIME/TIMESTAMP/TIMESTAMPTZSupportedSupportedCalendar-aware append encoding
TIME_NSSupportedSupportedQuackDB.NanosecondTime
TIMESTAMP_NSSupportedSupportedQuackDB.NanosecondTimestamp
TIMESTAMPTZ_NSSupportedSupportedQuackDB.NanosecondTimestamp holding the UTC instant
TIME WITH TIME ZONESupportedSupportedQuackDB.TimeWithTimeZone
INTERVALSupportedSupportedQuackDB.Interval
LISTSupportedSupportedNested values covered by real integration
STRUCTSupportedSupportedString-key maps on decode
ARRAYSupportedSupportedFixed-size metadata is encoded/decoded
MAPSupportedSupportedDecodes to maps; duplicate keys follow Map.put/3 semantics
SQLNULLPartialPartialCovered as ordinary null values, not all standalone logical-type edge cases
UNIONUnsupportedUnsupportedShould raise explicit unsupported errors
VARIANTSupportedVia JSONDecodes to Elixir terms, shredded or not; :variant append columns send JSON text that DuckDB casts
TUPLESupportedUnsupportedDecodes to Elixir tuples
ANY/TEMPLATE/LAMBDA/POINTERUnsupportedUnsupportedProtocol metadata reserved/unsupported
LEGACY_AGGREGATE_STATEUnsupportedUnsupportedMetadata not implemented
Extension/custom typesUnsupportedUnsupportedMetadata not implemented
GEOMETRYPartialPartialDecoded as WKB-compatible bytes from DuckDB spatial geometry values; semantic geometry structs are not implemented

DBConnection and client coverage

FeatureStatusCoverage
Query executionSupportedUnit and integration
Prepare/executeSupportedUnit and integration
Streaming/fetch continuationSupportedUnit and integration
TransactionsSupportedUnit and integration
Native row appendSupportedUnit and integration, including ON CONFLICT, RETURNING, and column defaults
Native column appendSupportedUnit and integration
Query cancellationSupportedQuackDB.cancel/3; timeouts and disconnects cancel their query
Heartbeat leasesSupportedIdle pings renew; expired leases reconnect
Ecto raw SQLSupportedUnit and integration
Ecto analytical readsPartialBroad SQL-generation and integration coverage
Ecto insert/insert_allCoveredPlain inserts, returning, insert-from-query, common upserts, on_conflict: :nothing, and explicit native append fast path covered
Ecto mutations and DDLPartialSchema update/delete, joined update_all, joined delete_all, rowid-filtered ordered/limited mutations, Repo.explain, transactions, and basic migrator-backed DDL covered where DuckDB SQL allows it

Conformance fixtures

Golden fixtures captured from a real DuckDB 2.0 server cover the handshake, typed errors, prepare and fetch responses, and VARIANT layouts. The older quack-ts chunks remain as decode checks for the pre-2.0 string layout. See fixtures.md for the fixture inventory and malformed fixtures.