Atlas Schema Rule

This page contains simple explanations of the predicate and rule blocks used for creating custom schema rules and examples of how to use the various operators.

predicate

A predicate is composed of multiple condition blocks, operators, and quantifiers. A condition can be applied to one or more attributes of the object, such as checking column nullability and type. Additionally, a condition can be negated, combined with other conditions using logical operators, and quantified to check if the condition holds for all or some attributes.

predicate table

predicate table consists of a set of condition blocks that apply to a table. Table attributes that may be used in each block include:

Attribute	Description	Operators
name	Name of the table	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
comment	Comment field of the table	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
self	Table object itself	Supports the eq and ne operators for comparison
primary_key	Primary key of the table	Can be checked using the condition or predicate attribute
schema	Schema of the table	Can be checked using the condition or predicate attribute

Driver specific attributes:

PostgreSQL

Attribute	Description	Operators
row_security_enabled	Row security status of the table	Supports the eq and ne operators for comparison
row_security_enforced	Row security enforcement status of the table	Supports the eq and ne operators for comparison

SQLite

Attribute	Description	Operators
strict	Srict mode status of the table	Supports the eq and ne operators for comparison
without_rowid	Without rowid status of the table	Supports the eq and ne operators for comparison

Child objects:

Type	Description
column	A column of the table
index	An index of the table
foreign_key	A foreign key of the table
check	A check constraint of the table
trigger	A trigger of the table
attr	An attribute of the table
policy (PostgreSQL)	A policy of the table

Example:

schema.rule.hcl

predicate "table" "not_audit" {
  not {
    name {
      match = ".+_audit$"
    }
  }
}

predicate "table" "has_sibling_audit" {
  schema {
    predicate = predicate.schema.has_table
    vars = {
      has_table = "${self.name}_audit"
    }
  }
}

predicate "schema" "has_table" {
  variable "table_name" {
    type = string
  }
  any {
    table {
      condition = self.name == var.table_name
    }
  }
}

predicate column

predicate column consists of a set of condition blocks that apply to a column. Column attributes that may be used in each block include:

Attribute	Description	Operators
null	Nullability of the column	Supports the eq and ne operators for comparison
name	Name of the column	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
type	Data type of the column	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
default	Default value of the column	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
comment	Comment field of the column	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
primary_key	Primary key status of the column	Can be checked using the condition or predicate attribute
self	Column object itself	Supports the eq and ne operators for comparison

Example:

predicate "column" "not_null_or_have_default" {
  or {
    default {
      ne = null
    }
    null {
      eq = false
    }
  }
}

predicate schema

predicate schema consists of a set of condition blocks that apply to a schema. Schema attributes that may be used in each block include:

Attribute	Description	Operators
name	Name of the schema	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
comment	Comment field of the schema	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
self	Schema object itself	Supports the eq and ne operators for comparison

Child objects:

Type	Description
table	A table in the schema
view	A view in the schema
attr	An attribute of the schema
function	A function in the schema
procedure	A procedure in the schema
policy (PostgreSQL)	A policy of the schema

Example:

schema.rule.hcl

predicate "schema" "has_tenant_policy" {
  exists {
    policy {
      predicate = predicate.policy.tenant
    }
  }
}

predicate view

predicate view consists of a set of condition blocks that apply to a view. View attributes that may be used in each block include:

Attribute	Description	Operators
name	Name of the view	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
query	Query of the view	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
comment	Comment field of the view	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
self	View object itself	Supports the eq and ne operators for comparison

Driver specific attributes:

PostgreSQL

Attribute	Operators
security_barrier	Supports the eq and ne operators for comparison
security_invoker	Supports the eq and ne operators for comparison

More details on these PostgreSQL attributes can be found in the PostgreSQL documentation

MySQL

Attribute	Operators
security	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison

More details on these MySQL attributes can be found in the MySQL documentation

Child objects:

Type	Description
column	A column of the view
index	An index of the view
trigger	A trigger of the view
attr	An attribute of the view

Example:

schema.rule.hcl

predicate "view" "check_option" {
  variable "value" {
    type = string
  }
  check_option {
    eq_fold = var.value
  }
}

rule "schema" "view-check-option" {
  description = "require all views to have a specific check option"
  view {
    assert {
      predicate = predicate.view.check_option
      vars = {
        value = "CASCADED"
      }
      message = "view \"${self.name}\" must have check option CASCADED"
    }
  }
}

