Schemalint

2.3.2 · active · verified Wed Apr 22

Schemalint is a Node.js-based command-line interface (CLI) tool designed to apply linting rules to PostgreSQL database schemas. It aims to enforce consistent naming conventions, best practices, and architectural patterns directly on the database structure, similar to how ESLint functions for JavaScript code. The package is currently at version 2.3.2 and receives regular updates, often bumping dependencies and occasionally adding new built-in rules or features, typically every few weeks or months. Its key differentiators include built-in rules for common PostgreSQL patterns (e.g., preferring `text` to `varchar`, `jsonb` to `json`), the ability to define custom rules via a plugin system, and a robust configuration model that allows for fine-grained control over rule severity and ignored identifiers. It integrates directly with `node-postgres` for schema extraction.

Common errors

```
Error: Cannot find module './.schemalintrc.js'
```
cause The `npx schemalint` command was executed in a directory that does not contain a `.schemalintrc.js` configuration file.

fix Ensure you run `npx schemalint` from the root directory of your project where `.schemalintrc.js` is located, or specify the path to the config file via CLI options if supported.
```
Error: connect ECONNREFUSED 127.0.0.1:5432
```
cause Schemalint failed to establish a connection to the PostgreSQL database. This typically indicates the database server is not running, or the host/port in the `connection` configuration is incorrect.

fix Verify that your PostgreSQL server is running and accessible. Check the `host` and `port` (if specified) in your `.schemalintrc.js` `connection` object to ensure they are correct.
```
TypeError: schemalint.Config is not a constructor
```
cause Attempting to use `Config` as a class or constructor at runtime, rather than as a TypeScript type for static analysis.

fix When using TypeScript, `Config` should only be imported with `import type { Config } from 'schemalint'` for type declarations, not for runtime instantiation.
```
Error: Rule 'my-custom-rule' not found
```
cause A rule specified in the `.schemalintrc.js` `rules` object could not be found, either because it's a non-existent built-in rule or a custom plugin was not loaded correctly.

fix Check the spelling of the rule name. For custom rules, ensure the plugin file is correctly specified in the `plugins` array and that the rule is exported with the correct name from the plugin module.

Warnings

breaking Version 2.0.0 introduced several new built-in rules (e.g., `mandatory-columns`, `row-level-security`, `index-referencing-column`, `reference-actions`). While rules are 'off' by default if not configured, enabling them or using a configuration that applies 'all' rules can introduce new linting errors on existing schemas.
Fix: Review the new rules in the documentation and explicitly disable any unwanted rules in your `.schemalintrc.js` configuration, or adjust your schema to comply.
breaking Version 1.1.0 converted the project to TypeScript. This significant internal change could potentially affect custom rule development or programmatic interactions with the library if internal APIs or type definitions shifted unexpectedly.
Fix: If developing custom plugins or using Schemalint programmatically, review your code against the new TypeScript definitions and ensure compatibility with updated interfaces.
gotcha Schemalint requires Node.js version 16.0.0 or higher. Running it with older Node.js versions will result in execution failures or errors.
Fix: Upgrade your Node.js environment to version 16.0.0 or newer to ensure compatibility.
gotcha Incorrect or incomplete PostgreSQL connection details (host, user, password, database) in the `.schemalintrc.js` file will prevent Schemalint from connecting to your database, leading to connection errors.
Fix: Double-check all `connection` parameters in your `.schemalintrc.js` file, ensuring they accurately reflect your PostgreSQL server's configuration and credentials.
gotcha Prior to v2.3.1, handling of relative plugin paths might have been inconsistent or required specific working directory contexts. Absolute paths or careful management of `process.cwd()` was often necessary.
Fix: For versions before 2.3.1, use absolute paths for plugins. For v2.3.1 and later, ensure relative paths are correctly specified from the current working directory where `npx schemalint` is executed.

Install

npm install schemalint npm
yarn add schemalint yarn
pnpm add schemalint pnpm

Imports

Config
wrong:
```
import { Config } from 'schemalint'
```
correct:
```
import type { Config } from 'schemalint'
```
Used for type-checking the `.schemalintrc.js` configuration file in TypeScript projects. `Config` is a type, not a runtime value.
Rule
```
import type { Rule } from 'schemalint'
```
Interface for defining custom linting rules when developing plugins, typically used in TypeScript.
run
wrong:
```
import schemalint from 'schemalint'
```
correct:
```
import { run } from 'schemalint/cli'
```
For programmatic execution of the CLI, though `npx schemalint` is the standard approach. Direct programmatic use is less common than CLI or config file type-checking.

Quickstart

Demonstrates the basic installation and command-line execution of Schemalint, along with a complete example of a `.schemalintrc.js` configuration file for linting a PostgreSQL schema with common rules.

{
  // .schemalintrc.js
  // This file should be in your project root or specified via CLI.
  /** @type {import("schemalint").Config } */
  module.exports = {
    // Connection configuration. Uses environment variables for security.
    connection: {
      host: process.env.DB_HOST ?? 'localhost',
      user: process.env.DB_USER ?? 'postgres',
      password: process.env.DB_PASSWORD ?? 'postgres',
      database: process.env.DB_NAME ?? 'acme_database',
      charset: "utf8",
    },

    // Schemas to be linted (e.g., 'public').
    schemas: [{ name: "public" }],

    // Linting rules with severity ('error', 'off') and parameters.
    rules: {
      "name-casing": ["error", "snake"],
      "name-inflection": ["error", "singular"],
      "prefer-jsonb-to-json": ["error"],
      "prefer-text-to-varchar": ["error"],
      "mandatory-columns": ["error", { "columns": ["id", "created_at", "updated_at"] }]
    },

    // (Optional) Ignore specific targets or rules.
    ignores: [
      { identifier: "public.sessions", rule: "name-inflection" },
      { identifierPattern: "public\\.knex_migrations.*", rulePattern: ".*" },
    ],

    // (Optional) Load custom rules from local paths.
    plugins: [],
  };
}

// To install:
// npm install -D schemalint

// To run (from the directory containing .schemalintrc.js):
// npx schemalint

view raw JSON →