Skip to content

Home

Jump to bottom
Tayeb Chlyah edited this page Jun 23, 2022 · 6 revisions

Getting started

Add Couchmove dependency

With Maven

<dependency>
    <groupId>com.github.differentway</groupId>
    <artifactId>couchmove</artifactId>
    <version>3.3</version>
</dependency>

With Gradle

compile 'com.github.differentway:couchmove:3.3'

Usage

All you need to do is to instantiate a Couchmove Object with some configuration. Iy you use Spring, you can instantiate it as a bean. Don't forget to run migrate() method to start migration process.

@Bean
public Couchmove couchmove(Bucket bucket) {
    log.debug("Configuring Couchmove");
    Couchmove couchmove = new Couchmove(bucket, "couchmove/changelog");
    couchmove.migrate();
    return couchmove;
}

Creating change logs

Couchmove is widely inspired from the simplicity of Flyway, the only difference is that you can import documents, design documents, execute n1ql requests, create FTS index, or eventing function, depending on the change log format (file or folder) and extension (.n1ql, .json, .fts, .eventing).

Naming

In order to be picked by the class path scanner, the migrations must follow a naming pattern :

  • prefix : For now, only Vfor versioned migrations are supported.
  • version : Each versioned migration must have a unique version, composed by one or more numeric parts, separated by a dot . or an underscore _
  • separator : two underscores __
  • description : Underscore _ or spaces separate the words. Underscores are replaced by spaces at runtime
  • suffix : .n1ql, .json, .fts, .eventing for files, or none for folders

Examples :

V1__Create_index.n1ql
V1.1__insert_clients
V2_1__all.json
V3__client.fts
V3.1__update-client.eventing

Change log types

1. n1ql scripts :

Format : Files with .n1qlextension

Syntax :

  • Single or multi-line statements
  • Placeholder replacement : it looks for Ant-style placeholders like ${placeholder}. For now, it only support injecting bucket name in n1ql scripts with ${bucket} placeholder
  • Single --, or Multi-line /* */ comments spanning complete lines

Example : V1__Create_Index.n1ql

/* Single line comment */
CREATE INDEX type ON default(`_class`)
    WITH { "defer_build" : true };

/*
Multi-line
comment
*/

-- Placeholder
INSERT INTO ${bucket} (KEY, VALUE)
  VALUES
    ("user::Administrator",
      {
        "type": "admin",
        "username": "Administrator",
        "birthday": "01/09/1998"
      });

2. Design Documents :

Format : Files with .jsonextension

Syntax : Use JSON Format. The format of the design document should include all the views defined in the design document, incorporating both the map and reduce functions for each named view.

Description is used as a design document name.

Example : V2__location.json

{
   "views" : {
      "byloc" : {
         "map" : "function (doc, meta) {\n  if (meta.type == \"json\") {\n    emit(doc.city, doc.sales);\n  } else {\n    emit([\"blob\"]);\n  }\n}"
      }
   }
}

3. Documents

Folder containing JSON Files with .json extension. Couchmove import all documents to Couchbase bucket, using file names (without .json extension) as document keys.

4. Full Text Search indexes

Format : Files with .fts extension

Syntax : Use JSON Format. The format of the FTS index should respect FTS Index Definition: PUT /api/index/{indexName}.

Description is used as index name.

Example : V3__client.fts

{
    "type": "fulltext-index",
    "params": {
        "doc_config": {
            "docid_prefix_delim": "",
            "docid_regexp": "",
            "mode": "scope.collection.type_field",
            "type_field": "type"
        },
        "mapping": {
            "analysis": {},
            "default_analyzer": "standard",
            "default_datetime_parser": "dateTimeOptional",
            "default_field": "_all",
            "default_mapping": {
                "dynamic": true,
                "enabled": false
            },
            "default_type": "_default",
            "docvalues_dynamic": false,
            "index_dynamic": true,
            "store_dynamic": false,
            "types": {
                "${scope}.client.client": {
                    "dynamic": true,
                    "enabled": true
                }
            }
        },
        "store": {
            "indexType": "scorch",
            "segmentVersion": 15
        }
    },
    "sourceType": "couchbase",
    "sourceName": "${bucket}",
    "uuid": "",
    "name": "category"
}

5. Eventing functions

Format : Files with .eventing extension

Syntax : Use JSON Format. The format should respect Eventing REST API: POST /api/v1/functions/

Description is used as a description.

Example : V3.1__update-client.eventing

[
    {
        "appcode": "function OnUpdate(doc, meta) {\n    log(\"Doc created/updated\", meta.id);\n}",
        "depcfg": {
            "source_bucket": "${bucket}",
            "source_scope": "_default",
            "source_collection": "_default",
            "metadata_bucket": "${bucket}",
            "metadata_scope": "${scope}",
            "metadata_collection": "eventing"
        },
        "version": "evt-7.0.3-7031-ee",
        "enforce_schema": false,
        "appname": "update-client",
        "settings": {
            "cluster_stats": null,
            "dcp_stream_boundary": "everything",
            "deployment_status": false,
            "description": "",
            "execution_timeout": 60,
            "language_compatibility": "6.6.2",
            "log_level": "INFO",
            "n1ql_consistency": "none",
            "num_timer_partitions": 128,
            "processing_status": false,
            "timer_context_size": 1024,
            "user_prefix": "eventing",
            "worker_count": 1
        }
    }
]
Clone this wiki locally