predicate index

predicate index consists of a set of condition blocks that apply to an index. Index attributes that may be used in each block include:

Attribute	Description	Operators
name	Name of the index	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
comment	Comment field of the index	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
unique	Unique status of the index	Supports the eq and ne operators for comparison

Driver specific attributes:

PostgreSQL

Attribute	Description	Operators
type	Data type of the index	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
where	Predicate in the index definition	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
nulls_distinct		Supports the eq and ne operators for comparison

MySQL

Attribute	Description	Operators
type	Data type of the index	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison

Child objects:

Type	Description
part	A part of the index (e.g., column or an expression)
attr	An attribute of the index

Example:

schema.rule.hcl

predicate "index" "type" {
  variable "type" {
    type = string
  }
  type {
    eq = var.type
  }
}

rule "schema" "all-indexes-btree" {
  description = "Require all indexes to be BTREE."
  table {
    index {
      assert {
        predicate = predicate.index.type
        vars      = { type = "BTREE" }
        message   = "Table ${self.table.name} index ${self.name} must be BTREE"
      }
    }
  }
}

predicate index_part

predicate index_part consists of a set of condition blocks that apply to an index/key part (e.g., a column or an expression together with its attributes). Attributes that may be used in each block include:

Attribute	Description	Operators
columm	Not-empty if the index-part is set on a column	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
expr	Not-empty if the index-part is set on an expression	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
desc	Description of the index-part	Supports the eq and ne operators for comparison

Driver specific attributes:

MySQL

Attribute	Description	Operators
prefix	Not-zero if the index-part was set on a column prefix	Supports the eq, ne, lt, le, gt, and ge operators for comparison

Example:

schema.rule.hcl

predicate "index_part" "max_length" {
  variable "len" {
    type = number
  }
  or {
    prefix {
      eq = null
    }
    prefix {
      le = var.len
    }
  }
}

predicate check

predicate check consists of a set of condition blocks that apply to a check constraint. Check attributes that may be used in each block include:

Attribute	Description	Operators
name	Name of the check	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
expr	Expression of the check	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
comment	Comment field of the check	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison

Example:

schema.rule.hcl

predicate "table" "contains_age" {
  any {
    column {
      predicate = predicate.column.is_age
    }
  }
}

predicate "column" "is_age" {
  name {
    eq = "age"
  }
}

predicate "table" "contains_check" {
  any {
    check {
      predicate = predicate.check.age_minimum
    }
  }
}

predicate "check" "age_minimum" {
  expr {
    contains = "age >= 18"
  }
}

rule "schema" "adult-age-minimum" {
  description = "Enforce age columns limit to ages 18+"
  table {
    match {
      predicate = predicate.table.contains_age
    }
    assert {
      predicate = predicate.table.contains_check
      message = "table does not enforce 18+ age"
    }
  }
}

predicate foreign_key

predicate foreign_key consists of a set of condition blocks that apply to a foreign key constraint. Foreign key attributes that may be used in each block include:

Attribute	Description	Operators
name	Name of the foreign key	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
comment	Comment field of the foreign key	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
on_update	Update operator of the foreign key	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
on_delete	Delete operator of the foreign key	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
table	Table hosting the foreign key	Can be checked using the condition or predicate attribute
ref_table	Table referred to by the foreign key	Can be checked using the condition or predicate attribute

Driver specific attributes:

PostreSQL

Attribute	Operators
deferrable	Supports the eq and the ne operators for comparison
initially_deferred	Supports the eq and the ne operators for comparison

Child objects:

Type	Description
column	A column of the foreign key
ref_column	A column of the referenced table
attr	An attribute of the foreign key

Example:

schema.rule.hcl

predicate "foreign_key" "on_delete_cascade" {
  on_delete {
    eq = "CASCADE"
  }
  all {
    ref_column {
      predicate = predicate.column.is_pk
    }
  }
}

predicate "column" "is_pk" {
  primary_key {
    eq = true
  }
}

rule "schema" "fk-action-cascade" {
  description = "All foreign keys must reference primary keys of the target table and use ON DELETE CASCADE"
  table {
    foreign_key {
      assert {
        predicate = predicate.foreign_key.on_delete_cascade
        message   = "foreign key ${self.name} must reference primary key of target table and use ON DELETE CASCADE"
      }
    }
  }
}

predicate trigger

