pg-structure

# Concepts

# Database Objects vs. pg-structure Objects

In this documentation database objects means database parts provided by PostgreSQL RDMS such as table, column, constraint etc. Sometimes those objects are simply refereed as database as a general term in this documentation.

pg-structure objects means object instances provided by pg-structure classes such as DB, Schema, Table, Column etc.

# Objects (Instances)

In pg-structure database objects such as Schema, Column etc. are represented by JavaScript objects such as Schema, Column etc.

// db is an pg-structure DB object.
const db = await pgStructure({ database: "db", user: "u", password: "pass" }, { includeSchemas: ["public"] });

# Attributes

pg-structure objects' attributes are designed to be read only and formed as nouns. Generally:

# Methods

pg-structure also provides methods to access some database details.

Methods are named as verbs like table.getForeignKeysTo().

# get shortcut

DB, Schema, Table instances provide get method for a shortcut.

For example columnA, columnB and columnC below has same object:

const columnA = db.get("account.user_name"); // Uses default `public` schema.
const columnB = db.get("public.account.user_name");
const columnC = db.schemas.get("public").tables.get("account").columns.get("user_name");

# Collections

Collections in pg-structure are provided using IndexableArray (opens new window). IndexableArray (opens new window) inherits Array class and therefore provide all methods and attributes of Array base class in addition to get(), getMaybe(), getAll(), has() methods to access elements like JS Object or Map.

Please note IndexableArray (opens new window) throws exception if get() does not found required element. To get undefined use getMaybe().

const columnNames = table.columns.map((c) => c.name); // Base array map.
const column = table.columns.get("surname"); // Gets surname column.
const unknown = table.columns.get("unknown_column"); // Throws exception
const undef = table.columns.getMaybe("unknown_column"); // Undefined

# Relation Classes vs. Foreign Key Constraint

pg-structure provides ForeignKey object which represents directly PostgreSQL foreign key constraints.

Sometimes developers and ORM users need to have more information about relations than available in foreign key constraints. For example many to many relationships and many to one relationships are not available in database engine. pg-structure provides one to many, many to one and many to many relation classes to address those needs.

# Description Data / Comment Data

PostgreSQL objects holds free form text in their description. pg-structure offers some help to store extra data in database objects' description as JSON. pg-structure automatically parses JSON data between [pg-structure]and [/pg-structure] tags. Tags are case-insensitive. Only one pg-structure object is processed per description. Tag name may be configured using pgStructure() options.

For maximum comfort JSON parsing is made by JSON5 (opens new window). It is a relaxed JSON parser. See JSON5 (opens new window) page for details.

// Assuming account table has description below:
// Account table holds info about companies. [pg-structure]{ someData: 'Some value here' }[/pg-structure]
const data = accountTable.descriptionData; // -> { someData: 'Some value here' }

← Examples →