Skip to content

Cache per-table schema lookups until the schema changes - #3102

Open
simonw wants to merge 1 commit into
mainfrom
claude/duplicate-schema-lookups-03a1e7
Open

simonw wants to merge 1 commit into
mainfrom
claude/duplicate-schema-lookups-03a1e7

Conversation

@simonw

@simonw simonw commented Nov 22, 2026

Copy link
Copy Markdown
Owner

An HTML table page ran PRAGMA table_xinfo for the same table 9 times (15 as root), each a separate trip to a database thread, plus repeated foreign key, label column and FTS lookups. ?_trace=1 does not show these because they go through execute_fn(), not execute().

A warm table page now runs none of them.

/fixtures/... Before After
facetable: trips to a database thread 77 57
facetable: statements run 107 57
facetable: median time 15.2 ms 11.9 ms (-22%)
simple_primary_key: median time 7.5 ms 6.2 ms (-17%)

Times are medians of 400 warm requests through datasette.client, three alternating runs each, on one laptop.

How it works

table_columns(), table_column_details(), primary_keys(), foreign_keys_for_table(), fts_table(), label_column_for_table(), describe_columns() and derived_table_dependencies() share one cache on the Database object. It is thrown away when PRAGMA schema_version changes, and that version is read again:

  • after any write made through the Database object (execute_write*, execute_isolated_fn), including one that fails
  • once in every request, which is how a change made by another process is noticed
  • on every call made outside of a request, so tests, scripts and plugins never get an unchecked answer

Not cached:

  • the unnamed _memory database, where every connection is a separate database
  • tables in attached databases, which the main database's schema version says nothing about
  • names that match no table or view. ?_through= passes a table name from the query string to foreign_keys_for_table(), so without this the cache could be grown without limit

Immutable databases are cached without any checks.

Callers get copies of the cached lists and dictionaries. An explicit label_column in configuration is still read on every call.

Things to check

  • The remaining window: if another process alters a table in the middle of a request that has already checked, that request finishes with the columns it started with. The next request sees the change.
  • derived_table_dependencies() had its own schema_version cache in _cached_derived_table_dependencies. That is replaced by the shared one, which removes two PRAGMA schema_version trips per page.
  • Three existing tests edited: two in tests/test_fts_permissions.py and one in tests/test_internals_database.py asserted on that removed private attribute. They now assert the same guarantee, that a failed refresh leaves nothing cached, against the new cache.

Tests

tests/test_schema_cache.py covers each of the cases above with 0, 1 and 3 SQL threads. The tests fail if write invalidation, the per-request re-check or the copying is removed.

🤖 Generated with Claude Code

An HTML table page ran PRAGMA table_xinfo for the same table 9 times
(15 as root), each a separate trip to a database thread, plus repeated
foreign key, label column and FTS lookups. A warm table page now runs
none of them: 77 trips to a database thread become 57, and the page is
17-22% faster against the fixtures database.

table_columns(), table_column_details(), primary_keys(),
foreign_keys_for_table(), fts_table(), label_column_for_table(),
describe_columns() and derived_table_dependencies() share one cache on
the Database object, thrown away when PRAGMA schema_version changes.
That version is read again:

- after any write made through the Database object, including one
  that fails
- once in every request, so a change made by another process is seen
  by the next request
- on every call made outside of a request

The unnamed _memory database is not cached, and nor are tables in
attached databases or names that match no table or view. That last rule
stops table names taken from the query string, such as ?_through=, from
growing the cache without limit. Immutable databases are cached without
any checks.

Callers get copies of the cached lists and dictionaries.
derived_table_dependencies() used its own schema_version cache, which
this replaces.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@codecov

codecov Bot commented Nov 22, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 0% with 93 lines in your changes missing coverage. Please review.
✅ Project coverage is 0.00%. Comparing base (1ad8e36) to head (3bd5b9e).

Files with missing lines Patch % Lines
datasette/database.py 0.00% 88 Missing ⚠️
datasette/app.py 0.00% 3 Missing ⚠️
datasette/utils/__init__.py 0.00% 2 Missing ⚠️
Additional details and impacted files
@@          Coverage Diff          @@
##            main   #3102   +/-   ##
=====================================
  Coverage   0.00%   0.00%           
=====================================
  Files         81      81           
  Lines      14516   14579   +63     
=====================================
- Misses     14516   14579   +63     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

This branch has not been deployed

No deployments
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