0
# Command Framework
1

2
This document covers Liquibase's modern command framework through the CommandScope class, which provides a flexible and extensible way to execute Liquibase operations.
3

4
## Imports
5

6
```java { .api }
7
import liquibase.command.CommandScope;
8
import liquibase.command.CommandResults;
9
import liquibase.exception.CommandExecutionException;
10

11
import java.io.OutputStream;
12
import java.io.Writer;
13
```
14

15
## CommandScope Class
16

17
The CommandScope class is the primary facade for executing commands using Liquibase's modern command framework.
18

19
### Constructor
20

21
```java { .api }
22
/**
23
 * Create a new command scope for execution
24
 * @param commandName Command name(s) to execute
25
 * @throws CommandExecutionException if command cannot be found
26
 */
27
public CommandScope(String... commandName) throws CommandExecutionException
28
```
29

30
### Argument Configuration
31

32
```java { .api }
33
/**
34
 * Add argument value for command execution
35
 * @param argumentName Name of the argument
36
 * @param value Argument value
37
 * @return CommandScope for method chaining
38
 */
39
public CommandScope addArgumentValue(String argumentName, Object value)
40
```
41

42
### Output Configuration
43

44
```java { .api }
45
/**
46
 * Set output stream for command results
47
 * @param outputStream Target output stream
48
 * @return CommandScope for method chaining
49
 */
50
public CommandScope setOutput(OutputStream outputStream)
51
```
52

53
### Command Execution
54

55
```java { .api }
56
/**
57
 * Execute the configured command
58
 * @return CommandResults containing execution results
59
 * @throws CommandExecutionException if command execution fails
60
 */
61
public CommandResults execute() throws CommandExecutionException
62
```
63

64
## Core Commands
65

66
### Update Commands
67

68
Execute database update operations:
69

70
```java { .api }
71
// Standard update
72
CommandScope updateCommand = new CommandScope("update")
73
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
74
    .addArgumentValue("url", "jdbc:h2:mem:test")
75
    .addArgumentValue("username", "sa")
76
    .addArgumentValue("password", "")
77
    .addArgumentValue("contexts", "dev,test")
78
    .addArgumentValue("labelFilter", "feature-1");
79

80
CommandResults results = updateCommand.execute();
81

82
// Update with count limit
83
CommandScope updateCountCommand = new CommandScope("updateCount")
84
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
85
    .addArgumentValue("url", "jdbc:h2:mem:test")
86
    .addArgumentValue("username", "sa") 
87
    .addArgumentValue("password", "")
88
    .addArgumentValue("count", 5);
89

90
// Update to specific tag
91
CommandScope updateToTagCommand = new CommandScope("updateToTag")
92
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
93
    .addArgumentValue("url", "jdbc:h2:mem:test")
94
    .addArgumentValue("username", "sa")
95
    .addArgumentValue("password", "") 
96
    .addArgumentValue("tag", "version-1.0");
97
```
98

99
### Update SQL Commands
100

101
Generate SQL for update operations without executing them:
102

103
```java { .api }
104
// Generate update SQL
105
CommandScope updateSqlCommand = new CommandScope("updateSql")
106
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
107
    .addArgumentValue("url", "jdbc:h2:mem:test")
108
    .addArgumentValue("username", "sa")
109
    .addArgumentValue("password", "");
110

111
// Generate update count SQL  
112
CommandScope updateCountSqlCommand = new CommandScope("updateCountSql")
113
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
114
    .addArgumentValue("url", "jdbc:h2:mem:test")
115
    .addArgumentValue("username", "sa")
116
    .addArgumentValue("password", "")
117
    .addArgumentValue("count", 3);
118

119
// Generate update to tag SQL
120
CommandScope updateToTagSqlCommand = new CommandScope("updateToTagSql")
121
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
122
    .addArgumentValue("url", "jdbc:h2:mem:test")
123
    .addArgumentValue("username", "sa")
124
    .addArgumentValue("password", "")
125
    .addArgumentValue("tag", "version-1.0");
126
```
127

128
### Rollback Commands
129

130
Execute rollback operations:
131

