From 66a25bd80a01bc86799cbad40b8384c4aa05b462 Mon Sep 17 00:00:00 2001
From: Risto Lahtela <djrapitops@hotmail.com>
Date: Sun, 28 Jul 2019 11:57:27 +0300
Subject: [PATCH] Created APIv5 Query API (markdown)

---
 APIv5-Query-API.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 APIv5-Query-API.md

diff --git a/APIv5-Query-API.md b/APIv5-Query-API.md
new file mode 100644
index 0000000..d4b6fdd
--- /dev/null
+++ b/APIv5-Query-API.md
@@ -0,0 +1,98 @@
+![Plan Header](http://puu.sh/AXSg7/5f2f78c06c.jpg)
+# Plan API version 5 - Query API
+
+This page is about API that is available in **version 4.9.0** and above.  
+API can be called on all platforms.
+
+This API requires `QUERY_API` capability.
+
+See [APIv5](https://github.com/plan-player-analytics/Plan/wiki/APIv5#plan-api-version-5) for dependency information
+
+### Table of contents
+
+- Obtaining QueryService
+- Checking that database is what you expect
+- Performing Queries
+  - Available pre-made queries
+- Executing Statements
+
+## Obtaining QueryService
+
+`QueryService` can be obtained like so:
+```
+try {
+    QueryService queryService = QueryService.getInstance();
+} catch (IllegalStateException planIsNotEnabled) {
+    // Plan is not enabled, handle exception
+} 
+```
+
+## Checking that database is what you expect
+
+Database schema might change due to optimizations or additions so it might be necessary to check if the schema matches what you need.
+
+- [[Database Schema]]
+
+You can check if a table exists like this:
+```
+boolean hasTable = queryService.getCommonQueries().doesDBHaveTable(tableName);
+```
+
+You can check if a table has a column like this:
+```
+boolean hasColumn = queryService.getCommonQueries().doesDBHaveTableColumn(tableName, columName);
+```
+
+Any method called in `CommonQueries` blocks the thread.
+
+In order to perform queries in the correct SQL dialect, you might need the following code. Please note that H2 has MySQL compatibility mode engaged.
+```
+String dbType = queryService.getDBType(); // H2, SQLITE, MYSQL
+```
+
+## Performing queries
+
+Queries can be done with `QueryService#query` method. Queries block the thread.
+
+Here is an example of a completed query
+```
+String result = queryService.query(
+    "SELECT * FROM plan_users WHERE uuid=?",
+    (PreparedStatement) statement -> {
+        statement.setString(1, playerUUID.toString());
+        try (ResultSet results = statement.executeQuery()) {
+            return set.next ? set.getString("name") : null;
+        }
+    }
+);
+```
+
+### Available pre-made queries
+
+Some queries can be performed without the query method above, they are available with `QueryService#getCommonQueries`
+
+Any method called in `CommonQueries` blocks the thread.
+
+## Executing statements
+
+Statements can be executed with `QueryService#execute` method.
+
+Here is an example of a executed statement
+```
+Future<?> done = queryService.execute(
+    "INSERT INTO custom_table (uuid, value) VALUES (?, ?)",
+    (PreparedStatement) statement -> {
+        statement.setString(1, playerUUID.toString());
+        statement.setString(2, value);
+        statement.execute();
+    }
+);
+done.get(); // (Optional) Block thread until transaction was executed
+```
+
+### Note: Transactions
+
+`execute` does not block the thread, because the SQL is executed on another thread concurrently.
+If you would like to wait for the statement to execute you can call `Future#get()` to block the thread.
+
+**Do not call `Future#get()` inside `execute` - This might deadlock the whole database due to blocked transaction thread!**
\ No newline at end of file