# Configuration

## `delembic.ini`

Delembic reads configuration from `delembic.ini`. It walks up from the current directory, so you can run `delembic` commands from any subdirectory of your project.

### Full example

```ini
[delembic]
script_location = delembic
sqlalchemy.url = postgresql+psycopg://user:pass@localhost/mydb
alembic_config = alembic.ini
```

### Options

`script_location`
: Path to the folder containing `versions/`. Relative to the location of `delembic.ini`. **Default:** `delembic`

`sqlalchemy.url`
: SQLAlchemy database URL. Required. Examples:
  ```
  postgresql+psycopg://user:pass@localhost/mydb
  postgresql+psycopg2://user:pass@localhost/mydb
  sqlite:///data.db
  sqlite:///:memory:
  ```

`alembic_config`
: Path to your `alembic.ini`. Relative to `delembic.ini`. Optional — only needed if you use Alembic integration. When set, `delembic revision` will auto-capture current Alembic heads into `depends_on`.

## Custom Folder Name

```bash
delembic init data-migrations
```

`delembic.ini` is updated automatically:

```ini
[delembic]
script_location = data-migrations
```

## Environment Variables

Delembic does not read environment variables directly. Use `env.py` (generated by `delembic init`) to inject them:

```python
# delembic/env.py
import os
from sqlalchemy import create_engine

DATABASE_URL = os.environ["DATABASE_URL"]

def get_engine():
    return create_engine(DATABASE_URL)
```

Then reference it from your migrations if needed, or configure `sqlalchemy.url` to read from env using a wrapper.

## Metadata Tables

Delembic automatically creates two tables on first run:

### `delembic_version`

Current status per revision. One row per revision, replaced on retry.

| Column | Type | Description |
|---|---|---|
| `revision` | TEXT | Revision ID (e.g. `D001`) |
| `status` | TEXT | `success` or `failed` |
| `applied_at` | DATETIME | When this run started |
| `duration_seconds` | FLOAT | How long the migration took |
| `username` | TEXT | OS user who ran the migration |
| `hostname` | TEXT | Hostname where migration ran |

### `delembic_run_history`

Full append-only audit log. Every run appended, never deleted.

| Column | Type | Description |
|---|---|---|
| `id` | INTEGER | Auto-increment primary key |
| `revision` | TEXT | Revision ID |
| `status` | TEXT | `success` or `failed` |
| `started_at` | DATETIME | Run start time |
| `ended_at` | DATETIME | Run end time |
| `duration_seconds` | FLOAT | Duration |
| `exception` | TEXT | Full traceback (failures only) |
| `username` | TEXT | OS user |
| `hostname` | TEXT | Hostname |

```{note}
Failed migration work is rolled back. The failure record is always committed on a separate connection — the audit trail survives transaction failures.
```
