meadow-connection-postgresql 1.0.0 → 1.0.1

package/docs/api/createTables.md

@@ -0,0 +1,128 @@
+# createTables(pMeadowSchema, fCallback)
+
+Creates multiple PostgreSQL tables sequentially from a Stricture schema object.
+
+## Signature
+
+```javascript
+createTables(pMeadowSchema, fCallback)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pMeadowSchema` | `object` | Schema with a `Tables` array of Meadow table schemas |
+| `fCallback` | `function` | Callback receiving `(error)` |
+
+## Return Value
+
+Returns the result of the callback invocation.
+
+## Behavior
+
+1. Iterates over `pMeadowSchema.Tables` using `fable.Utility.eachLimit` with concurrency of 1
+2. Calls `this.createTable(table, callback)` for each table
+3. On completion: logs info, calls `fCallback()` with no error
+4. On error: logs the error, calls `fCallback(pError)`
+
+## Basic Usage
+
+```javascript
+let tmpSchema =
+{
+	Tables:
+	[
+		{
+			TableName: 'Animal',
+			Columns:
+			[
+				{ Column: 'IDAnimal', DataType: 'ID' },
+				{ Column: 'GUIDAnimal', DataType: 'GUID', Size: 36 },
+				{ Column: 'Name', DataType: 'String', Size: 128 },
+				{ Column: 'IDFarm', DataType: 'ForeignKey' }
+			]
+		},
+		{
+			TableName: 'Farm',
+			Columns:
+			[
+				{ Column: 'IDFarm', DataType: 'ID' },
+				{ Column: 'GUIDFarm', DataType: 'GUID', Size: 36 },
+				{ Column: 'FarmName', DataType: 'String', Size: 256 }
+			]
+		},
+		{
+			TableName: 'Veterinarian',
+			Columns:
+			[
+				{ Column: 'IDVeterinarian', DataType: 'ID' },
+				{ Column: 'GUIDVeterinarian', DataType: 'GUID', Size: 36 },
+				{ Column: 'LastName', DataType: 'String', Size: 128 },
+				{ Column: 'IDFarm', DataType: 'ForeignKey' }
+			]
+		}
+	]
+};
+
+_Fable.MeadowPostgreSQLProvider.createTables(tmpSchema,
+	(pError) =>
+	{
+		if (pError)
+		{
+			console.error('Schema creation failed:', pError);
+			return;
+		}
+		console.log('All tables created!');
+	});
+```
+
+## Sequential Processing
+
+Tables are created one at a time (concurrency of 1) using `fable.Utility.eachLimit`. This ensures:
+
+- Deterministic creation order (important for foreign key dependencies)
+- Clear log output showing each table as it is created
+- Predictable error reporting -- the first failure stops the sequence
+
+## Error Handling
+
+If any table creation fails (other than the expected `42P07` duplicate_table error), the error is passed to the callback and remaining tables are skipped:
+
+```javascript
+_Fable.MeadowPostgreSQLProvider.createTables(tmpSchema,
+	(pError) =>
+	{
+		if (pError)
+		{
+			// Only the first error is reported
+			console.error('Failed during schema creation:', pError);
+		}
+	});
+```
+
+## Application Startup Pattern
+
+Since `createTable()` handles existing tables gracefully, `createTables()` is safe to call on every application startup:
+
+```javascript
+_Fable.MeadowPostgreSQLProvider.connectAsync(
+	(pError) =>
+	{
+		if (pError) { return console.error(pError); }
+
+		_Fable.MeadowPostgreSQLProvider.createTables(appSchema,
+			(pSchemaError) =>
+			{
+				if (pSchemaError) { return console.error(pSchemaError); }
+				console.log('Database ready -- starting application');
+				startApp();
+			});
+	});
+```
+
+## Related
+
+- [createTable](createTable.md) -- Create a single table
+- [generateCreateTableStatement](generateCreateTableStatement.md) -- Generate DDL without executing
+- [Schema & Column Types](../schema.md) -- Full type mapping reference

package/docs/api/generateCreateTableStatement.md

@@ -0,0 +1,136 @@
+# generateCreateTableStatement(pMeadowTableSchema)
+
+Generates a PostgreSQL `CREATE TABLE IF NOT EXISTS` DDL string from a Meadow table schema. Returns the SQL string without executing it.
+
+## Signature
+
+```javascript
+generateCreateTableStatement(pMeadowTableSchema)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pMeadowTableSchema` | `object` | Meadow table schema with `TableName` and `Columns` array |
+
+## Return Value
+
+| Type | Description |
+|------|-------------|
+| `string` | The complete `CREATE TABLE IF NOT EXISTS` SQL statement |
+
+## Schema Object Format
+
+```javascript
+let tmpSchema =
+{
+	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' }
+	]
+};
+```
+
+## Basic Usage
+
+```javascript
+let tmpDDL = _Fable.MeadowPostgreSQLProvider.generateCreateTableStatement(tmpSchema);
+console.log(tmpDDL);
+```
+
+Output:
+
+```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
+    );
+```
+
+## Type Mapping
+
+| Meadow DataType | PostgreSQL Type | Constraints |
+|-----------------|-----------------|-------------|
+| `ID` | `SERIAL` | `PRIMARY KEY` |
+| `GUID` | `VARCHAR(Size)` | `DEFAULT '0xDe'` |
+| `ForeignKey` | `INTEGER` | `NOT NULL DEFAULT 0` |
+| `Numeric` | `INTEGER` | `NOT NULL DEFAULT 0` |
+| `Decimal` | `DECIMAL(Size)` | -- |
+| `String` | `VARCHAR(Size)` | `NOT NULL DEFAULT ''` |
+| `Text` | `TEXT` | -- |
+| `DateTime` | `TIMESTAMP` | -- |
+| `Boolean` | `BOOLEAN` | `NOT NULL DEFAULT false` |
+
+## DDL Structure
+
+The generated DDL has these parts:
+
+1. **Comment line** -- `--   [ TableName ]`
+2. **CREATE TABLE IF NOT EXISTS** -- idempotent creation
+3. **Quoted table name** -- double-quoted for reserved word safety
+4. **Column definitions** -- each column on its own line, comma-separated
+5. **Closing parenthesis and semicolon**
+
+### Quoted Identifiers
+
+All table and column names are wrapped in double quotes (`"Name"`). This ensures safe handling of PostgreSQL reserved words (e.g., `"User"`, `"Order"`, `"Group"`).
+
+## GUID Size Handling
+
+The `GUID` type defaults to `VARCHAR(36)` if no `Size` is specified. If the `Size` value is `NaN`, it also falls back to 36:
+
+```javascript
+// Explicit size
+{ Column: 'GUIDAnimal', DataType: 'GUID', Size: 36 }
+// => "GUIDAnimal" VARCHAR(36) DEFAULT '0xDe'
+
+// No size -- defaults to 36
+{ Column: 'GUIDAnimal', DataType: 'GUID' }
+// => "GUIDAnimal" VARCHAR(36) DEFAULT '0xDe'
+```
+
+## Inspecting Without Executing
+
+Use this method to preview the DDL without applying it to the database:
+
+```javascript
+let tmpDDL = _Fable.MeadowPostgreSQLProvider.generateCreateTableStatement(tmpSchema);
+console.log('Would execute:');
+console.log(tmpDDL);
+```
+
+## Differences from MySQL DDL
+
+| Feature | PostgreSQL | MySQL |
+|---------|-----------|-------|
+| Auto-increment | `SERIAL PRIMARY KEY` | `INT UNSIGNED NOT NULL AUTO_INCREMENT` |
+| Boolean | `BOOLEAN NOT NULL DEFAULT false` | `TINYINT NOT NULL DEFAULT 0` |
+| DateTime | `TIMESTAMP` | `DATETIME` |
+| Identifier quoting | `"column"` | `` `column` `` |
+| Integer signing | Signed only | `UNSIGNED` support |
+| Character set | Inherited from database | Per-table `CHARSET`/`COLLATE` |
+
+## Related
+
+- [createTable](createTable.md) -- Generate and execute the DDL
+- [createTables](createTables.md) -- Create multiple tables
+- [generateDropTableStatement](generateDropTableStatement.md) -- Generate DROP TABLE DDL
+- [Schema & Column Types](../schema.md) -- Full type mapping reference

package/docs/api/generateDropTableStatement.md

@@ -0,0 +1,71 @@
+# generateDropTableStatement(pTableName)
+
+Generates a PostgreSQL `DROP TABLE IF EXISTS` DDL string for the named table.
+
+## Signature
+
+```javascript
+generateDropTableStatement(pTableName)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pTableName` | `string` | The name of the table to drop |
+
+## Return Value
+
+| Type | Description |
+|------|-------------|
+| `string` | The `DROP TABLE IF EXISTS` SQL statement |
+
+## Basic Usage
+
+```javascript
+let tmpDrop = _Fable.MeadowPostgreSQLProvider.generateDropTableStatement('Animal');
+console.log(tmpDrop);
+// => 'DROP TABLE IF EXISTS "Animal";'
+```
+
+## DDL Format
+
+The generated statement uses:
+
+- **`IF EXISTS`** -- prevents errors when the table does not exist
+- **Quoted identifier** -- double-quoted table name for reserved word safety
+
+## Executing the Drop
+
+The method only generates the SQL string. To execute it, use the `pool` getter:
+
+```javascript
+let tmpDrop = _Fable.MeadowPostgreSQLProvider.generateDropTableStatement('Animal');
+let tmpPool = _Fable.MeadowPostgreSQLProvider.pool;
+
+tmpPool.query(tmpDrop,
+	(pError, pResult) =>
+	{
+		if (pError) { return console.error(pError); }
+		console.log('Table dropped.');
+	});
+```
+
+## Cascading Drops
+
+The generated statement does not include `CASCADE`. If the table has dependent objects (foreign keys, views), add `CASCADE` manually:
+
+```javascript
+let tmpDrop = _Fable.MeadowPostgreSQLProvider.generateDropTableStatement('Farm');
+// => 'DROP TABLE IF EXISTS "Farm";'
+
+// To cascade:
+let tmpCascadeDrop = tmpDrop.replace(';', ' CASCADE;');
+// => 'DROP TABLE IF EXISTS "Farm" CASCADE;'
+```
+
+## Related
+
+- [generateCreateTableStatement](generateCreateTableStatement.md) -- Generate CREATE TABLE DDL
+- [createTable](createTable.md) -- Create a table
+- [Schema & Column Types](../schema.md) -- Full type mapping reference

package/docs/api/pool.md

@@ -0,0 +1,171 @@
+# pool (getter)
+
+Returns the `pg.Pool` connection pool instance for executing queries against PostgreSQL.
+
+## Signature
+
+```javascript
+get pool()
+```
+
+## Return Value
+
+| Type | Description |
+|------|-------------|
+| `pg.Pool` | The node-postgres connection pool (after connecting) |
+| `false` | Before connection |
+
+## Primary Use
+
+The `pool` getter is the main entry point for all PostgreSQL operations. It returns the `pg.Pool` instance which manages a pool of connections and provides automatic connection checkout/return.
+
+```javascript
+let tmpPool = _Fable.MeadowPostgreSQLProvider.pool;
+```
+
+## Simple Query
+
+```javascript
+let tmpPool = _Fable.MeadowPostgreSQLProvider.pool;
+
+tmpPool.query('SELECT * FROM "Animal" WHERE "Deleted" = false',
+	(pError, pResult) =>
+	{
+		if (pError) { return console.error(pError); }
+		console.log(pResult.rows);
+	});
+```
+
+## Parameterized Query
+
+PostgreSQL uses `$1, $2, $3, ...` for parameter placeholders:
+
+```javascript
+let tmpPool = _Fable.MeadowPostgreSQLProvider.pool;
+
+tmpPool.query(
+	'SELECT * FROM "Animal" WHERE "Age" > $1 AND "Deleted" = $2',
+	[3, false],
+	(pError, pResult) =>
+	{
+		if (pError) { return console.error(pError); }
+		console.log(pResult.rows);
+	});
+```
+
+## Insert with Returning
+
+PostgreSQL supports `RETURNING` to get the inserted row:
+
+```javascript
+let tmpPool = _Fable.MeadowPostgreSQLProvider.pool;
+
+tmpPool.query(
+	'INSERT INTO "Animal" ("Name", "Age") VALUES ($1, $2) RETURNING "IDAnimal"',
+	['Luna', 5],
+	(pError, pResult) =>
+	{
+		if (pError) { return console.error(pError); }
+		console.log('Inserted ID:', pResult.rows[0].IDAnimal);
+	});
+```
+
+## Update
+
+```javascript
+let tmpPool = _Fable.MeadowPostgreSQLProvider.pool;
+
+tmpPool.query(
+	'UPDATE "Animal" SET "Name" = $1, "Age" = $2 WHERE "IDAnimal" = $3',
+	['Luna Belle', 6, 1],
+	(pError, pResult) =>
+	{
+		if (pError) { return console.error(pError); }
+		console.log('Rows updated:', pResult.rowCount);
+	});
+```
+
+## Promise-Based Query
+
+The `pg.Pool` supports both callbacks and Promises:
+
+```javascript
+let tmpPool = _Fable.MeadowPostgreSQLProvider.pool;
+
+tmpPool.query('SELECT * FROM "Animal" WHERE "IDAnimal" = $1', [1])
+	.then((pResult) =>
+	{
+		console.log(pResult.rows[0]);
+	})
+	.catch((pError) =>
+	{
+		console.error(pError);
+	});
+```
+
+## Client Checkout
+
+For transactions or multiple queries on the same connection, check out a client:
+
+```javascript
+let tmpPool = _Fable.MeadowPostgreSQLProvider.pool;
+
+tmpPool.connect((pError, pClient, pDone) =>
+{
+	if (pError) { return console.error(pError); }
+
+	pClient.query('BEGIN');
+	pClient.query('INSERT INTO "Animal" ("Name") VALUES ($1)', ['Fido']);
+	pClient.query('UPDATE "Farm" SET "AnimalCount" = "AnimalCount" + 1 WHERE "IDFarm" = $1', [42]);
+	pClient.query('COMMIT', (pCommitError) =>
+	{
+		pDone(); // Return client to pool
+		if (pCommitError) { console.error(pCommitError); }
+	});
+});
+```
+
+## Pool Methods
+
+| Method | Returns | Purpose |
+|--------|---------|---------|
+| `pool.query(sql, params, callback)` | `void` | Execute a query (auto-checkout) |
+| `pool.query(sql, params)` | `Promise` | Execute a query (Promise) |
+| `pool.connect(callback)` | `void` | Check out a client from the pool |
+| `pool.end()` | `Promise` | Close all connections in the pool |
+| `pool.on(event, handler)` | `Pool` | Listen for pool events |
+
+## Pool Events
+
+| Event | Description |
+|-------|-------------|
+| `'connect'` | Fired when a new client is created |
+| `'acquire'` | Fired when a client is checked out from the pool |
+| `'remove'` | Fired when a client is closed and removed |
+| `'error'` | Fired on idle client error |
+
+## Before Connection
+
+Returns `false` before `connect()` or `connectAsync()` is called:
+
+```javascript
+let tmpPool = _Fable.MeadowPostgreSQLProvider.pool;
+// tmpPool => false (not connected yet)
+```
+
+Always check `connected` before using `pool`:
+
+```javascript
+if (!_Fable.MeadowPostgreSQLProvider.connected)
+{
+	console.error('Not connected to PostgreSQL.');
+	return;
+}
+
+let tmpPool = _Fable.MeadowPostgreSQLProvider.pool;
+```
+
+## Related
+
+- [connectAsync](connectAsync.md) -- Establish the connection
+- [connect](connect.md) -- Synchronous connection

package/docs/api/reference.md

@@ -0,0 +1,112 @@
+# API Reference
+
+Complete reference for `meadow-connection-postgresql`.
+
+## Service Information
+
+| Property | Value |
+|----------|-------|
+| Service Type | `MeadowConnectionPostgreSQL` |
+| Extends | `fable-serviceproviderbase` |
+| Driver | `pg` ^8.13.0 |
+
+## Connection Methods
+
+### [connectAsync(fCallback)](connectAsync.md)
+
+Callback-style connection method (recommended). Creates the `pg.Pool` instance. If already connected, returns the existing pool immediately.
+
+```javascript
+_Fable.MeadowPostgreSQLProvider.connectAsync(
+	(pError, pPool) =>
+	{
+		if (pError) { return console.error(pError); }
+		// pPool is the pg.Pool instance
+	});
+```
+
+### [connect()](connect.md)
+
+Synchronous connection method. Creates the `pg.Pool` from the resolved settings. Called automatically when `MeadowConnectionPostgreSQLAutoConnect` is `true`.
+
+```javascript
+_Fable.MeadowPostgreSQLProvider.connect();
+```
+
+## Accessors
+
+### [pool](pool.md)
+
+Getter that returns the `pg.Pool` instance. Provides access to queries, parameterized statements, and client checkout.
+
+```javascript
+let tmpPool = _Fable.MeadowPostgreSQLProvider.pool;
+tmpPool.query('SELECT * FROM "Animal"', (pErr, pRes) =>
+{
+	console.log(pRes.rows);
+});
+```
+
+## Schema Management
+
+### [generateCreateTableStatement(pMeadowTableSchema)](generateCreateTableStatement.md)
+
+Generates a PostgreSQL `CREATE TABLE IF NOT EXISTS` DDL string from a Meadow table schema. Returns the SQL string without executing it.
+
+```javascript
+let tmpDDL = _Fable.MeadowPostgreSQLProvider.generateCreateTableStatement(tmpSchema);
+console.log(tmpDDL);
+```
+
+### [createTable(pMeadowTableSchema, fCallback)](createTable.md)
+
+Generates and executes a `CREATE TABLE` statement via the pool. Handles duplicate table errors gracefully.
+
+```javascript
+_Fable.MeadowPostgreSQLProvider.createTable(tmpAnimalSchema,
+	(pError) =>
+	{
+		if (pError) { console.error(pError); }
+	});
+```
+
+### [createTables(pMeadowSchema, fCallback)](createTables.md)
+
+Creates multiple tables sequentially from a Stricture schema object.
+
+```javascript
+_Fable.MeadowPostgreSQLProvider.createTables(tmpSchema,
+	(pError) =>
+	{
+		if (pError) { console.error(pError); }
+	});
+```
+
+### [generateDropTableStatement(pTableName)](generateDropTableStatement.md)
+
+Generates a `DROP TABLE IF EXISTS` DDL string for the named table.
+
+```javascript
+let tmpDrop = _Fable.MeadowPostgreSQLProvider.generateDropTableStatement('Animal');
+// => 'DROP TABLE IF EXISTS "Animal";'
+```
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `connected` | `boolean` | `true` after successful connection |
+| `serviceType` | `string` | Always `'MeadowConnectionPostgreSQL'` |
+| `options.PostgreSQL` | `object` | Resolved connection settings |
+
+## Method Summary
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `connect()` | `void` | Synchronous connection |
+| `connectAsync(fCallback)` | `void` | Callback-style connection |
+| `pool` | `pg.Pool` / `false` | Connection pool instance |
+| `generateCreateTableStatement(schema)` | `string` | SQL DDL for CREATE TABLE |
+| `createTable(schema, fCallback)` | `void` | Execute CREATE TABLE |
+| `createTables(schema, fCallback)` | `void` | Create multiple tables |
+| `generateDropTableStatement(name)` | `string` | SQL DDL for DROP TABLE |

package/docs/api.md

@@ -0,0 +1,3 @@
+# API Reference
+
+See the [full API reference](api/reference.md) for complete documentation.