packages feed

pqi 1.0.0.0 → 1.0.0.1

raw patch · 4 files changed

+26/−23 lines, 4 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

CHANGELOG.md view
@@ -1,3 +1,7 @@+# v1.0.0.1++Documentation corrections.+ # v1.0.0.0  ## Breaking
README.md view
@@ -11,14 +11,14 @@ |---------|-------------| | **[pqi](https://github.com/nikita-volkov/pqi)** *(this)* | The interface: `IsConnection` class, shared types, and connection-independent helpers | | [pqi-ffi](https://github.com/nikita-volkov/pqi-ffi) | FFI adapter backed by `postgresql-libpq` and the C `libpq` library. Battle-tested, production-safe |-| [pqi-native](https://github.com/nikita-volkov/pqi-native) | Pure-Haskell adapter speaking the PostgreSQL wire protocol directly. No C dependency. Alpha — interchangeable with `pqi-ffi` |+| [pqi-native](https://github.com/nikita-volkov/pqi-native) | Pure-Haskell adapter speaking the PostgreSQL wire protocol directly. No C dependency. Alpha - interchangeable with `pqi-ffi` | | [pqi-conformance](https://github.com/nikita-volkov/pqi-conformance) | Reusable `hspec` conformance suite that differentially tests any adapter against `postgresql-libpq` |  ## Motivation  Every major Haskell PostgreSQL driver today depends on [`postgresql-libpq`][postgresql-libpq], a binding to the C `libpq` library.-This means every user of every driver needs `libpq` installed — on their+This means every user of every driver needs `libpq` installed - on their development machine, in CI, in production containers, on cross-compilation targets. There is no way to opt out. @@ -26,15 +26,15 @@ defines a driver-agnostic type class (`IsConnection`) that mirrors the `libpq` API surface, then ships two adapters: -- [`pqi-ffi`](https://github.com/nikita-volkov/pqi-ffi) — a thin wrapper+- [`pqi-ffi`](https://github.com/nikita-volkov/pqi-ffi) - a thin wrapper   around `postgresql-libpq`. Battle-tested, production-safe. The default   choice.-- [`pqi-native`](https://github.com/nikita-volkov/pqi-native) — a from-scratch+- [`pqi-native`](https://github.com/nikita-volkov/pqi-native) - a from-scratch   pure-Haskell implementation of the PostgreSQL wire protocol. **Alpha.** It-  produces byte-identical output to `postgresql-libpq` for all+  produces identical output to `postgresql-libpq` for all   protocol-derived values (verified by differential testing), but it has not   yet been exercised in production at scale. Because it implements the same-  `pqi` interface as `pqi-ffi`, the two are fully interchangeable — switching+  `pqi` interface as `pqi-ffi`, the two are fully interchangeable - switching   between them is a one-line change, so adopting `pqi-native` now carries no   lock-in. If you adopt it, we want to hear from you. @@ -58,21 +58,21 @@ ## Interface  `pqi` reproduces the API surface of the [`postgresql-libpq`][postgresql-libpq]-package, but reifies the connection — and the results and cancellation-handles it produces — as plain records of closures instead of a single+package, but reifies the connection - and the results and cancellation+handles it produces - as plain records of closures instead of a single concrete type tied to `libpq`. There is exactly one `Connection`, one `Result`, and one `Cancel` type in the whole package; each field is an `IO` action that an adapter has already closed over its own underlying handle (a C `PGconn` pointer, a native socket, etc.). Code written against this interface runs unchanged on any adapter: -- [`pqi-ffi`](https://github.com/nikita-volkov/pqi-ffi) — a thin+- [`pqi-ffi`](https://github.com/nikita-volkov/pqi-ffi) - a thin   adapter backed by the C `libpq` library via `postgresql-libpq`.-- [`pqi-native`](https://github.com/nikita-volkov/pqi-native) — a+- [`pqi-native`](https://github.com/nikita-volkov/pqi-native) - a   pure-Haskell adapter that speaks the PostgreSQL wire protocol directly.  The interface mirrors `libpq` in semantics, not just shape: every compliant-adapter must produce byte-identical output to `libpq` for all protocol-derived+adapter must produce identical output to `libpq` for all protocol-derived values. This contract is enforced by [`pqi-conformance`](https://github.com/nikita-volkov/pqi-conformance), which runs every operation differentially against [`postgresql-libpq`][postgresql-libpq] and asserts equality.@@ -81,7 +81,7 @@ `Cancel` records, the `Adapter` type that adapter packages bundle their connection-establishing functions under, and the shared type vocabulary (statuses, field codes, formats, OIDs). It does not itself construct any-connections — that's each adapter package's job, exposed as a single+connections - that's each adapter package's job, exposed as a single top-level `adapter :: Adapter` value.  ## Relationship to `postgresql-libpq`
pqi.cabal view
@@ -1,6 +1,6 @@ cabal-version: 3.0 name: pqi-version: 1.0.0.0+version: 1.0.0.1 category: Database, PostgreSQL synopsis: Driver-agnostic interface to the PostgreSQL libpq API description:
src/library/Pqi.hs view
@@ -3,18 +3,17 @@ -- -- t'Connection', t'Result' and t'Cancel' are records of @IO@ closures, each -- already closed over the handle it needs (a C @PGconn@ pointer, a native--- socket, ...). Exactly one of each type exists in the package: no classes,--- no type parameters.+-- socket, ...). ----- Connections come from adapter packages — @pqi-ffi@ (C @libpq@ via--- @postgresql-libpq@) and @pqi-native@ (pure-Haskell wire protocol) — each--- exporting one top-level t'Adapter' value. An adapter must be byte-identical--- to @libpq@ on every protocol-derived value; @pqi-conformance@ enforces that+-- Connections come from adapter packages - @pqi-ffi@ (C @libpq@ via+-- @postgresql-libpq@) and @pqi-native@ (pure-Haskell wire protocol) - each+-- exporting one top-level t'Adapter' value. An adapter must be identical+-- to @libpq@ on every protocol-derived value. @pqi-conformance@ enforces that -- differentially. -- -- == Differences from @postgresql-libpq@ ----- Everything else — names, argument order, semantics — mirrors+-- Everything else - names, argument order, semantics - mirrors -- @Database.PostgreSQL.LibPQ@. -- -- * Connection acquisition lives in t'Adapter': @connectdb@, @connectStart@@@ -28,7 +27,7 @@ --   @exec connection sql@ selects a field and applies it. -- -- * @Oid@ is 'Word32'; @Row@, @Column@, @LoFd@ are 'Int32'. No @invalidOid@---   constant — it is @0@.+--   constant - it is @0@. -- -- * @libpqVersion@ is omitted. module Pqi@@ -477,8 +476,8 @@ -- -- This is the only value that identifies an adapter: t'Connection', t'Result' -- and t'Cancel' say nothing about which adapter produced them. Callers that--- must stay adapter-agnostic — a differential test harness, a library letting--- its users pick a driver at runtime — pass an t'Adapter' around instead of a+-- must stay adapter-agnostic - a differential test harness, a library letting+-- its users pick a driver at runtime - pass an t'Adapter' around instead of a -- family of adapter-qualified top-level functions. data Adapter = Adapter   { -- | A short identifier for the adapter (e.g. @\"pqi-ffi\"@), for use in