# Specx Sqlalchemy Migrations

> Add or repair Alembic migrations for specx SQLAlchemy services. Use when adding SQLAlchemy models or repositories, replacing metadata.create_all schema bootstraps, creating async Alembic env.py, adding migration Makefile targets, generating initial revisions, or testing migration drift.

- **Type:** Skill
- **Install:** `agentstack add skill-maksimzayats-specx-specx-sqlalchemy-migrations`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [maksimzayats](https://agentstack.voostack.com/s/maksimzayats)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [maksimzayats](https://github.com/maksimzayats)
- **Source:** https://github.com/maksimzayats/specx/tree/main/skills/specx-sqlalchemy-migrations
- **Website:** https://specx.dev

## Install

```sh
agentstack add skill-maksimzayats-specx-specx-sqlalchemy-migrations
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# specx SQLAlchemy Migrations

Use this skill whenever a specx project has SQLAlchemy models or persistence
adapters. Read `references/alembic.md` before editing migration files.

## Workflow

1. Add `alembic>=1.18.5` as a runtime dependency when SQLAlchemy adapters
   exist, together with SQLAlchemy's asyncio extra and the selected driver.
2. Add `alembic.ini`, `migrations/env.py`, `migrations/script.py.mako`, and
   `migrations/versions/`.
3. Use Alembic's async pattern for async SQLAlchemy engines.
4. Put app-wide SQLAlchemy settings/session factory under top-level
   `infrastructure/sqlalchemy/`.
5. Keep scope-owned ORM models and repositories under
   `core//infrastructure/sqlalchemy/`.
6. Add a project-local SQLAlchemy declarative base under
   `src//foundation/sqlalchemy_model.py`; do not use shared packaged
   metadata for generated services.
7. Put reusable model discovery under top-level
   `infrastructure/sqlalchemy/model_discovery.py`. Use that same function from
   `migrations/env.py` and its guardrail test before assigning
   `target_metadata`; do not duplicate discovery or maintain hard-coded model
   module names.
8. Set `target_metadata` to the project-local `BaseSQLAlchemyModel.metadata`.
9. Generate or hand-review an initial migration for current models.
10. Add `make migrate` and `make makemigrations`.
11. Add tests that run `alembic upgrade head` against an isolated database,
    check for pending autogenerate changes, and prove every core SQLAlchemy
    model file is included by the exact discovery function Alembic uses. Use
    the production database family when dialect behavior matters.

## Guardrails

- Do not call `Base.metadata.create_all`, `metadata.create_all`, or
  `drop_all` from `src/`.
- Do not run migrations from FastAPI startup by default. Run migrations as an
  operational command before app startup.
- Do not put app-wide engine/session factory code inside one core scope.
- Do not let delivery controllers import ORM models, repositories, sessions, or
  migration helpers.
- Do not let Alembic drift checks depend on incomplete metadata. Model discovery
  must include every `core/*/infrastructure/sqlalchemy/models/*.py` file.
- Do not trust autogenerated migrations without review.
- Do not edit, delete, or reorder a revision that may already have been applied;
  add a new corrective revision.
- Do not pass SQLite's `autocommit` connect argument on Python 3.11. For a
  savepoint-based SQLite test harness spanning Python versions, use
  SQLAlchemy's `connect` and `begin` event-hook recipe.

## Code Style

Use blank lines as logical separators in all code. Keep related statements
together, but separate independent setup, action, assertion, response, branch,
and transformation groups so long blocks stay readable.

## References

- `references/alembic.md` - async Alembic layout, env.py, Makefile targets,
  initial migration, and migration tests.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [maksimzayats](https://github.com/maksimzayats)
- **Source:** [maksimzayats/specx](https://github.com/maksimzayats/specx)
- **License:** MIT
- **Homepage:** https://specx.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-maksimzayats-specx-specx-sqlalchemy-migrations
- Seller: https://agentstack.voostack.com/s/maksimzayats
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.