meadow-connection-postgresql 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,133 @@
+# meadow-connection-postgresql
+
+PostgreSQL connection service for the Meadow data access layer.
+
+[![Coverage Status](https://coveralls.io/repos/github/stevenvelozo/meadow-connection-postgresql/badge.svg?branch=main)](https://coveralls.io/github/stevenvelozo/meadow-connection-postgresql?branch=main)
+[![Build Status](https://github.com/stevenvelozo/meadow-connection-postgresql/workflows/Tests/badge.svg)](https://github.com/stevenvelozo/meadow-connection-postgresql/actions)
+[![npm version](https://badge.fury.io/js/meadow-connection-postgresql.svg)](https://www.npmjs.com/package/meadow-connection-postgresql)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Fable Service Provider** -- integrates with the Fable dependency injection ecosystem
+- **Connection Pooling** -- managed pool via the `pg` driver's `Pool` class
+- **SQL DDL Generation** -- produces PostgreSQL-native `CREATE TABLE` and `DROP TABLE` statements
+- **Meadow-Compatible Settings** -- accepts both Meadow-style (`Server`, `Port`) and native `pg` property names
+- **Quoted Identifiers** -- double-quoted table and column names for safe handling of reserved words
+- **Auto-Connect Mode** -- optionally connect during service construction
+- **Idempotent Schema** -- `CREATE TABLE IF NOT EXISTS` and graceful handling of duplicate table errors
+
+## Installation
+
+```shell
+npm install meadow-connection-postgresql
+```
+
+## Quick Start
+
+```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"
+		}
+	});
+
+_Fable.serviceManager.addAndInstantiateServiceType(
+	'MeadowPostgreSQLProvider', libMeadowConnectionPostgreSQL);
+
+_Fable.MeadowPostgreSQLProvider.connectAsync(
+	(pError, pPool) =>
+	{
+		if (pError) { return console.error(pError); }
+
+		let tmpPool = _Fable.MeadowPostgreSQLProvider.pool;
+		tmpPool.query('SELECT NOW()', (pErr, pRes) =>
+		{
+			console.log('Server time:', pRes.rows[0].now);
+		});
+	});
+```
+
+## Configuration
+
+Settings are read from `fable.settings.PostgreSQL`:
+
+| Setting | Alias | Default | Description |
+|---------|-------|---------|-------------|
+| `Server` | `host` | -- | PostgreSQL host |
+| `Port` | `port` | -- | PostgreSQL port |
+| `User` | `user` | -- | Authentication username |
+| `Password` | `password` | -- | Authentication password |
+| `Database` | `database` | -- | Target database name |
+| `ConnectionPoolLimit` | `max` | -- | Maximum connections in the pool |
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `connect()` | Synchronous -- create `pg.Pool` instance |
+| `connectAsync(fCallback)` | Callback-style connection (recommended) |
+| `pool` | Getter -- returns the `pg.Pool` instance |
+| `generateCreateTableStatement(schema)` | Generate a `CREATE TABLE` DDL string |
+| `createTable(schema, fCallback)` | Execute `CREATE TABLE` via the pool |
+| `createTables(schema, fCallback)` | Create multiple tables sequentially |
+| `generateDropTableStatement(name)` | Generate a `DROP TABLE IF EXISTS` DDL string |
+
+## Column 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` |
+
+## Part of the Retold Framework
+
+This module is a Meadow connector that plugs into the Retold application framework. It provides the PostgreSQL persistence layer for the Meadow data access abstraction.
+
+## Testing
+
+```shell
+npm test
+```
+
+Coverage:
+
+```shell
+npm run coverage
+```
+
+## Related Packages
+
+- [meadow](https://github.com/stevenvelozo/meadow) -- Data access layer and ORM
+- [fable](https://github.com/stevenvelozo/fable) -- Application framework and service manager
+- [foxhound](https://github.com/stevenvelozo/foxhound) -- Query generation DSL
+- [stricture](https://github.com/stevenvelozo/stricture) -- Schema definition and DDL tools
+- [meadow-endpoints](https://github.com/stevenvelozo/meadow-endpoints) -- RESTful endpoint generation
+- [meadow-connection-mysql](https://github.com/stevenvelozo/meadow-connection-mysql) -- MySQL / MariaDB connector
+- [meadow-connection-mssql](https://github.com/stevenvelozo/meadow-connection-mssql) -- Microsoft SQL Server connector
+- [meadow-connection-sqlite](https://github.com/stevenvelozo/meadow-connection-sqlite) -- SQLite connector
+- [meadow-connection-mongodb](https://github.com/stevenvelozo/meadow-connection-mongodb) -- MongoDB connector
+
+## License
+
+MIT
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

package/docker-compose.yml

@@ -0,0 +1,20 @@
+version: '3.8'
+
+services:
+  postgresql-test:
+    image: postgres:16
+    container_name: meadow-connection-postgresql-test
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: testpassword
+      POSTGRES_DB: testdb
+    ports:
+      - "25432:5432"
+    volumes:
+      - ./test/docker-init:/docker-entrypoint-initdb.d
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+      start_period: 10s

package/docs/README.md

@@ -0,0 +1,96 @@
+# meadow-connection-postgresql
+
+PostgreSQL connection service for the Meadow data access layer. This module provides connection pool management, SQL DDL generation, and table creation for applications using PostgreSQL as their persistence store.
+
+## Quick Start
+
+```javascript
+const libFable = require('fable');
+const libMeadowConnectionPostgreSQL = require('meadow-connection-postgresql');
+
+// 1. Create a Fable instance with PostgreSQL settings
+let _Fable = new libFable(
+	{
+		"PostgreSQL":
+		{
+			"Server": "localhost",
+			"Port": 5432,
+			"User": "postgres",
+			"Password": "secret",
+			"Database": "myapp",
+			"ConnectionPoolLimit": 20
+		}
+	});
+
+// 2. Register and instantiate the service
+_Fable.serviceManager.addAndInstantiateServiceType(
+	'MeadowPostgreSQLProvider', libMeadowConnectionPostgreSQL);
+
+// 3. Connect
+_Fable.MeadowPostgreSQLProvider.connectAsync(
+	(pError, pPool) =>
+	{
+		if (pError) { return console.error(pError); }
+
+		// 4. Use the pool
+		let tmpPool = _Fable.MeadowPostgreSQLProvider.pool;
+		tmpPool.query('SELECT NOW()', (pErr, pRes) =>
+		{
+			console.log('Server time:', pRes.rows[0].now);
+		});
+	});
+```
+
+## Configuration
+
+Settings are read from `fable.settings.PostgreSQL`. Both Meadow-style names and native `pg` driver names are supported:
+
+| Setting | Alias | Description |
+|---------|-------|-------------|
+| `Server` | `host` | PostgreSQL hostname or IP |
+| `Port` | `port` | PostgreSQL port |
+| `User` | `user` | Authentication username |
+| `Password` | `password` | Authentication password |
+| `Database` | `database` | Target database name |
+| `ConnectionPoolLimit` | `max` | Maximum connections in the pool |
+
+## How It Fits
+
+```
+Application
+    |
+    v
+ Meadow (ORM)
+    |
+    v
+ FoxHound (Query Dialect)
+    |
+    v
+ meadow-connection-postgresql  <-- this module
+    |
+    v
+ pg (node-postgres)
+    |
+    v
+ PostgreSQL Server
+```
+
+## Learn More
+
+- [Quickstart Guide](quickstart.md) -- step-by-step setup
+- [Architecture](architecture.md) -- connection lifecycle and design diagrams
+- [Schema & Column Types](schema.md) -- DDL generation and type mapping
+- [API Reference](api/reference.md) -- complete method documentation
+
+## Companion Modules
+
+| Module | Purpose |
+|--------|---------|
+| [meadow](https://github.com/stevenvelozo/meadow) | Data access layer and ORM |
+| [foxhound](https://github.com/stevenvelozo/foxhound) | Query generation DSL |
+| [stricture](https://github.com/stevenvelozo/stricture) | Schema definition and DDL tools |
+| [meadow-connection-mysql](https://github.com/stevenvelozo/meadow-connection-mysql) | MySQL / MariaDB connector |
+| [meadow-connection-mssql](https://github.com/stevenvelozo/meadow-connection-mssql) | Microsoft SQL Server connector |
+| [meadow-connection-sqlite](https://github.com/stevenvelozo/meadow-connection-sqlite) | SQLite connector |
+| [meadow-connection-mongodb](https://github.com/stevenvelozo/meadow-connection-mongodb) | MongoDB connector |
+| [meadow-connection-rocksdb](https://github.com/stevenvelozo/meadow-connection-rocksdb) | RocksDB key-value connector |

package/docs/_cover.md

@@ -0,0 +1,17 @@
+# meadow-connection-postgresql
+
+<small>v1.0.0</small>
+
+> PostgreSQL connection service for the Meadow data access layer
+
+- **Fable Service Provider** -- seamless dependency injection integration
+- **Connection Pooling** -- managed pool via the `pg` driver
+- **SQL DDL Generation** -- PostgreSQL-native `CREATE TABLE` statements
+- **Quoted Identifiers** -- safe handling of reserved words
+- **Meadow-Compatible Settings** -- accepts both Meadow-style and native property names
+- **Idempotent Schema** -- safe to call on every startup
+
+[Overview](README.md)
+[Quickstart](quickstart.md)
+[API Reference](api/reference.md)
+[GitHub](https://github.com/stevenvelozo/meadow-connection-postgresql)

package/docs/_sidebar.md

@@ -0,0 +1,33 @@
+- **Getting Started**
+  - [Overview](README.md)
+  - [Quickstart](quickstart.md)
+
+- **Concepts**
+  - [Architecture](architecture.md)
+  - [Schema & Column Types](schema.md)
+
+- **API Reference**
+  - [Full Reference](api/reference.md)
+  - Connection
+    - [connectAsync(fCallback)](api/connectAsync.md)
+    - [connect()](api/connect.md)
+  - Accessors
+    - [pool](api/pool.md)
+  - Schema Management
+    - [generateCreateTableStatement()](api/generateCreateTableStatement.md)
+    - [createTable()](api/createTable.md)
+    - [createTables()](api/createTables.md)
+    - [generateDropTableStatement()](api/generateDropTableStatement.md)
+
+- **Ecosystem**
+  - [Meadow](https://github.com/stevenvelozo/meadow)
+  - [FoxHound](https://github.com/stevenvelozo/foxhound)
+  - [Stricture](https://github.com/stevenvelozo/stricture)
+  - [Fable](https://github.com/stevenvelozo/fable)
+  - Connectors
+    - [MySQL](https://github.com/stevenvelozo/meadow-connection-mysql)
+    - [MSSQL](https://github.com/stevenvelozo/meadow-connection-mssql)
+    - [SQLite](https://github.com/stevenvelozo/meadow-connection-sqlite)
+    - [MongoDB](https://github.com/stevenvelozo/meadow-connection-mongodb)
+    - [RocksDB](https://github.com/stevenvelozo/meadow-connection-rocksdb)
+    - [Dgraph](https://github.com/stevenvelozo/meadow-connection-dgraph)

package/docs/_topbar.md

@@ -0,0 +1,5 @@
+- [Overview](README.md)
+- [Quickstart](quickstart.md)
+- [Architecture](architecture.md)
+- [API Reference](api/reference.md)
+- [GitHub](https://github.com/stevenvelozo/meadow-connection-postgresql)

package/docs/api/connect.md

@@ -0,0 +1,100 @@
+# connect()
+
+Synchronous method that creates the `pg.Pool` connection pool instance.
+
+## Signature
+
+```javascript
+connect()
+```
+
+## Parameters
+
+None.
+
+## Return Value
+
+None.
+
+## Behavior
+
+1. Builds connection settings from `this.options.PostgreSQL` (host, port, user, password, database, max)
+2. If already connected (`this._ConnectionPool` exists), logs an error with masked password and returns
+3. Otherwise, logs the connection details and creates a new `pg.Pool`
+4. Sets `this.connected = true`
+
+## Usage
+
+```javascript
+_Fable.MeadowPostgreSQLProvider.connect();
+
+if (_Fable.MeadowPostgreSQLProvider.connected)
+{
+	let tmpPool = _Fable.MeadowPostgreSQLProvider.pool;
+	// Use the pool
+}
+```
+
+## Why Both connect() and connectAsync()?
+
+The `pg.Pool` constructor is synchronous -- it does not open actual TCP connections until a query is issued. The `connect()` method works reliably for immediate use. However, `connectAsync()` is preferred because:
+
+- It follows the Fable service provider convention
+- It provides error handling via the callback
+- It guards against missing callbacks with a warning about race conditions
+- It is consistent with other Meadow connector APIs
+
+## Double-Connect Protection
+
+If `connect()` is called when already connected, it logs an error with the settings (password masked) and returns without action:
+
+```javascript
+_Fable.MeadowPostgreSQLProvider.connect();
+_Fable.MeadowPostgreSQLProvider.connect();
+// Logs: "Meadow-Connection-PostgreSQL trying to connect but is already
+//        connected - skipping the generation of extra connections."
+// Settings logged with password: '*****************'
+```
+
+## Auto-Connect
+
+The `connect()` method is called automatically during construction if `MeadowConnectionPostgreSQLAutoConnect` is `true`:
+
+```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;
+```
+
+## Pool Settings
+
+The `pg.Pool` is created with these settings from `options.PostgreSQL`:
+
+| Setting | pg Option | Description |
+|---------|-----------|-------------|
+| `host` | `host` | Server hostname |
+| `port` | `port` | Server port |
+| `user` | `user` | Authentication user |
+| `password` | `password` | Authentication password |
+| `database` | `database` | Target database |
+| `max` | `max` | Maximum pool connections |
+
+## Related
+
+- [connectAsync](connectAsync.md) -- Callback-style connection (recommended)
+- [pool](pool.md) -- Access the pool after connecting

package/docs/api/connectAsync.md

@@ -0,0 +1,92 @@
+# connectAsync(fCallback)
+
+Callback-style connection method. Creates the `pg.Pool` instance, or returns the existing pool if already connected.
+
+## Signature
+
+```javascript
+connectAsync(fCallback)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fCallback` | `function` | Callback receiving `(error, pool)` |
+
+## Return Value
+
+Returns the result of the callback invocation.
+
+## Behavior
+
+1. If no callback is provided, logs an error and substitutes a no-op function
+2. If already connected (`this._ConnectionPool` exists), calls `fCallback(null, this._ConnectionPool)` immediately
+3. Otherwise, calls `this.connect()` to create the pool
+4. On success: calls `fCallback(null, this._ConnectionPool)`
+5. On error: logs the error, calls `fCallback(pError)`
+
+## Basic Usage
+
+```javascript
+_Fable.MeadowPostgreSQLProvider.connectAsync(
+	(pError, pPool) =>
+	{
+		if (pError)
+		{
+			console.error('Connection failed:', pError);
+			return;
+		}
+		console.log('Connected! Pool ready.');
+	});
+```
+
+## Idempotent Calls
+
+Calling `connectAsync()` multiple times is safe. If already connected, the existing pool is returned without creating a new one:
+
+```javascript
+// First call -- creates the pool
+_Fable.MeadowPostgreSQLProvider.connectAsync(
+	(pError, pPool) =>
+	{
+		// pPool is the pg.Pool instance
+
+		// Second call -- reuses the existing pool
+		_Fable.MeadowPostgreSQLProvider.connectAsync(
+			(pError2, pPool2) =>
+			{
+				// pPool2 === pPool (same pool)
+			});
+	});
+```
+
+## Missing Callback
+
+If called without a callback, a warning is logged and a no-op function is used:
+
+```javascript
+// Logs: "Meadow PostgreSQL connectAsync() called without a callback;
+//        this could lead to connection race conditions."
+_Fable.MeadowPostgreSQLProvider.connectAsync();
+```
+
+## Error Handling
+
+If `connect()` throws, the error is caught and passed to the callback:
+
+```javascript
+_Fable.MeadowPostgreSQLProvider.connectAsync(
+	(pError) =>
+	{
+		if (pError)
+		{
+			console.error('PostgreSQL connection error:', pError.message);
+		}
+	});
+```
+
+## Related
+
+- [connect()](connect.md) -- Synchronous connection method
+- [pool](pool.md) -- Access the pool after connecting

package/docs/api/createTable.md

@@ -0,0 +1,116 @@
+# createTable(pMeadowTableSchema, fCallback)
+
+Generates and executes a PostgreSQL `CREATE TABLE IF NOT EXISTS` statement from a Meadow table schema. Handles existing tables gracefully.
+
+## Signature
+
+```javascript
+createTable(pMeadowTableSchema, fCallback)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pMeadowTableSchema` | `object` | Meadow table schema with `TableName` and `Columns` array |
+| `fCallback` | `function` | Callback receiving `(error)` |
+
+## Return Value
+
+Returns the result of the callback invocation.
+
+## Behavior
+
+1. Calls `generateCreateTableStatement(pMeadowTableSchema)` to produce the DDL string
+2. Executes the DDL via `this._ConnectionPool.query(ddl, callback)`
+3. On success: logs info, calls `fCallback()` with no error
+4. On error code `42P07` (duplicate_table): logs a warning, calls `fCallback()` with no error
+5. On other errors: logs the error, calls `fCallback(pError)`
+
+## Basic Usage
+
+```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' }
+	]
+};
+
+_Fable.MeadowPostgreSQLProvider.createTable(tmpAnimalSchema,
+	(pError) =>
+	{
+		if (pError)
+		{
+			console.error('Table creation failed:', pError);
+			return;
+		}
+		console.log('Animal table ready!');
+	});
+```
+
+## Idempotent Execution
+
+Table creation is idempotent through two layers of protection:
+
+1. **`CREATE TABLE IF NOT EXISTS`** in the generated SQL
+2. **Error code 42P07 handling** -- if PostgreSQL returns `duplicate_table`, it is logged as a warning and does not produce an error in the callback
+
+This makes `createTable()` safe to call during application startup:
+
+```javascript
+// Safe to call every time the app starts
+_Fable.MeadowPostgreSQLProvider.createTable(tmpAnimalSchema,
+	(pError) =>
+	{
+		// First run: table created
+		// Subsequent runs: table already exists (warning logged)
+	});
+```
+
+## Prerequisites
+
+The connection must be established before calling `createTable()`:
+
+```javascript
+_Fable.MeadowPostgreSQLProvider.connectAsync(
+	(pError) =>
+	{
+		if (pError) { return; }
+
+		_Fable.MeadowPostgreSQLProvider.createTable(tmpAnimalSchema,
+			(pCreateError) =>
+			{
+				if (pCreateError) { console.error(pCreateError); }
+			});
+	});
+```
+
+## Error Handling
+
+Non-duplicate errors (e.g., syntax errors, permission denied) are passed to the callback:
+
+```javascript
+_Fable.MeadowPostgreSQLProvider.createTable(tmpBadSchema,
+	(pError) =>
+	{
+		if (pError)
+		{
+			// pError.code might be '42601' (syntax error) or '42501' (insufficient privilege)
+			console.error('DDL execution failed:', pError.message);
+		}
+	});
+```
+
+## Related
+
+- [generateCreateTableStatement](generateCreateTableStatement.md) -- Generate DDL without executing
+- [createTables](createTables.md) -- Create multiple tables sequentially
+- [generateDropTableStatement](generateDropTableStatement.md) -- Generate DROP TABLE DDL
+- [Schema & Column Types](../schema.md) -- Full type mapping reference