0
# Configuration Management
1

2
Comprehensive configuration system providing fluent API for customizing all aspects of Flyway's migration behavior, from database connections to migration discovery and execution patterns.
3

4
## Capabilities
5

6
### Fluent Configuration
7

8
Builder pattern interface for constructing Flyway configurations with method chaining and type safety.
9

10
```java { .api }
11
/**
12
 * Fluent configuration that can be customized and used to create a Flyway instance
13
 */
14
public class FluentConfiguration {
15
    /** Create Flyway instance from this configuration */
16
    public Flyway load();
17
    
18
    /** Configure the ClassLoader to use for loading migrations and JDBC drivers */
19
    public FluentConfiguration classLoader(ClassLoader classLoader);
20
}
21
```
22

23
### Database Configuration
24

25
Configure database connections and schema management settings.
26

27
```java { .api }
28
public class FluentConfiguration {
29
    /** Configure database connection using URL, username and password */
30
    public FluentConfiguration dataSource(String url, String user, String password);
31
    
32
    /** Configure database connection using existing DataSource */
33
    public FluentConfiguration dataSource(DataSource dataSource);
34
    
35
    /** Configure database connection using JDBC driver and properties */
36
    public FluentConfiguration driver(String driver);
37
    public FluentConfiguration url(String url);
38
    public FluentConfiguration user(String user);
39
    public FluentConfiguration password(String password);
40
    
41
    /** Set the schemas managed by Flyway */
42
    public FluentConfiguration schemas(String... schemas);
43
    
44
    /** Set the default schema containing the schema history table */
45
    public FluentConfiguration defaultSchema(String defaultSchema);
46
    
47
    /** Set the name of the schema history table */
48
    public FluentConfiguration table(String table);
49
}
50
```
51

52
**Usage Examples:**
53

54
```java
55
// Basic database configuration
56
Flyway flyway = Flyway.configure()
57
    .dataSource("jdbc:postgresql://localhost:5432/mydb", "user", "password")
58
    .schemas("public", "migration_schema")
59
    .load();
60

61
// Using existing DataSource
62
DataSource dataSource = getApplicationDataSource();
63
Flyway flyway = Flyway.configure()
64
    .dataSource(dataSource)
65
    .defaultSchema("public")
66
    .table("flyway_schema_history")
67
    .load();
68

69
// Multiple database support
70
Flyway flyway = Flyway.configure()
71
    .driver("org.postgresql.Driver")
72
    .url("jdbc:postgresql://localhost:5432/mydb")
73
    .user("flyway_user")
74
    .password("flyway_pass")
75
    .schemas("schema1", "schema2", "schema3")
76
    .load();
77
```
78

79
### Migration Discovery
80

81
Configure how Flyway discovers and processes migration files and Java migrations.
82

83
```java { .api }
84
public class FluentConfiguration {
85
    /** Set the locations to scan for migrations */
86
    public FluentConfiguration locations(String... locations);
87
    public FluentConfiguration locations(Location... locations);
88
    
89
    /** Set the character encoding of SQL migration files */
90
    public FluentConfiguration encoding(Charset encoding);
91
    public FluentConfiguration encoding(String encoding);
92
    
93
    /** Set the file name prefix for SQL migrations */
94
    public FluentConfiguration sqlMigrationPrefix(String sqlMigrationPrefix);
95
    
96
    /** Set the file name suffix for SQL migrations */
97
    public FluentConfiguration sqlMigrationSuffix(String sqlMigrationSuffix);
98
    
99
    /** Set the file name suffixes for SQL migrations */
100
    public FluentConfiguration sqlMigrationSuffixes(String... sqlMigrationSuffixes);
101
    
102
    /** Set the file name separator for SQL migrations */
103
    public FluentConfiguration sqlMigrationSeparator(String sqlMigrationSeparator);
104
    
105
    /** Set the file name prefix for repeatable SQL migrations */
106
    public FluentConfiguration repeatableSqlMigrationPrefix(String repeatableSqlMigrationPrefix);
107
}
108
```
109

