reshape 0.9.1

An easy-to-use, zero-downtime schema migration tool for Postgres
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

# Reshape

Reshape is a zero-downtime schema migration tool for PostgreSQL (12+). It works by creating views that encapsulate tables, with triggers to translate between old and new schemas during migrations. This allows gradual application rollouts without downtime.

## Build and Test Commands

```bash
# Build
cargo build

# Run all tests (must use single thread due to shared database)
cargo test -- --test-threads=1

# Run a single test
cargo test test_name -- --test-threads=1

# Lint (fails hard for warnings as well)
cargo clippy -- -D warnings
```

**Test database setup:** Tests require a Postgres database.

## Architecture

### Core Components

- **`src/lib.rs`**: Main `Reshape` struct with public API (`migrate`, `complete`, `abort`, `remove`)
- **`src/db.rs`**: Database connection with `DbLocker` for advisory locking to prevent concurrent runs
- **`src/state.rs`**: State machine tracking migration lifecycle (`Idle` → `Applying` → `InProgress` → `Completing`)
- **`src/schema.rs`**: Schema introspection and change tracking during migrations
- **`src/main.rs`**: CLI interface using clap

### Migration Actions (`src/migrations/`)

All migration types implement the `Action` trait:

- `run()`: Apply the migration (create views, triggers, temporary columns)
- `complete()`: Finalize the migration (drop old columns, rename, cleanup)
- `abort()`: Roll back changes
- `update_schema()`: Track schema changes for subsequent actions

Supported actions: `create_table`, `alter_column`, `add_column`, `remove_column`, `rename_table`, `remove_table`, `add_index`, `remove_index`, `create_enum`, `remove_enum`, `add_foreign_key`, `remove_foreign_key`, `custom`

### Key Patterns

- **State persistence**: Migration state stored in `reshape.data` table as JSON; completed migrations tracked in `reshape.migrations`
- **Naming conventions**: Objects created during migration use prefix `__reshape_{migration_index}_{action_index}`
- **Schema naming**: Views created in schema named `migration_{migration_name}`
- **Retry logic**: Database queries use exponential backoff (100ms to 3.2s, up to 10 attempts)
- **Trait serialization**: Migration actions use `typetag` for trait object serialization in TOML/JSON files

### Migration File Format

Migrations are TOML or JSON files in `migrations/` directory with `[[actions]]` arrays:

```toml
[[actions]]
type = "create_table"
name = "users"
primary_key = ["id"]

    [[actions.columns]]
    name = "id"
    type = "INTEGER"
```