Skip to content

Clarify docs on in-memory pooling, execution options and bulk insert fallbacks - #226

Merged
leonardovida merged 1 commit into
mainfrom
docs/clarity-pass
Nov 9, 2026
Merged

leonardovida merged 1 commit into
mainfrom
docs/clarity-pass

Conversation

@leonardovida

Copy link
Copy Markdown
Owner

Summary

Documentation only. No code or version change, so nothing publishes.

  • Corrects the :memory: pooling statement. docs/configuration.md said every connection sees the same in-memory database. SingletonThreadPool opens one connection per thread and each gets its own database, so a second thread does not see the first thread's tables. The guide now says so and recommends a named :memory:name database or a file when threads share data.
  • Execution options in one table in docs/types-and-caveats.md, including the retry options and arraysize, with defaults and links.
  • Complete list of bulk insert fallbacks in docs/performance.md, matching the checks in _bulk_insert.py and _bulk_insert_register_columns.
  • Inspector cache note in docs/performance.md.
  • docs/index.md groups guides by task with one-line descriptions.
  • README compatibility paragraph becomes a list.
  • llms.txt follows the llms.txt format with full URLs, a description per guide, and the facts agents most often need.
  • CLAUDE.md and ARCHITECTURE.md record the thread-private :memory: behavior and the relation cache rule.

Test evidence

  • The :memory: claim was checked with a real engine: a table created in one thread is absent from a connection opened in another thread.
  • pre-commit passes on the changed files. pytest duckdb_sqlalchemy: 896 passed, 10 skipped.
  • Not checked: the rendered Jekyll site, so cross-page anchor links are unverified.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-09T20:18:28.287481Z 2d74438 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2d744387e8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread llms.txt

- DuckDB has no SAVEPOINT, so `begin_nested()` raises. `with_for_update()` is ignored.
- DuckDB cannot add UNIQUE, FOREIGN KEY or CHECK constraints to an existing table. Alembic batch mode recreates the table.
- `result.rowcount` reports rows changed by INSERT, UPDATE, DELETE and MERGE. It is -1 with RETURNING and for `executemany`.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Correct the rowcount caveat for RETURNING and batch inserts

The new caveat contradicts the dialect's behavior: Core DML with RETURNING materializes the returned rows and reports their count, and Core inserts with multiple parameter sets can report the full count when handled in one insertmanyvalues page or by the registration path. For example, test_returning_preserves_rows_and_affected_count expects rowcount == matches, while test_dml_rowcount_reports_changed_rows expects a two-row Core batch to report 2. Restrict the -1 warning to the DBAPI executemany cases that actually lack a count, such as batched UPDATE/DELETE and textual INSERTs.

Useful? React with 👍 / 👎.

Comment thread docs/performance.md
Comment on lines +41 to +42
- a value is a `timedelta`, a `time` with a time zone, a non-finite `Decimal`,
or a `Decimal` that needs more than 38 digits

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Include oversized integers in the fallback checklist

For a batch containing a Python integer whose magnitude reaches 2**127—for example, when loading it into a text or variable-width numeric column—Arrow construction fails and build_bulk_insert_dataframe() explicitly rejects the value, so the batch remains on the ordinary path. The newly expanded checklist is presented as the set of fallback cases but omits this condition, leaving users diagnosing why the optimization was skipped without the documented cause.

Useful? React with 👍 / 👎.

@leonardovida
leonardovida merged commit aeacdcf into main Nov 9, 2026
31 checks passed
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