predicate trigger consists of a set of condition blocks that apply to a trigger. Trigger attributes that may be used in each block include:

Attribute	Description	Operators
name	Name of the trigger	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
for	FOR statement of the trigger	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
comment	Comment field of the trigger	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
event	Event that sets off the trigger	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
body	Logic executed by the trigger	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
table	Table that causes the trigger	Can be checked using the condition or predicate attribute
view	View that causes the trigger	Can be checked using the condition or predicate attribute

Driver specific attributes:

PostreSQL

Attribute	Operators
deferrable	Supports the eq and the ne operators for comparison
initially_deferred	Supports the eq and the ne operators for comparison

Example:

predicate "trigger" "audit_trigger" {
  name {
    eq = "history_audit"
  }
  event {
    contains_fold = "DELETE OR INSERT OR UPDATE"
  }
}

predicate function

predicate function consists of a set of condition blocks that apply to a function. Function attributes that may be used in each block include:

Attribute	Description	Operators
name	Name of the function	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
lang	Programming language the function is written in	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
return	Return type of the function	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
comment	Comment field of the function	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
body	Logic executed by the function	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
schema	Schema of the function	Can be checked using the condition or predicate attribute

Driver specific attributes:

PostreSQL

Attribute	Operators
leakproof	Supports the eq and the ne operators for comparison
strict	Supports the eq and the ne operators for comparison
parallel	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
security	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
volatility	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison

More details on these PostgreSQL attributes can be found in the PostgreSQL documentation

schema.rule.hcl

predicate "function" "security_invoker" {
  security {
    eq = "INVOKER"
  }
}

MySQL

Attribute	Operators
deterministic	Supports the eq and the ne operators for comparison
security	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
data_access	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison

More details on these MySQL attributes can be found in the MySQL documentation

schema.rule.hcl

predicate "function" "deterministic" {
  deterministic {
    eq = true
  }
}

Child objects:

Type	Description
arg	An argument of the function
attr	An attribute of the function

Example:

schema.rule.hcl

predicate "function" "match_name" {
  variable "pattern" {
    type = string
  }
  name {
    match = var.pattern
  }
}

predicate procedure

predicate procedure consists of a set of condition blocks that apply to a procedure. Procedure attributes that may be used in each block include:

Attribute	Description	Operators
name	Name of the procedure	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
lang	Programming language the procedure is written in	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
comment	Comment field of the procedure	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
body	Logic executed by the procedure	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
schema	Schema of the procedure	Can be checked using the condition or predicate attribute

Driver specific attributes:

PostreSQL

Attribute	Operators
security	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison

More details on the PostgreSQL attributes can be found in the PostgreSQL documentation

MySQL

Attribute	Operators
deterministic	Supports the eq and the ne operators for comparison
security	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
data_access	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison

More details on these MySQL attributes can be found in the MySQL documentation

Child objects:

Type	Description
arg	An argument of the procedure
attr	An attribute of the procedure

Example:

schema.rule.hcl

predicate "procedure" "is_sql" {
  lang {
    eq = "SQL"
  }
}

predicate arg

predicate arg consists of a set of condition blocks that apply to a function argument. Argument attributes that may be used in each block include:

Attribute	Description	Operators
name	Name of the argument	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
type	Data type of the argument	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
default	Default value of the argument	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
mode	Input/Output mode of the argument	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison

Example:

schema.rule.hcl

predicate "arg" "not_out" {
  mode {
    ne = "OUT"
  }
}
predicate "function" "no_out_arg" {
  not {
    exists {
      arg {
        predicate = predicate.arg.not_out
      }
    }
  }
}

predicate attr

predicate attr consists of two attributes: name and value and allows testing an attribute's value by its name.

note

Most attributes can be checked inline on the object predicate itself, making this predicate unnecessary in most cases. You can use this predicate to check attributes that are not directly accessible from the object predicate.

Attribute	Description	Operators
name	Name of the attribute	Supports the eq, eq_fold, contains, contains_fold, ne, in, and match operators for comparison
value	Value of the attribute	Supports the eq, ne

rule

The rule "schema" block defines a rule applied to the schema. It requires a name label and a description attribute that provides a human-readable explanation of the rule (it is used in the linting output).

When traversing a schema element, two blocks can be used: match and assert.

• match filters the elements the rule should apply to
• assert applies the predicate to the matched elements. If the predicate evaluates to false, an assertion is raised with the provided message attribute.

