schemats-v2

library3.0.5jsnpmunverified

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.

database type-stubs

npm install schemats-v2

github ↗package ↗

INSTALL

IMPORT

SIG · SCHEMATS-V2

schemats-v2

databasejavascriptv3.0.5

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.

generateSchema

✓ import { generateSchema } from 'schemats/lib/typescript';

✗ import { generateSchema } from 'schemats';

For programmatic use, the core generation logic is exposed from the 'lib/typescript' path, not directly from the root 'schemats' package.

Config

✓ import { Config } from 'schemats/lib/config';

✗ import { Config } from 'schemats';

The configuration interface for programmatic schema generation is imported from the 'lib/config' module.

Schemats CLI

✓ schemats generate -c postgres://user@host/db -o types.ts

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.

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.

npm install -g schemats # PostgreSQL example: Generate types for the 'users' table from a local PostgreSQL database schemats generate -c postgres://postgres:password@localhost:5432/mydatabase -t users -o src/database/types/user.ts # MySQL example: Generate types for all tables in the 'public' schema from a local MySQL database schemats generate -c mysql://root:password@localhost:3306/mydatabase -s public -o src/database/types/all.ts // Example of how to use the generated types in your application // Assuming the generated file looks like: // export interface Users { id: number; username: string; last_logon: Date; } import * as dbTypes from './src/database/types/user'; interface MyUserRow extends dbTypes.Users { // Add any application-specific fields or methods if needed } // Example usage with a database client (e.g., pg-promise, knex, or direct pg) async function getUserById(id: number): Promise<MyUserRow | null> { // This is illustrative; actual DB query logic would go here const result: dbTypes.Users[] = await Promise.resolve([{ id: 1, username: 'testuser', password: 'hashedpassword', last_logon: new Date() }]); return result.length > 0 ? result[0] : null; }

schemats --version

Debug

Known issues

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

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.

affects: >=3.0.0

breakingThe `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.

fix

Uninstall `mysql` if it was a direct dependency for `schemats` and install `mysql2` (`npm install mysql2`). Verify your MySQL connection string format.

affects: >=3.0.0

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

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.

affects: >=1.0.0

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

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`).

affects: >=1.0.0

Errors

Common errors & fixes

Error: self-signed certificate in certificate chain

Occurs when connecting to a PostgreSQL database with SSL enabled and a self-signed certificate, without explicitly trusting it.

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

Error: Command failed with exit code 1

Generic error often indicating an issue with database connection parameters, insufficient permissions, or an incorrectly formatted connection string.

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.

No tables or schemas were specified for type generation. Please specify a table (-t) or schema (-s).

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.

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.

Upgrade

Version history

3.0.5latest on npm

Audit

Dependencies

pgrequiredRequired for connecting to PostgreSQL databases to extract schema information.

mysql2requiredRequired for connecting to MySQL databases to extract schema information. This replaces the older 'mysql' package.

Agent activity

24 hits · last 30 days

node