132
```java { .api }
133
// Rollback to tag
134
CommandScope rollbackCommand = new CommandScope("rollback")
135
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
136
    .addArgumentValue("url", "jdbc:h2:mem:test")
137
    .addArgumentValue("username", "sa")
138
    .addArgumentValue("password", "")
139
    .addArgumentValue("tag", "version-1.0");
140

141
// Rollback count
142
CommandScope rollbackCountCommand = new CommandScope("rollbackCount")
143
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
144
    .addArgumentValue("url", "jdbc:h2:mem:test")
145
    .addArgumentValue("username", "sa")
146
    .addArgumentValue("password", "")
147
    .addArgumentValue("count", 2);
148

149
// Rollback to date
150
CommandScope rollbackToDateCommand = new CommandScope("rollbackToDate")
151
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
152
    .addArgumentValue("url", "jdbc:h2:mem:test")
153
    .addArgumentValue("username", "sa")
154
    .addArgumentValue("password", "")
155
    .addArgumentValue("date", "2023-01-01T00:00:00");
156
```
157

158
### Rollback SQL Commands
159

160
Generate SQL for rollback operations:
161

162
```java { .api }
163
// Generate rollback SQL to tag
164
CommandScope rollbackSqlCommand = new CommandScope("rollbackSql")
165
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
166
    .addArgumentValue("url", "jdbc:h2:mem:test")
167
    .addArgumentValue("username", "sa")
168
    .addArgumentValue("password", "")
169
    .addArgumentValue("tag", "version-1.0");
170

171
// Generate rollback count SQL
172
CommandScope rollbackCountSqlCommand = new CommandScope("rollbackCountSql")
173
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
174
    .addArgumentValue("url", "jdbc:h2:mem:test")
175
    .addArgumentValue("username", "sa")
176
    .addArgumentValue("password", "")
177
    .addArgumentValue("count", 2);
178

179
// Generate rollback to date SQL
180
CommandScope rollbackToDateSqlCommand = new CommandScope("rollbackToDateSql")
181
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
182
    .addArgumentValue("url", "jdbc:h2:mem:test")
183
    .addArgumentValue("username", "sa")
184
    .addArgumentValue("password", "")
185
    .addArgumentValue("date", "2023-01-01T00:00:00");
186
```
187

188
### Changelog Commands
189

190
Manage changelog synchronization:
191

192
```java { .api }
193
// Sync changelog
194
CommandScope changelogSyncCommand = new CommandScope("changelogSync")
195
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
196
    .addArgumentValue("url", "jdbc:h2:mem:test")
197
    .addArgumentValue("username", "sa")
198
    .addArgumentValue("password", "");
199

200
// Sync to tag
201
CommandScope changelogSyncToTagCommand = new CommandScope("changelogSyncToTag")
202
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
203
    .addArgumentValue("url", "jdbc:h2:mem:test")
204
    .addArgumentValue("username", "sa")
205
    .addArgumentValue("password", "")
206
    .addArgumentValue("tag", "version-1.0");
207

208
// Generate sync SQL
209
CommandScope changelogSyncSqlCommand = new CommandScope("changelogSyncSql")
210
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
211
    .addArgumentValue("url", "jdbc:h2:mem:test")
212
    .addArgumentValue("username", "sa")
213
    .addArgumentValue("password", "");
214
```
215

216
### Utility Commands
217

218
Various utility and maintenance operations:
219

220
```java { .api }
221
// Show status
222
CommandScope statusCommand = new CommandScope("status")
223
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
224
    .addArgumentValue("url", "jdbc:h2:mem:test")
225
    .addArgumentValue("username", "sa")
226
    .addArgumentValue("password", "")
227
    .addArgumentValue("verbose", true);
228

229
// Validate changelog
230
CommandScope validateCommand = new CommandScope("validate")
231
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
232
    .addArgumentValue("url", "jdbc:h2:mem:test")
233
    .addArgumentValue("username", "sa")
234
    .addArgumentValue("password", "");
235

236
// Clear checksums
237
CommandScope clearChecksumsCommand = new CommandScope("clearChecksums")
238
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
239
    .addArgumentValue("url", "jdbc:h2:mem:test")
240
    .addArgumentValue("username", "sa")
241
    .addArgumentValue("password", "");
242

243
// Calculate checksum
244
CommandScope calculateChecksumCommand = new CommandScope("calculateChecksum")
245
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
246
    .addArgumentValue("url", "jdbc:h2:mem:test")
247
    .addArgumentValue("username", "sa")
248
    .addArgumentValue("password", "")
249
    .addArgumentValue("changesetPath", "db/changelog/changes/001-create-table.xml")
250
    .addArgumentValue("changesetAuthor", "admin")
251
    .addArgumentValue("changesetId", "1");
252

253
// Tag database
254
CommandScope tagCommand = new CommandScope("tag")
255
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
256
    .addArgumentValue("url", "jdbc:h2:mem:test")
257
    .addArgumentValue("username", "sa")
258
    .addArgumentValue("password", "")
259
    .addArgumentValue("tag", "release-1.0");
260

261
// Check tag existence
262
CommandScope tagExistsCommand = new CommandScope("tagExists")
263
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
264
    .addArgumentValue("url", "jdbc:h2:mem:test")
265
    .addArgumentValue("username", "sa")
266
    .addArgumentValue("password", "")
267
    .addArgumentValue("tag", "release-1.0");
268
```
269

270
### Lock Management Commands
271

272
Manage database locks:
273

274
```java { .api }
275
// List locks
276
CommandScope listLocksCommand = new CommandScope("listLocks")
277
    .addArgumentValue("url", "jdbc:h2:mem:test")
278
    .addArgumentValue("username", "sa")
279
    .addArgumentValue("password", "");
280

281
// Release locks
282
CommandScope releaseLocksCommand = new CommandScope("releaseLocks")
283
    .addArgumentValue("url", "jdbc:h2:mem:test")
284
    .addArgumentValue("username", "sa")
285
    .addArgumentValue("password", "");
286
```
287

288
### Documentation Commands
289

290
Generate database documentation:
291

292
```java { .api }
293
// Generate database documentation
294
CommandScope dbDocCommand = new CommandScope("dbDoc")
295
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
296
    .addArgumentValue("url", "jdbc:h2:mem:test")
297
    .addArgumentValue("username", "sa")
298
    .addArgumentValue("password", "")
299
    .addArgumentValue("outputDirectory", "./dbdoc");
300

301
// Generate changelog from database
302
CommandScope generateChangelogCommand = new CommandScope("generateChangelog")
303
    .addArgumentValue("url", "jdbc:h2:mem:test")
304
    .addArgumentValue("username", "sa")
305
    .addArgumentValue("password", "")
306
    .addArgumentValue("changelogFile", "generated-changelog.xml");
307
```
308

309
### Diff Commands
310

311
Compare databases and generate change scripts:
312

313
```java { .api }
314
// Compare databases
315
CommandScope diffCommand = new CommandScope("diff")
316
    .addArgumentValue("referenceUrl", "jdbc:h2:mem:reference")
317
    .addArgumentValue("referenceUsername", "sa")
318
    .addArgumentValue("referencePassword", "")
319
    .addArgumentValue("url", "jdbc:h2:mem:target")
320
    .addArgumentValue("username", "sa")
321
    .addArgumentValue("password", "");
322

323
// Generate diff changelog
324
CommandScope diffChangelogCommand = new CommandScope("diffChangelog")
325
    .addArgumentValue("referenceUrl", "jdbc:h2:mem:reference")
326
    .addArgumentValue("referenceUsername", "sa")
327
    .addArgumentValue("referencePassword", "")
328
    .addArgumentValue("url", "jdbc:h2:mem:target")
329
    .addArgumentValue("username", "sa")
330
    .addArgumentValue("password", "")
331
    .addArgumentValue("changelogFile", "diff-changelog.xml");
332

333
// Snapshot database
334
CommandScope snapshotCommand = new CommandScope("snapshot")
335
    .addArgumentValue("url", "jdbc:h2:mem:test")
336
    .addArgumentValue("username", "sa")
337
    .addArgumentValue("password", "")
338
    .addArgumentValue("snapshotFormat", "json");
339
```
340

341
## Command Results
342

343
The CommandResults object contains the results of command execution:
344

345
```java { .api }
346
// Execute command and get results
347
CommandResults results = updateCommand.execute();
348

349
// Access result data (varies by command)
350
// Results structure depends on specific command executed
351
```
352

353
## Common Arguments
354

355
### Database Connection Arguments
356

357
Standard database connection parameters used across commands:
358

359
```java { .api }
360
.addArgumentValue("url", "jdbc:h2:mem:test")           // Database URL
361
.addArgumentValue("username", "sa")                    // Database username  
362
.addArgumentValue("password", "")                      // Database password
363
.addArgumentValue("driver", "org.h2.Driver")           // JDBC driver class
364
```
365

366
### Changelog Arguments
367

368
Changelog and filtering parameters:
369

370
```java { .api }
371
.addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")  // Changelog file path
372
.addArgumentValue("contexts", "dev,test")              // Execution contexts
373
.addArgumentValue("labelFilter", "feature-1")         // Label expression
374
.addArgumentValue("defaultsFile", "liquibase.properties")  // Properties file
375
```
376

377
### Schema Arguments
378

379
Schema and catalog targeting:
380

381
```java { .api }
382
.addArgumentValue("defaultSchemaName", "public")       // Default schema
383
.addArgumentValue("defaultCatalogName", "mydb")        // Default catalog  
384
.addArgumentValue("liquibaseSchemaName", "liquibase")  // Liquibase schema
385
.addArgumentValue("liquibaseCatalogName", "liquibase") // Liquibase catalog
386
```
387

388
## Example Usage
389

390
### Complete Update Workflow
391

392
```java { .api }
393
import liquibase.command.CommandScope;
394
import liquibase.command.CommandResults;
395

396
try {
397
    // Validate changelog first
398
    CommandScope validateCommand = new CommandScope("validate")
399
        .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
400
        .addArgumentValue("url", "jdbc:postgresql://localhost:5432/mydb")
401
        .addArgumentValue("username", "dbuser")
402
        .addArgumentValue("password", "dbpass");
403
    
404
    validateCommand.execute();
405
    
406
    // Check status
407
    CommandScope statusCommand = new CommandScope("status")
408
        .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
409
        .addArgumentValue("url", "jdbc:postgresql://localhost:5432/mydb")
410
        .addArgumentValue("username", "dbuser")
411
        .addArgumentValue("password", "dbpass")
412
        .addArgumentValue("verbose", true);
413
    
414
    CommandResults statusResults = statusCommand.execute();
415
    
416
    // Execute update
417
    CommandScope updateCommand = new CommandScope("update")
418
        .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
419
        .addArgumentValue("url", "jdbc:postgresql://localhost:5432/mydb")
420
        .addArgumentValue("username", "dbuser")
421
        .addArgumentValue("password", "dbpass")
422
        .addArgumentValue("contexts", "production")
423
        .addArgumentValue("labelFilter", "release-2.0");
424
    
425
    CommandResults updateResults = updateCommand.execute();
426
    
427
    // Tag the release
428
    CommandScope tagCommand = new CommandScope("tag")
429
        .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
430
        .addArgumentValue("url", "jdbc:postgresql://localhost:5432/mydb")
431
        .addArgumentValue("username", "dbuser")
432
        .addArgumentValue("password", "dbpass")
433
        .addArgumentValue("tag", "release-2.0-deployed");
434
    
435
    tagCommand.execute();
436
    
437
} catch (CommandExecutionException e) {
438
    System.err.println("Command execution failed: " + e.getMessage());
439
    throw e;
440
}
441
```
442

443
### Rollback Workflow with SQL Preview
444

445
```java { .api }
446
// First generate rollback SQL for review
447
CommandScope rollbackSqlCommand = new CommandScope("rollbackSql")
448
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
449
    .addArgumentValue("url", "jdbc:postgresql://localhost:5432/mydb")
450
    .addArgumentValue("username", "dbuser")
451
    .addArgumentValue("password", "dbpass")
452
    .addArgumentValue("tag", "release-1.0");
453

454
CommandResults sqlResults = rollbackSqlCommand.execute();
455

456
// After review, execute actual rollback
457
CommandScope rollbackCommand = new CommandScope("rollback")
458
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
459
    .addArgumentValue("url", "jdbc:postgresql://localhost:5432/mydb")
460
    .addArgumentValue("username", "dbuser")
461
    .addArgumentValue("password", "dbpass")
462
    .addArgumentValue("tag", "release-1.0");
463

464
CommandResults rollbackResults = rollbackCommand.execute();
465
```
466

467
### Database Comparison
468

469
```java { .api }
470
// Compare two databases
471
CommandScope diffCommand = new CommandScope("diff")
472
    .addArgumentValue("referenceUrl", "jdbc:postgresql://prod:5432/mydb")
473
    .addArgumentValue("referenceUsername", "readonly")
474
    .addArgumentValue("referencePassword", "password")
475
    .addArgumentValue("url", "jdbc:postgresql://staging:5432/mydb")
476
    .addArgumentValue("username", "readonly")
477
    .addArgumentValue("password", "password");
478

479
CommandResults diffResults = diffCommand.execute();
480

481
// Generate changelog for differences
482
CommandScope diffChangelogCommand = new CommandScope("diffChangelog")
483
    .addArgumentValue("referenceUrl", "jdbc:postgresql://prod:5432/mydb")
484
    .addArgumentValue("referenceUsername", "readonly")
485
    .addArgumentValue("referencePassword", "password")
486
    .addArgumentValue("url", "jdbc:postgresql://staging:5432/mydb")
487
    .addArgumentValue("username", "readonly")
488
    .addArgumentValue("password", "password")
489
    .addArgumentValue("changelogFile", "sync-staging-to-prod.xml");
490

491
CommandResults changelogResults = diffChangelogCommand.execute();
492
```