mongoCrIndexNameStdChk

mongoCrIndexNameStdChk is a custom policy check that requires every db.<collection>.createIndex call to name the index starting with IDX.

Tip: This is a suggested naming standard, but can be tailored to look for any string that fits your specific requirement.

regex: (?i)(?s)createIndex(?!.*IDX-)

This example utilizes MongoDB. You can use this check as it is or customize it further to fit your needs in your NoSQL database. All Regex Custom Policy Checks can only run against the changelog, not against the database.

Scope Database
changelog MongoDB
  • Install Liquibase 4.29.0+
  • Configure a valid Liquibase Pro license key
  • Ensure the Liquibase Checks extension is installed. In Liquibase 4.31.0+, it is already installed in the /liquibase/internal/lib directory, so no action is needed. If the checks JAR is not installed, download liquibase-checks-<version>.jar and put it in the liquibase/lib directory.
    • Maven users only: Add this dependency to your pom.xml file:
    • <dependency>
    <groupId>org.liquibase.ext</groupId>
    <artifactId>liquibase-checks</artifactId>
    <version>2.0.0</version>
</dependency>
  • Java Development Kit 17+ (available for Open JDK and Oracle JDK)
  • Linux, macOS, or Windows operating system
  • Familiarity with Liquibase concepts: Changelog, Changeset, Policy Checks Commands, checks-scope, and snapshot

Before creating a custom policy check with Python, we recommend being familiar with:

  • Python 3.10.14+. (See here for the official Python tutorial)
  • Optional: General coding and Python best practices which will improve your check performance:
    • Efficient handling of structured data objects
    • Effective and targeted parsing of text, objects, and SQL
    • Using regular expressions and other pattern-matching tools within Python
    • Using Python virtual environments. Liquibase comes with a built-in virtual environment for Liquibase Custom Policy Checks. The built-in environment includes Liquibase Python modules and some common external Python modules—no configuration needed. However, if you want to install additional modules, or if you want your IDE to recognize the Liquibase modules, you must Create a Python Virtual Environment separately.

Tip: Downloading Python itself is not required to create custom checks in the Liquibase checks framework, but it may be useful to test checks against Python 3.10.14+.

Step-by-Step

Note: These steps describe how to create the custom policy check. It does not exist by default in Liquibase Pro.

  1. Enter this command into the CLI: 
    liquibase checks customize --check-name=SqlUserDefinedPatternCheck
  2. Give your check a short name for easier identification. In this example we will title the check:
    mongoCrIndexNameStdChk

  3. Set the Severity to return a code of 0-4 when triggered.
    Options: 'INFO'=0, 'MINOR'=1, 'MAJOR'=2, 'CRITICAL'=3, 'BLOCKER'=4

  4. Set the SEARCH_STRING to this valid regular expression:
    (?i)(?s)createIndex(?!.*IDX-)

  5. Set the MESSAGE for when a match for regular expression <SEARCH_STRING> is found in a Changeset:

    Example: The createIndex you are running in Mongo does not meet naming standards

  6. Set STRIP_COMMENTS to true if you want to remove the comments from the output.

    The regex custom policy check is created successfully.

Sample Passing Script

Copy 
          "changeSet": {
              "id": "create_students-name-index",
              "author": "jennl",
              "labels": "[jira-101],'version 1.0'",
              "runWith": "mongosh",
              "changes": [
                {
                  "mongoFile": {
                    "dbms": "mongodb",
                    "path": "create-idxname-students.js",
                    "relativeToChangelogFile": true
                  }
                }
                ],       
              "rollback": [
                  {
                    "mongo": {
                      "mongo": "db.students.dropIndex( \"IDX-students-uniquename\")"
                    }
                  }
              ]
          }    
      }
--create-idxname-students.js contents
-- current bug in core is not finding QCs violation when this is embedded in JSON changelog so
--it is defined in separate file that contains what is passed to mongosh
db.students.createIndex({
    "name": "text"
},
{
    name: "IDX-students-uniquename",
    unique: true
});

Sample Failing Scripts

Copy 
          "changeSet": {
              "id": "create_students-name-index",
              "author": "jennl",
              "labels": "[jira-101],'version 1.0'",
              "runWith": "mongosh",
              "changes": [
                {
                  "mongoFile": {
                    "dbms": "mongodb",
                    "path": "create-idxname-students.js",
                    "relativeToChangelogFile": true
                  }
                }
                ],       
              "rollback": [
                  {
                    "mongo": {
                      "mongo": "db.students.dropIndex( \"ID-students-uniquename\")"
                    }
                  }
              ]
          }    
      }
--create-idxname-students-fails.js contents
-- current bug in core is not finding QCs violation when this is embedded in JSON changelog so
--it is defined in separate file that contains what is passed to mongosh
db.students.createIndex({
    "name": "text"
},
{
    name: "ID-students-uniquename",
    unique: true
});

Sample Error Message

Copy 
CHANGELOG CHECKS
----------------
Checks completed validation of the changelog and found the following issues:

Check Name:         Check for specific patterns in sql (mongoCrIndexNameStdChk)
Changeset ID:       create_students-name-index
Changeset Filepath: dbchangelog.json
Check Severity:     MINOR (Return code: 1)
Message:            The createIndex you are running in Mongo does not meet
                    naming standards