Skip to content

fix(sqlite): map a raced create reported as SQLITE_SCHEMA to a duplicate - #1076

Open
abnegate wants to merge 1 commit into
mainfrom
fix/sqlite-schema-duplicate
Open

abnegate wants to merge 1 commit into
mainfrom
fix/sqlite-schema-duplicate

Conversation

@abnegate

@abnegate abnegate commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Problem

When two connections race to create the same table on SQLite, for example two tenants creating the same collection on a fresh shared-tables schema, the losing createCollection() can throw a raw PDOException instead of Utopia\Database\Exception\Duplicate. A probe in a downstream test harness caught it from SQLite::createCollection():

["HY000",17,"table `shared_changelog_tombstones` already exists"]

Cause

The losing CREATE TABLE can be re-prepared while the winner's next schema change lands. SQLite then reports "already exists" under SQLITE_SCHEMA (17), not SQLITE_ERROR (1). SQLite::processException() only mapped code 1 + "already exists" to a duplicate, so the code 17 error escaped unmapped. createCollectionInSchema() never saw the duplicate it handles by reusing the shared table and writing only the losing tenant's metadata. MySQL and MariaDB always raise 1050 here, so only SQLite is affected.

Fix

  • processException() maps "already exists" under code 1 or 17 to the same Duplicate('Collection already exists'). Other code 17 errors, such as "database schema has changed", still pass through raw.
  • The SQLite result codes processException() matches are now named constants (SQLITE_ERROR, SQLITE_BUSY, SQLITE_SCHEMA, SQLITE_TOOBIG, SQLITE_CONSTRAINT) instead of bare numbers.

Tests

  • EngineErrorMappingTest::testSQLiteCreateRacedIntoASchemaChangeIsADuplicateCollection feeds the reported error through processException().
  • EngineErrorMappingTest::testSQLiteSchemaChangeWithoutAnExistingTableStaysRaw checks that other code 17 errors are not swallowed.
  • Adapter/SQLiteSchemaChangeRaceTest runs the adapter and Database paths against SchemaChangeRacingPDO. That PDO raises an existing-table create the way the race does (code 17). A losing SQLite::createCollection() gets a duplicate and leaves the winner's tables in place. On shared tables, a second tenant's create() and createCollection() both succeed, and its documents stay isolated from the first tenant's.

SQLite's timing for this race can't be reproduced deterministically, so the double injects the code 17 SQLite reports.

Before the fix, the mapping test failed (the raw PDOException came back) and both race tests errored with the raw PDOException. After the fix, all of them pass. Pint and both PHPStan configurations are clean.

Downstream

appwrite-labs/cloud PR #6690 works around this in its test harness at tests/unit/Database/TimedSQLite.php::processException(). That workaround can be removed once cloud pins a release that includes this fix.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Bug Fixes
    • SQLite now reports a duplicate collection error when a concurrent creation has already created the collection, rather than surfacing a generic database error.
    • Shared collections created during a schema race are correctly registered for the relevant tenant, with document counts kept separate.

When two connections race to create the same table, the losing CREATE TABLE
can be re-prepared while the winner's next schema change lands, and SQLite
then reports "table ... already exists" under SQLITE_SCHEMA (17) instead of
SQLITE_ERROR (1). processException() only mapped code 1, so the raw
PDOException escaped createCollection() and the shared-tables create path
never got the duplicate it handles by registering only the losing tenant's
metadata. MySQL and MariaDB always raise 1050 here, so only SQLite was
affected. Other code 17 errors stay raw.

The result codes processException() matches are now named constants.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@appwrite

appwrite Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Code review

Commit Status Tier Verdict Details
0df5b86 Reviewed Reviewed 🟢 S · Ready to merge ✅ Approved View review

SQLite exception mapping now recognizes an existing-table error reported with SQLITE_SCHEMA and maps it to a duplicate. The added tests exercise the mapping and verify direct adapter and shared-table tenant creation behavior with an injected schema-race error.

Walkthrough (4)
File Change
src/Database/Adapter/SQLite.php Names SQLite result codes and maps SQLITE_SCHEMA existing-table errors to Duplicate.
tests/unit/Adapter/SQLiteSchemaChangeRaceTest.php Adds adapter and shared-tenant tests for a simulated schema-change race.
tests/unit/Adapter/SchemaChangeRacingPDO.php Adds a PDO test double that converts existing-table errors into SQLITE_SCHEMA errors.
tests/unit/EngineErrorMappingTest.php Tests duplicate mapping for SQLITE_SCHEMA and confirms unrelated schema-change errors remain raw.

Reviewed 0df5b86

Tip

Comment @appwrite review to re-run, or mention @appwrite with a question.

@coderabbitai

coderabbitai Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

SQLite now maps already-exists errors with error code 17 to DuplicateException. New tests cover this mapping and collection creation races, including shared-table behavior across tenants.

Changes: SQLite error mapping

Layer / File(s) Summary
Map SQLite exception codes
src/Database/Adapter/SQLite.php, tests/unit/EngineErrorMappingTest.php
SQLite error-code constants replace numeric literals in existing mappings. Already-exists errors with code 17 now map to DuplicateException. Tests cover this mapping and confirm schema-changed errors pass through unchanged.
Test schema-change races
tests/unit/Adapter/SchemaChangeRacingPDO.php, tests/unit/Adapter/SQLiteSchemaChangeRaceTest.php
The test PDO converts matching already-exists errors from code 1 to code 17. Race tests check duplicate collection creation and table preservation, and verify shared-table registration and document counts across tenants.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Suggested reviewers: chiragagg5k

Merge Risk: Minimal · up to 0df5b

This fixes a SQLite race where a losing collection creation could surface a raw database exception instead of a duplicate-collection error. The change is narrow and tested, and no merge-blocking risk remains.

Pre-merge checks: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title names the main change: SQLite processException() now maps a raced create that reports SQLITE_SCHEMA (17) with an "already exists" message to a duplicate. The raw summary and objectives c…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the main change: SQLite processException() now maps a raced create that reports SQLITE_SCHEMA (17) with an "already exists" message to a duplicate. The raw summary and objectives confirm this is the central fix, with the new constants and tests supporting it. The title is specific and concise, and it follows the conventional commit style.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between b0da7f7 and 0df5b86.

Files selected for processing: 4

  • src/Database/Adapter/SQLite.php
  • tests/unit/Adapter/SQLiteSchemaChangeRaceTest.php
  • tests/unit/Adapter/SchemaChangeRacingPDO.php
  • tests/unit/EngineErrorMappingTest.php

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

@appwrite appwrite 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.

🟢 Tier S · Looks good to merge. Summary

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