home / skills / codyswanngt / lisa / ops-db-ops

ops-db-ops skill

safe

/expo/copy-overwrite/.claude/skills/ops-db-ops

This skill manages database migrations, schema generation, and GraphQL codegen for Expo and serverless backends, with safe, environment-aware operations.

npx playbooks add skill codyswanngt/lisa --skill ops-db-ops

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.1 KB

---
name: ops-db-ops
description: Database migrations, reverts, schema generation, and GraphQL codegen for Expo + serverless backend projects. Operates on the backend (TypeORM) and frontend (GraphQL code generation).
allowed-tools:
  - Bash
  - Read
---

# Ops: Database Operations

Manage database migrations, schema generation, and GraphQL code generation.

**Argument**: `$ARGUMENTS` — operation (`migrate`, `revert`, `generate`, `schema`, `codegen`) and optional environment (default: `dev`)

## Path Convention

- **Frontend**: Current project directory (`.`)
- **Backend**: `${BACKEND_DIR:-../backend-v2}` — set `BACKEND_DIR` in `.claude/settings.local.json` if your backend is elsewhere

## Safety

**CRITICAL**: Never run migrations or reverts against production without explicit human confirmation.

## Discovery

Read the backend `package.json` to discover available migration and schema scripts:
- `migration:run:*` — run pending migrations
- `migration:revert:*` — revert last migration
- `migration:generate:*` — generate new migration from entity changes
- `migration:create` — create empty migration
- `generate:sql-schema*` — regenerate SQL schema for MCP
- `aws:signin:*` — AWS credential scripts

Read the frontend `package.json` to discover codegen scripts:
- `fetch:graphql:schema:*` — fetch GraphQL schema
- `generate:types:*` — generate TypeScript types

## AWS Prerequisite

All database operations (except `codegen`) require AWS credentials. Run the backend's AWS signin script first:

```bash
cd "${BACKEND_DIR:-../backend-v2}"
bun run aws:signin:{env}
```

## Operations

### migrate (run pending migrations)

**Local database**:
```bash
cd "${BACKEND_DIR:-../backend-v2}"
STAGE={env} bun run migration:run:local
```

**Remote database**:
```bash
cd "${BACKEND_DIR:-../backend-v2}"
STAGE={env} bun run migration:run:remote:local
```

### revert (undo last migration)

**Local database**:
```bash
cd "${BACKEND_DIR:-../backend-v2}"
STAGE={env} bun run migration:revert:local
```

**Remote database**:
```bash
cd "${BACKEND_DIR:-../backend-v2}"
STAGE={env} bun run migration:revert:remote:local
```

### generate (create new migration from entity changes)

```bash
cd "${BACKEND_DIR:-../backend-v2}"
NAME={migration_name} bun run migration:generate:{env}
```

### create (create empty migration)

```bash
cd "${BACKEND_DIR:-../backend-v2}"
NAME={migration_name} bun run migration:create
```

### schema (regenerate SQL schema for MCP)

```bash
cd "${BACKEND_DIR:-../backend-v2}"
STAGE={env} bun run generate:sql-schema
```

### codegen (regenerate GraphQL types in frontend)

1. **Fetch schema**:
   ```bash
   bun run fetch:graphql:schema:{env}
   ```

2. **Generate types**:
   ```bash
   bun run generate:types:{env}
   ```

**Note**: The backend must be running (locally or deployed) for schema fetching to work.

## Output Format

Report operation result:

| Operation | Environment | Target | Status | Details |
|-----------|-------------|--------|--------|---------|
| migrate | dev | local DB | SUCCESS | 2 migrations applied |
| codegen | dev | frontend | SUCCESS | Types regenerated |

Overview

This skill automates database migrations, reverts, schema generation, and GraphQL code generation for Expo + serverless backends using TypeORM. It operates across the backend (migrations, SQL schema) and frontend (GraphQL type generation), streamlining common devops tasks. It enforces a safety guardrail: never run destructive operations against production without explicit human confirmation.

How this skill works

The skill discovers runnable scripts by reading package.json files in the backend and frontend projects and maps high-level commands (migrate, revert, generate, schema, codegen) to concrete bun run scripts. For database operations it ensures AWS credentials are present by invoking the backend aws signin script before running TypeORM migration or schema commands. For frontend codegen it fetches the GraphQL schema from the running backend and then runs type generation scripts.

When to use it

Apply pending database migrations on a local or remote environment.
Revert the last applied migration when a change needs to be undone.
Generate a new migration after changing TypeORM entities.
Regenerate the canonical SQL schema used by MCP workflows.
Regenerate frontend GraphQL TypeScript types after schema changes.

Best practices

Always run the backend aws signin step before any migration or schema operation that accesses remote databases.
Never run migrate or revert against production without explicit human confirmation and a backup.
Run codegen only after the backend is running (locally or deployed) so schema fetching succeeds.
Set BACKEND_DIR in local settings if your backend is not at the default relative path.
Name generated migrations clearly (NAME={migration_name}) to track intent in version control.

Example use cases

Apply two pending migrations to your dev database: STAGE=dev migration:run:local.
Undo a faulty migration on a staging instance after human review: STAGE=staging migration:revert:remote:local.
Create a new migration from entity changes: NAME=add-user-index migration:generate:dev.
Regenerate the SQL schema artifact used by MCP: STAGE=prod generate:sql-schema.
Refresh frontend TypeScript types after schema updates: fetch schema then generate types for the chosen environment.

FAQ

Do I need AWS credentials to run codegen?

No. AWS credentials are required for database operations but not for frontend codegen. Codegen requires the backend to be reachable so schema fetching succeeds.

How do I target a non-default backend directory?

Set BACKEND_DIR in your local settings to point to your backend path, then commands will operate there instead of the default ../backend-v2.