{"id":11213,"library":"knex-schema-inspector","title":"Knex Schema Inspector","description":"Knex Schema Inspector is a utility library designed to extract detailed information about existing database schemas. It leverages an initialized Knex.js instance to query metadata from various relational databases, including PostgreSQL, MySQL, MS SQL, SQLite, and OracleDB. The current stable version is 3.1.0, with major versions released approximately annually, indicating an active development and maintenance cadence. Its key differentiator is its deep integration with Knex, allowing developers to use their existing Knex configurations to introspect database structures, retrieve table names, column details, primary keys, and foreign key relationships across a wide range of SQL dialects. It ships with TypeScript types, facilitating robust development with type safety. It does not provide migration or schema modification capabilities, focusing solely on schema introspection.","status":"active","version":"3.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/knex/knex-schema-inspector","tags":["javascript","sql","knex","schema","mysql","postgresql","sqlite3","typescript"],"install":[{"cmd":"npm install knex-schema-inspector","lang":"bash","label":"npm"},{"cmd":"yarn add knex-schema-inspector","lang":"bash","label":"yarn"},{"cmd":"pnpm add knex-schema-inspector","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime peer dependency for database connection and query building; requires knex@2 or newer since knex-schema-inspector v2.0.0.","package":"knex","optional":false}],"imports":[{"note":"The library exports a default function. Type declarations indicate a default export for direct use. While CommonJS `require` *might* work, ESM `import` is the primary and recommended method, especially with TypeScript.","wrong":"import { schemaInspector } from 'knex-schema-inspector';\nconst schemaInspector = require('knex-schema-inspector');","symbol":"schemaInspector","correct":"import schemaInspector from 'knex-schema-inspector';"},{"note":"When initializing Knex, the primary `Knex` constructor is typically imported as a default export, though `knex` package might have named exports for specific types/utilities.","wrong":"import { Knex } from 'knex';","symbol":"Knex","correct":"import Knex from 'knex';"},{"note":"Type imports are crucial for type safety when working with the schema information returned by the inspector. `Column` is an interface, not a runtime value, so use `import type`.","wrong":"import { Column } from 'knex-schema-inspector';","symbol":"Column","correct":"import type { Column } from 'knex-schema-inspector';"}],"quickstart":{"code":"import Knex from 'knex';\nimport schemaInspector from 'knex-schema-inspector';\n\n// Initialize Knex with your database configuration\nconst database = Knex({\n  client: 'mysql',\n  connection: {\n    host: process.env.DB_HOST ?? '127.0.0.1',\n    user: process.env.DB_USER ?? 'root',\n    password: process.env.DB_PASSWORD ?? '',\n    database: process.env.DB_NAME ?? 'myapp_test',\n    charset: 'utf8',\n  },\n});\n\n// Initialize the schema inspector with the Knex instance\nconst inspector = schemaInspector(database);\n\nasync function inspectDatabase() {\n  try {\n    const tables = await inspector.tables();\n    console.log('Tables:', tables);\n\n    if (tables.length > 0) {\n      const firstTableInfo = await inspector.tableInfo(tables[0]);\n      console.log(`Info for table '${tables[0]}':`, firstTableInfo);\n\n      const columns = await inspector.columns(tables[0]);\n      console.log(`Columns in table '${tables[0]}':`, columns);\n    }\n  } catch (error) {\n    console.error('Error inspecting database:', error);\n  } finally {\n    await database.destroy(); // Always remember to destroy the Knex connection\n  }\n}\n\ninspectDatabase();","lang":"typescript","description":"This quickstart initializes Knex, creates a schema inspector instance, and then logs all table names, detailed information for the first table found, and all columns within that table. It includes environment variable placeholders for secure database connection and proper resource cleanup."},"warnings":[{"fix":"Review the `tedious` v15 release notes (https://github.com/tediousjs/tedious/releases/tag/v15.0.0) and adjust your Knex configuration or application logic if you are using MS SQL and encounter unexpected behavior.","message":"Starting with v3.0.0, the underlying `tedious` driver (used for MS SQL) was updated to v15. This update introduces changes to some default behaviors in how MS SQL connections are handled and queried. Users should consult the `tedious` v15 release notes for potential impacts on existing MS SQL implementations.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your project's `knex` dependency is updated to `knex@2` or a later compatible version (e.g., `npm install knex@latest` or `yarn add knex@latest`).","message":"Version 2.0.0 introduced a breaking change requiring `knex@2` or newer as a peer dependency. Older versions of Knex will not be compatible.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update your application logic to expect and parse default values as strings. If you need a different type, you will need to cast or convert the string representation explicitly.","message":"Since v2.0.0, default values for columns are consistently returned as strings across all supported databases, even if they represent numeric or boolean types in the database.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"When working with MySQL, rely on the `connection.database` setting in your Knex configuration rather than attempting to use the `schema` parameter for database selection within the inspector.","message":"In MySQL, the concepts of 'schema' and 'database' are often used interchangeably. The `schema` parameter in methods like `withSchema()` is not officially supported by Knex Schema Inspector for the MySQL dialect, meaning it might not behave as expected or might be ignored.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Avoid relying on `comment` metadata for MS SQL databases. If you need to store descriptive metadata, consider alternative approaches such as dedicated documentation or a separate metadata table.","message":"MS SQL does not inherently support comments for tables or columns in the same way other databases like Postgres do. Therefore, `comment` fields in `Table` or `Column` info objects will typically be `null` or undefined when inspecting an MS SQL database.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use the correct ESM default import syntax: `import schemaInspector from 'knex-schema-inspector';`","cause":"Attempting to import `schemaInspector` as a named export or using a CommonJS `require` call on an ESM default export.","error":"TypeError: inspector is not a function"},{"fix":"Ensure your Knex instance is fully configured and connected before passing it to `schemaInspector`. Example: `const database = Knex({ client: 'pg', connection: {...} });`","cause":"The Knex instance passed to `schemaInspector` was not properly configured or initialized (e.g., missing `client` in the Knex constructor options).","error":"Error: Knex client must be initialized with a 'client' option."},{"fix":"Upgrade your `knex` dependency to version 2.x or newer: `npm install knex@latest` or `yarn add knex@latest`.","cause":"The project's `knex` dependency is an older version (1.x) which is incompatible with `knex-schema-inspector` v2.0.0 and later.","error":"Error: knex-schema-inspector requires knex@^2.0.0. Current version is 1.x.x."},{"fix":"Parse the `default_value` string to the desired type manually. For example, `Number(columnInfo.default_value)` or `columnInfo.default_value === 'true'`.","cause":"Since `knex-schema-inspector` v2.0.0, all `default_value` fields are returned as strings, regardless of their original database type.","error":"Property 'default_value' is a string but expected number/boolean."}],"ecosystem":"npm"}