meadow-connection-postgresql 1.0.0 → 1.0.2

package/docs/schema.md

@@ -0,0 +1,148 @@
+# Schema & Column Types
+
+## Overview
+
+The PostgreSQL connector generates standard SQL DDL (`CREATE TABLE`, `DROP TABLE`) from Meadow table schemas. Unlike MongoDB or Dgraph connectors that produce descriptor objects, this connector generates SQL strings that are executed directly via `pool.query()`.
+
+## Column Type Mapping
+
+| Meadow DataType | PostgreSQL Type | Constraints | Size Used |
+|-----------------|-----------------|-------------|-----------|
+| `ID` | `SERIAL` | `PRIMARY KEY` | No |
+| `GUID` | `VARCHAR(Size)` | `DEFAULT '0xDe'` | Yes (default 36) |
+| `ForeignKey` | `INTEGER` | `NOT NULL DEFAULT 0` | No |
+| `Numeric` | `INTEGER` | `NOT NULL DEFAULT 0` | No |
+| `Decimal` | `DECIMAL(Size)` | -- | Yes (e.g. `10,2`) |
+| `String` | `VARCHAR(Size)` | `NOT NULL DEFAULT ''` | Yes |
+| `Text` | `TEXT` | -- | No |
+| `DateTime` | `TIMESTAMP` | -- | No |
+| `Boolean` | `BOOLEAN` | `NOT NULL DEFAULT false` | No |
+
+### Key Behaviors
+
+- **`ID`** -- uses PostgreSQL's `SERIAL` type which auto-creates a sequence and sets `NOT NULL DEFAULT nextval(...)`. The `PRIMARY KEY` constraint is declared inline.
+- **`GUID`** -- defaults to `VARCHAR(36)` if no `Size` is provided or if the `Size` value is not a number.
+- **`Boolean`** -- uses PostgreSQL's native `BOOLEAN` type (not `TINYINT` like MySQL).
+- **`Decimal`** -- the `Size` property is passed directly (e.g. `'10,2'` becomes `DECIMAL(10,2)`).
+- **Quoted identifiers** -- all table and column names are wrapped in double quotes (`"Name"`) to safely handle PostgreSQL reserved words.
+
+## Generated DDL Example
+
+Given this Meadow table schema:
+
+```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' }
+	]
+};
+```
+
+The generated DDL:
+
+```sql
+--   [ Animal ]
+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
+    );
+```
+
+## Drop Table Statement
+
+The `generateDropTableStatement(name)` method generates a `DROP TABLE IF EXISTS` statement:
+
+```javascript
+let tmpDrop = _Fable.MeadowPostgreSQLProvider.generateDropTableStatement('Animal');
+// => 'DROP TABLE IF EXISTS "Animal";'
+```
+
+## Multiple Tables
+
+Use `createTables()` to create multiple tables from a Stricture schema:
+
+```javascript
+let tmpSchema =
+{
+	Tables:
+	[
+		{
+			TableName: 'Animal',
+			Columns:
+			[
+				{ Column: 'IDAnimal', DataType: 'ID' },
+				{ Column: 'GUIDAnimal', DataType: 'GUID', Size: 36 },
+				{ Column: 'Name', DataType: 'String', Size: 128 }
+			]
+		},
+		{
+			TableName: 'Farm',
+			Columns:
+			[
+				{ Column: 'IDFarm', DataType: 'ID' },
+				{ Column: 'GUIDFarm', DataType: 'GUID', Size: 36 },
+				{ Column: 'FarmName', DataType: 'String', Size: 256 }
+			]
+		}
+	]
+};
+
+_Fable.MeadowPostgreSQLProvider.createTables(tmpSchema,
+	(pError) =>
+	{
+		if (pError) { console.error(pError); return; }
+		console.log('All tables created!');
+	});
+```
+
+Tables are created sequentially (concurrency of 1) to ensure deterministic ordering.
+
+## PostgreSQL vs MySQL Type Mapping
+
+| Meadow DataType | PostgreSQL | MySQL |
+|-----------------|-----------|-------|
+| `ID` | `SERIAL PRIMARY KEY` | `INT UNSIGNED NOT NULL AUTO_INCREMENT` |
+| `GUID` | `VARCHAR(36)` | `CHAR(36)` |
+| `ForeignKey` | `INTEGER NOT NULL DEFAULT 0` | `INT UNSIGNED NOT NULL DEFAULT 0` |
+| `Numeric` | `INTEGER NOT NULL DEFAULT 0` | `INT NOT NULL DEFAULT 0` |
+| `Decimal` | `DECIMAL(Size)` | `DECIMAL(Size)` |
+| `String` | `VARCHAR(Size) NOT NULL DEFAULT ''` | `VARCHAR(Size) NOT NULL DEFAULT ''` |
+| `Text` | `TEXT` | `TEXT` |
+| `DateTime` | `TIMESTAMP` | `DATETIME` |
+| `Boolean` | `BOOLEAN NOT NULL DEFAULT false` | `TINYINT NOT NULL DEFAULT 0` |
+
+### Notable Differences
+
+- **Auto-increment**: PostgreSQL uses `SERIAL` (sequence-backed); MySQL uses `AUTO_INCREMENT`
+- **Boolean**: PostgreSQL has a native `BOOLEAN` type; MySQL uses `TINYINT`
+- **DateTime**: PostgreSQL uses `TIMESTAMP`; MySQL uses `DATETIME`
+- **Integer signing**: PostgreSQL integers are always signed; MySQL supports `UNSIGNED`
+- **GUID default**: PostgreSQL uses `DEFAULT '0xDe'`; this placeholder is replaced at insertion time by Meadow's auto-GUID mechanism
+- **Identifiers**: PostgreSQL uses double quotes (`"Name"`); MySQL uses backticks (`` `Name` ``)
+
+## Idempotent Schema
+
+Table creation is idempotent through two mechanisms:
+
+1. **`CREATE TABLE IF NOT EXISTS`** -- PostgreSQL skips creation if the table exists
+2. **Error code 42P07** -- the connector catches `duplicate_table` errors and logs a warning instead of failing
+
+This makes `createTable()` and `createTables()` safe to call during application startup.

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "meadow-connection-postgresql",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Meadow PostgreSQL Connection Plugin",
   "main": "source/Meadow-Connection-PostgreSQL.js",
   "scripts": {
     "coverage": "npx quack coverage",
-    "test": "npx quack test"
+    "test": "npx quack test",
+    "docker-postgresql-start": "bash ./start-postgresql.sh",
+    "docker-postgresql-stop": "bash ./stop-postgresql.sh",
+    "test-docker": "bash ./start-postgresql.sh && npm test; bash ./stop-postgresql.sh"
   },
   "mocha": {
     "diff": true,

package/source/Meadow-Connection-PostgreSQL.js

@@ -6,6 +6,8 @@ const libFableServiceProviderBase = require('fable-serviceproviderbase');
 
 const libPG = require('pg');
 
+const libMeadowSchemaPostgreSQL = require('./Meadow-Schema-PostgreSQL.js');
+
 class MeadowConnectionPostgreSQL extends libFableServiceProviderBase
 {
 	constructor(pFable, pManifest, pServiceHash)
@@ -66,128 +68,105 @@ class MeadowConnectionPostgreSQL extends libFableServiceProviderBase
 		this._ConnectionPool = false;
 		this.connected = false;
 
+		// Schema provider handles DDL operations (create, drop, index, etc.)
+		this._SchemaProvider = new libMeadowSchemaPostgreSQL(this.fable, this.options, `${this.Hash}-Schema`);
+
 		if (this.options.MeadowConnectionPostgreSQLAutoConnect)
 		{
 			this.connect();
 		}
 	}
 
+	get schemaProvider()
+	{
+		return this._SchemaProvider;
+	}
+
 	generateDropTableStatement(pTableName)
 	{
-		return `DROP TABLE IF EXISTS "${pTableName}";`;
+		return this._SchemaProvider.generateDropTableStatement(pTableName);
 	}
 
 	generateCreateTableStatement(pMeadowTableSchema)
 	{
-		this.log.info(`--> Building the table create string for ${pMeadowTableSchema} ...`);
+		return this._SchemaProvider.generateCreateTableStatement(pMeadowTableSchema);
+	}
 
-		let tmpPrimaryKey = false;
-		let tmpCreateTableStatement = `--   [ ${pMeadowTableSchema.TableName} ]`;
+	createTables(pMeadowSchema, fCallback)
+	{
+		return this._SchemaProvider.createTables(pMeadowSchema, fCallback);
+	}
 
-		tmpCreateTableStatement += `\nCREATE TABLE IF NOT EXISTS\n    "${pMeadowTableSchema.TableName}"\n    (`;
-		for (let j = 0; j < pMeadowTableSchema.Columns.length; j++)
-		{
-			let tmpColumn = pMeadowTableSchema.Columns[j];
+	createTable(pMeadowTableSchema, fCallback)
+	{
+		return this._SchemaProvider.createTable(pMeadowTableSchema, fCallback);
+	}
 
-			// If we aren't the first column, append a comma.
-			if (j > 0)
-			{
-				tmpCreateTableStatement += `,`;
-			}
+	getIndexDefinitionsFromSchema(pMeadowTableSchema)
+	{
+		return this._SchemaProvider.getIndexDefinitionsFromSchema(pMeadowTableSchema);
+	}
 
-			tmpCreateTableStatement += `\n`;
-			// Dump out each column......
-			switch (tmpColumn.DataType)
-			{
-				case 'ID':
-					tmpCreateTableStatement += `        "${tmpColumn.Column}" SERIAL PRIMARY KEY`;
-					tmpPrimaryKey = tmpColumn.Column;
-					break;
-				case 'GUID':
-					let tmpSize = tmpColumn.hasOwnProperty('Size') ? tmpColumn.Size : 36;
-					if (isNaN(tmpSize))
-					{
-						// Use the old default if Size is improper
-						tmpSize = 36;
-					}
-					tmpCreateTableStatement += `        "${tmpColumn.Column}" VARCHAR(${tmpSize}) DEFAULT '0xDe'`;
-					break;
-				case 'ForeignKey':
-					tmpCreateTableStatement += `        "${tmpColumn.Column}" INTEGER NOT NULL DEFAULT 0`;
-					break;
-				case 'Numeric':
-					tmpCreateTableStatement += `        "${tmpColumn.Column}" INTEGER NOT NULL DEFAULT 0`;
-					break;
-				case 'Decimal':
-					tmpCreateTableStatement += `        "${tmpColumn.Column}" DECIMAL(${tmpColumn.Size})`;
-					break;
-				case 'String':
-					tmpCreateTableStatement += `        "${tmpColumn.Column}" VARCHAR(${tmpColumn.Size}) NOT NULL DEFAULT ''`;
-					break;
-				case 'Text':
-					tmpCreateTableStatement += `        "${tmpColumn.Column}" TEXT`;
-					break;
-				case 'DateTime':
-					tmpCreateTableStatement += `        "${tmpColumn.Column}" TIMESTAMP`;
-					break;
-				case 'Boolean':
-					tmpCreateTableStatement += `        "${tmpColumn.Column}" BOOLEAN NOT NULL DEFAULT false`;
-					break;
-				default:
-					break;
-			}
-		}
-		// PostgreSQL SERIAL PRIMARY KEY is declared inline; no separate PRIMARY KEY clause needed
-		tmpCreateTableStatement += `\n    );`;
+	generateCreateIndexScript(pMeadowTableSchema)
+	{
+		return this._SchemaProvider.generateCreateIndexScript(pMeadowTableSchema);
+	}
 
-		return tmpCreateTableStatement;
+	generateCreateIndexStatements(pMeadowTableSchema)
+	{
+		return this._SchemaProvider.generateCreateIndexStatements(pMeadowTableSchema);
 	}
 
-	createTables(pMeadowSchema, fCallback)
+	createIndex(pIndexStatement, fCallback)
 	{
-		this.fable.Utility.eachLimit(pMeadowSchema.Tables, 1,
-			(pTable, fCreateComplete) =>
-			{
-				return this.createTable(pTable, fCreateComplete);
-			},
-			(pCreateError) =>
-			{
-				if (pCreateError)
-				{
-					this.log.error(`Meadow-PostgreSQL Error creating tables from Schema: ${pCreateError}`, pCreateError);
-				}
-				this.log.info('Done creating tables!');
-				return fCallback(pCreateError);
-			});
+		return this._SchemaProvider.createIndex(pIndexStatement, fCallback);
 	}
 
-	createTable(pMeadowTableSchema, fCallback)
+	createIndices(pMeadowTableSchema, fCallback)
 	{
-		let tmpCreateTableStatement = this.generateCreateTableStatement(pMeadowTableSchema);
-		this._ConnectionPool.query(tmpCreateTableStatement,
-			(pError, pResult) =>
-			{
-				if (pError)
-				{
-					// Check for "already exists" type errors
-					if (pError.code === '42P07')
-					{
-						// 42P07 = duplicate_table
-						this.log.warn(`Meadow-PostgreSQL CREATE TABLE ${pMeadowTableSchema.TableName} executed but table already existed.`);
-						return fCallback();
-					}
-					else
-					{
-						this.log.error(`Meadow-PostgreSQL CREATE TABLE ${pMeadowTableSchema.TableName} failed!`, pError);
-						return fCallback(pError);
-					}
-				}
-				else
-				{
-					this.log.info(`Meadow-PostgreSQL CREATE TABLE ${pMeadowTableSchema.TableName} executed successfully.`);
-					return fCallback();
-				}
-			});
+		return this._SchemaProvider.createIndices(pMeadowTableSchema, fCallback);
+	}
+
+	createAllIndices(pMeadowSchema, fCallback)
+	{
+		return this._SchemaProvider.createAllIndices(pMeadowSchema, fCallback);
+	}
+
+	// Database Introspection delegation
+
+	listTables(fCallback)
+	{
+		return this._SchemaProvider.listTables(fCallback);
+	}
+
+	introspectTableColumns(pTableName, fCallback)
+	{
+		return this._SchemaProvider.introspectTableColumns(pTableName, fCallback);
+	}
+
+	introspectTableIndices(pTableName, fCallback)
+	{
+		return this._SchemaProvider.introspectTableIndices(pTableName, fCallback);
+	}
+
+	introspectTableForeignKeys(pTableName, fCallback)
+	{
+		return this._SchemaProvider.introspectTableForeignKeys(pTableName, fCallback);
+	}
+
+	introspectTableSchema(pTableName, fCallback)
+	{
+		return this._SchemaProvider.introspectTableSchema(pTableName, fCallback);
+	}
+
+	introspectDatabaseSchema(fCallback)
+	{
+		return this._SchemaProvider.introspectDatabaseSchema(fCallback);
+	}
+
+	generateMeadowPackageFromTable(pTableName, fCallback)
+	{
+		return this._SchemaProvider.generateMeadowPackageFromTable(pTableName, fCallback);
 	}
 
 	connect()
@@ -212,6 +191,7 @@ class MeadowConnectionPostgreSQL extends libFableServiceProviderBase
 		{
 			this.fable.log.info(`Meadow-Connection-PostgreSQL connecting to [${this.options.PostgreSQL.host} : ${this.options.PostgreSQL.port}] as ${this.options.PostgreSQL.user} for database ${this.options.PostgreSQL.database} at a pool limit of ${this.options.PostgreSQL.max}`);
 			this._ConnectionPool = new libPG.Pool(tmpConnectionSettings);
+			this._SchemaProvider.setConnectionPool(this._ConnectionPool);
 			this.connected = true;
 		}
 	}