SEEK-517: make catalog bootstrap concurrency-safe

[cms-cms]

Summary

• make SDK catalog bootstrap state-driven and concurrency-safe
• create missing tables/indexes only, then verify actual catalog state
• retry only explicit transient DDL races with bounded backoff
• reuse the same bootstrap logic for namespace catalogs
• add upgrade, race, error-classification, and failure-path tests

Verification

• original server reproducer on retained SeekDB revision: 100/100 passed
• targeted unit tests: 162 passed
• existing full unit suite: 437 passed, 358 skipped, 0 failed
• Ruff and format checks passed
• pylibseekdb package was reused, not rebuilt

Source: SEEK-517

Summary by CodeRabbit

• Bug Fixes
  • Improved catalog initialization reliability by verifying table and index availability after setup.
  • Added bounded retries for temporary visibility issues and concurrent creation conflicts.
  • Prevented unnecessary database changes when catalog objects are already ready.
  • Catalog setup now rejects incompatible existing indexes and surfaces permission errors without retrying.
  • Namespace catalog creation completes with fewer redundant database operations while preserving required uniqueness constraints.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 9b507705-67e6-443c-acf2-1840a7075b59

📥 Commits

Reviewing files that changed from the base of the PR and between 830801f and e88e9af.

📒 Files selected for processing (2)

• src/pyseekdb/client/client_base.py
• tests/unit_tests/test_get_or_create_collection_concurrency.py

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

---

📝 Walkthrough

Walkthrough

Catalog bootstrap now uses bounded retries, error classification, rollback, and metadata re-checks. SDK and namespace setup uses shared catalog table initialization. Tests cover missing tables, legacy indexes, concurrent creation, visibility failures, permissions, and invalid indexes.

Changes

Catalog bootstrap

Layer / File(s)	Summary
Bootstrap error and retry contracts src/pyseekdb/client/client_base.py	Defines retry timing, transient database error classification, exception-chain handling, and catalog readiness signals.
Catalog table initialization src/pyseekdb/client/client_base.py	Adds verified table and unique-index initialization for SDK and namespace catalogs. Transient failures trigger rollback and bounded backoff.
Bootstrap behavior validation tests/unit_tests/test_get_or_create_collection_concurrency.py, tests/unit_tests/test_namespace.py	Tests ready, missing, legacy, concurrent, persistent, permission, invalid-index, wrapped-error, and catalog-order cases.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to e88e9

Catalog bootstrap now creates and verifies only missing schema objects, retries bounded transient DDL races, and shares this behavior with namespace catalogs. The supplied checks pass without an identified merge-blocking risk.

Sequence Diagram(s)

sequenceDiagram
  participant BaseClient
  participant CatalogDatabase
  participant CatalogMetadata
  BaseClient->>CatalogDatabase: Probe catalog table and index state
  BaseClient->>CatalogDatabase: Create missing table or unique index
  CatalogDatabase-->>CatalogMetadata: Expose updated catalog state
  BaseClient->>CatalogMetadata: Re-read table and index visibility
  BaseClient->>CatalogDatabase: Roll back transient failure

Loading

Suggested reviewers: hnwyllmm

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: making catalog bootstrap concurrency-safe.
Docstring Coverage	✅ Passed	Docstring coverage is 82.05% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 39 functions across 3 files.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[CLAassistant]

All committers have signed the CLA.