---
url: /seedling/latest/getting-started.md
description: >-
  Install sqlalchemy-seedling and seed your first SQLAlchemy database in five
  minutes.
---

# Getting Started

## Installation

```bash
pip install sqlalchemy-seedling
# or with uv
uv add sqlalchemy-seedling
```

Optional YAML fixture support:

```bash
pip install sqlalchemy-seedling[yaml]
```

## 5-minute quickstart

### 1. Scaffold the layout

```bash
seed init
```

Creates `seeders/` and `factories/` packages and appends a `[tool.seedling]` block to `pyproject.toml`.

### 2. Configure your runner

Point the CLI at your runner factory in `pyproject.toml`:

```toml
[tool.seedling]
runner = "myapp.seeders:create_runner"
```

### 3. Create a runner factory

```python [myapp/seeders/__init__.py]
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from seedling import SeederRunner


def create_runner(env: str) -> SeederRunner:
    engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/mydb")
    session_factory = async_sessionmaker(engine, expire_on_commit=False)
    runner = SeederRunner(session_factory, env=env)
    runner.discover("myapp.seeders")
    return runner
```

### 4. Write a seeder

```python [myapp/seeders/users.py]
from seedling import Seeder, DEV_AND_TEST
from sqlalchemy.ext.asyncio import AsyncSession
from myapp.models import User


class UserSeeder(Seeder):
    environments = DEV_AND_TEST
    models = [User]
    tags = {"demo"}

    async def run(self, session: AsyncSession) -> None:
        session.add(User(email="admin@example.com", name="Admin"))
        await session.commit()

    async def truncate(self, session: AsyncSession) -> None:
        await session.execute(text("TRUNCATE users CASCADE"))
```

### 5. Run it

```bash
seed run          # run all seeders for development
seed fresh        # truncate then re-seed
seed list         # show execution order
seed status       # show last run per seeder + drift detection
seed export       # dump seeded rows to fixtures.json
```