Skip to content

docs: State the goals and non-goals - #607

Open
krlmlr wants to merge 1 commit into
mainfrom
claude/readme-goals
Open

krlmlr wants to merge 1 commit into
mainfrom
claude/readme-goals

Conversation

@krlmlr

@krlmlr krlmlr commented Sep 13, 2026

Copy link
Copy Markdown
Member

Evidence:

  • "does not define what the database interface looks like" and "does not translate R code into SQL" — DBI is an Imports; the API takes SQL strings, with no query builder in NAMESPACE.
  • "does not bundle a client library"SystemRequirements: libpq >= 9.0, and no libpq source in the package. The bullet deliberately does not say "the build relies on the system libpq": that holds on Unix, but tools/winlibs.R downloads a prebuilt libpq on Windows (statically linked by src/Makevars.win) and configure falls back to autobrew on macOS when the local libpq is too old or lacks SSL. What survives across all three is that the package ships no libpq source.
  • "does not reproduce the full driver/connection/result generality the original DBI design imagined" — the README's own Design notes, verbatim: "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." A package that has already written down where it deviates from the interface it implements is the best possible source for a non-goal.
  • "does not offer the whole specification on Redshift, where BLOBs are not supported"tests/testthat/helper-DBItest.R still carries omit_blob_tests = TRUE in its Redshift context, and NEWS.md 1.4.0 records it. The bullet stops there: 1.4.0 also reported "limitations with enumerating temporary and persistent tables", but 1.4.3 (2021-12-20) supersedes that entry — "Temporary tables are now discovered correctly for Redshift() connections, all DBItest tests pass (Allow to find table in temporary schema for Redshift #358)".
  • "map PostgreSQL types to the R types that fit them best" — deliberately a best-fit claim, not a lossless one. src/PqResultImpl.cpp maps oid 1700 (NUMERIC/DECIMAL) and oid 790 (MONEY) to DT_REAL, i.e. double, and INTERVAL and UUID to character, so "without losing information" would not be true. What the code does support is bit64::integer64 for BIGINT, blob for bytea, and a distinct datetime-with-timezone type.

The Postgres-specific goals name the things DBI has no generic for: postgresWaitForNotify(), postgresImportLargeObject(), and Redshift().

The DBI specification is linked as https://dbi.r-dbi.org/articles/spec.html — pkgdown on GitHub Pages does not append .html for you.

This package has no README.Rmd, so README.md is the source and was edited directly; nothing is rendered.

Stacked on #606, which this PR targets.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m

@krlmlr
krlmlr force-pushed the claude/readme-goals branch from 0f00825 to 0b44d78 Compare September 13, 2026 14:26
@krlmlr
krlmlr force-pushed the claude/readme-goals branch from 0b44d78 to e5bc052 Compare September 13, 2026 14:29
@krlmlr
krlmlr force-pushed the claude/readme-goals branch 3 times, most recently from 44da833 to 855f9e9 Compare September 13, 2026 16:31
@krlmlr
krlmlr force-pushed the claude/readme-goals branch from 855f9e9 to cc42687 Compare September 13, 2026 16:59
@krlmlr
krlmlr force-pushed the claude/readme-goals branch from cc42687 to 0c10e62 Compare September 13, 2026 18:26
@krlmlr
krlmlr force-pushed the claude/readme-goals branch from 0c10e62 to 447b399 Compare September 13, 2026 18:38
@krlmlr
krlmlr added this pull request to stack #611 September 13, 2026 21:05
@krlmlr
krlmlr force-pushed the claude/readme-goals branch 2 times, most recently from 9ad9a43 to fa79a6f Compare September 13, 2026 21:42
@krlmlr
krlmlr force-pushed the claude/readme-goals branch from fa79a6f to 3c59035 Compare September 14, 2026 05:27
Base automatically changed from claude/sembr to main September 14, 2026 14:37
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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WWhverMTZZKgEpUuTK117m
@krlmlr
krlmlr force-pushed the claude/readme-goals branch from 3c59035 to 12b1284 Compare September 14, 2026 14:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant