1 /*
2 * Copyright 2010-2020 Redgate Software Ltd
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.flywaydb.core.api.migration;
17
18 import org.flywaydb.core.api.MigrationVersion;
19
20 /**
21 * Interface to be implemented by Java-based Migrations.
22 *
23 * <p>Java-based migrations are a great fit for all changes that can not easily be expressed using SQL.</p>
24 *
25 * <p>These would typically be things like</p>
26 * <ul>
27 * <li>BLOB & CLOB changes</li>
28 * <li>Advanced bulk data changes (Recalculations, advanced format changes, …)</li>
29 * </ul>
30 *
31 * <p>Migration classes implementing this interface will be
32 * automatically discovered when placed in a location on the classpath.</p>
33 *
34 * <p>Most users will be better served by subclassing subclass {@link BaseJavaMigration} instead of implementing this
35 * interface directly, as {@link BaseJavaMigration} encourages the use of Flyway's default naming convention and
36 * comes with sensible default implementations of all methods (except migrate of course) while at the same time also
37 * providing better isolation against future additions to this interface.</p>
38 */
39 public interface JavaMigration {
40 /**
41 * @return The version of the schema after the migration is complete. {@code null} for repeatable migrations.
42 */
43 MigrationVersion getVersion();
44
45 /**
46 * @return The description of this migration for the migration history. Never {@code null}.
47 */
48 String getDescription();
49
50 /**
51 * Computes the checksum of the migration.
52 *
53 * @return The checksum of the migration.
54 */
55 Integer getChecksum();
56
57 /**
58 * Whether this is an undo migration for a previously applied versioned migration.
59 *
60 * @return {@code true} if it is, {@code false} if not. Always {@code false} for repeatable migrations.
61 */
62 boolean isUndo();
63
64 /**
65 * Whether the execution should take place inside a transaction. Almost all implementation should return {@code true}.
66 * This however makes it possible to execute certain migrations outside a transaction. This is useful for databases
67 * like PostgreSQL and SQL Server where certain statement can only execute outside a transaction.
68 *
69 * @return {@code true} if a transaction should be used (highly recommended), or {@code false} if not.
70 */
71 boolean canExecuteInTransaction();
72
73 /**
74 * Executes this migration. The execution will automatically take place within a transaction, when the underlying
75 * database supports it and the canExecuteInTransaction returns {@code true}.
76 *
77 * @param context The context relevant for this migration, containing things like the JDBC connection to use and the
78 * current Flyway configuration.
79 * @throws Exception when the migration failed.
80 */
81 void migrate(Context context) throws Exception;
82 }