{"id":16526,"library":"schemalint","title":"Schemalint","description":"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.","status":"active","version":"2.3.2","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/kristiandupont/schemalint","tags":["javascript","postgresql","schema","lint","typescript"],"install":[{"cmd":"npm install schemalint","lang":"bash","label":"npm"},{"cmd":"yarn add schemalint","lang":"bash","label":"yarn"},{"cmd":"pnpm add schemalint","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for connecting to PostgreSQL databases, specified in the connection configuration.","package":"pg","optional":false},{"reason":"Core dependency for introspecting and extracting schema details from PostgreSQL.","package":"extract-pg-schema","optional":false}],"imports":[{"note":"Used for type-checking the `.schemalintrc.js` configuration file in TypeScript projects. `Config` is a type, not a runtime value.","wrong":"import { Config } from 'schemalint'","symbol":"Config","correct":"import type { Config } from 'schemalint'"},{"note":"Interface for defining custom linting rules when developing plugins, typically used in TypeScript.","symbol":"Rule","correct":"import type { Rule } from 'schemalint'"},{"note":"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.","wrong":"import schemalint from 'schemalint'","symbol":"run","correct":"import { run } from 'schemalint/cli'"}],"quickstart":{"code":"{\n  // .schemalintrc.js\n  // This file should be in your project root or specified via CLI.\n  /** @type {import(\"schemalint\").Config } */\n  module.exports = {\n    // Connection configuration. Uses environment variables for security.\n    connection: {\n      host: process.env.DB_HOST ?? 'localhost',\n      user: process.env.DB_USER ?? 'postgres',\n      password: process.env.DB_PASSWORD ?? 'postgres',\n      database: process.env.DB_NAME ?? 'acme_database',\n      charset: \"utf8\",\n    },\n\n    // Schemas to be linted (e.g., 'public').\n    schemas: [{ name: \"public\" }],\n\n    // Linting rules with severity ('error', 'off') and parameters.\n    rules: {\n      \"name-casing\": [\"error\", \"snake\"],\n      \"name-inflection\": [\"error\", \"singular\"],\n      \"prefer-jsonb-to-json\": [\"error\"],\n      \"prefer-text-to-varchar\": [\"error\"],\n      \"mandatory-columns\": [\"error\", { \"columns\": [\"id\", \"created_at\", \"updated_at\"] }]\n    },\n\n    // (Optional) Ignore specific targets or rules.\n    ignores: [\n      { identifier: \"public.sessions\", rule: \"name-inflection\" },\n      { identifierPattern: \"public\\\\.knex_migrations.*\", rulePattern: \".*\" },\n    ],\n\n    // (Optional) Load custom rules from local paths.\n    plugins: [],\n  };\n}\n\n// To install:\n// npm install -D schemalint\n\n// To run (from the directory containing .schemalintrc.js):\n// npx schemalint\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"If developing custom plugins or using Schemalint programmatically, review your code against the new TypeScript definitions and ensure compatibility with updated interfaces.","message":"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.","severity":"breaking","affected_versions":">=1.1.0"},{"fix":"Upgrade your Node.js environment to version 16.0.0 or newer to ensure compatibility.","message":"Schemalint requires Node.js version 16.0.0 or higher. Running it with older Node.js versions will result in execution failures or errors.","severity":"gotcha","affected_versions":"<16.0.0"},{"fix":"Double-check all `connection` parameters in your `.schemalintrc.js` file, ensuring they accurately reflect your PostgreSQL server's configuration and credentials.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.3.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The `npx schemalint` command was executed in a directory that does not contain a `.schemalintrc.js` configuration file.","error":"Error: Cannot find module './.schemalintrc.js'"},{"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.","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.","error":"Error: connect ECONNREFUSED 127.0.0.1:5432"},{"fix":"When using TypeScript, `Config` should only be imported with `import type { Config } from 'schemalint'` for type declarations, not for runtime instantiation.","cause":"Attempting to use `Config` as a class or constructor at runtime, rather than as a TypeScript type for static analysis.","error":"TypeError: schemalint.Config is not a constructor"},{"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.","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.","error":"Error: Rule 'my-custom-rule' not found"}],"ecosystem":"npm"}