Schema Rules: Enforcing Database Policy with Atlas

Atlas manages and migrates database schemas by following modern DevOps principles. This includes allowing teams to define and enforce custom rules for their database schemas to ensure consistency, compliance, and best practices throughout the development lifecycle.

Here's a breakdown of what Atlas Schema Rules are, why they are beneficial, and how to implement them:

What are Atlas Schema Rules?

Atlas Schema Rules are custom linting rules for database schemas. They are defined using an HCL-based language and comprise three main building blocks: rule, predicate, and variable. These rules enable teams to specify desired schema characteristics and enforce them during development and within CI/CD pipelines.

Why Use Schema Rules?

Implementing Atlas Schema Rules offers several key advantages for database management:

• Enforce Best Practices

Automatically ensure your schema adheres to organizational conventions and compliance requirements. For example, you can mandate that all columns are non-nullable or have a default value, or that foreign keys reference primary keys and use ON DELETE CASCADE.

• Improve Consistency

Maintain a consistent database schema across different environments and projects, thus reducing the likelihood of errors and simplifying collaboration among team members.

• Prevent Destructive Changes

Atlas includes a static code analysis engine that can analyze proposed schema changes against your defined rules. This helps to identify and flag potential issues before they are applied to the database, avoiding costly failures and data corruption.

• Streamline Workflows

By automating schema validation, developers can focus more on building features and less on manual schema checks, leading to more efficient development cycles.

How to Use Schema Rules

To integrate Atlas Schema Rules into your database workflow, follow these general steps:

1. Define Your Rules

Create a .rule.hcl file (e.g., schema.rule.hcl) to define your custom schema rules. This file will contain rule blocks, which describe the rule's purpose, and predicate blocks, which define reusable conditions for validation.

schema.rule.hcl

# Example: A predicate that checks if a column is not null or has a default value.
predicate "column" "not_null_or_have_default" {
  or {
    default {
      ne = null
    }
    null {
      eq = false
    }
  }
}

# Example: A rule that requires columns to be not null or have a default value.
rule "schema" "column-notnull" {
  description = "require columns to be not null or have a default value"
  table {
    column {
      assert {
        predicate = predicate.column.not_null_or_have_default
        message   = "column ${self.name} must be not null or have a default value"
      }
    }
  }
}

2. Configure Atlas

In your atlas.hcl configuration file, include a lint block that references your rule file(s). This tells Atlas which rules to apply during linting.

atlas.hcl

lint {
  rule "hcl" "schema-rules" {
    src = ["schema.rule.hcl"]
  }
}

3. Run Linting Commands

Execute atlas schema lint or atlas migrate lint in your terminal to apply the defined rules.

• atlas schema lint: Applies rules to the entire schema and reports all results.
• atlas migrate lint: Applies rules to the schema but only reports results for changes introduced by the analyzed migrations, making it ideal for CI environments.

Atlas will then analyze your schema against the custom rules and report any violations, providing clear messages to guide you in correcting the schema.

Example Output

Analyzing schema objects (3 objects in total):

  column-notnull rule violated:
    -- schema.pg.hcl:5: column id must be not null or have a default value

  -------------------------
  -- 61.458µs
  -- 1 diagnostic

Conclusion

By leveraging Atlas Schema Rules, teams can ensure their database schemas are robust, consistent, and compliant with organizational standards, ultimately leading to more stable and maintainable applications.

For more detailed information and examples, you can refer to the official Atlas documentation on Schema Linting Rules and explore video tutorials such as Validating Your Schema Using Custom Rules.