diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ +# v1.0.0.1 + +Documentation corrections. + # v1.0.0.0 ## Breaking diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -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` diff --git a/pqi.cabal b/pqi.cabal --- a/pqi.cabal +++ b/pqi.cabal @@ -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: diff --git a/src/library/Pqi.hs b/src/library/Pqi.hs --- a/src/library/Pqi.hs +++ b/src/library/Pqi.hs @@ -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