110
**Usage Examples:**
111

112
```java
113
// Migration file discovery
114
Flyway flyway = Flyway.configure()
115
    .dataSource(dataSource)
116
    .locations("classpath:db/migration", "filesystem:/path/to/migrations")
117
    .sqlMigrationPrefix("V")
118
    .sqlMigrationSeparator("__")
119
    .sqlMigrationSuffixes(".sql", ".SQL")
120
    .encoding("UTF-8")
121
    .load();
122

123
// Custom migration patterns
124
Flyway flyway = Flyway.configure()
125
    .dataSource(dataSource)
126
    .locations("classpath:db/migration", "classpath:db/special")
127
    .sqlMigrationPrefix("Migration_")
128
    .repeatableSqlMigrationPrefix("R__")
129
    .encoding(StandardCharsets.UTF_8)
130
    .load();
131
```
132

133
### Version and Baseline Configuration
134

135
Configure version management, baseline settings, and migration targeting.
136

137
```java { .api }
138
public class FluentConfiguration {
139
    /** Set the target version up to which Flyway should consider migrations */
140
    public FluentConfiguration target(MigrationVersion target);
141
    public FluentConfiguration target(String target);
142
    
143
    /** Set the version to tag an existing schema with when executing baseline */
144
    public FluentConfiguration baselineVersion(MigrationVersion baselineVersion);
145
    public FluentConfiguration baselineVersion(String baselineVersion);
146
    
147
    /** Set the description to tag an existing schema with when executing baseline */
148
    public FluentConfiguration baselineDescription(String baselineDescription);
149
    
150
    /** Whether to automatically call baseline when migrate is executed against a non-empty schema */
151
    public FluentConfiguration baselineOnMigrate(boolean baselineOnMigrate);
152
    
153
    /** Whether to allow mixing transactional and non-transactional statements within the same migration */
154
    public FluentConfiguration mixed(boolean mixed);
155
    
156
    /** Whether to group all pending migrations together in the same transaction when possible */
157
    public FluentConfiguration group(boolean group);
158
}
159
```
160

161
**Usage Examples:**
162

163
```java
164
// Version targeting
165
Flyway flyway = Flyway.configure()
166
    .dataSource(dataSource)
167
    .target(MigrationVersion.fromVersion("2.5"))
168
    .baselineVersion("1.0")
169
    .baselineDescription("Initial baseline")
170
    .baselineOnMigrate(true)
171
    .load();
172

173
// Transaction management
174
Flyway flyway = Flyway.configure()
175
    .dataSource(dataSource)
176
    .mixed(true)  // Allow mixed DDL/DML
177
    .group(false) // Execute each migration in separate transaction
178
    .load();
179
```
180

181
### Validation and Error Handling
182

183
Configure migration validation behavior and error handling strategies.
184

185
```java { .api }
186
public class FluentConfiguration {
187
    /** Whether to automatically call validate when running migrate */
188
    public FluentConfiguration validateOnMigrate(boolean validateOnMigrate);
189
    
190
    /** Whether to allow out of order migrations */
191
    public FluentConfiguration outOfOrder(boolean outOfOrder);
192
    
193
    /** Whether to skip executing migrations */
194
    public FluentConfiguration skipExecutingMigrations(boolean skipExecutingMigrations);
195
    
196
    /** Whether to ignore missing migrations when validating */
197
    public FluentConfiguration ignoreMissingMigrations(boolean ignoreMissingMigrations);
198
    
199
    /** Whether to ignore ignored migrations when validating */
200
    public FluentConfiguration ignoreIgnoredMigrations(boolean ignoreIgnoredMigrations);
201
    
202
    /** Whether to ignore pending migrations when validating */
203
    public FluentConfiguration ignorePendingMigrations(boolean ignorePendingMigrations);
204
    
205
    /** Whether to ignore future migrations when validating */
206
    public FluentConfiguration ignoreFutureMigrations(boolean ignoreFutureMigrations);
207
    
208
    /** Ignore migrations that match these patterns during validation */
209
    public FluentConfiguration ignoreMigrationPatterns(ValidatePattern... ignoreMigrationPatterns);
210
    public FluentConfiguration ignoreMigrationPatterns(String... ignoreMigrationPatterns);
211
}
212
```
213

