schemalint

library2.3.2jsnpmunverified

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.

database devops

npm install schemalint

github ↗package ↗

INSTALL

IMPORT

SIG · SCHEMALINT

schemalint

databasejavascriptv2.3.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Config

✓ import type { Config } from 'schemalint'

✗ import { 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

✓ import { run } from 'schemalint/cli'

✗ import schemalint from 'schemalint'

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.

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

schemalint --version

Debug

Known issues

breakingVersion 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.

affects: >=2.0.0

breakingVersion 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.

affects: >=1.1.0

gotchaSchemalint 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.

affects: <16.0.0

gotchaIncorrect 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.

affects: all

gotchaPrior 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.

affects: <2.3.1

Errors

Common errors & fixes

Error: Cannot find module './.schemalintrc.js'

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

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

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

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.

Upgrade

Version history

2.3.2latest on npm

Audit

Dependencies

pgrequiredRequired for connecting to PostgreSQL databases, specified in the connection configuration.

extract-pg-schemarequiredCore dependency for introspecting and extracting schema details from PostgreSQL.

Agent activity

12 hits · last 30 days

node