Knex.js TypeScript Type Generator

Common errors

• Error: Cannot find module 'knex' from 'knex-types'

  cause The 'knex' package is a peer dependency of 'knex-types' and must be installed separately in your project.
  fix Install Knex.js in your project: `npm install knex` (or `yarn add knex`). If you're using TypeScript, Knex ships its own types, so `@types/knex` is typically not needed.

• Property 'EntityRecord' does not exist on type '...'

  cause The `EntityRecord` type was deprecated in `knex-types` v0.2.0 and replaced with `Knex.DbRecord<Entity>`.
  fix Update your type references from `EntityRecord<TableName>` to `Knex.DbRecord<TableName>` and ensure `import { Knex } from 'knex';` is present.

• SyntaxError: Named export 'knex' not found. The requested module 'knex' is a CommonJS module, which may not support named exports.

  cause This error occurs when trying to `import { knex } from 'knex';` in an ES Module environment, as the main Knex factory function is primarily a default export in ESM contexts.
  fix Change your import statement for the Knex factory to `import KnexFactory from 'knex';`.

Warnings

• breaking Version 0.2.0 introduced a breaking change by deprecating the `EntityRecord` types. Developers should update their code to use `Knex.DbRecord<Entity>` instead for improved type consistency and adherence to Knex's own type definitions.
  Fix: Replace all instances of `EntityRecord` with `Knex.DbRecord<YourTableName>` where `YourTableName` is the interface representing your table's structure.
• gotcha `knex-types` is specifically designed for PostgreSQL databases. While Knex.js supports multiple databases, this library's schema introspection is tailored for PostgreSQL. Using it with other database systems will likely result in incorrect or incomplete type generation.
  Fix: Ensure your project is using PostgreSQL as its database. For other database systems, explore alternative type generation tools or manually create type definitions.
• gotcha The documentation and older examples often show `require()` syntax for both `knex` and `knex-types`. However, in modern TypeScript and ESM-first Node.js projects, `import` statements are preferred. Incorrect import styles (e.g., named import for the Knex factory) can lead to runtime errors.
  Fix: For `knex-types`, use `import { updateTypes } from 'knex-types';`. For the Knex factory function, use `import KnexFactory from 'knex';` and for Knex types, `import { Knex } from 'knex';`.

Install

• npm install knex-types npm
• yarn add knex-types yarn
• pnpm add knex-types pnpm

Imports

• updateTypes
  wrong:

  const { updateTypes } = require('knex-types');

  correct:

  import { updateTypes } from 'knex-types';

  While the quickstart example uses CommonJS 'require', modern TypeScript/ESM projects should prefer named import syntax for 'knex-types'.
• KnexFactory
  wrong:

  import { knex } from 'knex';

  correct:

  import KnexFactory from 'knex';

  The Knex initialization function is typically imported as a default export in ESM. Attempting to use a named import `{ knex }` can lead to issues in pure ESM environments, especially with older Knex versions.
• Knex (Type)

  import { Knex } from 'knex';

  This named import is used specifically for the TypeScript `Knex` namespace, providing access to types like `Knex.DbRecord<Entity>` for advanced type annotations.

Quickstart

This quickstart demonstrates how to initialize Knex and then use `knex-types` to generate TypeScript definition files from a PostgreSQL database schema, including common configuration options.

import KnexFactory, { Knex } from 'knex';
import { updateTypes } from 'knex-types';

// Assuming knexfile.ts exports a Knex configuration object
// Or you can directly define the config here
const knexConfig = {
  client: 'pg',
  connection: {
    host: process.env.DB_HOST ?? 'localhost',
    user: process.env.DB_USER ?? 'postgres',
    password: process.env.DB_PASSWORD ?? '',
    database: process.env.DB_NAME ?? 'mydatabase',
  },
};

const db: Knex = KnexFactory(knexConfig);

updateTypes(db, {
  output: './src/types/db.ts',
  schema: ['public'], // default schema to inspect
  exclude: ['knex_migrations', 'knex_migrations_lock'], // tables to ignore
  prefix: `// Generated by knex-types on ${new Date().toISOString()}\n`, // custom header
})
  .then(() => {
    console.log('TypeScript types generated successfully!');
    return db.destroy();
  })
  .catch((err) => {
    console.error('Error generating types:', err);
    return db.destroy().then(() => process.exit(1));
  });