From 12b1284f1ef2c339a66a612b5a009dae96b20f57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kirill=20M=C3=BCller?= Date: Sun, 13 Sep 2026 11:12:19 +0000 Subject: [PATCH] docs: State the goals and non-goals Scope drawn from the README's own opening and its "Design notes" section ("This turns out to be too general: a driver has no real state, for PostgreSQL each connection can only have one result set ... the driver class is just a dummy class with no contents"), the DESCRIPTION (Imports DBI, bit64, blob, hms, lubridate; SystemRequirements names libpq >= 9.0), the exported PostgreSQL-specific helpers in NAMESPACE (postgresWaitForNotify(), postgresImportLargeObject(), Redshift()), and tests/testthat/test-DBItest.R, which runs DBItest::test_all(). The type-mapping goal claims a best fit rather than a lossless one. src/PqResultImpl.cpp maps NUMERIC and MONEY to double, and INTERVAL and UUID to character, so "without losing information" would not hold. The Redshift non-goal names BLOBs only, which tests/testthat/helper-DBItest.R still records as `omit_blob_tests = TRUE` in its Redshift context. NEWS.md 1.4.0 also reported limitations enumerating temporary and persistent tables, but 1.4.3 supersedes that entry: "Temporary tables are now discovered correctly for `Redshift()` connections, all DBItest tests pass". The "does not bundle a client library" non-goal says that no libpq source ships with the package, rather than that the build relies on the system libpq. The latter holds on Unix only: tools/winlibs.R downloads a prebuilt libpq on Windows, and configure falls back to autobrew on macOS. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m --- README.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/README.md b/README.md index 7da2c9b6..0c307b68 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,32 @@ Compared to RPostgreSQL, it: * A simplified build process that relies on system libpq. +## Goals and non-goals + +RPostgres aims to: + +- implement the [DBI specification](https://dbi.r-dbi.org/articles/spec.html) for PostgreSQL, + and to keep proving it by running the `DBItest` suite as part of its own tests +- support parameterised queries through `dbSendQuery()` and `dbBind()`, + so that values never have to be pasted into the SQL string +- map PostgreSQL types to the R types that fit them best: + 64-bit integers via `bit64`, `bytea` via `blob`, and date-time columns with an explicit time zone +- reach the PostgreSQL features that DBI has no generic for, + such as `LISTEN`/`NOTIFY` through `postgresWaitForNotify()` and large objects through `postgresImportLargeObject()` +- serve AWS Redshift clusters through `Redshift()`, with the behaviour of individual methods adjusted where that cluster differs + +It is explicitly not trying to: + +- define what the database interface looks like: + the generics, their semantics and the specification are DBI's, this package supplies the PostgreSQL implementation +- translate R code into SQL: queries are handed to `dbSendQuery()` and friends as SQL strings +- bundle a client library: no `libpq` source ships with the package, + the build links the one the platform provides and downloads a prebuilt binary where it does not +- reproduce the full driver/connection/result generality the original DBI design imagined: + a driver has no real state and a PostgreSQL connection can only have one result set, + so the driver class is a dummy used for dispatch and connection and result share one external pointer +- offer the whole specification on Redshift, where BLOBs are not supported + ## Installation ```R # Install the latest RPostgres release from CRAN: