meadow-connection-postgresql 1.0.0 → 1.0.2

package/docs/architecture.md

@@ -0,0 +1,168 @@
+# Architecture
+
+## System Overview
+
+The PostgreSQL connector bridges Meadow's data access abstraction with the `pg` (node-postgres) driver. It follows the Fable service provider pattern, providing connection pool management and SQL DDL generation.
+
+```mermaid
+graph TB
+	subgraph Application Layer
+		APP[Application Code]
+		MEA[Meadow ORM]
+		FH[FoxHound Query Dialect]
+	end
+	subgraph Connection Layer
+		MCP["meadow-connection-postgresql<br/>(MeadowConnectionPostgreSQL)"]
+		POOL[pg.Pool]
+	end
+	subgraph PostgreSQL Server
+		PG[(PostgreSQL)]
+	end
+	APP --> MEA
+	MEA --> FH
+	FH --> MCP
+	MCP --> POOL
+	POOL --> PG
+```
+
+## Connection Lifecycle
+
+```mermaid
+sequenceDiagram
+	participant App as Application
+	participant Fable as Fable
+	participant MCP as MeadowConnectionPostgreSQL
+	participant PG as pg.Pool
+	participant Server as PostgreSQL Server
+
+	App->>Fable: new libFable(settings)
+	App->>Fable: addAndInstantiateServiceType()
+	Fable->>MCP: constructor(fable, options)
+	MCP->>MCP: Read PostgreSQL config
+	MCP->>MCP: Normalize property names
+	Note over MCP: Server→host, Port→port, etc.
+
+	alt Auto-Connect Enabled
+		MCP->>MCP: connect()
+	end
+
+	App->>MCP: connectAsync(callback)
+
+	alt Already Connected
+		MCP-->>App: callback(null, pool)
+	else Not Connected
+		MCP->>PG: new pg.Pool(settings)
+		PG->>Server: Establish Connection Pool
+		MCP->>MCP: connected = true
+		MCP-->>App: callback(null, pool)
+	end
+
+	App->>MCP: pool (getter)
+	MCP-->>App: pg.Pool instance
+	App->>PG: pool.query(sql, params, callback)
+	PG->>Server: Execute query
+	Server-->>PG: Result rows
+	PG-->>App: callback(error, result)
+```
+
+## Service Provider Model
+
+`MeadowConnectionPostgreSQL` extends `fable-serviceproviderbase`, providing standard lifecycle integration with the Fable ecosystem.
+
+```mermaid
+classDiagram
+	class FableServiceProviderBase {
+		+fable
+		+options
+		+log
+		+serviceType
+	}
+	class MeadowConnectionPostgreSQL {
+		+serviceType: "MeadowConnectionPostgreSQL"
+		+connected: boolean
+		-_ConnectionPool: pg.Pool
+		+connect()
+		+connectAsync(fCallback)
+		+pool: pg.Pool
+		+createTable(schema, fCallback)
+		+createTables(schema, fCallback)
+		+generateCreateTableStatement(schema)
+		+generateDropTableStatement(name)
+	}
+	FableServiceProviderBase <|-- MeadowConnectionPostgreSQL
+```
+
+## Settings Flow
+
+The connector normalizes Meadow-style property names to the native `pg` driver format:
+
+```mermaid
+flowchart LR
+	subgraph Input Sources
+		OPT[Constructor Options]
+		SET[fable.settings.PostgreSQL]
+	end
+	subgraph Normalization
+		NORM["Property Mapping<br/>Server → host<br/>Port → port<br/>User → user<br/>Password → password<br/>Database → database<br/>ConnectionPoolLimit → max"]
+	end
+	subgraph Output
+		PGPOOL["pg.Pool Config<br/>{ host, port, user,<br/>  password, database, max }"]
+	end
+	OPT --> NORM
+	SET --> NORM
+	NORM --> PGPOOL
+```
+
+## DDL Generation Pipeline
+
+```mermaid
+flowchart TD
+	A[Meadow Table Schema] --> B[generateCreateTableStatement]
+	B --> C["SQL DDL String<br/>CREATE TABLE IF NOT EXISTS..."]
+	C --> D{createTable called?}
+	D -->|Yes| E[pool.query executes DDL]
+	E --> F{Result?}
+	F -->|Success| G[Callback - no error]
+	F -->|Error 42P07| H[Log warning - table exists]
+	H --> G
+	F -->|Other Error| I[Callback with error]
+	D -->|No| J[Return DDL string for inspection]
+```
+
+## Connection Safety
+
+The connector includes several safety mechanisms:
+
+```mermaid
+flowchart TD
+	A[connect called] --> B{Already connected?}
+	B -->|Yes| C[Log error with masked password]
+	C --> D[Return without action]
+	B -->|No| E[Log connection info]
+	E --> F[Create pg.Pool]
+	F --> G[Set connected = true]
+```
+
+Key safety features:
+
+| Feature | Implementation |
+|---------|---------------|
+| Double-connect guard | Logs error and returns if `_ConnectionPool` already exists |
+| Password masking | Cleansed settings logged on double-connect attempt |
+| Missing callback guard | `connectAsync()` provides a no-op callback if none given |
+| Idempotent tables | `CREATE TABLE IF NOT EXISTS` + error code 42P07 handling |
+| Quoted identifiers | Double-quoted table and column names in DDL |
+
+## Connector Comparison
+
+| Feature | PostgreSQL | MySQL | MSSQL | SQLite |
+|---------|-----------|-------|-------|--------|
+| Driver | `pg` | `mysql2` | `mssql` | `better-sqlite3` |
+| Connection | `pg.Pool` | MySQL Pool | MSSQL Pool | File path |
+| Schema | SQL DDL | SQL DDL | SQL DDL | SQL DDL |
+| `pool` returns | `pg.Pool` | MySQL Pool | MSSQL Pool | SQLite Database |
+| Auto-increment | `SERIAL` | `AUTO_INCREMENT` | `IDENTITY` | `INTEGER PRIMARY KEY` |
+| Parameterized | `$1, $2, $3` | `?, ?, ?` | `@p1, @p2, @p3` | `?, ?, ?` |
+| Boolean type | `BOOLEAN` | `TINYINT(1)` | `BIT` | `INTEGER` |
+| Idempotent DDL | `IF NOT EXISTS` + 42P07 | `IF NOT EXISTS` | `IF NOT EXISTS` | `IF NOT EXISTS` |
+| Identifiers | Double-quoted `"col"` | Backtick-quoted `` `col` `` | Bracket-quoted `[col]` | Double-quoted `"col"` |

package/docs/css/docuserve.css

@@ -0,0 +1,73 @@
+/* ============================================================================
+   Pict Docuserve - Base Styles
+   ============================================================================ */
+
+/* Reset and base */
+*, *::before, *::after {
+	box-sizing: border-box;
+}
+
+html, body {
+	margin: 0;
+	padding: 0;
+	font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+	font-size: 16px;
+	line-height: 1.5;
+	color: #423D37;
+	background-color: #fff;
+	-webkit-font-smoothing: antialiased;
+	-moz-osx-font-smoothing: grayscale;
+}
+
+/* Typography */
+h1, h2, h3, h4, h5, h6 {
+	margin-top: 0;
+	line-height: 1.3;
+}
+
+a {
+	color: #2E7D74;
+	text-decoration: none;
+}
+
+a:hover {
+	color: #256861;
+}
+
+/* Application container */
+#Docuserve-Application-Container {
+	min-height: 100vh;
+}
+
+/* Utility: scrollbar styling */
+::-webkit-scrollbar {
+	width: 8px;
+}
+
+::-webkit-scrollbar-track {
+	background: #F5F0E8;
+}
+
+::-webkit-scrollbar-thumb {
+	background: #D4CCBE;
+	border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+	background: #B5AA9A;
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+	html {
+		font-size: 14px;
+	}
+
+	#Docuserve-Sidebar-Container {
+		display: none;
+	}
+
+	.docuserve-body {
+		flex-direction: column;
+	}
+}

package/docs/index.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8">
+		<meta http-equiv="X-UA-Compatible" content="IE=edge">
+		<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+		<meta name="description" content="Documentation powered by pict-docuserve">
+
+		<title>Documentation</title>
+
+		<!-- Application Stylesheet -->
+		<link href="css/docuserve.css" rel="stylesheet">
+		<!-- KaTeX stylesheet for LaTeX equation rendering -->
+		<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css">
+		<!-- PICT Dynamic View CSS Container -->
+		<style id="PICT-CSS"></style>
+
+		<!-- Load the PICT library from jsDelivr CDN -->
+		<script src="https://cdn.jsdelivr.net/npm/pict@1/dist/pict.min.js" type="text/javascript"></script>
+		<!-- Bootstrap the Application -->
+		<script type="text/javascript">
+//<![CDATA[
+		Pict.safeOnDocumentReady(() => { Pict.safeLoadPictApplication(PictDocuserve, 2)});
+//]]>
+		</script>
+	</head>
+	<body>
+		<!-- The root container for the Pict application -->
+		<div id="Docuserve-Application-Container"></div>
+
+		<!-- Mermaid diagram rendering -->
+		<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+		<script>mermaid.initialize({ startOnLoad: false, theme: 'default' });</script>
+		<!-- KaTeX for LaTeX equation rendering -->
+		<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.js"></script>
+		<!-- Load the Docuserve PICT Application Bundle from jsDelivr CDN -->
+		<script src="https://cdn.jsdelivr.net/npm/pict-docuserve@0/dist/pict-docuserve.min.js" type="text/javascript"></script>
+	</body>
+</html>

package/docs/quickstart.md

@@ -0,0 +1,181 @@
+# Quickstart
+
+Get a PostgreSQL connection running in five steps.
+
+## Step 1: Install
+
+```bash
+npm install meadow-connection-postgresql fable
+```
+
+Requires a running PostgreSQL server (local or remote). The module uses the `pg` (node-postgres) driver v8.
+
+## Step 2: Configure and Connect
+
+```javascript
+const libFable = require('fable');
+const libMeadowConnectionPostgreSQL = require('meadow-connection-postgresql');
+
+let _Fable = new libFable(
+	{
+		"PostgreSQL":
+		{
+			"Server": "localhost",
+			"Port": 5432,
+			"User": "postgres",
+			"Password": "secret",
+			"Database": "myapp",
+			"ConnectionPoolLimit": 20
+		}
+	});
+
+_Fable.serviceManager.addAndInstantiateServiceType(
+	'MeadowPostgreSQLProvider', libMeadowConnectionPostgreSQL);
+
+_Fable.MeadowPostgreSQLProvider.connectAsync(
+	(pError, pPool) =>
+	{
+		if (pError)
+		{
+			console.error('Connection failed:', pError);
+			return;
+		}
+		console.log('Connected to PostgreSQL!');
+	});
+```
+
+## Step 3: Create a Table
+
+Define a Meadow table schema and apply it. The `CREATE TABLE IF NOT EXISTS` clause ensures idempotent execution, and the connector also handles the PostgreSQL `42P07` (duplicate_table) error gracefully.
+
+```javascript
+let tmpAnimalSchema =
+{
+	TableName: 'Animal',
+	Columns:
+	[
+		{ Column: 'IDAnimal', DataType: 'ID' },
+		{ Column: 'GUIDAnimal', DataType: 'GUID', Size: 36 },
+		{ Column: 'Name', DataType: 'String', Size: 128 },
+		{ Column: 'Age', DataType: 'Numeric' },
+		{ Column: 'Weight', DataType: 'Decimal', Size: '10,2' },
+		{ Column: 'Description', DataType: 'Text' },
+		{ Column: 'CreateDate', DataType: 'DateTime' },
+		{ Column: 'Deleted', DataType: 'Boolean' }
+	]
+};
+
+_Fable.MeadowPostgreSQLProvider.createTable(tmpAnimalSchema,
+	(pError) =>
+	{
+		if (pError)
+		{
+			console.error('Table creation failed:', pError);
+			return;
+		}
+		console.log('Animal table ready!');
+	});
+```
+
+This generates and executes:
+
+```sql
+CREATE TABLE IF NOT EXISTS
+    "Animal"
+    (
+        "IDAnimal" SERIAL PRIMARY KEY,
+        "GUIDAnimal" VARCHAR(36) DEFAULT '0xDe',
+        "Name" VARCHAR(128) NOT NULL DEFAULT '',
+        "Age" INTEGER NOT NULL DEFAULT 0,
+        "Weight" DECIMAL(10,2),
+        "Description" TEXT,
+        "CreateDate" TIMESTAMP,
+        "Deleted" BOOLEAN NOT NULL DEFAULT false
+    );
+```
+
+## Step 4: Use the Pool
+
+Access the `pg.Pool` instance via the `pool` getter and run queries:
+
+```javascript
+let tmpPool = _Fable.MeadowPostgreSQLProvider.pool;
+
+// Simple query
+tmpPool.query('SELECT * FROM "Animal" WHERE "Deleted" = false',
+	(pError, pResult) =>
+	{
+		if (pError) { return console.error(pError); }
+		console.log('Animals:', pResult.rows);
+	});
+
+// Parameterized query
+tmpPool.query('SELECT * FROM "Animal" WHERE "Age" > $1', [3],
+	(pError, pResult) =>
+	{
+		if (pError) { return console.error(pError); }
+		console.log('Animals older than 3:', pResult.rows);
+	});
+```
+
+## Step 5: Use with Meadow
+
+For full ORM capabilities, pair this connection with the Meadow data access layer:
+
+```javascript
+const libMeadow = require('meadow');
+
+let tmpAnimalMeadow = libMeadow.new(_Fable, 'Animal')
+	.setProvider('PostgreSQL')
+	.setDefaultIdentifier('IDAnimal')
+	.setSchema(
+	[
+		{ Column: 'IDAnimal', Type: 'AutoIdentity' },
+		{ Column: 'GUIDAnimal', Type: 'AutoGUID' },
+		{ Column: 'Name', Type: 'String', Size: 128 },
+		{ Column: 'Age', Type: 'Number' },
+		{ Column: 'Weight', Type: 'Number' },
+		{ Column: 'Description', Type: 'String' },
+		{ Column: 'CreateDate', Type: 'CreateDate' },
+		{ Column: 'Deleted', Type: 'Deleted' }
+	]);
+
+// Meadow handles CRUD through FoxHound's query dialect
+let tmpQuery = tmpAnimalMeadow.query.addRecord(
+	{
+		Name: 'Luna',
+		Age: 5,
+		Weight: 4.5
+	});
+
+tmpAnimalMeadow.doCreate(tmpQuery,
+	(pQuery) =>
+	{
+		console.log('Created with ID:', pQuery.parameters.result.value);
+	});
+```
+
+## Auto-Connect Mode
+
+Skip the explicit `connectAsync()` call by enabling auto-connect:
+
+```javascript
+let _Fable = new libFable(
+	{
+		"PostgreSQL":
+		{
+			"Server": "localhost",
+			"Port": 5432,
+			"User": "postgres",
+			"Password": "secret",
+			"Database": "myapp"
+		},
+		"MeadowConnectionPostgreSQLAutoConnect": true
+	});
+
+_Fable.serviceManager.addAndInstantiateServiceType(
+	'MeadowPostgreSQLProvider', libMeadowConnectionPostgreSQL);
+
+// Already connected -- pool is ready
+let tmpPool = _Fable.MeadowPostgreSQLProvider.pool;
+```

