Merge pull request #1 from php-etl/feature/initilizer-queries

Updated plugin to integrate initializer and de-initializer requests

Author: gplanchat

README.md

@@ -1,39 +1,67 @@
 # SQL Plugin
 
-This plugin allows you to retrieve or insert data from/to a database.
+## What is it ?
+
+The SQL plugin allows you to write your own SQL queries and use them into the Pipeline stack.
+
+SQL, Structured Query Language, is a language for manipulating databases.
 
 ## Installation
 
-```
+```shell
 composer require php-etl/sql-plugin
 ```
 
-## Basic usage
+## Usage
+
+### Database connection
+The SQL plugin uses the PDO extension and relies on its interface to access databases using
+the `dsn`, `username` and `password` parameters.
+
+This connection must be present in any case, whether it be when defining the extractor,
+loader or lookup.
+
+```yaml
+connection:
+    dsn: 'mysql:host=127.0.0.1;port=3306;dbname=kiboko'
+    username: username
+    password: password
+```
+
+It is possible to specify options at the time of this connection using `options`. Currently, it is only possible to 
+specify if the database connection should be persistent.
+
+```yaml
+connection:
+    # ...
+    options:
+      persistent: true
+```
 
 ### Building an extractor
 ```yaml
 sql:
   extractor:
     query: 'SELECT * FROM table1'
-    connection:
-      dsn: 'mysql:host=127.0.0.1;port=3306;dbname=kiboko'
-      username: username
-      password: password
+  connection:
+    dsn: 'mysql:host=127.0.0.1;port=3306;dbname=kiboko'
+    username: username
+    password: password
 ```
 ### Building a lookup
 
 ```yaml
 sql:
   lookup:
     query: 'SELECT * FROM table2 WHERE bar = foo'
-    connection:
-      dsn: 'mysql:host=127.0.0.1;port=3306;dbname=kiboko'
-      username: username
-      password: password
     merge:
       map:
         - field: '[options]'
           expression: 'lookup["name"]'
+  connection:
+    dsn: 'mysql:host=127.0.0.1;port=3306;dbname=kiboko'
+    username: username
+    password: password
 
 ```
 
@@ -42,33 +70,33 @@ sql:
 sql:
   loader:
     query: 'INSERT INTO table1 VALUES (bar, foo, barfoo)'
-    connection:
-      dsn: 'mysql:host=127.0.0.1;port=3306;dbname=kiboko'
-      username: username
-      password: password
+  connection:
+    dsn: 'mysql:host=127.0.0.1;port=3306;dbname=kiboko'
+    username: username
+    password: password
 
 ```
 
-## Advanced Usage : using params in your queries
+## Advanced Usage
 
-Thanks to the SQL plugin, it is possible to write your queries with parameters.
+### Using params in your queries
 
-### With params
+Thanks to the SQL plugin, it is possible to write your queries with parameters.
 
 If you write a prepared statement using named parameters (`:param`), your parameter key in the configuration will be 
 the name of your parameter without the `:` :
 
 ```yaml
 sql:
-  # ... 
-  query: 'INSERT INTO table1 VALUES (:value1, :value2, :value3)'
-  params:
-    - key: value1
-      value: '@=input["value1"]'
-    - key: value2
-      value: '@=input["value3"]'
-    - key: value3
-      value: '@=input["value3"]'
+  loader:
+    query: 'INSERT INTO table1 VALUES (:value1, :value2, :value3)'
+    parameters:
+      - key: value1
+        value: '@=input["value1"]'
+      - key: value2
+        value: '@=input["value3"]'
+      - key: value3
+        value: '@=input["value3"]'
     # ... 
 ```
 
@@ -77,16 +105,46 @@ configuration will be its position (starting from 1) :
 
 ```yaml
 sql:
+  loader: 
+    query: 'INSERT INTO table1 VALUES (?, ?, ?)'
+    parameters:
+      - key: 1
+        value: '@=input["value1"]'
+      - key: 2
+        value: '@=input["value3"]'
+      - key: 3
+        value: '@=input["value3"]'
   # ... 
-  query: 'INSERT INTO table1 VALUES (?, ?, ?)'
-  params:
-    - key: 1
-      value: '@=input["value1"]'
-    - key: 2
-      value: '@=input["value3"]'
-    - key: 3
-      value: '@=input["value3"]'
-  # ... 
+```
+
+### Creating before and after queries
+
+In some cases, you may need to run queries in order to best prepare for the execution of your pipeline.
+
+#### Before queries
+Before queries will be executed before performing the query written in the configuration. Often, these are
+queries that set up the database.
+
+```yaml
+sql:
+  before:
+    queries:
+      - 'CREATE TABLE foo (id INTEGER NOT NULL, value VARCHAR(255) NOT NULL)'
+      - 'INSERT INTO foo (id, value) VALUES (1, "Lorem ipsum dolor")'
+      - 'INSERT INTO foo (id, value) VALUES (2, "Sit amet consecutir")'
+  # ...
+```
+
+#### After queries
+After queries will be executed after performing the query written in the configuration. Often, these are
+queries that clean up the database.
+
+```yaml
+sql:
+  after:
+    queries:
+      - 'DROP TABLE foo'
+  # ...
 ```
 
 ## See more

composer.json

@@ -20,6 +20,13 @@
         "php-etl/satellite-toolbox": "^0.1.0",
         "php-etl/fast-map-plugin": "^0.4.0"
     },
+    "require-dev": {
+        "phpunit/phpunit": "^9.0",
+        "php-etl/phpunit-extension": "^0.2.0",
+        "adlawson/vfs": "^0.12.1",
+        "phpstan/phpstan": "^0.12.93",
+        "php-etl/sql-flow": "^0.1.0"
+    },
     "autoload": {
         "psr-4": {
             "Kiboko\\Plugin\\SQL\\": "src/"
@@ -40,12 +47,5 @@
     },
     "config": {
         "bin-dir": "bin"
-    },
-    "require-dev": {
-        "symfony/console": "^5.2",
-        "symfony/yaml": "^5.2",
-        "phpunit/phpunit": "^9.0",
-        "php-etl/phpunit-extension": "^0.2.0",
-        "adlawson/vfs": "^0.12.1"
     }
 }