shilion/liquibase-orientdb

Liquibase Plugin for OrientDB

Liquibase Plugin for OrientDB

This is a plugin for Liquibase that allows to use Liquibase for migrations on an OrientDB database.

Note	This plugin is still work in progress. It may still contain bugs, and not all the change types advertised in the XML schema are implemented yet. Contributions are welcome!

Requirements

The plugin requires a Java 8 (or higher) JRE. It has been tested with Liquibase 3.5.3 and OrientDB 3.0.0, though it may work with older versions of Liquibase and/or OrientDB.

Setup

Make sure the plugin JAR is on the classpath when running Liquibase. For example, when running Liquibase from your application, add it as a runtime dependency to your Gradle or Maven build:

build.gradle

dependencies {
    runtimeOnly 'org.unbroken-dome.liquibase-orientdb:liquibase-orientdb:0.3.0'
}

pom.xml

<dependencies>
    <dependency>
        <groupId>org.unbroken-dome.liquibase-orientdb</groupId>
        <artifactId>liquibase-orientdb</artifactId>
        <version>0.3.0</version>
        <scope>runtime</scope>
    </dependency>
</dependencies>

The plugin JAR is available via JCenter.

You will also need the OrientDB JDBC Driver on the classpath at runtime. The plugin does not declare a runtime dependency on it, to allow it to be used with different versions of the driver.

OrientDB Changes

This plugin contributes several change types that are unique to OrientDB. When using XML changelog files, they can be imported using the namespace http://www.unbroken-dome.org/schema/liquibase-orientdb. The XML schema definition (XSD) can be found inside the plugin JAR, and should be picked up automatically by your IDE for code completion.

<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:o="http://www.unbroken-dome.org/schema/liquibase-orientdb" (1)
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
                        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.2.xsd">

    <!-- Change set definitions -->

</databaseChangeLog>

1. Define a namespace prefix for the http://www.unbroken-dome.org/schema/liquibase-orientdb namespace.

In the following examples, we will assume the the prefix o is mapped to the plugin’s namespace.

Classes

Creating Classes

Create a class in a change set using the createClass change:

<o:createClass name="MyClass" />

You can specify the superclass using the extends attribute:

<o:createClass name="BaseClass"/>
<o:createClass name="DerivedClass" extends="BaseClass" />

Properties and indices may be added as children of the createClass element for convenience and brevity:

<o:createClass name="Book">
    <o:property name="title" type="string" />
    <o:property name="pages" type="integer" />
    <o:property name="authors" type="embeddedlist" linkedType="string" />
    <o:index property="title" type="notunique" />
</o:createClass>

Renaming Classes

<o:renameClass from="OldName" to="NewName" />

Dropping Classes

<o:dropClass name="MyClass" />

Properties

Add properties to an existing class with the createProperty change:

<changeSet id="1" author="tk">
    <o:createClass name="Book" />
</changeSet>


<changeSet id="2" author="tk">
    <o:createProperty name="title" type="string"
                      className="Book" />
</changeSet>

Property attributes like NOTNULL can be specified directly in the createProperty change, even though in SQL this requires an extra statement:

<o:createProperty name="title" type="string" className="Book"
                  notNull="true" mandatory="true" />

Indices

Automatic Indices

Create an automatic (property-based) index:

<o:createIndex on="Book" property="title" type="notunique" />

If the index spans multiple properties, list them in the properties attribute, separated by spaces:

<o:createIndex on="Book" property="author title" type="unique" />

When using indexes on EMBEDDEDMAP properties, use the more verbose form with an indexedProperty child element:

<o:createClass name="Book">
    <o:property name="titles" type="embeddedmap" linkedType="string"/>
</o:createClass>

<o:createIndex on="Book" name="titles" type="notunique">
    <o:indexedProperty name="titles" by="value" />
</o:createIndex>

An index engine may be specified with the engine attribute. The value is passed to OrientDB as-is, and is usually case-sensitive. Currently all built-in engine types have uppercase names.

<o:createIndex on="Book" property="title" type="fulltext" engine="LUCENE" />

Manual Indices

To create a manual index, set the name and keyType attributes on the createIndex change:

<o:createIndex name="mostRecentRecords"
               type="unique"
               keyType="date" />

Index Metadata

Metadata may be added to the index using the <metadata> child element. The metadata JSON can be written as the content of the element.

<o:createIndex on="Book" property="title" type="fulltext" engine="LUCENE">
    <o:metadata>{
        "analyzer": "org.apache.lucene.analysis.en.EnglishAnalyzer"
    }</o:metadata>
</o:createIndex>

Edge Classes

When creating classes for edges in a graph database, consider using the createEdgeClass change instead of createClass. It allows to be more specific about the expected inbound and outbound types, and can optionally create link properties on the edge and/or vertex classes.

<o:createClass name="Author" extends="V" />
<o:createClass name="Book" extends="V" />

<o:createEdgeClass name="WrittenBy" (1)
                   from="Book" to="Author" (2)
                   createLinkProperties="true" (3)
                   createVertexLinkProperties="true" /> (4)

1. The superclass E is implied, it is not necessary to write extends="E".

2. The attributes from and to are only meaningful when also using createLinkProperties or createVertexLinkProperties.

3. This creates link properties named out and in on the edge class. They are of type LINK and point to the corresponding vertex class. OrientDB sets these properties in any case when instantiating an edge class, but this way we can make them part of the schema.

4. This creates the properties Book.out_WrittenBy and Author.in_WrittenBy on each of the vertex classes. They are of type LINKLIST, with the edge class as the linked type. OrientDB sets these properties in any case when instantiating an edge class, but this way we can make them part of the schema.

DISCLAIMER: The author of this library has no affiliation with either the OrientDB or Liquibase projects, or the companies behind them.