Skip to content

MacHu-GWU/sqlalchemy_upsert_kit-project / .claude/skills/maintain-sqlalchemy_upsert_kit-base

maintain-sqlalchemy_upsert_kit-base

Verified

Maintenance knowledge of sqlalchemy_upsert_kit, the bulk upsert library for SQLAlchemy: its one job (three upsert strategies on several database backends), the core versus per-backend architecture and why, how each backend's strategies behave, the local database mise tasks, and how each backend is tested locally and in CI. Load it before changing the package, its tests, its mise tasks, or its CI in this repo.

sqlalchemy_upsert_kit does one thing: three bulk upsert strategies (insert or ignore, insert or replace, insert or merge), each staged through a temporary table, on several database backends. Everything that is the same on every database lives in sqlalchemy_upsert_kit/core/: input validation, the staging table, and the workflow (UpsertExecutor), which runs each call inside one SAVEPOINT. Each backend is its own subpackage, sqlalchemy_upsert_kit/<engine>/ (today sqlite/, postgres/ and mysql/), exposed as api.<engine>: its executor overrides only the hooks its database needs (the upsert statement always; how a transaction begins, how the staging table is dropped and cleaned up, how rows are counted, the identifier limit, and checks of other unique keys before and after the upsert, where the database differs), and its three modules hold the public functions. One shared contract suite, sqlalchemy_upsert_kit/tests/contract.py, tests every backend the same way.

For template conventions (layout, code style, tests, docs, release), load pywf-oss-base. This family records only what is specific to this library.

References

Numbered in the order a change usually touches them; each cites only earlier ones.

  • Scope and Strategy Contract (references/01-scope.md): Read before adding a feature, changing a strategy's behavior, or deciding whether a request belongs in this library.
  • Architecture: Core and Backends (references/02-architecture.md): Read before moving code between core and a backend, or adding shared logic.
  • Backend: SQLite (references/03-backend-sqlite.md): Read before changing the sqlite backend, or when a SQLite upsert commits, locks, or fires triggers unexpectedly.
  • Backend: PostgreSQL (references/04-backend-postgres.md): Read before changing the postgres backend, or when a PostgreSQL upsert's counts or transaction state look wrong.
  • Backend: MySQL (references/05-backend-mysql.md): Read before changing the mysql backend, or when a MySQL upsert commits, leaves a staging table, or updates the wrong row.
  • Local Database Tasks (references/06-local-db-tasks.md): Read before changing or adding a local database task, or when psql-up or mysql-up fails.
  • Testing the Backends (references/07-testing.md): Read before writing or changing tests, or when a backend's tests fail locally or in CI.

Which skill to use

JobSkill
Add a new database backend (such as MySQL)maintain-sqlalchemy_upsert_kit-add-backend
Any other change: read the references above that it touchesthis skill
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall