0
# Helper API
1

2
MikroORM CLI Helper API provides programmatic access to CLI functionality for custom tooling, scripts, and integrations. The CLIHelper class offers static methods for common ORM operations used throughout the CLI commands.
3

4
## Capabilities
5

6
### Configuration Management
7

8
Load and validate MikroORM configuration from various sources and contexts.
9

10
```typescript { .api }
11
/**
12
 * Load ORM configuration with context and path resolution
13
 */
14
static async getConfiguration<D extends IDatabaseDriver = IDatabaseDriver>(
15
  contextName?: string,
16
  configPaths?: string[],
17
  options?: Partial<Options<D>>
18
): Promise<Configuration<D>>;
19
```
20

21
**Usage Examples:**
22

23
```typescript
24
import { CLIHelper } from '@mikro-orm/cli';
25

26
// Load default configuration
27
const config = await CLIHelper.getConfiguration();
28

29
// Load specific context
30
const prodConfig = await CLIHelper.getConfiguration('production');
31

32
// Load with custom config paths
33
const config = await CLIHelper.getConfiguration('default', ['./custom.config.js']);
34

35
// Load with additional options
36
const config = await CLIHelper.getConfiguration('default', undefined, {
37
  debug: true,
38
  discovery: { warnWhenNoEntities: false }
39
});
40
```
41

42
### ORM Instance Management
43

44
Initialize MikroORM instances with CLI-specific configuration and settings.
45

46
```typescript { .api }
47
/**
48
 * Initialize MikroORM instance with CLI settings
49
 */
50
static async getORM<D extends IDatabaseDriver = IDatabaseDriver>(
51
  contextName?: string,
52
  configPaths?: string[],
53
  opts?: Partial<Options<D>>
54
): Promise<MikroORM<D>>;
55
```
56

57
**Usage Examples:**
58

59
```typescript
60
import { CLIHelper } from '@mikro-orm/cli';
61

62
// Initialize default ORM instance
63
const orm = await CLIHelper.getORM();
64

65
// Initialize with specific context
66
const orm = await CLIHelper.getORM('development');
67

68
// Initialize with custom options
69
const orm = await CLIHelper.getORM('default', undefined, {
70
  pool: { min: 1, max: 2 },
71
  discovery: { warnWhenNoEntities: false }
72
});
73

74
// Don't forget to close when done
75
await orm.close(true);
76
```
77

78
### Database Connectivity
79

80
Test database connections and validate connectivity status.
81

82
```typescript { .api }
83
/**
84
 * Check database connection status
85
 */
86
static async isDBConnected(config: Configuration, reason?: false): Promise<boolean>;
87
static async isDBConnected(config: Configuration, reason: true): Promise<true | string>;
88
```
89

90
**Usage Examples:**
91

92
```typescript
93
import { CLIHelper } from '@mikro-orm/cli';
94

95
const config = await CLIHelper.getConfiguration();
96

97
// Simple boolean check
98
const connected = await CLIHelper.isDBConnected(config);
99
if (connected) {
100
  console.log('Database is connected');
101
}
102

103
// Get connection status with reason
104
const status = await CLIHelper.isDBConnected(config, true);
105
if (status === true) {
106
  console.log('Connection successful');
107
} else {
108
  console.log(`Connection failed: ${status}`);
109
}
110
```
111

112
### System Information
113

114
Retrieve system and dependency information for debugging and diagnostics.
115

116
```typescript { .api }
117
/**
118
 * Get Node.js version
119
 */
120
static getNodeVersion(): string;
121

122
/**
123
 * Get database driver dependencies
124
 */
125
static getDriverDependencies(config: Configuration): string[];
126

127
/**
128
 * Get module version information
129
 */
130
static async getModuleVersion(name: string): Promise<string>;
131
```
132

133
**Usage Examples:**
134

135
```typescript
136
import { CLIHelper } from '@mikro-orm/cli';
137

138
// Get Node.js version
139
const nodeVersion = CLIHelper.getNodeVersion();
140
console.log(`Node.js: ${nodeVersion}`);
141

142
// Get driver dependencies
143
const config = await CLIHelper.getConfiguration();
144
const drivers = CLIHelper.getDriverDependencies(config);
145
console.log('Drivers:', drivers);
146

147
// Get specific module version
148
const tsVersion = await CLIHelper.getModuleVersion('typescript');
149
console.log(`TypeScript: ${tsVersion}`);
150
```
151

152
### Output and Display
153

154
Format and display information with consistent styling and formatting.
155

156
```typescript { .api }
157
/**
158
 * Output text with optional syntax highlighting
159
 */
160
static dump(text: string, config?: Configuration): void;
161

162
/**
163
 * Display formatted table
164
 */
165
static dumpTable(options: TableOptions): void;
166

167
/**
168
 * Display dependency information
169
 */
170
static async dumpDependencies(): Promise<void>;
171

172
/**
173
 * Show CLI help
174
 */
175
static showHelp(): void;
176
```
177

178
**Usage Examples:**
179

180
```typescript
181
import { CLIHelper } from '@mikro-orm/cli';
182

183
// Simple text output
184
CLIHelper.dump('Operation completed successfully');
185

186
// Output with highlighting (if configured)
187
const config = await CLIHelper.getConfiguration();
188
CLIHelper.dump('SELECT * FROM users;', config);
189

190
// Display table
191
CLIHelper.dumpTable({
192
  columns: ['Name', 'Version', 'Status'],
193
  rows: [
194
    ['mikro-orm', '6.5.2', 'installed'],
195
    ['typescript', '5.2.0', 'installed']
196
  ],
197
  empty: 'No packages found'
198
});
199

200
// Display system dependencies
201
await CLIHelper.dumpDependencies();
202

203
// Show help
204
CLIHelper.showHelp();
205
```
206

207
### Configuration Path Management
208

209
Manage and discover configuration file paths.
210

211
```typescript { .api }
212
/**
213
 * Get standard configuration file paths
214
 */
215
static getConfigPaths(): string[];
216
```
217

218
**Usage Examples:**
219

220
```typescript
221
import { CLIHelper } from '@mikro-orm/cli';
222

223
// Get standard config paths
224
const paths = CLIHelper.getConfigPaths();
225
console.log('Searching config paths:', paths);
226

227
// Use with configuration loading
228
const config = await CLIHelper.getConfiguration('default', paths);
229
```
230

231
## Types and Interfaces
232

233
```typescript { .api }
234
// Table formatting options
235
interface TableOptions {
236
  columns: string[];      // Column headers
237
  rows: string[][];      // Table data rows
238
  empty: string;         // Message when no rows
239
}
240

241
// Database driver interface
242
interface IDatabaseDriver {
243
  // Driver-specific implementation
244
}
245

246
// Configuration options
247
interface Options<D extends IDatabaseDriver> {
248
  debug?: boolean;
249
  discovery?: {
250
    warnWhenNoEntities?: boolean;
251
  };
252
  pool?: {
253
    min?: number;
254
    max?: number;
255
  };
256
  connect?: boolean;
257
  allowGlobalContext?: boolean;
258
  preferTs?: boolean;
259
  entities?: any[];
260
  entitiesTs?: any[];
261
  // ... other MikroORM options
262
}
263
```
264

265
## Error Handling
266

267
### Common Errors
268

269
- **Configuration not found**: When config files don't exist at specified paths
270
- **Invalid context**: When requested context doesn't exist in configuration
271
- **Connection failures**: Database connectivity issues
272
- **Module not found**: When checking versions of uninstalled packages
273
- **Permission errors**: File system access issues
274

275
### Error Examples
276

277
```typescript
278
import { CLIHelper } from '@mikro-orm/cli';
279

280
try {
281
  const config = await CLIHelper.getConfiguration('invalid-context');
282
} catch (error) {
283
  console.error('Configuration error:', error.message);
284
}
285

286
try {
287
  const orm = await CLIHelper.getORM();
288
  // ... use ORM
289
} catch (error) {
290
  console.error('ORM initialization failed:', error.message);
291
} finally {
292
  // Ensure proper cleanup
293
  if (orm) await orm.close(true);
294
}
295
```
296

297
## Integration Examples
298

299
### Custom CLI Script
300

301
```typescript
302
#!/usr/bin/env node
303
import { CLIHelper } from '@mikro-orm/cli';
304

305
async function customMigrationCheck() {
306
  try {
307
    const orm = await CLIHelper.getORM();
308
    const migrator = orm.getMigrator();
309
    
310
    const pending = await migrator.getPendingMigrations();
311
    if (pending.length > 0) {
312
      CLIHelper.dump(`Found ${pending.length} pending migrations`);
313
      process.exit(1);
314
    }
315
    
316
    CLIHelper.dump('Database is up to date');
317
    await orm.close(true);
318
  } catch (error) {
319
    CLIHelper.dump(`Error: ${error.message}`);
320
    process.exit(1);
321
  }
322
}
323

324
customMigrationCheck();
325
```
326

327
### Build Process Integration
328

329
```typescript
330
import { CLIHelper } from '@mikro-orm/cli';
331

332
export async function validateDatabaseSetup(): Promise<boolean> {
333
  try {
334
    const config = await CLIHelper.getConfiguration();
335
    const connected = await CLIHelper.isDBConnected(config);
336
    
337
    if (!connected) {
338
      console.error('Database connection failed');
339
      return false;
340
    }
341
    
342
    // Additional validation...
343
    return true;
344
  } catch (error) {
345
    console.error('Setup validation failed:', error.message);
346
    return false;
347
  }
348
}
349
```
350

351
## Best Practices
352

353
### Resource Management
354

355
- Always close ORM instances when done: `await orm.close(true)`
356
- Handle configuration errors gracefully
357
- Use try-catch blocks for async operations
358
- Clean up resources in finally blocks
359

360
### Performance Considerations
361

362
- Reuse configuration objects when possible
363
- Use connection pooling options for multiple operations
364
- Close database connections promptly
365
- Cache system information when making multiple calls
366

367
### Error Handling
368

369
- Provide meaningful error messages
370
- Log errors appropriately for debugging
371
- Handle network timeouts and connection failures
372
- Validate inputs before processing