0
# Liquibase Database Migration Tool
1

2
## Overview
3

4
Liquibase is a powerful database schema change management tool that provides version control for your database. It tracks, manages, and applies database schema changes in a structured, repeatable manner across different environments. Liquibase supports multiple database platforms and provides both programmatic APIs and command-line interfaces for database migrations, rollbacks, and schema management.
5

6
## Package Information
7

8
- **Package Name**: liquibase-core
9
- **Package Type**: maven
10
- **Language**: Java
11
- **Group ID**: org.liquibase
12
- **Artifact ID**: liquibase-core
13
- **Version**: 5.0.0
14
- **Main Namespace**: liquibase.*
15

16
**Maven Dependency:**
17
```xml
18
<dependency>
19
    <groupId>org.liquibase</groupId>
20
    <artifactId>liquibase-core</artifactId>
21
    <version>5.0.0</version>
22
</dependency>
23
```
24

25
**Gradle Dependency:**
26
```gradle
27
implementation 'org.liquibase:liquibase-core:5.0.0'
28
```
29

30
**Direct JAR Download:**
31
Available from [Maven Central](https://central.sonatype.com/artifact/org.liquibase/liquibase-core/5.0.0)
32

33
## Core Imports
34

35
```java { .api }
36
// Primary facade class
37
import liquibase.Liquibase;
38

39
// Modern command framework
40
import liquibase.command.CommandScope;
41
import liquibase.command.CommandResults;
42

43
// Database connection and management
44
import liquibase.database.Database;
45
import liquibase.database.DatabaseFactory;
46
import liquibase.database.DatabaseConnection;
47

48
// Changelog management
49
import liquibase.changelog.DatabaseChangeLog;
50
import liquibase.changelog.ChangeSet;
51

52
// Configuration
53
import liquibase.GlobalConfiguration;
54

55
// Resource access
56
import liquibase.resource.ResourceAccessor;
57
import liquibase.resource.ClassLoaderResourceAccessor;
58
import liquibase.resource.FileSystemResourceAccessor;
59

60
// Context and label filtering
61
import liquibase.Contexts;
62
import liquibase.LabelExpression;
63

64
// Exception handling
65
import liquibase.exception.LiquibaseException;
66
import liquibase.exception.DatabaseException;
67
```
68

69
## Basic Usage
70

71
### Simple Database Update
72

73
```java { .api }
74
import liquibase.Liquibase;
75
import liquibase.database.DatabaseFactory;
76
import liquibase.database.jvm.JdbcConnection;
77
import liquibase.resource.ClassLoaderResourceAccessor;
78

79
// Create database connection
80
Connection connection = DriverManager.getConnection(
81
    "jdbc:h2:mem:test", "sa", ""
82
);
83
DatabaseConnection databaseConnection = new JdbcConnection(connection);
84
Database database = DatabaseFactory.getInstance()
85
    .findCorrectDatabaseImplementation(databaseConnection);
86

87
// Create Liquibase instance
88
Liquibase liquibase = new Liquibase(
89
    "changelog/db.changelog-master.xml",
90
    new ClassLoaderResourceAccessor(),
91
    database
92
);
93

94
// Execute update
95
liquibase.update((String) null);
96

97
// Close resources
98
liquibase.close();
99
```
100

101
### Using Command Framework
102

103
```java { .api }
104
import liquibase.command.CommandScope;
105

106
CommandScope updateCommand = new CommandScope("update")
107
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
108
    .addArgumentValue("url", "jdbc:h2:mem:test")
109
    .addArgumentValue("username", "sa")
110
    .addArgumentValue("password", "");
111

112
CommandResults results = updateCommand.execute();
113
```
114

115
## Architecture
116

117
Liquibase follows a layered architecture with clear separation of concerns:
118

119
### Core Components
120

121
- **Liquibase Class**: Main facade providing high-level operations
122
- **Command Framework**: Modern command execution system via CommandScope
123
- **Database Layer**: Abstraction over different database implementations
124
- **Changelog System**: Management of database change definitions
125
- **Change Types**: Specific database operations (create table, add column, etc.)
126
- **Resource Accessor**: Flexible file and resource access system
127

128
### Database Support
129

130
Liquibase provides native support for major database platforms including Oracle, MySQL, PostgreSQL, SQL Server, H2, SQLite, DB2, Derby, and many others through the Database interface and implementations.
131

132
## Capabilities
133

134
### Core Database Operations
135

136
Primary database migration operations using the main Liquibase class:
137

138
```java { .api }
139
// Update operations
140
public void update() throws LiquibaseException
141
public void update(Contexts contexts) throws LiquibaseException  
142
public void update(Contexts contexts, LabelExpression labelExpression) throws LiquibaseException
143
public void update(int changesToApply, String contexts) throws LiquibaseException
144
public void update(String tag, String contexts) throws LiquibaseException
145

146
// Rollback operations  
147
public void rollback(int changesToRollback, String contexts) throws LiquibaseException
148
public void rollback(String tagToRollBackTo, String contexts) throws LiquibaseException
149
public void rollback(Date dateToRollBackTo, String contexts) throws LiquibaseException
150

151
// Status and validation
152
public List<ChangeSet> listUnrunChangeSets(Contexts contexts, LabelExpression labels) throws LiquibaseException
153
public void validate() throws LiquibaseException
154

155
// Database operations
156
public void dropAll() throws DatabaseException
157
public void tag(String tagString) throws LiquibaseException
158
```
159

160
**→ See [Database Operations](database-operations.md) for comprehensive API coverage**
161

162
### Command Framework
163

164
Modern command execution system for programmatic and CLI usage:
165

166
```java { .api }
167
// Command construction and execution
168
public CommandScope(String... commandName) throws CommandExecutionException
169
public CommandScope addArgumentValue(String argumentName, Object value)
170
public CommandResults execute() throws CommandExecutionException
171

172
// Output control
173
public CommandScope setOutput(OutputStream outputStream)
174
```
175

176
**→ See [Command Framework](command-framework.md) for detailed command usage**
177

178
### Configuration System
179

180
Global configuration management for Liquibase behavior:
181

182
```java { .api }
183
// Core configuration properties
184
public static final ConfigurationDefinition<String> DATABASECHANGELOG_TABLE_NAME
185
public static final ConfigurationDefinition<String> LIQUIBASE_CATALOG_NAME  
186
public static final ConfigurationDefinition<String> LIQUIBASE_SCHEMA_NAME
187
public static final ConfigurationDefinition<Boolean> VALIDATE_XML_CHANGELOG_FILES
188
```
189

190
**→ See [Configuration System](configuration.md) for all settings and options**
191

192
### Changelog Management  
193

194
Database change definition and management:
195

196
```java { .api }
197
// DatabaseChangeLog management
198
public List<ChangeSet> getChangeSets()
199
public void addChangeSet(ChangeSet changeSet) 
200
public ChangeSet getChangeSet(String path, String author, String id)
201
public void validate(Database database, Contexts contexts, LabelExpression labelExpression)
202

203
// ChangeSet properties
204
public String getId()
205
public String getAuthor() 
206
public List<Change> getChanges()
207
public Contexts getContexts()
208
public Labels getLabels()
209
```
210

211
**→ See [Changelog Management](changelog.md) for changeset creation and management**
212

213
### Database Support
214

215
Multi-database abstraction and platform-specific implementations:
216

217
```java { .api }
218
// Database factory and detection
219
public static DatabaseFactory getInstance()
220
public Database findCorrectDatabaseImplementation(DatabaseConnection connection)
221
public Database openDatabase(String url, String username, String password, ...)
222

223
// Database interface
224
public boolean isCorrectDatabaseImplementation(DatabaseConnection conn)
225
public String getDatabaseProductName()
226
public String getDefaultCatalogName()
227
public boolean supportsAutoIncrement()
228
```
229

230
**→ See [Database Support](database-support.md) for platform-specific features**
231

232
### Diff and Comparison
233

234
Schema comparison and change generation tools:
235

236
```java { .api }
237
// Diff operations
238
public DiffResult diff(Database referenceDatabase, Database targetDatabase, CompareControl compareControl)
239

240
// Diff results
241
public Set<DatabaseObject> getMissingObjects()
242
public Set<DatabaseObject> getUnexpectedObjects() 
243
public Map<DatabaseObject, ObjectDifferences> getChangedObjects()
244
public boolean areEqual()
245

246
// Comparison control
247
public CompareControl(SchemaComparison[] schemaComparisons, Set<Class<? extends DatabaseObject>> compareTypes)
248
```
249

250
**→ See [Diff and Comparison](diff-comparison.md) for schema analysis tools**
251

252
### Exception Handling
253

254
Comprehensive exception hierarchy for error management:
255

256
```java { .api }
257
// Base exceptions
258
public class LiquibaseException extends Exception
259
public class DatabaseException extends LiquibaseException
260
public class ValidationFailedException extends LiquibaseException
261

262
// Execution exceptions
263
public class CommandExecutionException extends LiquibaseException
264
public class MigrationFailedException extends LiquibaseException
265
public class RollbackFailedException extends LiquibaseException
266

267
// Parsing exceptions  
268
public class ChangeLogParseException extends LiquibaseException
269
public class LiquibaseParseException extends LiquibaseException
270
```
271

272
**→ See [Exception Handling](exceptions.md) for complete error management**
273

274
## Related Documentation
275

276
- [Database Operations](database-operations.md) - Core migration and rollback operations
277
- [Command Framework](command-framework.md) - Modern command execution system  
278
- [Configuration System](configuration.md) - Global settings and behavior control
279
- [Changelog Management](changelog.md) - Change definition and organization
280
- [Database Support](database-support.md) - Multi-platform database abstraction
281
- [Diff and Comparison](diff-comparison.md) - Schema analysis and change generation
282
- [Exception Handling](exceptions.md) - Error management and troubleshooting