Schemats

Common errors

• Error: self-signed certificate in certificate chain

  cause 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

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

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

Warnings

• breaking 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.
  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.
• breaking 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.
  Fix: Uninstall `mysql` if it was a direct dependency for `schemats` and install `mysql2` (`npm install mysql2`). Verify your MySQL connection string format.
• gotcha 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.
  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.
• gotcha 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.
  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`).

Install

• npm install schemats-v2 npm
• yarn add schemats-v2 yarn
• pnpm add schemats-v2 pnpm

Imports

• generateSchema
  wrong:

  import { generateSchema } from 'schemats';

  correct:

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

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

  import { Config } from 'schemats';

  correct:

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

  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.

Quickstart

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;
}