Skip to content

Microsoft.Data.Sqlite: Include extended error code and guidance in SqliteException messages - #39588

Open
ajcvickers wants to merge 2 commits into
dotnet:mainfrom
ajcvickers:sqlite-extended-error-guidance
Open

ajcvickers wants to merge 2 commits into
dotnet:mainfrom
ajcvickers:sqlite-extended-error-guidance

Conversation

@ajcvickers

@ajcvickers ajcvickers commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Part of #29514

Exception messages from Microsoft.Data.Sqlite included the primary SQLite error code but not the extended one, which is often what identifies the real cause. For #29514 the message was just SQLite Error 5: 'database is locked'., while the underlying error was SQLITE_BUSY_SNAPSHOT (517).

When SqliteException.ThrowExceptionForRC builds a message, it now:

  • Appends Extended error code: N (NAME). when the extended code differs from the primary code, with the symbolic name for every extended error code in the SQLite result code list (the name is also shown when extended result codes are enabled, in which case the primary and extended codes are equal). For example, a unique violation now reads SQLite Error 19: 'UNIQUE constraint failed: Data.Value'. Extended error code: 2067 (SQLITE_CONSTRAINT_UNIQUE).
  • Appends guidance for SQLITE_BUSY_SNAPSHOT: this happens when a connection with an open read transaction writes after another connection committed, waiting can't help, and the fix is to roll back and retry the transaction. To avoid it, start a non-deferred transaction before reading, and outside a transaction dispose any open readers before writing.

The existing SQLite Error N: '...'. prefix is unchanged, so anything matching on it keeps working. Messages for errors where the extended code equals the primary code are identical to before. Anyone comparing the full Message of an error that has an extended code (e.g. SQLITE_CONSTRAINT_*) will see the extra text, so this is a (minor) breaking change that should go in the release notes.

SQLitePCL doesn't define some extended codes (for example SQLITE_ERROR_MISSING_COLLSEQ and SQLITE_CONSTRAINT_DATATYPE, which STRICT tables raise), so those are declared locally with their documented values.

Deliberately no guidance for plain SQLITE_BUSY

Plain SQLITE_BUSY has several causes (another writer, BackupDatabase, which doesn't use the timeout at all, and so on), and advice that mentions the timeout or WAL would be wrong for some of them.

Tests

  • A FormatMessage theory covers named and unnamed extended codes and which codes get guidance.
  • Real-connection tests cover a unique constraint violation, a stale-snapshot write (message contains the name and guidance), plain SQLITE_BUSY (no guidance), and BackupDatabase being busy (message doesn't mention a timeout).
  • The ThrowExceptionForRC path with no database handle is covered too.
  • CreateCollation_with_null_comparer_works now asserts the full message, because that error carries extended code 257.
  • Further real-connection tests cover a deferred transaction that writes after another connection commits, a STRICT table type violation, and extended result codes being enabled.

Related

#39587 makes Microsoft.Data.Sqlite throw immediately for SQLITE_BUSY_SNAPSHOT instead of retrying until the timeout. The two PRs are independent, but this one should merge after #39587: without it, a primary SQLITE_BUSY_SNAPSHOT is still retried until the timeout, so users wait the full Default Timeout before they see "Waiting cannot help". Until that one merges, the stale-snapshot test here sets Default Timeout=1 so it doesn't wait 30 seconds, and it could drop that once both have landed.

🤖 Generated with Claude Code

@ajcvickers
ajcvickers requested a review from a team as a code owner November 10, 2026 10:48
Copilot AI balanced review requested due to automatic review settings November 10, 2026 10:48

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@ajcvickers

Copy link
Copy Markdown
Contributor Author

/cc @bricelam

…essages

Append the extended error code (with its symbolic name where known) when it
differs from the primary code, and add guidance for SQLITE_BUSY_SNAPSHOT and
SQLITE_BUSY.

Part of dotnet#29514

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@ajcvickers
ajcvickers force-pushed the sqlite-extended-error-guidance branch from 10b8d3d to 7cc65f3 Compare November 14, 2026 11:40
Copilot AI balanced review requested due to automatic review settings November 14, 2026 11:40

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

… names

- BUSY_SNAPSHOT guidance now says to roll back and retry the transaction, and
  that disposing readers only helps outside a transaction.
- Name every extended error code from the SQLite result code list, declaring
  locally the ones SQLitePCL.raw doesn't define (e.g. SQLITE_CONSTRAINT_DATATYPE,
  which STRICT tables raise).
- Show the name even when extended result codes are enabled and the primary
  and extended codes are equal.
- Tests: cover a deferred transaction that writes after another connection
  commits, a STRICT table type violation and extended result codes; remove the
  backup test that asserted on text nothing produces; reuse DeleteDatabase;
  assert the full message in CreateCollation_with_null_comparer_works.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 16, 2026 10:30

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants