PostgreSQL Runtime Guide

PostgresReflector is the runtime entry point for PostgreSQL projects.

Typical Workflow

1. Define entities in code.
2. Create a reflector with a PostgreSQL connection string or compatible client.
3. Run planReflect(...) if you want a preview of what will happen.
4. Run reflect(...) to apply the approved changes.
5. Use the PostgreSQL query builders for application queries.

What PostgreSQL Runtime Covers

• schema inspection and entity generation
• additive and destructive schema synchronization
• approval and change-ticket gates for destructive operations
• dependency-aware orchestration across views, foreign keys, routines, and triggers
• trigger and view management
• function and procedure lifecycle management through StoreProcedure

Good Entry Points To Search

• PostgresReflector
• StoreProcedure
• PostgresQueryBuilder
• PostgresInsertBuilder
• PostgresUpdateBuilder
• PostgresDeleteBuilder
• inspectPostgresSchema
• generatePostgresSchemaOutput

Planning Before Applying

If your workflow has operational controls, start with planReflect(...) and inspect the returned preview types before calling reflect(...).

That is the safest way to understand:

• which tables will be created
• whether a rebuild is required
• which approved column renames will be applied during the rebuild copy step
• whether destructive approval is needed
• whether production protections will block the action

Approved Column Renames

PostgreSQL rebuild plans can preserve data for explicit renames when you approve the mapping up front.

const db = new PostgresReflector(connectionString, {
	approvedColumnRenames: [
		{ table: "public.accounts", from: "name", to: "display_name" },
	],
	approvedDestructiveTableChanges: ["public.accounts"],
	changeTicketId: "CHG-3108",
});
Copy

planReflect(...) exposes the mapping in preview.tables[].columnRenames, and reflect(...) copies data with explicit SELECT old_column AS new_column projections during the rebuild.

Stored Procedures As Versioned Code

Use StoreProcedure when you want procedural PostgreSQL logic to live in versioned TypeScript classes instead of ad hoc SQL files.

Inspector Fidelity Notes

The current PostgreSQL inspector preserves standard indexes, expression indexes, and partial index predicates in generated entity classes.

That means generated metadata can now round-trip patterns such as:

• mixed column-plus-expression indexes
• filtered uniqueness with WHERE ...
• expression-only indexes through index([], { expressions: [...] })

Some PostgreSQL-specific index details still require manual review during legacy onboarding.

• operator classes are not emitted into generated index(...) metadata
• INCLUDE (...) columns are not reconstructed in the generated entity layer
• storage parameters, tablespaces, and other method-specific options are not currently modeled

Compatibility Contract

Use DATABASE_ENGINE.md as the stricter compatibility contract when you need exact cross-engine status for orchestration depth, returning(...), routines, triggers, views, and governance features.