introspectron

4.11.8 verified Sat Apr 25 auth: no javascript

Introspectron introspects a PostgreSQL database and generates a typed SDK with GraphQL, REST, or direct SQL endpoints. The current stable version is 4.11.8, released regularly on npm. It differentiates by offering multiple output formats (GraphQL schema, REST endpoints, TypeScript SDK) from a single introspection, supporting Graphile Engine for advanced schema generation. It requires a running PostgreSQL instance and outputs code for both Node.js and browser environments.

Common errors

error Error: Cannot find module 'pg' ↓

cause Missing peer dependency 'pg'

fix

Run npm install pg

error TypeError: introspectron is not a function ↓

cause Incorrect import: using default import instead of named import

fix

Use import { introspectron } from 'introspectron'

error Error: Database connection failed: password authentication failed for user ↓

cause Invalid database credentials in connection string

fix

Check DATABASE_URL environment variable or pool config

Warnings

breaking In v4, the output format changed from JSON string to an object with 'schema' and 'sdk' properties. ↓

fix Access result.schema instead of the whole result.

deprecated The 'introspection' function is deprecated in favor of 'introspectron'. ↓

fix Use the 'introspectron' named export instead.

gotcha The introspection requires a database connection with read access to system catalogs. Ensure the user has appropriate permissions. ↓

fix Grant SELECT on pg_catalog tables to the user.

breaking Node.js 12 is no longer supported; requires Node.js 14 or higher. ↓

fix Upgrade Node.js to version 14 or above.

gotcha The 'watch' option in v4+ returns a WebSocket URL instead of a polling endpoint. ↓

fix Handle WebSocket connections when using watch: true.

Install

npm install introspectron

yarn add introspectron

pnpm add introspectron

Imports

introspectron
wrong
```
const introspectron = require('introspectron')
```
correct
```
import { introspectron } from 'introspectron'
```
ESM import is the standard for v4; CommonJS require works but is not recommended.

buildSchema

wrong

import buildSchema from 'introspectron/buildSchema'

correct

import { buildSchema } from 'introspectron'

buildSchema is a named export, not a default export.

generateSDK

wrong

import { generateSdk } from 'introspectron'

correct

import { generateSDK } from 'introspectron'

Note the capitalization: generateSDK, not generateSdk.

IntrospectionOptions

wrong

import { IntrospectionOptions } from 'introspectron'

correct

import type { IntrospectionOptions } from 'introspectron'

For type-only imports, use the 'type' modifier to avoid runtime bundling.

Quickstart

Introspects a PostgreSQL database and logs the generated GraphQL schema.

import { introspectron } from 'introspectron';
import { Pool } from 'pg';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL ?? 'postgres://localhost/mydb',
});

async function main() {
  const result = await introspectron(pool, {
    schemas: ['public'],
    output: 'graphql',
    watch: false,
  });
  console.log(JSON.stringify(result.schema, null, 2));
}

main().catch(console.error);