eugene lint

The eugene lint command will analyze the syntax tree of a SQL script and spot a number of dangerous patterns. It works by using the library to parse SQL scripts using the same parser that PostgreSQL uses internally. This allows Eugene to work with the same kind of syntax trees that the server uses.

eugene lint will attempt to keep track of whether objects are new in the same transaction, so that it can avoid false positives for tables that aren't visible to other transactions yet. In some cases, it will report false positives, since it can't know the DDL of the tables that are being referenced. For example, it can't know if a type change is safe. It is easy to ignore these false positives by adding a comment to the SQL script, see ignores.

eugene lint can catch many things that it is specifically designed to catch, but it must have reasonably precise rules. Some SQL statements will implicitly create indexes, which will prevent writes to the table, and eugene lint will catch those that it knows about, but there may be some ways for this to happen that it doesn't know about.

If you want to run eugene lint in CI, or as a pre-commit hook, you can use --git-diff=main or -gmain to lint files that are new/unstaged, or have changes in them since main.


$ eugene help lint
Lint SQL migration script by analyzing syntax tree

`eugene lint` exits with failure if any lint is detected.

Usage: eugene lint [OPTIONS] [paths]...

          Path to SQL migration scripts, directories, or '-' to read from stdin

  -v, --var <PLACEHOLDERS>
          Provide name=value for replacing ${name} with value in the SQL script
          Can be used multiple times to provide more placeholders.

  -i, --ignore <IGNORED_HINTS>
          Ignore the hints with these IDs, use `eugene hints` to see available hints
          Can be used multiple times: `-i E3 -i E4`
          Or comment your SQL statement like this:
          `-- eugene-ignore: E3, E4`
          alter table foo add column bar json;
          This will ignore hints E3 and E4 for this statement only.

  -f, --format <FORMAT>
          Output format, plain, json or markdown
          [default: plain]
          [possible values: json, markdown, md, plain]

  -a, --accept-failures
          Exit successfully even if problems are detected.
          Will still fail for syntax errors in the SQL script.

      --sort-mode <SORT_MODE>
          Sort mode for script discovery, auto, name or none
          This is used to order scripts when a path is a directory, or many paths are provided.
          `auto` will sort by versions or sequence numbers.
          `auto` requires all files to have the same naming scheme, either flyway-style or leading sequence numbers.
          `name` will sort lexically by name.
          [default: auto]
          [possible values: auto, name, none]

  -s, --skip-summary
          Skip the summary section for markdown output

  -g, --git-diff <GIT_DIFF>
          Filter out discovered scripts that are have not been changed since this git ref
          Pass a git ref, like a commit hash, tag, or branch name.

  -h, --help
          Print help (see a summary with '-h')