0
# Schema Commands
1

2
MikroORM CLI schema management commands for creating, updating, dropping, and recreating database schemas based on entity definitions. These commands provide direct schema manipulation capabilities for development and deployment workflows.
3

4
## Capabilities
5

6
### Create Schema
7

8
Creates database schema based on current entity metadata. Generates tables, indexes, and constraints from entity definitions.
9

10
```typescript { .api }
11
/**
12
 * Create database schema command
13
 */
14
command: "schema:create"
15

16
interface SchemaCreateOptions extends BaseArgs {
17
  run?: boolean;       // Execute queries (--run / -r)
18
  dump?: boolean;      // Dump queries to console (--dump / -d) 
19
  fkChecks?: boolean;  // Include foreign key checks (--fk-checks)
20
  schema?: string;     // Set current schema for wildcard entities (--schema)
21
  seed?: string;       // Seed database after creation (--seed)
22
}
23
```
24

25
**Usage Examples:**
26

27
```bash
28
# Display schema creation queries without executing
29
mikro-orm schema:create --dump
30

31
# Create schema and execute queries
32
mikro-orm schema:create --run
33

34
# Create schema and seed with data
35
mikro-orm schema:create --run --seed DatabaseSeeder
36

37
# Create for specific schema with FK checks
38
mikro-orm schema:create --run --schema public --fk-checks
39
```
40

41
### Update Schema
42

43
Updates existing database schema to match current entity definitions. Handles adding/modifying columns, indexes, and constraints.
44

45
```typescript { .api }
46
/**
47
 * Update database schema command
48
 */
49
command: "schema:update"
50

51
interface SchemaUpdateOptions extends BaseArgs {
52
  run?: boolean;         // Execute queries (--run / -r)
53
  dump?: boolean;        // Dump queries to console (--dump / -d)
54
  fkChecks?: boolean;    // Include foreign key checks (--fk-checks)
55
  schema?: string;       // Set current schema for wildcard entities (--schema)
56
  safe?: boolean;        // Disable table and column dropping (--safe)
57
  dropTables?: boolean;  // Control table dropping (--drop-tables, default: true)
58
}
59
```
60

61
**Usage Examples:**
62

63
```bash
64
# Show update queries without executing
65
mikro-orm schema:update --dump
66

67
# Update schema safely (no drops)
68
mikro-orm schema:update --run --safe
69

70
# Update with table dropping disabled
71
mikro-orm schema:update --run --drop-tables=false
72

73
# Update specific schema
74
mikro-orm schema:update --run --schema myschema
75
```
76

77
### Drop Schema
78

79
Drops database schema including all tables, indexes, and constraints. Provides options for complete database cleanup.
80

81
```typescript { .api }
82
/**
83
 * Drop database schema command
84
 */
85
command: "schema:drop"
86

87
interface SchemaDropOptions extends BaseArgs {
88
  run?: boolean;                  // Execute queries (--run / -r)
89
  dump?: boolean;                 // Dump queries to console (--dump / -d)
90
  fkChecks?: boolean;            // Include foreign key checks (--fk-checks)
91
  schema?: string;               // Set current schema for wildcard entities (--schema)
92
  dropMigrationsTable?: boolean; // Drop migrations table (--drop-migrations-table)
93
  dropDb?: boolean;              // Drop entire database (--drop-db)
94
}
95
```
96

97
**Usage Examples:**
98

99
```bash
100
# Show drop queries without executing
101
mikro-orm schema:drop --dump
102

103
# Drop schema but keep migrations table
104
mikro-orm schema:drop --run
105

106
# Drop schema including migrations table
107
mikro-orm schema:drop --run --drop-migrations-table
108

109
# Drop entire database
110
mikro-orm schema:drop --run --drop-db
111
```
112

113
### Fresh Schema
114

115
Drops existing schema and recreates it from current entity definitions. Combines drop and create operations for clean schema reset.
116

