0
# Flyway
1

2
Flyway is a database migration tool that provides reliable database schema evolution through versioned SQL scripts and Java migrations. It enables developers to manage database changes across all environments using simple SQL files or programmatic Java migrations, with automatic discovery and execution order management.
3

4
## Package Information
5

6
- **Package Name**: flyway-core
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `<dependency><groupId>org.flywaydb</groupId><artifactId>flyway-core</artifactId><version>11.12.0</version></dependency>`
10

11
## Core Imports
12

13
```java
14
import org.flywaydb.core.Flyway;
15
import org.flywaydb.core.api.configuration.FluentConfiguration;
16
import org.flywaydb.core.api.output.MigrateResult;
17
```
18

19
For dependency injection frameworks:
20

21
```java
22
import org.flywaydb.core.api.configuration.Configuration;
23
import org.flywaydb.core.api.MigrationInfoService;
24
```
25

26
## Basic Usage
27

28
```java
29
import org.flywaydb.core.Flyway;
30

31
// Configure and execute migrations
32
Flyway flyway = Flyway.configure()
33
    .dataSource("jdbc:h2:mem:testdb", "sa", "")
34
    .locations("classpath:db/migration")
35
    .load();
36

37
// Execute migrations
38
flyway.migrate();
39

40
// Get migration information
41
flyway.info().all();
42
```
43

44
For existing applications:
45

46
```java
47
import org.flywaydb.core.Flyway;
48
import javax.sql.DataSource;
49

50
// Use existing DataSource
51
DataSource dataSource = getDataSource();
52
Flyway flyway = Flyway.configure()
53
    .dataSource(dataSource)
54
    .schemas("myschema")
55
    .baselineOnMigrate(true)
56
    .load();
57

58
flyway.migrate();
59
```
60

61
## Architecture
62

63
Flyway is built around several key components:
64

65
- **Core Migration Engine**: Central `Flyway` class that orchestrates all database operations
66
- **Fluent Configuration**: Type-safe configuration builder with extensive customization options
67
- **Migration Resolution**: Automatic discovery and ordering of SQL files and Java migrations
68
- **Schema History**: Tracking table that maintains applied migrations and their metadata
69
- **Callback System**: Extensible lifecycle hooks for custom logic at every migration phase
70
- **Database Abstraction**: Support for 50+ database types through pluggable database implementations
71

72
## Capabilities
73

74
### Core Migration Operations
75

76
Primary database migration operations for schema evolution, validation, and maintenance.
77

78
```java { .api }
79
public class Flyway {
80
    public static FluentConfiguration configure();
81
    public static FluentConfiguration configure(ClassLoader classLoader);
82
    
83
    public MigrateResult migrate() throws FlywayException;
84
    public void validate() throws FlywayException;
85
    public ValidateResult validateWithResult() throws FlywayException;
86
    public CleanResult clean();
87
    public BaselineResult baseline() throws FlywayException;
88
    public RepairResult repair() throws FlywayException;
89
    public MigrationInfoService info();
90
    public OperationResult undo() throws FlywayException;
91
    
92
    public Configuration getConfiguration();
93
    public <T extends ConfigurationExtension> T getConfigurationExtension(Class<T> configClass);
94
}
95
```
96

97
[Core Operations](./core-operations.md)
98

99
### Configuration Management
100

101
Comprehensive configuration system for customizing migration behavior across all aspects of database operations.
102

103
```java { .api }
104
public class FluentConfiguration {
105
    public FluentConfiguration dataSource(String url, String user, String password);
106
    public FluentConfiguration dataSource(DataSource dataSource);
107
    public FluentConfiguration locations(String... locations);
108
    public FluentConfiguration schemas(String... schemas);
109
    public FluentConfiguration baselineVersion(MigrationVersion baselineVersion);
110
    public FluentConfiguration baselineOnMigrate(boolean baselineOnMigrate);
111
    public FluentConfiguration target(MigrationVersion target);
112
    public FluentConfiguration target(String target);
113
    public FluentConfiguration validateOnMigrate(boolean validateOnMigrate);
114
    public FluentConfiguration cleanDisabled(boolean cleanDisabled);
115
    public FluentConfiguration outOfOrder(boolean outOfOrder);
116
    public Flyway load();
117
}
118

119
public interface Configuration {
120
    public DataSource getDataSource();
121
    public Location[] getLocations();
122
    public String[] getSchemas();
123
    public MigrationVersion getBaselineVersion();
124
}
125
```
126

127
[Configuration](./configuration.md)
128

129
### Java Migration Development
130

131
Framework for creating programmatic migrations with full access to database connections and configuration.
132

