{"id":16681,"library":"schemats-v2","title":"Schemats","description":"Schemats is a command-line interface (CLI) tool that automatically generates TypeScript interface definitions directly from existing SQL database schemas. It supports PostgreSQL and MySQL databases, allowing developers to ensure static type checking and autocompletion for database query results within TypeScript applications. The current stable version is 3.0.5, with major version updates occurring when significant architectural changes or dependency upgrades necessitate breaking changes to its API or CLI. Its primary differentiation lies in generating types directly from the live database schema, which helps keep type definitions synchronized with the actual database structure without manual intervention, supporting a 'database-first' approach to type safety in data access layers. It can generate types for individual tables or an entire schema and supports configuration via a JSON file.","status":"active","version":"3.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/devteck-io/schemats","tags":["javascript","postgres","schema","typescript","sql"],"install":[{"cmd":"npm install schemats-v2","lang":"bash","label":"npm"},{"cmd":"yarn add schemats-v2","lang":"bash","label":"yarn"},{"cmd":"pnpm add schemats-v2","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for connecting to PostgreSQL databases to extract schema information.","package":"pg","optional":false},{"reason":"Required for connecting to MySQL databases to extract schema information. This replaces the older 'mysql' package.","package":"mysql2","optional":false}],"imports":[{"note":"For programmatic use, the core generation logic is exposed from the 'lib/typescript' path, not directly from the root 'schemats' package.","wrong":"import { generateSchema } from 'schemats';","symbol":"generateSchema","correct":"import { generateSchema } from 'schemats/lib/typescript';"},{"note":"The configuration interface for programmatic schema generation is imported from the 'lib/config' module.","wrong":"import { Config } from 'schemats';","symbol":"Config","correct":"import { Config } from 'schemats/lib/config';"},{"note":"Schemats is primarily designed as a CLI tool, installed globally, and invoked via the 'schemats' command. Direct programmatic import of the CLI entry point is not typically done by end-users.","symbol":"Schemats CLI","correct":"schemats generate -c postgres://user@host/db -o types.ts"}],"quickstart":{"code":"npm install -g schemats\n\n# PostgreSQL example: Generate types for the 'users' table from a local PostgreSQL database\nschemats generate -c postgres://postgres:password@localhost:5432/mydatabase -t users -o src/database/types/user.ts\n\n# MySQL example: Generate types for all tables in the 'public' schema from a local MySQL database\nschemats generate -c mysql://root:password@localhost:3306/mydatabase -s public -o src/database/types/all.ts\n\n// Example of how to use the generated types in your application\n// Assuming the generated file looks like:\n// export interface Users { id: number; username: string; last_logon: Date; }\n\nimport * as dbTypes from './src/database/types/user';\n\ninterface MyUserRow extends dbTypes.Users {\n  // Add any application-specific fields or methods if needed\n}\n\n// Example usage with a database client (e.g., pg-promise, knex, or direct pg)\nasync function getUserById(id: number): Promise<MyUserRow | null> {\n  // This is illustrative; actual DB query logic would go here\n  const result: dbTypes.Users[] = await Promise.resolve([{ id: 1, username: 'testuser', password: 'hashedpassword', last_logon: new Date() }]);\n  return result.length > 0 ? result[0] : null;\n}","lang":"typescript","description":"This quickstart demonstrates how to install Schemats globally, generate TypeScript interfaces from a PostgreSQL or MySQL database schema using CLI commands, and illustrates basic usage of the generated types within a TypeScript application."},"warnings":[{"fix":"Review the new documentation for updated CLI arguments and programmatic API usage. Existing build scripts and direct imports from 'schemats' (if any) will likely need adjustments, specifically checking the new `lib/typescript` path for core functions and `lib/config` for configuration types. Ensure `pg` is updated to a compatible `^8.x` version and `mysql2` is used for MySQL connections.","message":"Version 3.0.0 introduced significant breaking changes. The project underwent a full TypeScript rewrite and a change in maintainership (from SweetIQ to devteck-io). This included a refactor of the internal programmatic API and updates to CLI argument parsing.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Uninstall `mysql` if it was a direct dependency for `schemats` and install `mysql2` (`npm install mysql2`). Verify your MySQL connection string format.","message":"The `mysql` dependency was replaced by `mysql2` in version 3.0.0 for improved compatibility and features. Projects relying on `schemats` for MySQL type generation must ensure `mysql2` is installed and the connection string is compatible.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"After generation, always inspect the output `.ts` file to confirm type correctness. For specific type overrides, investigate Schemats' configuration options, potentially using `--typesFile` for custom type mappings via JSDoc comments or other configuration parameters if available.","message":"Default type mappings from SQL to TypeScript (e.g., `TIMESTAMP` to `Date`, `TEXT` to `string`) might change between major versions or be configurable. Always verify the generated types align with your expected TypeScript representations, especially for complex or custom SQL types.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Place `schemats.json` in the root of your project or the directory from which you run the `schemats generate` command. Alternatively, provide the full path to the config file if the CLI supports such an option (check `schemats --help`).","message":"When using `schemats.json` for configuration, ensure the file is in the current working directory where the `schemats generate` command is executed, or specify its path explicitly. Misplaced config files will lead to default behavior or errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For development, you can disable SSL verification by adding `?ssl=false` to your PostgreSQL connection string (`-c postgres://user:pass@host:port/db?ssl=false`). For production, properly configure SSL certificates or set `PGSSLMODE=no-verify` in your environment (though this is less secure).","cause":"Occurs when connecting to a PostgreSQL database with SSL enabled and a self-signed certificate, without explicitly trusting it.","error":"Error: self-signed certificate in certificate chain"},{"fix":"Double-check your database connection string for correctness (username, password, host, port, database name). Verify that the database server is running and accessible from where you're running `schemats`. Ensure the provided user has sufficient permissions to access the schema and tables you are trying to generate types for.","cause":"Generic error often indicating an issue with database connection parameters, insufficient permissions, or an incorrectly formatted connection string.","error":"Error: Command failed with exit code 1"},{"fix":"Specify the `-t <table_name>` argument to generate types for a single table, or `-s <schema_name>` to generate types for all tables in a specific schema. If you intend to generate all tables in the default 'public' schema, you can usually omit `-t` and `-s`, but ensure your connection string points to the correct database and the default behavior is understood.","cause":"The `schemats generate` command was run without specifying either a target table (`-t`) or a target schema (`-s`), and no `schemats.json` was found to provide these defaults.","error":"No tables or schemas were specified for type generation. Please specify a table (-t) or schema (-s)."}],"ecosystem":"npm"}