meadow-connection-mysql 1.0.8 → 1.0.10

package/README.md

@@ -10,13 +10,13 @@ A MySQL connection pool provider for the Meadow ORM. Wraps [mysql2](https://gith
 
 ## Features
 
-- **MySQL2 Connection Pooling** - High-performance pooled connections via [mysql2](https://github.com/sidorares/node-mysql2)
-- **Fable Service Provider** - Registers with a Fable instance for dependency injection, logging, and configuration
-- **Named Placeholders** - Automatically enables named placeholders for parameterized queries
-- **Auto-Connect** - Optional automatic connection on instantiation via the `MeadowConnectionMySQLAutoConnect` flag
-- **Schema-Driven DDL** - Generates `CREATE TABLE IF NOT EXISTS` statements from Meadow table schemas with primary keys, UTF-8 charset, and proper column types
-- **Connection Safety** - Guards against creating duplicate connection pools with descriptive logging (passwords are never leaked)
-- **Settings Coercion** - Accepts both Meadow-style (`Server`, `Port`, `User`) and mysql2-native (`host`, `port`, `user`) configuration formats
+- **MySQL2 Connection Pooling** -- High-performance pooled connections via [mysql2](https://github.com/sidorares/node-mysql2)
+- **Fable Service Provider** -- Registers with a Fable instance for dependency injection, logging, and configuration
+- **Named Placeholders** -- Automatically enables named placeholders for parameterized queries
+- **Auto-Connect** -- Optional automatic connection on instantiation via the `MeadowConnectionMySQLAutoConnect` flag
+- **Schema-Driven DDL** -- Generates `CREATE TABLE IF NOT EXISTS` statements from Meadow table schemas with primary keys, UTF-8 charset, and proper column types
+- **Connection Safety** -- Guards against creating duplicate connection pools with descriptive logging (passwords are never leaked)
+- **Settings Coercion** -- Accepts both Meadow-style (`Server`, `Port`, `User`) and mysql2-native (`host`, `port`, `user`) configuration formats
 
 ## Installation
 
@@ -167,13 +167,13 @@ Generate a `DROP TABLE IF EXISTS` SQL statement for the given table name.
 
 Meadow Connection MySQL is a database connector for the Meadow data access layer:
 
-- [meadow](https://github.com/stevenvelozo/meadow) - ORM and data access framework
-- [foxhound](https://github.com/stevenvelozo/foxhound) - Query DSL used by Meadow
-- [stricture](https://github.com/stevenvelozo/stricture) - Schema definition tool
-- [meadow-endpoints](https://github.com/stevenvelozo/meadow-endpoints) - RESTful endpoint generation
-- [meadow-connection-mssql](https://github.com/stevenvelozo/meadow-connection-mssql) - MSSQL connector
-- [meadow-connection-sqlite](https://github.com/stevenvelozo/meadow-connection-sqlite) - SQLite connector
-- [fable](https://github.com/stevenvelozo/fable) - Application services framework
+- [meadow](https://github.com/stevenvelozo/meadow) -- ORM and data access framework
+- [foxhound](https://github.com/stevenvelozo/foxhound) -- Query DSL used by Meadow
+- [stricture](https://github.com/stevenvelozo/stricture) -- Schema definition tool
+- [meadow-endpoints](https://github.com/stevenvelozo/meadow-endpoints) -- RESTful endpoint generation
+- [meadow-connection-mssql](https://github.com/stevenvelozo/meadow-connection-mssql) -- MSSQL connector
+- [meadow-connection-sqlite](https://github.com/stevenvelozo/meadow-connection-sqlite) -- SQLite connector
+- [fable](https://github.com/stevenvelozo/fable) -- Application services framework
 
 ## Testing
 
@@ -191,8 +191,9 @@ npm run coverage
 
 ## Related Packages
 
-- [meadow](https://github.com/stevenvelozo/meadow) - Data access and ORM
-- [fable](https://github.com/stevenvelozo/fable) - Application services framework
+- [meadow](https://github.com/stevenvelozo/meadow) -- Data access and ORM
+- [meadow-connection-rocksdb](https://github.com/stevenvelozo/meadow-connection-rocksdb) -- RocksDB connection provider
+- [fable](https://github.com/stevenvelozo/fable) -- Application services framework
 
 ## License
 

package/docs/README.md

@@ -152,9 +152,29 @@ tmpBookDAL.doReads(tmpBookDAL.query, (pError, pQuery, pRecords) =>
 
 The service can generate and execute CREATE TABLE statements from Meadow schema definitions. See [Schema & Table Creation](schema.md) for details.
 
+## How It Fits Together
+
+```
+Application Code
+        |
+    Meadow ORM   ← setProvider('MySQL')
+        |
+    FoxHound      ← Generates SQL queries
+        |
+    Meadow-Connection-MySQL   ← This module
+        |
+    mysql2 Pool   ← Connection pooling, named placeholders
+        |
+    MySQL Server  ← Your database
+```
+
+Meadow Connection MySQL sits between the Meadow ORM layer and the MySQL server. It manages the mysql2 connection pool, which Meadow's MySQL provider uses to execute queries generated by FoxHound.
+
 ## Learn More
 
+- [Quickstart](quickstart.md) -- Step-by-step walkthrough with code examples
+- [Architecture](architecture.md) -- Design, data flow, and component responsibilities
 - [Schema & Table Creation](schema.md) -- Generate MySQL tables from Meadow schemas
-- [API Reference](api.md) -- Complete method and property documentation
+- [API Reference](api/reference.md) -- Complete method and property documentation
 - [Meadow](/meadow/meadow/) -- The data access layer
 - [FoxHound](/meadow/foxhound/) -- Query DSL used by Meadow

package/docs/_cover.md

@@ -0,0 +1,21 @@
+# Meadow Connection MySQL
+
+<small>v1.0.8</small>
+
+> MySQL connection pooling as a Fable service
+
+A lightweight wrapper around [mysql2](https://github.com/sidorares/node-mysql2) that manages connection pooling, supports auto-connect, and integrates with Meadow for provider-based data access. Register once, query from anywhere.
+
+- **Connection Pooling** -- Managed mysql2 pool with configurable connection limits
+- **Auto-Connect** -- Set one flag and the pool is ready at service instantiation
+- **Schema-Driven DDL** -- Generate and execute CREATE TABLE statements from Meadow schema definitions
+- **Named Placeholders** -- Automatic named placeholder support for parameterized queries
+- **Flexible Config** -- Accepts both Meadow-style and mysql2-native configuration formats
+- **Connection Safety** -- Guards against duplicate pools with cleansed logging
+
+[Get Started](README.md)
+[Quickstart](quickstart.md)
+[Architecture](architecture.md)
+[Schema & Tables](schema.md)
+[API Reference](api/reference.md)
+[GitHub](https://github.com/stevenvelozo/meadow-connection-mysql)

package/docs/_sidebar.md

@@ -1,11 +1,23 @@
 - Getting Started
 
   - [Overview](README.md)
+  - [Quickstart](quickstart.md)
+
+- Architecture
+
+  - [Design & Data Flow](architecture.md)
   - [Schema & Table Creation](schema.md)
 
-- Reference
+- API Reference
 
-  - [API Reference](api.md)
+  - [Full Reference](api/reference.md)
+  - [connect()](api/connect.md)
+  - [connectAsync()](api/connectAsync.md)
+  - [pool](api/pool.md)
+  - [generateCreateTableStatement()](api/generateCreateTableStatement.md)
+  - [createTable()](api/createTable.md)
+  - [createTables()](api/createTables.md)
+  - [generateDropTableStatement()](api/generateDropTableStatement.md)
 
 - Retold Ecosystem
 
@@ -13,4 +25,7 @@
   - [FoxHound](/meadow/foxhound/)
   - [Stricture](/meadow/stricture/)
   - [Meadow Endpoints](/meadow/meadow-endpoints/)
+  - [Meadow Connection MSSQL](/meadow/meadow-connection-mssql/)
+  - [Meadow Connection SQLite](/meadow/meadow-connection-sqlite/)
+  - [Meadow Connection RocksDB](/meadow/meadow-connection-rocksdb/)
   - [Fable](/fable/fable/)

package/docs/_topbar.md

@@ -1,6 +1,8 @@
 # Meadow Connection MySQL
 
 - [Overview](README.md)
+- [Quickstart](quickstart.md)
+- [Architecture](architecture.md)
 - [Schema & Tables](schema.md)
-- [API Reference](api.md)
+- [API Reference](api/reference.md)
 - [GitHub](https://github.com/stevenvelozo/meadow-connection-mysql)

package/docs/api/connect.md

@@ -0,0 +1,92 @@
+# connect()
+
+Creates the mysql2 connection pool synchronously.
+
+## Signature
+
+```javascript
+connect()
+```
+
+## Parameters
+
+None.
+
+## Return Value
+
+None.
+
+## Behavior
+
+1. Builds a connection settings object from `this.options.MySQL` (host, port, user, password, database, connectionLimit) plus `namedPlaceholders: true`
+2. If a pool already exists (`this._ConnectionPool` is truthy):
+   - Logs an error with cleansed settings (password replaced with `*****************`)
+   - Skips pool creation to prevent duplicate connections
+3. If no pool exists:
+   - Logs the connection details (host, port, user, database, connection limit)
+   - Calls `mysql2.createPool()` with the settings
+   - Sets `this.connected = true`
+
+## Basic Usage
+
+```javascript
+const libFable = require('fable');
+const libMeadowConnectionMySQL = require('meadow-connection-mysql');
+
+let _Fable = new libFable(
+	{
+		"MySQL":
+		{
+			"Server": "127.0.0.1",
+			"Port": 3306,
+			"User": "root",
+			"Password": "secret",
+			"Database": "bookstore",
+			"ConnectionPoolLimit": 20
+		}
+	});
+
+_Fable.serviceManager.addServiceType('MeadowMySQLProvider', libMeadowConnectionMySQL);
+_Fable.serviceManager.instantiateServiceProvider('MeadowMySQLProvider');
+
+_Fable.MeadowMySQLProvider.connect();
+
+console.log(_Fable.MeadowMySQLProvider.connected);
+// => true
+
+// Query using the pool
+_Fable.MeadowMySQLProvider.pool.query('SELECT * FROM Book LIMIT 5',
+	(pError, pRows) =>
+	{
+		console.log(`Found ${pRows.length} books.`);
+	});
+```
+
+## Double-Connect Guard
+
+Calling `connect()` a second time does not create a new pool:
+
+```javascript
+_Fable.MeadowMySQLProvider.connect();
+// First call -- pool created, connected = true
+
+_Fable.MeadowMySQLProvider.connect();
+// Second call -- logs error, pool unchanged
+// "Meadow-Connection-MySQL trying to connect to MySQL but is already connected"
+```
+
+This prevents connection leaks from accidental double-initialization.
+
+## Password Safety
+
+When the double-connect guard triggers, the error log includes the connection settings with the password masked:
+
+```
+{ connectionLimit: 20, host: '127.0.0.1', port: 3306, user: 'root',
+  password: '*****************', database: 'bookstore', namedPlaceholders: true }
+```
+
+## Related
+
+- [connectAsync](connectAsync.md) -- Async connection with callback
+- [pool](pool.md) -- Access the connection pool

package/docs/api/connectAsync.md

@@ -0,0 +1,118 @@
+# connectAsync(fCallback)
+
+Async wrapper around `connect()` that provides a callback interface for consistency with other Meadow connection providers (MSSQL, SQLite, RocksDB).
+
+## Signature
+
+```javascript
+connectAsync(fCallback)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `fCallback` | function | Yes | Callback with signature `(pError, pConnectionPool)` |
+
+## Return Value
+
+None (result provided via callback).
+
+## Callback Arguments
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `pError` | Error or null | Connection error, if any |
+| `pConnectionPool` | mysql2 Pool | The mysql2 connection pool instance |
+
+## Behavior
+
+1. If `fCallback` is not a function, logs a warning and substitutes a no-op callback
+2. If a pool already exists, returns it immediately via the callback (no reconnection)
+3. Otherwise calls `connect()` to create the pool, then returns it via the callback
+4. Wraps the entire operation in try-catch -- any errors are passed to the callback
+
+## Basic Usage
+
+```javascript
+const libFable = require('fable');
+const libMeadowConnectionMySQL = require('meadow-connection-mysql');
+
+let _Fable = new libFable(
+	{
+		"MySQL":
+		{
+			"Server": "127.0.0.1",
+			"Port": 3306,
+			"User": "root",
+			"Password": "secret",
+			"Database": "bookstore",
+			"ConnectionPoolLimit": 20
+		}
+	});
+
+_Fable.serviceManager.addServiceType('MeadowMySQLProvider', libMeadowConnectionMySQL);
+_Fable.serviceManager.instantiateServiceProvider('MeadowMySQLProvider');
+
+_Fable.MeadowMySQLProvider.connectAsync(
+	(pError, pConnectionPool) =>
+	{
+		if (pError)
+		{
+			console.error('Connection failed:', pError);
+			return;
+		}
+
+		// pConnectionPool is the mysql2 pool
+		pConnectionPool.query('SELECT * FROM Book LIMIT 5',
+			(pQueryError, pRows) =>
+			{
+				console.log(`Found ${pRows.length} books.`);
+			});
+	});
+```
+
+## Idempotent Calls
+
+Calling `connectAsync()` multiple times is safe -- if the pool already exists, it is returned without creating a new one:
+
+```javascript
+_Fable.MeadowMySQLProvider.connectAsync(
+	(pError, pPool1) =>
+	{
+		// First call creates the pool
+
+		_Fable.MeadowMySQLProvider.connectAsync(
+			(pError, pPool2) =>
+			{
+				// Second call returns the same pool
+				console.log(pPool1 === pPool2);
+				// => true
+			});
+	});
+```
+
+## Why connectAsync() Exists
+
+MySQL connection via mysql2 is inherently synchronous (the pool is created immediately, and TCP connections are managed lazily). The `connectAsync()` method exists for API consistency across Meadow connection providers:
+
+- **MSSQL** -- Requires async handshake (TDS protocol)
+- **SQLite** -- Requires async file open
+- **RocksDB** -- Requires async database open
+
+Using `connectAsync()` makes your code portable across database backends.
+
+## Missing Callback Warning
+
+If called without a callback, `connectAsync()` logs a warning:
+
+```javascript
+// Not recommended
+_Fable.MeadowMySQLProvider.connectAsync();
+// Logs: "Meadow MySQL connectAsync() called without a callback; this could lead to connection race conditions."
+```
+
+## Related
+
+- [connect](connect.md) -- Synchronous connection
+- [pool](pool.md) -- Access the connection pool

package/docs/api/createTable.md

@@ -0,0 +1,93 @@
+# createTable(pMeadowTableSchema, fCallback)
+
+Generates and executes a `CREATE TABLE IF NOT EXISTS` statement against the connected MySQL pool.
+
+## Signature
+
+```javascript
+createTable(pMeadowTableSchema, fCallback)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pMeadowTableSchema` | object | Yes | Schema with `TableName` and `Columns` array |
+| `fCallback` | function | Yes | Callback with signature `(pError)` |
+
+## Return Value
+
+None (result provided via callback).
+
+## Behavior
+
+1. Calls `generateCreateTableStatement(pMeadowTableSchema)` to produce the DDL string
+2. Executes the DDL against `this._ConnectionPool` via `pool.query()`
+3. On success: logs a success message and calls `fCallback()` with no error
+4. On error:
+   - If the error indicates the table already exists (detected via `originalError.info.message`), logs a warning and calls `fCallback()` with no error
+   - Otherwise logs the error and calls `fCallback(pError)`
+
+## Basic Usage
+
+```javascript
+let tmpSchema =
+{
+	TableName: 'Book',
+	Columns:
+	[
+		{ Column: 'IDBook', DataType: 'ID' },
+		{ Column: 'GUIDBook', DataType: 'GUID', Size: 36 },
+		{ Column: 'Title', DataType: 'String', Size: 256 },
+		{ Column: 'Author', DataType: 'String', Size: 128 },
+		{ Column: 'Year', DataType: 'Numeric' },
+		{ Column: 'Price', DataType: 'Decimal', Size: '10,2' }
+	]
+};
+
+_Fable.MeadowMySQLProvider.createTable(tmpSchema,
+	(pError) =>
+	{
+		if (pError)
+		{
+			console.error('Table creation failed:', pError);
+			return;
+		}
+		console.log('Book table created successfully.');
+	});
+```
+
+## Idempotent Operation
+
+Because the generated DDL uses `CREATE TABLE IF NOT EXISTS`, calling `createTable()` for an existing table does not produce an error. A warning is logged instead:
+
+```
+Meadow-MySQL CREATE TABLE Book executed but table already existed.
+```
+
+This makes `createTable()` safe to call during application startup without worrying about pre-existing tables.
+
+## Prerequisites
+
+The connection pool must be established before calling `createTable()`:
+
+```javascript
+_Fable.MeadowMySQLProvider.connectAsync(
+	(pError) =>
+	{
+		if (pError) { return; }
+
+		_Fable.MeadowMySQLProvider.createTable(tmpSchema,
+			(pCreateError) =>
+			{
+				if (pCreateError) { console.error(pCreateError); }
+			});
+	});
+```
+
+## Related
+
+- [generateCreateTableStatement](generateCreateTableStatement.md) -- Generate DDL without executing
+- [createTables](createTables.md) -- Create multiple tables sequentially
+- [generateDropTableStatement](generateDropTableStatement.md) -- Generate DROP TABLE DDL
+- [Schema & Table Creation](../schema.md) -- Full walkthrough

package/docs/api/createTables.md

@@ -0,0 +1,124 @@
+# createTables(pMeadowSchema, fCallback)
+
+Creates all tables defined in a Meadow schema object by calling `createTable()` for each table sequentially.
+
+## Signature
+
+```javascript
+createTables(pMeadowSchema, fCallback)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pMeadowSchema` | object | Yes | Schema with a `Tables` array of table schema objects |
+| `fCallback` | function | Yes | Callback with signature `(pError)` |
+
+### Schema Object Format
+
+```javascript
+{
+	Tables:
+	[
+		{
+			TableName: 'Author',
+			Columns:
+			[
+				{ Column: 'IDAuthor', DataType: 'ID' },
+				{ Column: 'Name', DataType: 'String', Size: 200 }
+			]
+		},
+		{
+			TableName: 'Book',
+			Columns:
+			[
+				{ Column: 'IDBook', DataType: 'ID' },
+				{ Column: 'Title', DataType: 'String', Size: 256 },
+				{ Column: 'IDAuthor', DataType: 'ForeignKey' }
+			]
+		}
+	]
+}
+```
+
+## Return Value
+
+None (result provided via callback).
+
+## Behavior
+
+1. Iterates `pMeadowSchema.Tables` using `fable.Utility.eachLimit()` with a concurrency of 1 (serial)
+2. Calls `createTable()` for each table in the array
+3. If any table creation fails, logs the error and passes it to the final callback
+4. On completion, logs a success message and calls `fCallback()`
+
+## Basic Usage
+
+```javascript
+let tmpFullSchema =
+{
+	Tables:
+	[
+		{
+			TableName: 'Author',
+			Columns:
+			[
+				{ Column: 'IDAuthor', DataType: 'ID' },
+				{ Column: 'GUIDAuthor', DataType: 'GUID', Size: 36 },
+				{ Column: 'Name', DataType: 'String', Size: 200 },
+				{ Column: 'Bio', DataType: 'Text' }
+			]
+		},
+		{
+			TableName: 'Book',
+			Columns:
+			[
+				{ Column: 'IDBook', DataType: 'ID' },
+				{ Column: 'GUIDBook', DataType: 'GUID', Size: 36 },
+				{ Column: 'Title', DataType: 'String', Size: 256 },
+				{ Column: 'Year', DataType: 'Numeric' },
+				{ Column: 'Price', DataType: 'Decimal', Size: '10,2' },
+				{ Column: 'IDAuthor', DataType: 'ForeignKey' }
+			]
+		},
+		{
+			TableName: 'Review',
+			Columns:
+			[
+				{ Column: 'IDReview', DataType: 'ID' },
+				{ Column: 'GUIDReview', DataType: 'GUID', Size: 36 },
+				{ Column: 'IDBook', DataType: 'ForeignKey' },
+				{ Column: 'Rating', DataType: 'Numeric' },
+				{ Column: 'Body', DataType: 'Text' },
+				{ Column: 'ReviewDate', DataType: 'DateTime' }
+			]
+		}
+	]
+};
+
+_Fable.MeadowMySQLProvider.createTables(tmpFullSchema,
+	(pError) =>
+	{
+		if (pError)
+		{
+			console.error('Schema creation failed:', pError);
+			return;
+		}
+		console.log('All tables created.');
+	});
+```
+
+## Serial Execution
+
+Tables are created one at a time (concurrency of 1). This avoids race conditions with foreign key constraints and ensures predictable execution order. The tables are created in the order they appear in the `Tables` array.
+
+## Error Handling
+
+If a table creation fails with an error other than "table already exists", execution stops and the error is passed to the callback. Tables created before the failure remain in the database.
+
+## Related
+
+- [createTable](createTable.md) -- Create a single table
+- [generateCreateTableStatement](generateCreateTableStatement.md) -- Generate DDL without executing
+- [Schema & Table Creation](../schema.md) -- Full walkthrough