133
```java { .api }
134
public interface JavaMigration {
135
    public MigrationVersion getVersion();
136
    public String getDescription();
137
    public void migrate(Context context) throws Exception;
138
}
139

140
public abstract class BaseJavaMigration implements JavaMigration {
141
    public final MigrationVersion getVersion();
142
    public Integer getChecksum();
143
    public boolean canExecuteInTransaction();
144
}
145

146
public interface Context {
147
    public Configuration getConfiguration();
148
    public Connection getConnection();
149
}
150
```
151

152
[Java Migrations](./java-migrations.md)
153

154
### Callback System
155

156
Extensible lifecycle hooks enabling custom logic execution at any point during migration operations.
157

158
```java { .api }
159
public interface Callback {
160
    boolean supports(Event event, Context context);
161
    void handle(Event event, Context context);
162
}
163

164
public abstract class BaseCallback implements Callback {
165
    public boolean supports(Event event, Context context);
166
}
167

168
public enum Event {
169
    BEFORE_MIGRATE, AFTER_MIGRATE, BEFORE_EACH_MIGRATE, AFTER_EACH_MIGRATE,
170
    BEFORE_CLEAN, AFTER_CLEAN, BEFORE_VALIDATE, AFTER_VALIDATE,
171
    BEFORE_BASELINE, AFTER_BASELINE, BEFORE_REPAIR, AFTER_REPAIR
172
}
173
```
174

175
[Callbacks](./callbacks.md)
176

177
### Migration Information and Results
178

179
Comprehensive result objects and migration metadata providing detailed feedback on all operations.
180

181
```java { .api }
182
public interface MigrationInfoService {
183
    MigrationInfo[] all();
184
    MigrationInfo current();
185
    MigrationInfo[] pending();
186
    MigrationInfo[] applied();
187
}
188

189
public interface MigrationInfo {
190
    MigrationVersion getVersion();
191
    String getDescription();
192
    MigrationState getState();
193
    Date getInstalledOn();
194
    Integer getExecutionTime();
195
}
196
```
197

198
[Migration Information](./migration-info.md)
199

200
### Exception Handling
201

202
Comprehensive exception hierarchy for handling migration failures and validation errors.
203

204
```java { .api }
205
public class FlywayException extends RuntimeException {
206
    public FlywayException(String message);
207
    public FlywayException(String message, Throwable cause);
208
}
209

210
public class FlywayValidateException extends FlywayException {
211
    public FlywayValidateException(ErrorDetails errorDetails, String validationError);
212
}
213

214
public interface ErrorDetails {
215
    ErrorCode getErrorCode();
216
    String getMessage();
217
}
218
```
219

220
[Error Handling](./error-handling.md)
221

222
## Types
223

224
### Core Types
225

226
```java { .api }
227
public class MigrationVersion implements Comparable<MigrationVersion> {
228
    public static MigrationVersion fromVersion(String version);
229
    public static final MigrationVersion LATEST;
230
    public static final MigrationVersion CURRENT;
231
    public String getVersion();
232
    public int compareTo(MigrationVersion other);
233
}
234

235
public class Location {
236
    public Location(String descriptor);
237
    public String getDescriptor();
238
    public String getPath();
239
    public boolean isClassPath();
240
}
241

242
public enum MigrationState {
243
    PENDING, ABOVE_TARGET, BELOW_BASELINE, BASELINE, SUCCESS, 
244
    FAILED, OUT_OF_ORDER, FUTURE_SUCCESS, FUTURE_FAILED
245
}
246
```
247

248
### Result Types
249

250
```java { .api }
251
public class MigrateResult extends HtmlResult {
252
    public List<MigrateOutput> migrations;
253
    public String initialSchemaVersion;
254
    public String targetSchemaVersion;
255
    public String schemaName;
256
    public int migrationsExecuted;
257
    public boolean success;
258
    public String flywayVersion; 
259
    public String database;
260
    public String databaseType;
261
    public List<String> warnings;
262
    
263
    public long getTotalMigrationTime();
264
    public void addWarning(String warning);
265
    public List<MigrateOutput> getPendingMigrations();
266
    public List<MigrateOutput> getSuccessfulMigrations();
267
    public List<MigrateOutput> getFailedMigrations();
268
}
269

270
public class HtmlResult implements OperationResult {
271
    private String timestamp;
272
    private String operation;
273
    private String exception;
274
    public Exception exceptionObject;
275
    private boolean licenseFailed;
276
    
277
    public String getOperation();
278
    public String getException();
279
    public boolean isLicenseFailed();
280
}
281

282
public class CleanResult extends HtmlResult {
283
    public List<String> schemasCleaned;
284
    public List<String> schemasDropped; 
285
}
286

287
public class ValidateResult extends OperationResultBase {
288
    public final ErrorDetails errorDetails;
289
    public final List<ValidateOutput> invalidMigrations;
290
    public final boolean validationSuccessful;
291
    public final int validateCount;
292
    
293
    public String getAllErrorMessages();
294
}
295
```