Example schema check

schema.rule.hcl

rule "schema" "disallow-circular-table-references" {
  description = "Disallow circular table references"
  schema {
    assert {
      predicate = predicate.schema.not_circular_ref
      message = "schema ${self.name} has circular table references"
    }
  }
}

Example foreign_key check

schema.rule.hcl

rule "schema" "fk-action-cascade" {
  description = "All foreign keys must reference primary keys of the target table and use ON DELETE CASCADE"
  table {
    foreign_key {
      assert {
        predicate = predicate.foreign_key.on_delete_cascade
        message   = "foreign key ${self.name} must reference primary key of target table and use ON DELETE CASCADE"
      }
    }
  }
}

Example primary_key check

schema.rule.hcl

rule "schema" "pk-column-uuid" {
  description = "require primary key columns to be of type UUID"
  table {
    primary_key {
      match {
        predicate = predicate.index.is_set
      }
      assert {
        predicate = predicate.index.uuid_columns_only
        message   = "primary key must be set on UUID columns only"
      }
    }
  }
}

Example column check

schema.rule.hcl

rule "schema" "column-pii" {
  description = "require all PII columns to have a specific comment"
  table {
    column {
      match {
        predicate = predicate.column.is_pii
      }
      assert {
        predicate = predicate.column.comment_match
        vars = {
          pattern = ".*PII.*"
        }
        message = "column ${self.name} must have a comment PII"
      }
    }
  }
}

Operators

predicate and rule blocks use logical operators to define the rules.

Boolean operators:

• lt: The value is numerically less than a given value
• le: The value is numerically less than or equal to a given value
• gt: The value is numerically gretaer than a given value
• ge: The value is numerically greater than or equal to a given value
• ne: The value is not equal to a given value
• eq: The value is equal to a given value. The given value type must match the block type. For example, for string blocks (e.g. name), the value must be a string; for boolean blocks (e.g. null), the value must be a boolean; and so on
• eq_fold: Same as eq, but not case-sensitive
• contains: The string value contains a given string in it
• contains_fold: Same as contains, but not case-sensitive
• in: The string value exists within a list of strings
• match: The string value matches a regular expression or pattern

Block operators:

• not: Inverts the truth value of the block
• or: At least one of the statements in the block is true
• and: All of the statements in the block are true

In addition to the logical operators, the predicate block supports the following quantifiers for child objects:

• all: The condition holds for all child objects
• any: The condition holds for at least one child object
• exists: The condition holds for at least one child object (alias for any)
• count: The condition holds for a specific number of child objects

Examples:

not

predicate "column" "has-default" {
  default {
    not = null
  }
}

eq

predicate "column" "not-null" {
  null {
    eq = false
  }
}

eq_fold

predicate "column" "is-birthdate" {
  name {
    eq_fold = "birthdate"
  }
}

contains

predicate "foreign_key" "name-starts-with-ref-table" {
  variable "ref_table_name" {
    type = string
  }
  name {
    contains = var.ref_table_name
  }
}

contains_fold

predicate "trigger" "on-insert" {
  event {
    contains_fold = "INSERT"
  }
}

in

predicate "column" "is_pii" {
  name {
    in = ["name", "email", "phone", "address", "ssn", "dob"]
  }
}

match

predicate "foreign_key" "fk-suffix" {
  name {
    match = ".+_fk$"
  }
}

or

predicate "column" "not_null_or_have_default" {
  or {
    default {
      ne = null
    }
    null {
      eq = false
    }
  }
}

and

predicate "function" "sql-returns-json" {
  and {
    lang {
      eq_fold = "SQL"
    }
    return {
      eq_fold = "json"
    }
  }
}

any

predicate "table" "has_column" {
  variable "col_name" {
    type = string
  }
  any {
    column {
      condition = self.name == var.col_name
    }
  }
}

all

predicate "table" "no-null-cols" {
  all {
    column {
      predicate = predicate.column.no-null
    }
  }
}

predicate "column" "no-null" {
  null {
    ne = false
  }
}

exists

predicate "table" "no-pk" {
  not {
    exists {
      column {
        predicate = predicate.column.is-pk
      }
    }
  }
}

count

predicate "schema" "max-3-history-tables" {
  count {
    table {
      predicate = predicate.table.is-audit
    }
    le = 3
  }
}