CrossSchema

CrossSchema is a cross-platform database schema introspection library built on top of Knex.js. It allows you to retrieve schema metadata such as databases, tables, columns, primary keys, foreign keys, enums, and more — using a unified API across multiple relational database platforms.

Supports: MySQL, PostgreSQL, SQLite, SQL Server, Oracle DB (soon)

Features

• Unified interface for schema inspection
• Plug-and-play Knex instance injection
• Detailed column metadata: type, default, nullability, precision, autoincrement, enum values, etc.
• Works with modern versions of major SQL databases
• Discover primary keys, foreign keys, and constraints
• Lightweight, no runtime dependencies except Knex
• Zero dependencies beyond Knex
• Suitable for CLI tools, GUI database tools, code generators, and migrations

Supported Databases

| Database | NPM Package | | ---------------- | ----------- | | MySQL | mysql2 | | PostgreSQL | pg | | SQLite | sqlite3 | | SQL Server | tedious | | Oracle DB (soon) | oracledb |

Installation

npm install cross-schema

Requires knex and the appropriate database client (e.g. mysql2, pg, sqlite3, tedious, oracledb).

How to Usage

import knex from 'knex';
import CrossSchema from 'cross-schema';

const db = knex({
  client: 'mysql2',
  connection: {
    host: 'localhost',
    user: 'root',
    password: '',
    database: 'test_db',
  },
});

const cs = new CrossSchema('mysql', db);

// List database
const schemas = await cs.listDatabases();

// List tables
const tables = await cs.listTables();

// List views
const views = await cs.listViews();

// List columns
const columns = await cs.listColumns('table_name');

// List indexes
const indexes = await cs.listIndexes('table_name');

// List foreign keys
const fks = await cs.listConstraints('table_name');

// Get table schema
const tableSchema = await cs.getTableSchema('table_name');

// Get database version
const version = await cs.getDatabaseVersion();

API Reference

constructor(knexClient)

• Initializes the CrossSchema with a Knex client instance.

listDatabases(): Promise<string[]>

• Get a list of databases in the given connection

listTables(schema?: string): Promise<string[]>

• Get a list of tables in the specified schema

listViews(schema?: string): Promise<string[]>

• Get a list of views in the specified schema

listColumns(table: string, schema?: string): Promise<ColumnInfo[]>

• Retrieves detailed information about all columns in a given table.

listIndexes(table: string, schema?: string): Promise<IndexInfo[]>

• Retrieves index definitions from the specified table and schema.

listConstraints(table: string, schema?: string): Promise<ConstraintInfo[]>

• Retrieves foreign key constraints from a specific table.

getTableSchema(table: string, schema?: string): Promise<Schema[]>

• Retrieves the complete schema definition for a specific table, including: column metadata, primary key(s), auto-increment column, foreign keys (if any)

getDatabaseVersion(): Promise<string>

• Get the version of the connected database

Output Formats

ColumnInfo

{
  name: string,
  allowNull: boolean,
  autoIncrement: boolean,
  comment: string,
  dbType: string,
  type: string,
  rawType: string,
  defaultValue: any,
  enumValues: string[],
  isPrimaryKey: boolean,
  precision: number|null,
  scale: number|null,
  size: number|null,
  unsigned: boolean
}

IndexInfo

{
  name: string,              // Index name defined in the database
  columnName: string,       // Column name the index refers to
  isUnique: boolean,  // Whether the index enforces uniqueness
  isPrimaryKey: boolean,
  indexType: string
}

ConstraintInfo

{
  constraintName: string,
  columnName: string,
  referencedTableName: string,
  referencedColumnName: string,
  onUpdate: string,
  onDelete: string
}

Schema

{
  schemaName: string,
  tableName: string,
  primaryKeys: string[],
  sequenceName: string|null,
  indexes: IndexInfo[],
  foreignKeys: ConstraintInfo[],
  columns: ColumnInfo[]
}

Contributing

Thank you for considering contributing to CrossSchema!

To contribute:

1. Fork this repository.
2. Clone your fork:

   git clone https://github.com/didanurwanda/cross-schema.git
   cd cross-schema

3. Install dependencies:

   npm install

4. Make your changes in src/ folder.
5. Build the library:

   npm run build

6. Make sure the changes are working by running the example or writing tests.
7. Commit and push your changes, then open a Pull Request.

Note: Do not edit files in the dist/ folder manually. The build artifacts are generated by tsup and will be regenerated before publishing.

Development Scripts

| Command | Description | | --------------- | ---------------------------- | | npm install | Install all dependencies | | npm run build | Build the library to /dist |

Author

Created and maintained by Dida Nurwanda
[email protected]

CrossSchema is part of a broader effort to simplify metadata handling in backend tooling and developer utilities.

License

This project is licensed under the MPL-2.0. See the LICENSE file for more details.