@axiomdb/schema

Schema introspection and type generation CLI for AxiomDB.

Installation

npm install @axiomdb/schema

Overview

Introspects your database schema and generates TypeScript types for use with AxiomDB queries. Supports PostgreSQL, MySQL, and MSSQL connections as schema sources.

CLI Usage

npx axiomdb-schema generate [options]

Options

| Flag | Default | Description | |------|---------|-------------| | --adapter <name> | postgres | Schema adapter to use (postgres, mysql, mssql, or a custom adapter) | | --out <path> | axiomdb-schema.d.ts | Output file path for the generated type declarations | | --cwd <path> | . | Working directory for the adapter | | --connection-string <url> | — | Database connection string (required for built-in adapters) | | --schema <name> | public / dbo | Database schema to introspect | | --no-relations | — | Exclude foreign key relation metadata from output | | -h, --help | — | Show help |

Examples

# PostgreSQL
npx axiomdb-schema generate --adapter postgres \
  --connection-string postgres://user:pass@localhost:5432/mydb

# MySQL
npx axiomdb-schema generate --adapter mysql \
  --connection-string mysql://user:pass@localhost:3306/mydb

# MSSQL
npx axiomdb-schema generate --adapter mssql \
  --connection-string mssql://user:pass@localhost:1433/mydb

# Custom output path and schema
npx axiomdb-schema generate --adapter postgres \
  --connection-string postgres://localhost/mydb \
  --out src/generated/axiomdb-schema.d.ts \
  --schema my_schema

Generated output

The CLI generates two files:

1. axiomdb-schema.d.ts — TypeScript type declarations used by the TypeScript plugin and your IDE for type inference.
2. axiomdb-schema.json — JSON schema metadata used by @axiomdb/babel-plugin for runtime validation and the TypeScript language service plugin.

Generated type structure

The .d.ts file declares a module with the following interfaces:

declare module '@axiomdb/schema' {
  // Row types for each table (all columns required)
  export interface Tables {
    users: {
      id: number;
      name: string;
      email: string;
      active: boolean;
      created_at: Date;
    };
    orders: {
      id: number;
      user_id: number;
      total: number;
      status: string;
      created_at: Date;
    };
  }

  // Insert types (columns with defaults or nullable are optional)
  export interface InsertTypes {
    users: {
      id?: number;          // has default (serial/autoincrement)
      name: string;
      email: string;
      active?: boolean;     // has default
      created_at?: Date;    // has default
    };
    orders: {
      id?: number;
      user_id: number;
      total: number;
      status?: string;      // has default
      created_at?: Date;
    };
  }

  // Foreign key relationships (omitted with --no-relations)
  export interface Relations {
    orders: {
      user_id: { references: 'users'; column: 'id' };
    };
  }

  // Type helpers
  export type TableName = keyof Tables;
  export type ColumnsOf<T extends TableName> = keyof Tables[T];
  export type RowType<T extends TableName> = Tables[T];
}

Adapters

Built-in adapters:

• @axiomdb/schema/adapters/postgres — Direct PostgreSQL introspection
• @axiomdb/schema/adapters/mysql — Direct MySQL introspection
• @axiomdb/schema/adapters/mssql — Direct MSSQL introspection

Custom adapters

If --adapter <name> is not a built-in, the CLI tries to import @axiomdb/schema-<name> and calls its default export (or <name>Adapter named export) as a factory function. The factory must return a SchemaAdapter:

interface SchemaAdapter {
  name: string;
  introspect(options: {
    cwd: string;
    connectionString?: string;
    schema?: string;
  }): Promise<IntrospectedSchema>;
}

Install a custom adapter as a package (e.g., npm install @axiomdb/schema-sqlite) and use it with --adapter sqlite.

License

MIT