0
# Configuration System
1

2
This document covers Liquibase's global configuration system through the GlobalConfiguration class, which manages settings that affect Liquibase behavior across all operations.
3

4
## Imports
5

6
```java { .api }
7
import liquibase.GlobalConfiguration;
8
import liquibase.configuration.ConfigurationDefinition;
9

10
// Enums for configuration values
11
import liquibase.GlobalConfiguration.DuplicateFileMode;
12
```
13

14
## GlobalConfiguration Class
15

16
The GlobalConfiguration class provides access to global configuration properties that control Liquibase behavior.
17

18
### Instance Access
19

20
```java { .api }
21
/**
22
 * Get the singleton GlobalConfiguration instance
23
 * @return GlobalConfiguration instance
24
 */
25
public static GlobalConfiguration getInstance()
26
```
27

28
## Database Table Configuration
29

30
Configuration for Liquibase tracking tables:
31

32
```java { .api }
33
/**
34
 * Name of the database changelog table (default: "DATABASECHANGELOG")
35
 */
36
public static final ConfigurationDefinition<String> DATABASECHANGELOG_TABLE_NAME;
37

38
/**
39
 * Name of the database changelog lock table (default: "DATABASECHANGELOGLOCK") 
40
 */
41
public static final ConfigurationDefinition<String> DATABASECHANGELOGLOCK_TABLE_NAME;
42
```
43

44
### Example Usage
45

46
```java { .api }
47
// Get current table names
48
String changelogTable = GlobalConfiguration.DATABASECHANGELOG_TABLE_NAME.getCurrentValue();
49
String lockTable = GlobalConfiguration.DATABASECHANGELOGLOCK_TABLE_NAME.getCurrentValue();
50

51
// Set custom table names
52
System.setProperty("liquibase.databaseChangeLogTableName", "MY_CHANGELOG");
53
System.setProperty("liquibase.databaseChangeLogLockTableName", "MY_CHANGELOG_LOCK");
54
```
55

56
## Database Schema and Catalog Configuration
57

58
Configuration for database schema and catalog placement:
59

60
```java { .api }
61
/**
62
 * Catalog name for Liquibase objects
63
 */
64
public static final ConfigurationProperty<String> LIQUIBASE_CATALOG_NAME;
65

66
/**
67
 * Schema name for Liquibase objects
68
 */
69
public static final ConfigurationProperty<String> LIQUIBASE_SCHEMA_NAME;
70

71
/**
72
 * Tablespace name for Liquibase objects
73
 */
74
public static final ConfigurationProperty<String> LIQUIBASE_TABLESPACE_NAME;
75
```
76

77
### Example Usage
78

79
```java { .api }
80
// Configure Liquibase to use specific schema
81
System.setProperty("liquibase.liquibaseSchemaName", "LIQUIBASE_SCHEMA");
82
System.setProperty("liquibase.liquibaseCatalogName", "LIQUIBASE_CATALOG");
83
System.setProperty("liquibase.liquibaseTablespaceName", "LIQUIBASE_TBS");
84
```
85

86
## File Handling Configuration
87

88
Configuration for file encoding and path handling:
89

90
```java { .api }
91
/**
92
 * File encoding for reading changelog files (default: UTF-8)
93
 */
94
public static final ConfigurationProperty<String> FILE_ENCODING;
95

96
/**
97
 * File encoding for output files
98
 */
99
public static final ConfigurationProperty<String> OUTPUT_FILE_ENCODING;
100

101
/**
102
 * Line separator for output files
103
 */
104
public static final ConfigurationProperty<String> OUTPUT_LINE_SEPARATOR;
105

106
/**
107
 * Search path for changelog files
108
 */
109
public static final ConfigurationProperty<String> SEARCH_PATH;
110
```
111

112
### Example Usage
113

114
```java { .api }
115
// Set file encoding
116
System.setProperty("liquibase.fileEncoding", "ISO-8859-1");
117
System.setProperty("liquibase.outputFileEncoding", "UTF-16");
118

119
// Configure search paths
120
System.setProperty("liquibase.searchPath", "db/changelog,db/scripts,classpath:");
121

122
// Set line separator
123
System.setProperty("liquibase.outputLineSeparator", "\r\n");
124
```
125

126
## Database Locking Configuration
127

128
Configuration for database lock behavior:
129

130
```java { .api }
131
/**
132
 * Lock wait time in minutes (default: 5)
133
 */
134
public static final ConfigurationProperty<Long> CHANGELOGLOCK_WAIT_TIME;
135

136
/**
137
 * Lock poll rate in seconds (default: 10)
138
 */
139
public static final ConfigurationProperty<Long> CHANGELOGLOCK_POLL_RATE;
140
```
141

142
### Example Usage
143

144
```java { .api }
145
// Configure lock timeouts
146
System.setProperty("liquibase.changelogLockWaitTimeInMinutes", "10");
147
System.setProperty("liquibase.changelogLockPollRate", "5");
148
```
149

150
## Behavior Control Configuration
151

152
Configuration for general Liquibase behavior:
153

