pg-structure is a TypeScript-first library designed to reverse engineer a PostgreSQL database schema into a detailed JavaScript object structure. It provides an API to programmatically access and navigate details about databases, schemas, tables, columns, foreign keys, relations, indexes, and custom types. The current stable version is 7.15.3. Releases are somewhat infrequent, with several bug fix releases in 2024 and feature additions in 2023 and prior years, indicating active maintenance. Its key differentiator is offering a comprehensive, introspected object model of the entire PostgreSQL schema, which is useful for ORM generators, database documentation tools, schema analysis scripts, or custom code generation, rather than just basic table listings. It handles complex PostgreSQL features like custom types and generated columns.
npm install pg-structureVerified import paths — ran on the pinned version, not inferred.
This example connects to a PostgreSQL database, reverse engineers its structure, and demonstrates how to access specific tables, columns, their types, indexes, and relationships using the programmatic API.
Refer to the specific major version upgrade guide (if available) or the GitHub changelog for detailed migration steps and API changes.
Utilize the `includeSchemas` and `includeTables` options during introspection to limit the scope to only the necessary parts of the database. Consider caching the generated structure in production environments.
Upgrade to `pg-structure@7.15.3` or a newer version to ensure that schema names containing underscores are correctly handled and introspected.
Always use secure methods for managing credentials, such as dedicated secrets management services (e.g., AWS Secrets Manager, HashiCorp Vault), encrypted configuration files, or robust environment variable management. Avoid hardcoding credentials in source code.
Upgrade to `pg-structure@7.13.1` or newer to ensure accurate and complete introspection of all PostgreSQL triggers, regardless of their `WHEN` clause status.
Ensure the PostgreSQL server is running and listening on the correct host and port. Verify network connectivity and any relevant firewall settings. Double-check `host` and `port` in your connection configuration.
Correct the `database` name in your connection configuration to match an existing PostgreSQL database. If the database is truly missing, create it first.
Verify that the table name is correct and exists in the database. Check the `includeSchemas` and `includeTables` options passed to `pgStructure` to ensure the table is part of the introspection scope. Add null/undefined checks before accessing properties like `.columns`.
Run `npm install pg-structure` or `yarn add pg-structure` to add the package to your project. Ensure your project's `tsconfig.json` (for TypeScript) or build configuration correctly resolves modules.