knex-types

library0.5.0jsnpmunverified

Knex-types is an open-source utility module designed for Knex.js, focused on generating TypeScript definitions directly from a PostgreSQL database schema. Its primary purpose is to enhance type safety and developer experience when working with Knex.js by providing accurately typed database entities. The current stable version is 0.5.0, with minor feature updates and dependency upgrades released periodically, indicating an active maintenance and development cycle. Key differentiators include its tight integration with Knex.js, specific support for PostgreSQL features like `int2` arrays and `citext`, and options for schema inclusion/exclusion and custom prefixes/suffixes for generated files. It helps prevent runtime errors by catching schema-related type mismatches at compile-time, a common challenge in ORM-less database interactions.

database type-stubs

npm install knex-types

github ↗package ↗

INSTALL

IMPORT

SIG · KNEX-TYPES

knex-types

databasejavascriptv0.5.0

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.

updateTypes

✓ import { updateTypes } from 'knex-types';

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

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

KnexFactory

✓ import KnexFactory from 'knex';

✗ import { knex } 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.

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

knex-types --version

Debug

Known issues

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

affects: >=0.2.0

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.

affects: >=0.1.0

gotchaThe 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';`.

affects: >=0.1.0

Errors

Common errors & fixes

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

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

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.

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';`.

Upgrade

Version history

0.5.0latest on npm

Audit

Dependencies

knexrequiredRequired runtime dependency for database connection and query building. Knex-types uses a Knex instance to introspect the database schema.

Agent activity

33 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/kriasoft/knex-types ↗

packagehttps://www.npmjs.com/package/knex-types ↗