154
```java { .api }
155
/**
156
 * Convert data types to standard types (default: true)
157
 */
158
public static final ConfigurationProperty<Boolean> CONVERT_DATA_TYPES;
159

160
/**
161
 * Enable strict mode for best practices (default: false)
162
 */
163
public static final ConfigurationProperty<Boolean> STRICT;
164

165
/**
166
 * Force headless mode (default: false)
167
 */
168
public static final ConfigurationProperty<Boolean> HEADLESS;
169

170
/**
171
 * Show startup banner (default: true)
172
 */
173
public static final ConfigurationProperty<Boolean> SHOW_BANNER;
174

175
/**
176
 * Validate XML changelog files against XSD (default: true)
177
 */
178
public static final ConfigurationProperty<Boolean> VALIDATE_XML_CHANGELOG_FILES;
179
```
180

181
### Example Usage
182

183
```java { .api }
184
// Enable strict mode
185
System.setProperty("liquibase.strict", "true");
186

187
// Disable banner
188
System.setProperty("liquibase.showBanner", "false");
189

190
// Force headless mode
191
System.setProperty("liquibase.headless", "true");
192

193
// Disable XML validation
194
System.setProperty("liquibase.validateXmlChangelogFiles", "false");
195

196
// Disable data type conversion
197
System.setProperty("liquibase.convertDataTypes", "false");
198
```
199

200
## Diff and Generation Configuration
201

202
Configuration for diff operations and changelog generation:
203

204
```java { .api }
205
/**
206
 * Compare column order in diff operations (default: true)
207
 */
208
public static final ConfigurationProperty<Boolean> DIFF_COLUMN_ORDER;
209

210
/**
211
 * Include created timestamps in generated changesets (default: false)
212
 */
213
public static final ConfigurationProperty<Boolean> GENERATE_CHANGESET_CREATED_VALUES;
214

215
/**
216
 * Snapshot data by default in diff operations (default: false)
217
 */
218
public static final ConfigurationProperty<Boolean> SHOULD_SNAPSHOT_DATA;
219
```
220

221
### Example Usage
222

223
```java { .api }
224
// Configure diff options
225
System.setProperty("liquibase.diffColumnOrder", "false");
226
System.setProperty("liquibase.generateChangesetCreatedValues", "true");
227
System.setProperty("liquibase.shouldSnapshotData", "true");
228
```
229

230
## Configuration Property Access
231

232
### Direct Property Access
233

234
```java { .api }
235
// Get current value of a configuration property
236
String currentValue = GlobalConfiguration.DATABASECHANGELOG_TABLE_NAME.getCurrentValue();
237

238
// Check if property has been explicitly set
239
boolean wasSet = GlobalConfiguration.STRICT.getWasOverridden();
240

241
// Get default value
242
Boolean defaultValue = GlobalConfiguration.STRICT.getDefaultValue();
243
```
244

245
### System Property Configuration
246

247
Most configuration can be set via system properties using the pattern `liquibase.{propertyName}`:
248

249
```java { .api }
250
// Set via system properties
251
System.setProperty("liquibase.databaseChangeLogTableName", "CUSTOM_CHANGELOG");
252
System.setProperty("liquibase.strict", "true");
253
System.setProperty("liquibase.fileEncoding", "UTF-8");
254

255
// Set via environment variables (convert to uppercase and replace dots with underscores)
256
// LIQUIBASE_DATABASE_CHANGE_LOG_TABLE_NAME=CUSTOM_CHANGELOG
257
// LIQUIBASE_STRICT=true
258
```
259

260
## Configuration Enums
261

262
### DuplicateFileMode
263

264
Controls behavior when duplicate files are detected:
265

266
```java { .api }
267
public enum DuplicateFileMode {
268
    WARN,    // Log warning (default)
269
    ERROR,   // Throw error  
270
    INFO,    // Log info message
271
    DEBUG,   // Log debug message
272
    SILENT   // No logging
273
}
274
```
275

276
### UpdateSummaryEnum
277

278
Controls update summary display:
279

280
```java { .api }
281
// Values depend on implementation
282
// Used for controlling summary output format
283
```
284

285
### UpdateSummaryOutputEnum
286

287
Controls update summary output format:
288

289
```java { .api }
290
// Values depend on implementation  
291
// Used for controlling where summary is written
292
```
293

294
## Complete Configuration Example
295

296
### Production Configuration
297

