0
# Migration Commands
1
2
MikroORM CLI migration system providing comprehensive database schema versioning and migration management. Supports creating, executing, and tracking database schema changes over time.
3
4
## Capabilities
5
6
### Create Migration
7
8
Creates a new migration file with schema differences between current entities and database state.
9
10
```typescript { .api }
11
/**
12
* Create new migration command
13
*/
14
command: "migration:create"
15
16
interface MigrationCreateOptions extends BaseArgs {
17
blank?: boolean; // Create blank migration (--blank / -b)
18
initial?: boolean; // Create initial migration (--initial / -i)
19
dump?: boolean; // Dump queries to console (--dump / -d)
20
path?: string; // Migration directory path (--path / -p)
21
name?: string; // Custom migration name (--name / -n)
22
}
23
```
24
25
**Usage Examples:**
26
27
```bash
28
# Create migration with auto-generated schema diff
29
mikro-orm migration:create
30
31
# Create blank migration for custom SQL
32
mikro-orm migration:create --blank
33
34
# Create initial migration from current schema
35
mikro-orm migration:create --initial
36
37
# Create with custom name and dump queries
38
mikro-orm migration:create --name AddUserTable --dump
39
40
# Save to custom directory
41
mikro-orm migration:create --path ./migrations/custom
42
```
43
44
### Run Migrations Up
45
46
Executes pending migrations to bring database schema up to latest version.
47
48
```typescript { .api }
49
/**
50
* Migrate up to latest version command
51
*/
52
command: "migration:up"
53
54
interface MigrationUpOptions extends BaseArgs {
55
to?: string; // Migrate up to specific version (--to / -t)
56
from?: string; // Start migration from specific version (--from / -f)
57
only?: string; // Migrate only specified versions (--only / -o)
58
}
59
```
60
61
**Usage Examples:**
62
63
```bash
64
# Migrate to latest version
65
mikro-orm migration:up
66
67
# Migrate to specific version
68
mikro-orm migration:up --to 20231201_001
69
70
# Migrate from specific version
71
mikro-orm migration:up --from 20231120_002
72
73
# Run only specific migration
74
mikro-orm migration:up --only 20231201_001
75
```
76
77
### Run Migrations Down
78
79
Reverts migrations by executing down methods to undo schema changes.
80
81
```typescript { .api }
82
/**
83
* Migrate one step down command
84
*/
85
command: "migration:down"
86
87
interface MigrationDownOptions extends BaseArgs {
88
to?: string; // Migrate down to specific version (--to / -t)
89
from?: string; // Start migration from specific version (--from / -f)
90
only?: string; // Migrate only specified versions (--only / -o)
91
}
92
```
93
94
**Usage Examples:**
95
96
```bash
97
# Migrate one step down
98
mikro-orm migration:down
99
100
# Migrate down to specific version
101
mikro-orm migration:down --to 20231120_001
102
103
# Revert only specific migration
104
mikro-orm migration:down --only 20231201_002
105
```
106
107
### List Executed Migrations
108
109
Displays all executed migrations with their execution timestamps.
110
111
```typescript { .api }
112
/**
113
* List all executed migrations command
114
*/
115
command: "migration:list"
116
117
// No additional options beyond global options
118
```
119
120
**Usage Examples:**
121
122
```bash
123
# List executed migrations
124
mikro-orm migration:list
125
126
# List with specific config
127
mikro-orm migration:list --config ./orm.config.js
128
```
129
130
### Check Migration Status
131
132
Checks if there are pending migrations that need to be executed. Useful for CI/CD pipelines and deployment scripts.
133
134
```typescript { .api }
135
/**
136
* Check if migrations are needed command
137
*/
138
command: "migration:check"
139
140
// No additional options beyond global options
141
// Exit code 0: no pending migrations
142
// Exit code 1: pending migrations exist
143
```
144
145
**Usage Examples:**
146
147
```bash
148
# Check migration status
149
mikro-orm migration:check
150
151
# Use in scripts
152
if mikro-orm migration:check; then
153
echo "Database is up to date"
154
else
155
echo "Pending migrations found"
156
mikro-orm migration:up
157
fi
158
```
159
160
### List Pending Migrations
161
162
Shows all pending migrations that haven't been executed yet.
163
164
```typescript { .api }
165
/**
166
* List all pending migrations command
167
*/
168
command: "migration:pending"
169
170
// No additional options beyond global options
171
```
172
173
**Usage Examples:**
174
175
```bash
176
# List pending migrations
177
mikro-orm migration:pending
178
179
# Check with custom configuration
180
mikro-orm migration:pending --context production
181
```
182
183
### Fresh Migration
184
185
Drops the database schema and re-runs all migrations from scratch. Useful for testing and development environment resets.
186
187
```typescript { .api }
188
/**
189
* Clear database and rerun all migrations command
190
*/
191
command: "migration:fresh"
192
193
interface MigrationFreshOptions extends BaseArgs {
194
dropDb?: boolean; // Drop entire database (--drop-db)
195
seed?: string; // Seed database after migration (--seed)
196
}
197
```
198
199
**Usage Examples:**
200
201
```bash
202
# Drop schema and run all migrations
203
mikro-orm migration:fresh
204
205
# Fresh migration with database seeding
206
mikro-orm migration:fresh --seed DatabaseSeeder
207
208
# Fresh migration with database drop and recreation
209
mikro-orm migration:fresh --drop-db
210
211
# Fresh migration with seeding and custom config
212
mikro-orm migration:fresh --seed TestDataSeeder --config ./test.config.js
213
```
214
215
## Migration Options
216
217
### Global Options
218
219
All migration commands support:
220
- `--config`: Path to ORM configuration file(s)
221
- `--contextName` / `--context`: Configuration context name
222
223
### Creation Options
224
225
- `--blank` / `-b`: Create empty migration file for custom SQL
226
- `--initial` / `-i`: Create initial migration from current entity state
227
- `--dump` / `-d`: Display generated SQL queries in console
228
- `--path` / `-p`: Set custom directory for migration files
229
- `--name` / `-n`: Specify custom name for migration file
230
231
### Execution Options
232
233
- `--to` / `-t`: Target specific migration version
234
- `--from` / `-f`: Start from specific migration version
235
- `--only` / `-o`: Execute only specified migration(s)
236
237
## Migration File Structure
238
239
Generated migration files follow this structure:
240
241
```typescript
242
import { Migration } from '@mikro-orm/migrations';
243
244
export class Migration20231201001234 extends Migration {
245
246
async up(): Promise<void> {
247
this.addSql('CREATE TABLE "user" ("id" serial PRIMARY KEY, "name" varchar(255) NOT NULL);');
248
}
249
250
async down(): Promise<void> {
251
this.addSql('DROP TABLE "user";');
252
}
253
254
}
255
```
256
257
## Error Handling
258
259
### Common Migration Errors
260
261
- **Schema conflicts**: Database schema doesn't match entity definitions
262
- **Migration conflicts**: Multiple developers creating migrations simultaneously
263
- **Rollback failures**: Down migrations may fail due to data constraints
264
- **Syntax errors**: Invalid SQL in migration files
265
- **Permission errors**: Insufficient database privileges for schema changes
266
267
### Migration Safety
268
269
- **Backup recommendations**: Always backup production data before migrations
270
- **Testing**: Test migrations in development environment first
271
- **Rollback planning**: Ensure down migrations are properly implemented
272
- **Data preservation**: Be careful with destructive operations in migrations
273
274
## Configuration
275
276
Migration system uses these configuration options:
277
278
```typescript { .api }
279
interface MigrationConfiguration {
280
migrations: {
281
path?: string; // Migration files directory
282
pattern?: RegExp; // Migration file naming pattern
283
transactional?: boolean; // Run migrations in transactions
284
disableForeignKeys?: boolean; // Disable FK checks during migration
285
allOrNothing?: boolean; // All migrations succeed or all fail
286
};
287
}
288
```