backend/alembic/README - develop - Ru5Kasper/Trackly

backend/alembic/README
99 строк2 KB
DORANDKOR
feat(backend): create migrations, add support for user avatars
31 мар 2026, 07:30
31 мар 2026, 07:30b6b9ba7
# Alembic Database Migrations

This directory contains Alembic migrations for the Trackly backend database.

## Prerequisites

- PostgreSQL database running and accessible
- Environment variables configured in `.env.development` or `.env.production`

## First Time Setup

If your database already has tables created (e.g., from `metadata.create_all()`), you need to tell Alembic that your database is already at the latest migration version:

```bash
uv run alembic stamp head
```

Or using the helper script:
```bash
python migrate.py stamp head
```

This marks the database as being at the current migration state without actually running the migrations.

## Common Commands

### Run migrations (apply all pending migrations):
```bash
uv run alembic upgrade head
# or
python migrate.py upgrade
```

### Mark database at current version (without running migrations):
```bash
uv run alembic stamp head
# or
python migrate.py stamp
```

### Revert last migration:
```bash
uv run alembic downgrade -1
# or
python migrate.py downgrade
```

### Create a new migration (auto-generate from models):
```bash
uv run alembic revision --autogenerate -m "description of changes"
```

### Create a new empty migration:
```bash
uv run alembic revision -m "description of changes"
```

### Show current migration version:
```bash
uv run alembic current
# or
python migrate.py current
```

### Show migration history:
```bash
uv run alembic history
# or
python migrate.py history
```

### Downgrade to a specific revision:
```bash
uv run alembic downgrade <revision_id>
```

### Upgrade to a specific revision:
```bash
uv run alembic upgrade <revision_id>
```

## Configuration

- **alembic.ini**: Main configuration file
- **env.py**: Migration environment configuration with async support
- **versions/**: Directory containing migration files

## Async Support

This project uses SQLAlchemy async connections (asyncpg driver for PostgreSQL).
The migrations are configured to work with async engines automatically.

## Troubleshooting

### "relation already exists" error
This happens when tables already exist in the database. Use `alembic stamp head` to mark the database at the current version without running migrations.

### "No module named app"
Make sure you're running alembic from the backend directory and using `uv run alembic` to ensure the correct Python environment is used.