298
```java { .api }
299
import liquibase.GlobalConfiguration;
300

301
public class ProductionLiquibaseConfig {
302
    
303
    public static void configureForProduction() {
304
        // Use custom schema for Liquibase tables
305
        System.setProperty("liquibase.liquibaseSchemaName", "LIQUIBASE");
306
        System.setProperty("liquibase.liquibaseCatalogName", "PROD_DB");
307
        
308
        // Configure table names
309
        System.setProperty("liquibase.databaseChangeLogTableName", "DB_CHANGELOG");
310
        System.setProperty("liquibase.databaseChangeLogLockTableName", "DB_CHANGELOG_LOCK");
311
        
312
        // Production behavior settings
313
        System.setProperty("liquibase.strict", "true");
314
        System.setProperty("liquibase.showBanner", "false");
315
        System.setProperty("liquibase.headless", "true");
316
        
317
        // Lock configuration for production
318
        System.setProperty("liquibase.changelogLockWaitTimeInMinutes", "15");
319
        System.setProperty("liquibase.changelogLockPollRate", "30");
320
        
321
        // File handling
322
        System.setProperty("liquibase.fileEncoding", "UTF-8");
323
        System.setProperty("liquibase.outputFileEncoding", "UTF-8");
324
        
325
        // Validation settings
326
        System.setProperty("liquibase.validateXmlChangelogFiles", "true");
327
        
328
        // Diff settings for production comparisons
329
        System.setProperty("liquibase.diffColumnOrder", "true");
330
        System.setProperty("liquibase.generateChangesetCreatedValues", "false");
331
    }
332
    
333
    public static void verifyConfiguration() {
334
        GlobalConfiguration config = GlobalConfiguration.getInstance();
335
        
336
        System.out.println("Changelog Table: " + 
337
            GlobalConfiguration.DATABASECHANGELOG_TABLE_NAME.getCurrentValue());
338
        System.out.println("Schema: " + 
339
            GlobalConfiguration.LIQUIBASE_SCHEMA_NAME.getCurrentValue());
340
        System.out.println("Strict Mode: " + 
341
            GlobalConfiguration.STRICT.getCurrentValue());
342
    }
343
}
344
```
345

346
### Development Configuration
347

348
```java { .api }
349
public class DevelopmentLiquibaseConfig {
350
    
351
    public static void configureForDevelopment() {
352
        // Development-friendly settings
353
        System.setProperty("liquibase.strict", "false");
354
        System.setProperty("liquibase.showBanner", "true");
355
        
356
        // Shorter timeouts for development
357
        System.setProperty("liquibase.changelogLockWaitTimeInMinutes", "2");
358
        System.setProperty("liquibase.changelogLockPollRate", "5");
359
        
360
        // Include creation timestamps in generated changesets
361
        System.setProperty("liquibase.generateChangesetCreatedValues", "true");
362
        
363
        // Snapshot data for easier development comparisons
364
        System.setProperty("liquibase.shouldSnapshotData", "true");
365
        
366
        // Flexible search path for development
367
        System.setProperty("liquibase.searchPath", 
368
            "src/main/resources/db,src/test/resources/db,classpath:");
369
    }
370
}
371
```
372

373
### Configuration from Properties File
374

375
```java { .api }
376
import java.io.FileInputStream;
377
import java.io.IOException;
378
import java.util.Properties;
379

380
public class PropertiesBasedConfig {
381
    
382
    public static void loadFromFile(String propertiesFile) throws IOException {
383
        Properties props = new Properties();
384
        props.load(new FileInputStream(propertiesFile));
385
        
386
        // Apply all properties that start with "liquibase."
387
        for (String key : props.stringPropertyNames()) {
388
            if (key.startsWith("liquibase.")) {
389
                System.setProperty(key, props.getProperty(key));
390
            }
391
        }
392
    }
393
}
394

395
// Example liquibase.properties file:
396
// liquibase.databaseChangeLogTableName=MY_CHANGELOG
397
// liquibase.liquibaseSchemaName=LIQUIBASE_SCHEMA
398
// liquibase.strict=true
399
// liquibase.fileEncoding=UTF-8
400
// liquibase.changelogLockWaitTimeInMinutes=10
401
```
402

403
### Environment-Specific Configuration
404

405
```java { .api }
406
public class EnvironmentConfig {
407
    
408
    public static void configureForEnvironment(String environment) {
409
        switch (environment.toLowerCase()) {
410
            case "production":
411
                configureProduction();
412
                break;
413
            case "staging": 
414
                configureStaging();
415
                break;
416
            case "development":
417
                configureDevelopment();
418
                break;
419
            default:
420
                throw new IllegalArgumentException("Unknown environment: " + environment);
421
        }
422
    }
423
    
424
    private static void configureProduction() {
425
        System.setProperty("liquibase.strict", "true");
426
        System.setProperty("liquibase.showBanner", "false");
427
        System.setProperty("liquibase.changelogLockWaitTimeInMinutes", "30");
428
    }
429
    
430
    private static void configureStaging() {
431
        System.setProperty("liquibase.strict", "true");
432
        System.setProperty("liquibase.showBanner", "false");
433
        System.setProperty("liquibase.changelogLockWaitTimeInMinutes", "10");
434
        System.setProperty("liquibase.generateChangesetCreatedValues", "true");
435
    }
436
    
437
    private static void configureDevelopment() {
438
        System.setProperty("liquibase.strict", "false");
439
        System.setProperty("liquibase.showBanner", "true");
440
        System.setProperty("liquibase.changelogLockWaitTimeInMinutes", "2");
441
        System.setProperty("liquibase.shouldSnapshotData", "true");
442
    }
443
}
444
```