Sequelize TypeScript Generator

Common errors

• Error: Cannot find module 'pg'\nRequire stack:\n- .../node_modules/sequelize-typescript-generator/dist/cli.js

  cause The required database driver for the specified dialect is not installed in the project's `node_modules`.
  fix Install the appropriate database driver for your chosen dialect. For PostgreSQL, run `npm install pg pg-hstore`. For MySQL, `npm install mysql2`, etc.

• Error: Command 'stg' not found.

  cause The `stg` command (from a global install) is not in the system's PATH, or `npx` (for local install) is not available to execute it.
  fix If using locally, ensure `npx` is installed globally (`npm install -g npx`) or execute with `node ./node_modules/.bin/stg`. If using globally, ensure `npm install -g sequelize-typescript-generator` completed successfully and your global npm bin directory is in your system's PATH.

• SequelizeConnectionError: connect ECONNREFUSED <DB_HOST>:<DB_PORT>

  cause The generator failed to establish a connection to the database, likely due to incorrect host, port, credentials, or the database server being unavailable/inaccessible.
  fix Verify the database server is running, reachable from where the generator is executed, and that the provided `host`, `port`, `username`, `password`, and `database` credentials are correct and have appropriate network access.

• TypeError: (0 , sequelize_typescript_generator_1.generate) is not a function

  cause Attempting to use a CommonJS `require()` statement or an incorrect import syntax for an ES module-first library, or a bundling issue.
  fix Ensure you are using ES module imports: `import { generate } from 'sequelize-typescript-generator';`. If using CommonJS in a hybrid project, you might need `const { generate } = await import('sequelize-typescript-generator');` or configure your build system for proper ESM resolution.

Warnings

• breaking This library declares TypeScript version `^5.0.4` as a peer dependency. Using older or incompatible TypeScript versions might lead to compilation errors or unexpected type inference issues, especially with advanced features or strict mode.
  Fix: Ensure your project's `typescript` version meets the peer dependency requirement by running `npm install typescript@^5.0.4` or updating your `package.json`.
• gotcha The generator requires the appropriate database driver (e.g., `pg` for PostgreSQL, `mysql2` for MySQL) to be installed in your project. Failure to install the correct driver for your chosen dialect will result in runtime errors.
  Fix: Install the database driver for your dialect, e.g., `npm install -S pg pg-hstore` for PostgreSQL, `npm install -S mysql2` for MySQL, etc.
• gotcha When using `sequelize-typescript-generator` globally (`npm install -g`), automatic linting of generated models is not supported out-of-the-box. The `eslint` library does not support global plugins for this functionality.
  Fix: To enable linting with a global installation, ensure `typescript`, `eslint`, and `@typescript-eslint/parser` are installed locally in your project: `npm install -S typescript eslint @typescript-eslint/parser`.
• gotcha Generated models are a snapshot of your database schema at the time of generation. Any subsequent changes to your database schema (e.g., adding/removing columns, altering types, new tables) will *not* automatically update the generated models. You must re-run the generator to reflect these changes.
  Fix: Integrate the generator into your CI/CD pipeline or development workflow to rerun it whenever database schema migrations occur, ensuring models remain synchronized with the database.
• gotcha While the generator attempts to infer common associations, complex relationships or non-standard naming conventions might not be fully captured. In such cases, you might need to manually define associations via the `--associations-file` option or manually adjust the generated models.
  Fix: Review generated models carefully for complex associations. Use the `--associations-file` option (for CLI) or `associationsFile` option (programmatic) to provide explicit association definitions for challenging cases, or manually add them post-generation.

Install

• npm install sequelize-typescript-generator npm
• yarn add sequelize-typescript-generator yarn
• pnpm add sequelize-typescript-generator pnpm

Imports

• generate
  wrong:

  const generate = require('sequelize-typescript-generator');

  correct:

  import { generate } from 'sequelize-typescript-generator';

  This is the main function for programmatic model generation. The library primarily uses ES Modules.
• GeneratorOptions

  import type { GeneratorOptions } from 'sequelize-typescript-generator';

  Type definition for configuring the `generate` function programmatically.

Quickstart

Demonstrates programmatic generation of Sequelize TypeScript models from a PostgreSQL database, showing essential configuration and environment variable usage for credentials.

import { generate } from 'sequelize-typescript-generator';
import path from 'path';
import fs from 'fs';

async function runGenerator() {
  const outputDir = path.resolve(__dirname, 'generated-models');
  if (!fs.existsSync(outputDir)) {
    fs.mkdirSync(outputDir, { recursive: true });
  }

  try {
    await generate({
      dialect: 'postgres',
      host: process.env.DB_HOST ?? 'localhost',
      port: parseInt(process.env.DB_PORT ?? '5432', 10),
      database: process.env.DB_NAME ?? 'your_database_name',
      username: process.env.DB_USER ?? 'postgres',
      password: process.env.DB_PASSWORD ?? '',
      outDir: outputDir,
      schema: process.env.DB_SCHEMA ?? 'public', // Optional, for Postgres
      // tables: ['users', 'products'], // Optional: specify tables to generate
      // skipTables: ['audit_logs'], // Optional: specify tables to skip
      // indices: true, // Optional: include index annotations
      // strict: true, // Optional: enable strict mode
      // case: 'camel', // Optional: 'camel' | 'snake' | 'pascal'
      // associationsFile: path.resolve(__dirname, 'associations.json'), // Optional: define custom associations
    });
    console.log('Sequelize TypeScript models generated successfully!');
  } catch (error) {
    console.error('Error generating models:', error);
    process.exit(1);
  }
}

runGenerator();