From a1aaf10fb53aafdb4f0484cc75725a2177fc2a07 Mon Sep 17 00:00:00 2001
From: Christopher Vagnetoft <cvagnetoft@gmail.com>
Date: Thu, 16 Dec 2021 16:29:40 +0100
Subject: [PATCH] Added docs for com.noccy.pdo.shell

---
 Home.md                |  1 +
 com.noccy.pdo.shell.md | 78 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+)
 create mode 100644 com.noccy.pdo.shell.md

diff --git a/Home.md b/Home.md
index c6a2722..7217e83 100644
--- a/Home.md
+++ b/Home.md
@@ -6,5 +6,6 @@ Welcome to the Wiki.
 
 - [com.noccy.apiclient](com.noccy.apiclient) - API catalog and request helper
 - [com.noccy.pdo](com.noccy.pdo) - PDO Database helpers
+- [com.noccy.pdo.shell](com.noccy.pdo.shell) - PDO Shell
 - [com.noccy.watcher](com.noccy.watcher) - Run scripts when files are modified
 
diff --git a/com.noccy.pdo.shell.md b/com.noccy.pdo.shell.md
new file mode 100644
index 0000000..ac64d86
--- /dev/null
+++ b/com.noccy.pdo.shell.md
@@ -0,0 +1,78 @@
+# PDO Shell Plugin
+
+This is a plugin to work interactively with PDO.
+
+## Installation
+
+Global installation (recommended, requires SPARK_PLUGINS environment):
+
+1. Extract the plug into your global plugin directory (`$SPARK_PLUGINS`)
+2. Go to your project directory and run `spark plugin --enable com.noccy.pdo.shell`
+
+Local installation:
+
+1. Extract the directory into `.spark/plugins`, like a savage.
+
+## Configuration
+
+To define resorces using PHP, add this to the appropriate preloaded file:
+
+```php
+create_resource($name, $type, $uri);
+```
+
+You can also use the config file `.spark/resources.json`:
+
+```json
+{
+  "resources": {}
+}
+```
+
+Resources are defined with the name as the key, and the *full* connection URI
+as the value. The URI should contain the resource type as well as the resource
+URI separated by a plus sign, in this case `pdo+mysql`, `pdo+sqlite` etc.
+
+```json
+...
+  "db": "pdo+mysql://user:pass@host:port/dbname"
+...
+```
+
+You can also create a temporary in-memory SQLite database by using `pdo+sqlite:`
+
+## Usage
+
+The simplest use is invoking the shell directly:
+
+    $ spark pdo:shell
+    PDO[db]>
+
+You are presented with a prompt containing the string "PDO", follwed by the currently
+selected resource in brackets. Commands start with a period (`.`) and you can get a
+list of the valid commands with `.help`.
+
+To run a query, you can either run it directly:
+
+    PDO[db]> SELECT id FROM users WHERE username='bob'
+
+Or let the shell do the escaping for you:
+
+    PDO[db]> .query "SELECT id FROM users WHERE username=?" bob
+
+You can also read the commands from a file and have them executed as if they were
+entered into the shell:
+
+    $ spark pdo:shell -r sparkrc
+
+### Selecting the resource
+
+This can be done from the command line:
+
+    $ spark pdo:shell --db otherdb
+
+Or from within the shell:
+
+    PDO[db]> .select otherdb
+    PDO[otherdb]> 
+