package/docs/retold-catalog.json

@@ -0,0 +1,62 @@
+{
+	"Generated": "2026-03-02T00:47:16.544Z",
+	"GitHubOrg": "stevenvelozo",
+	"DefaultBranch": "master",
+	"Groups": [
+		{
+			"Name": "Dist",
+			"Key": "dist",
+			"Description": "",
+			"Modules": [
+				{
+					"Name": "indoctrinate_content_staging",
+					"Repo": "indoctrinate_content_staging",
+					"Group": "dist",
+					"Branch": "master",
+					"HasDocs": false,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": []
+				}
+			]
+		},
+		{
+			"Name": "Docs",
+			"Key": "docs",
+			"Description": "",
+			"Modules": [
+				{
+					"Name": "api",
+					"Repo": "api",
+					"Group": "docs",
+					"Branch": "master",
+					"HasDocs": true,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": [
+						"api/connect.md",
+						"api/connectAsync.md",
+						"api/createTable.md",
+						"api/createTables.md",
+						"api/generateCreateTableStatement.md",
+						"api/generateDropTableStatement.md",
+						"api/pool.md",
+						"api/reference.md"
+					]
+				},
+				{
+					"Name": "css",
+					"Repo": "css",
+					"Group": "docs",
+					"Branch": "master",
+					"HasDocs": true,
+					"HasCover": false,
+					"Sidebar": [],
+					"DocFiles": [
+						"css/docuserve.css"
+					]
+				}
+			]
+		}
+	]
+}