117
```typescript { .api }
118
/**
119
 * Drop and recreate database schema command
120
 */
121
command: "schema:fresh"
122

123
interface SchemaFreshOptions extends BaseArgs {
124
  run?: boolean;      // Execute queries (--run / -r)
125
  schema?: string;    // Set current schema for wildcard entities (--schema)
126
  seed?: string;      // Seed database after recreation (--seed)
127
  dropDb?: boolean;   // Drop entire database before recreating (--drop-db)
128
}
129
```
130

131
**Usage Examples:**
132

133
```bash
134
# Fresh schema recreation (must use --run)
135
mikro-orm schema:fresh --run
136

137
# Fresh schema with seeding
138
mikro-orm schema:fresh --run --seed TestDataSeeder
139

140
# Fresh with database drop and recreation
141
mikro-orm schema:fresh --run --drop-db
142

143
# Fresh for specific schema
144
mikro-orm schema:fresh --run --schema test_schema
145
```
146

147
## Command Requirements
148

149
### Execution Requirements
150

151
Schema commands require either `--run` or `--dump` option:
152
- `--run`: Execute the schema operations
153
- `--dump`: Display SQL queries without executing
154

155
Without one of these options, the command will show help instead of executing.
156

157
### Safety Considerations
158

159
- **Production use**: Always use `--dump` first to review queries
160
- **Backup data**: Schema operations can be destructive
161
- **Safe mode**: Use `--safe` for update operations to prevent data loss
162
- **Testing**: Test schema changes in development environment first
163

164
## Global Options
165

166
All schema commands support:
167
- `--config`: Path to ORM configuration file(s)
168
- `--contextName` / `--context`: Configuration context name
169

170
## Command-Specific Options
171

172
### Common Options
173

174
- `--run` / `-r`: Execute the SQL queries
175
- `--dump` / `-d`: Display queries in console without executing
176
- `--schema`: Set current schema name for wildcard schema entities
177
- `--fk-checks`: Include foreign key constraint checks (create/update/drop only)
178

179
### Create/Fresh Specific
180

181
- `--seed`: Run specified seeder class after schema creation
182

183
### Update Specific
184

185
- `--safe`: Disable destructive operations (table/column dropping)
186
- `--drop-tables`: Control whether tables can be dropped (default: true)
187

188
### Drop Specific
189

190
- `--drop-migrations-table`: Include migrations table in drop operation
191
- `--drop-db`: Drop entire database instead of just schema
192

193
### Fresh Specific
194

195
- `--drop-db`: Drop and recreate entire database
196

197
## Error Handling
198

199
### Common Schema Errors
200

201
- **Missing execution option**: Commands require either `--run` or `--dump`
202
- **Permission errors**: Database user needs schema modification privileges
203
- **Constraint violations**: Existing data may prevent schema changes
204
- **Foreign key conflicts**: Related tables may prevent drops/modifications
205
- **Syntax errors**: Generated SQL may have database-specific issues
206

207
### Schema Safety
208

209
- **Data preservation**: Update operations may lose data in column modifications
210
- **Constraint validation**: New constraints may conflict with existing data
211
- **Index rebuilding**: Large tables may take time for index operations
212
- **Transaction handling**: Schema operations may not be fully transactional
213

214
## Database Support
215

216
Schema commands work with:
217
- **PostgreSQL**: Full support including schemas, constraints, and indexes
218
- **MySQL/MariaDB**: Complete support with proper type handling
219
- **SQLite**: Basic support with standard SQL features
220
- **MongoDB**: Not applicable (schema-less document database)
221

222
## Configuration
223

224
Schema operations use these configuration options:
225

226
```typescript { .api }
227
interface SchemaConfiguration {
228
  schemaGenerator?: {
229
    disableForeignKeys?: boolean;  // Disable FK checks during operations
230
    createForeignKeyConstraints?: boolean; // Create FK constraints
231
  };
232
  schema?: string;                 // Default schema name
233
  entities: string[];              // Entity definitions for schema generation
234
}
235
```