214
**Usage Examples:**
215

216
```java
217
// Validation configuration
218
Flyway flyway = Flyway.configure()
219
    .dataSource(dataSource)
220
    .validateOnMigrate(true)
221
    .outOfOrder(false)
222
    .ignoreMissingMigrations(false)
223
    .ignoreFutureMigrations(true)
224
    .ignoreMigrationPatterns("*:missing", "*:future")
225
    .load();
226

227
// Development mode settings
228
Flyway flyway = Flyway.configure()
229
    .dataSource(dataSource)
230
    .outOfOrder(true)
231
    .skipExecutingMigrations(false)
232
    .ignorePendingMigrations(true)
233
    .load();
234
```
235

236
### Schema Management
237

238
Configure schema creation and management behavior.
239

240
```java { .api }
241
public class FluentConfiguration {
242
    /** Whether Flyway should attempt to create the schemas specified in the schemas property */
243
    public FluentConfiguration createSchemas(boolean createSchemas);
244
    
245
    /** Whether to disable clean */
246
    public FluentConfiguration cleanDisabled(boolean cleanDisabled);
247
    
248
    /** Whether to disable the removal of empty schema during clean */
249
    public FluentConfiguration cleanOnValidationError(boolean cleanOnValidationError);
250
}
251
```
252

253
**Usage Examples:**
254

255
```java
256
// Schema management
257
Flyway flyway = Flyway.configure()
258
    .dataSource(dataSource)
259
    .schemas("app_schema", "audit_schema")
260
    .createSchemas(true)
261
    .cleanDisabled(false)  // Enable clean for testing
262
    .load();
263
```
264

265
### Callback and Extension Configuration
266

267
Configure lifecycle callbacks and plugin extensions.
268

269
```java { .api }
270
public class FluentConfiguration {
271
    /** Set the callbacks for lifecycle notifications */
272
    public FluentConfiguration callbacks(Callback... callbacks);
273
    public FluentConfiguration callbacks(String... callbacks);
274
    
275
    /** Set the custom MigrationResolvers to be used in addition to the built-in ones */
276
    public FluentConfiguration resolvers(MigrationResolver... resolvers);
277
    public FluentConfiguration resolvers(String... resolvers);
278
    
279
    /** Set the custom ResourceProviders to be used */
280
    public FluentConfiguration resourceProvider(ResourceProvider resourceProvider);
281
    
282
    /** Set the custom ClassProviders to be used */
283
    public FluentConfiguration classProvider(ClassProvider classProvider);
284
}
285
```
286

287
**Usage Examples:**
288

289
```java
290
// Callback configuration
291
Flyway flyway = Flyway.configure()
292
    .dataSource(dataSource)
293
    .callbacks(new MyCustomCallback(), new AuditCallback())
294
    .resolvers(new CustomMigrationResolver())
295
    .resourceProvider(new S3ResourceProvider())
296
    .load();
297

298
// String-based configuration
299
Flyway flyway = Flyway.configure()
300
    .dataSource(dataSource)
301
    .callbacks("com.example.MyCallback", "com.example.AuditCallback")
302
    .resolvers("com.example.CustomResolver")
303
    .load();
304
```
305

306
## Configuration Interface
307

308
Read-only access to configuration values for use in migrations and callbacks.
309

310
```java { .api }
311
public interface Configuration {
312
    /** Get the ClassLoader to use for loading migrations and JDBC drivers */
313
    ClassLoader getClassLoader();
314
    
315
    /** Get the JDBC DataSource */
316
    DataSource getDataSource();
317
    
318
    /** Get the maximum number of retries when attempting to connect to the database */
319
    int getConnectRetries();
320
    
321
    /** Get the maximum time between retries when attempting to connect to the database in seconds */
322
    int getConnectRetriesInterval();
323
    
324
    /** Get the SQL statements to run to initialize a new database connection immediately after opening it */
325
    String getInitSql();
326
    
327
    /** Get the schemas managed by Flyway */
328
    String[] getSchemas();
329
    
330
    /** Get the name of the schema history table */
331
    String getTable();
332
    
333
    /** Get the target version up to which Flyway should consider migrations */
334
    MigrationVersion getTarget();
335
    
336
    /** Get the locations to scan recursively for migrations */
337
    Location[] getLocations();
338
    
339
    /** Get the encoding of SQL migration files */
340
    Charset getEncoding();
341
    
342
    /** Get the callbacks for lifecycle notifications */
343
    Callback[] getCallbacks();
344
    
345
    /** Get whether Flyway should attempt to create the schemas specified in the schemas property */
346
    boolean isCreateSchemas();
347
    
348
    /** Get whether to automatically call baseline when migrate is executed against a non-empty schema */
349
    boolean isBaselineOnMigrate();
350
    
351
    /** Get whether to automatically call validate when running migrate */
352
    boolean isValidateOnMigrate();
353
    
354
    /** Get whether clean is disabled */
355
    boolean isCleanDisabled();
356
}
357
```
358

359
**Usage Examples:**
360

361
```java
362
// In a callback or migration
363
public class MyCallback extends BaseCallback {
364
    @Override
365
    public void handle(Event event, Context context) {
366
        Configuration config = context.getConfiguration();
367
        String[] schemas = config.getSchemas();
368
        boolean createSchemas = config.isCreateSchemas();
369
        
370
        System.out.println("Managing schemas: " + Arrays.toString(schemas));
371
        System.out.println("Auto-create enabled: " + createSchemas);
372
    }
373
}
374

375
// In a Java migration
376
public class V2__CustomMigration extends BaseJavaMigration {
377
    @Override
378
    public void migrate(Context context) throws Exception {
379
        Configuration config = context.getConfiguration();
380
        Location[] locations = config.getLocations();
381
        
382
        // Use configuration information in migration logic
383
        if (locations.length > 1) {
384
            // Handle multiple location scenario
385
        }
386
    }
387
}
388
```
389

390
## Configuration Extensions
391

392
Plugin system for extending configuration with custom properties.
393

394
```java { .api }
395
public interface ConfigurationExtension {
396
    /** The namespace for this configuration extension */
397
    String getNamespace();
398
    
399
    /** Configuration properties specific to this extension */
400
    Map<String, String> getConfiguration();
401
}
402

403
// Access extensions via Configuration
404
public interface Configuration {
405
    /** Get plugin register for accessing extensions */
406
    PluginRegister getPluginRegister();
407
}
408
```
409

410
**Usage Examples:**
411

412
```java
413
// Custom configuration extension
414
public class MyConfigExtension implements ConfigurationExtension {
415
    @Override
416
    public String getNamespace() {
417
        return "mycompany";
418
    }
419
    
420
    @Override
421
    public Map<String, String> getConfiguration() {
422
        Map<String, String> config = new HashMap<>();
423
        config.put("customProperty", "customValue");
424
        return config;
425
    }
426
}
427

428
// Access in Flyway
429
Flyway flyway = Flyway.configure()
430
    .dataSource(dataSource)
431
    .load();
432

433
MyConfigExtension ext = flyway.getConfigurationExtension(MyConfigExtension.class);
434
String customValue = ext.getConfiguration().get("customProperty");
435
```