0.2.0 Update

README.md

@@ -1,72 +1,75 @@
 # skript-db
 
-> Awesome direct database access for Skript
+ > Sensible SQL support for Skript.
-
-## Syntax
-
-### Expression `Data Source` => `datasource`
-
-This stores the connection information for a data source. This should be saved to a variable in a `script load` event or manually through an effect command.
-
-The url format for your database may vary! The example below uses a MySQL database.
-
-#### Syntax
-
-`[the] data(base|[ ]source) [(of|at)] %string%`
-
-#### Example
-
-```
-set {sql} to the database "mysql://localhost:3306/sys?user=admin&password=12345&useSSL=false"
-```
-
 ---
 
 ### Effect `Execute Statement`
+Executes a statement on a database and optionally stores the result in a variable. Expressions
+ embedded in the query will be escaped to avoid SQL injection.
+ <p>
+ If a single variable, such as `{test}`, is passed, the variable will be set to the number of
+ affected rows.
+ <p>
+ If a list variable, such as `{test::*}`, is passed, the query result will be mapped to the list
+ variable in the form `{test::<column name>::<row number>}`
 
-Executes a statement on a database and optionally stores the result in a variable. Expressions embedded in the query will be escaped to avoid SQL injection.
+ Specifying `synchronously` will make skript-db execute the query on the event thread, which is useful for async
-
+ events. Note that skript-db will ignore this flag if you attempt to run this on the main thread.
-If a single variable, such as `{test}`, is passed, the variable will be set to the number of affected rows.
-
-If a list variable, such as `{test::*}`, is passed, the query result will be mapped to the list variable in the form `{test::<column name>::<row number>}`
-
 #### Syntax
+```
+[synchronously] execute %string% (in|on) %datasource% [and store [[the] (output|result)[s]] (to|in) [the] [var[iable]] %-objects%]
+```
 
-`execute %text% (in|on) %datasource% 
+#### Examples
- [and store [[the] (output|result)[s]] (to|in) [the] [var[iable]] %variable%]`
- 
-#### Example
-
 ```
 execute "select * from table" in {sql} and store the result in {output::*}
-execute "select * from %{table variable}%" in {sql} and store the result in {output::*}
 ```
-
----
-
-### Expression `Unsafe Expression` => `text`
-
-Opts out of automatic SQL injection protection for a specific expression in a statement.
-
-#### Syntax
-
-`unsafe %text%`
-
-#### Example
-
 ```
-execute "select %unsafe {columns variable}% from %{table variable}%" in {sql} and store the result in {output::*}
+execute "select * where player=%{player}%" in {sql} and store the result in {output::*}
-execute unsafe {fully dynamic query} in {sql}
 ```
 
 ---
 
 ### Expression `Last Data Source Error` => `text`
-
 Stores the error from the last executed statement, if there was one.
-
 #### Syntax
-
+```
-`[the] [last] (sql|db|data(base|[ ]source)) error`
+[the] [last] (sql|db|data(base|[ ]source)) error
+```
 
 ---
+
+### Expression `Unsafe Expression` => `text`
+Opts out of automatic SQL injection protection for a specific expression in a statement.
+#### Syntax
+```
+unsafe %text%
+```
+
+#### Examples
+```
+execute "select %unsafe {columns variable}% from %{table variable}%" in {sql}
+```
+```
+execute unsafe {fully dynamic query} in {sql}
+```
+
+---
+
+### Expression `Data Source` => `datasource`
+Stores the connection information for a data source. This should be saved to a variable in a
+ `script load` event or manually through an effect command.
+
+ The url format for your database may vary! The example provided uses a MySQL database.
+#### Syntax
+```
+[the] data(base|[ ]source) [(of|at)] %string% [with [a] [max[imum]] [connection] life[ ]time of %timespan%]"
+```
+
+#### Examples
+```
+set {sql} to the database "mysql://localhost:3306/mydatabase?user=admin&password=12345&useSSL=false"
+```
+
+---
+

build.gradle

@@ -1,5 +1,5 @@
 group 'com.btk5h.skript-db'
-version '0.1.0'
+version '0.2.0'
 
 buildscript {
   repositories {
@@ -33,3 +33,13 @@ dependencies {
   shadow 'ch.njol:skript:2.2-SNAPSHOT'
   compile 'com.zaxxer:HikariCP:2.6.2'
 }
+
+task buildReadme(type: Javadoc) {
+  source = sourceSets.main.allJava
+  classpath = sourceSets.main.compileClasspath
+  destinationDir = projectDir
+  options.docletpath = [file('tools/skriptdoclet.jar')]
+  options.doclet = 'com.btk5h.skriptdoclet.SkriptDoclet'
+  options.addStringOption('file', 'README.md')
+  options.addStringOption('markdown', '-quiet')
+}

src/main/java/com/btk5h/skriptdb/SkriptDB.java

@@ -36,6 +36,13 @@ import javax.sql.rowset.RowSetProvider;
 import ch.njol.skript.Skript;
 import ch.njol.skript.SkriptAddon;
 
+/**
+ * # skript-db
+ *
+ * > Sensible SQL support for Skript.
+ *
+ * @index -1
+ */
 public final class SkriptDB extends JavaPlugin {
 
   private static SkriptDB instance;

src/main/java/com/btk5h/skriptdb/skript/EffExecuteStatement.java

@@ -31,10 +31,30 @@ import ch.njol.skript.lang.VariableString;
 import ch.njol.skript.variables.Variables;
 import ch.njol.util.Kleenean;
 
+/**
+ * Executes a statement on a database and optionally stores the result in a variable. Expressions
+ * embedded in the query will be escaped to avoid SQL injection.
+ * <p>
+ * If a single variable, such as `{test}`, is passed, the variable will be set to the number of
+ * affected rows.
+ * <p>
+ * If a list variable, such as `{test::*}`, is passed, the query result will be mapped to the list
+ * variable in the form `{test::<column name>::<row number>}`
+ *
+ * Specifying `synchronously` will make skript-db execute the query on the event thread, which is useful for async
+ * events. Note that skript-db will ignore this flag if you attempt to run this on the main thread.
+ *
+ * @name Execute Statement
+ * @pattern [synchronously] execute %string% (in|on) %datasource% [and store [[the] (output|result)[s]] (to|in)
+ * [the] [var[iable]] %-objects%]
+ * @example execute "select * from table" in {sql} and store the result in {output::*}
+ * @example execute "select * where player=%{player}%" in {sql} and store the result in {output::*}
+ * @since 0.1.0
+ */
 public class EffExecuteStatement extends Delay {
   static {
     Skript.registerEffect(EffExecuteStatement.class,
-        "execute %string% (in|on) %datasource% " +
+        "[(1¦synchronously)] execute %string% (in|on) %datasource% " +
             "[and store [[the] (output|result)[s]] (to|in) [the] [var[iable]] %-objects%]");
   }
 
@@ -48,25 +68,43 @@ public class EffExecuteStatement extends Delay {
   private VariableString var;
   private boolean isLocal;
   private boolean isList;
+  private boolean isSync;
+
+  private void continueScriptExecution(Event e, String res) {
+    lastError = res;
+
+    if (getNext() != null) {
+      TriggerItem.walk(getNext(), e);
+    }
+  }
 
   @Override
   protected void execute(Event e) {
-    CompletableFuture<String> sql =
+    boolean isMainThread = Bukkit.isPrimaryThread();
-        CompletableFuture.supplyAsync(() -> executeStatement(e), threadPool);
 
-    sql.whenComplete((res, err) -> {
+    if (isSync && !isMainThread) {
-      if (err != null) {
+      String result = executeStatement(e);
-        err.printStackTrace();
+      continueScriptExecution(e, result);
+    } else {
+      if (isMainThread) {
+        Skript.warning("A SQL query was attempted on the main thread!");
       }
 
-      Bukkit.getScheduler().runTask(SkriptDB.getInstance(), () -> {
+      CompletableFuture<String> sql =
-        lastError = res;
+          CompletableFuture.supplyAsync(() -> executeStatement(e), threadPool);
 
-        if (getNext() != null) {
+      sql.whenComplete((res, err) -> {
-          TriggerItem.walk(getNext(), e);
+        if (err != null) {
+          err.printStackTrace();
+        }
+
+        if (isSync) {
+          continueScriptExecution(e, res);
+        } else {
+          Bukkit.getScheduler().runTask(SkriptDB.getInstance(), () -> continueScriptExecution(e, res));
         }
       });
-    });
+    }
   }
 
   @Override
@@ -128,16 +166,41 @@ public class EffExecuteStatement extends Delay {
     StringBuilder sb = new StringBuilder();
     List<Object> parameters = new ArrayList<>();
     Object[] objects = SkriptUtil.getTemplateString(((VariableString) query));
-    for (Object o : objects) {
+    for (int i = 0; i < objects.length; i++) {
+      Object o = objects[i];
       if (o instanceof String) {
         sb.append(o);
       } else {
         Expression<?> expr = SkriptUtil.getExpressionFromInfo(o);
+
+        String before = getString(objects, i - 1);
+        String after = getString(objects, i + 1);
+        boolean standaloneString = false;
+
+        if (before != null && after != null) {
+          if (before.endsWith("'") && after.endsWith("'")) {
+            standaloneString = true;
+          }
+        }
+
+        Object expressionValue = expr.getSingle(e);
+
         if (expr instanceof ExprUnsafe) {
-          sb.append(expr.getSingle(e));
+          sb.append(expressionValue);
+
+          if (standaloneString && expressionValue instanceof String) {
+            String rawExpression = ((ExprUnsafe) expr).getRawExpression();
+            Skript.warning(
+                String.format("Unsafe may have been used unnecessarily. Try replacing 'unsafe %1$s' with %1$s",
+                    rawExpression));
+          }
         } else {
-          parameters.add(expr.getSingle(e));
+          parameters.add(expressionValue);
           sb.append('?');
+
+          if (standaloneString) {
+            Skript.warning("Do not surround expressions with quotes!");
+          }
         }
       }
     }
@@ -151,6 +214,20 @@ public class EffExecuteStatement extends Delay {
     return stmt;
   }
 
+  private String getString(Object[] objects, int index) {
+    if (index < 0 || index >= objects.length) {
+      return null;
+    }
+
+    Object object = objects[index];
+
+    if (object instanceof String) {
+      return (String) object;
+    }
+
+    return null;
+  }
+
   private void setVariable(Event e, String name, Object obj) {
     Variables.setVariable(name.toLowerCase(Locale.ENGLISH), obj, e, isLocal);
   }
@@ -169,7 +246,7 @@ public class EffExecuteStatement extends Delay {
     while (crs.next()) {
       for (int i = 1; i <= columnCount; i++) {
         setVariable(e, baseVariable + meta.getColumnLabel(i).toLowerCase(Locale.ENGLISH)
-                + Variable.SEPARATOR + rowNumber, crs.getObject(i));
+            + Variable.SEPARATOR + rowNumber, crs.getObject(i));
       }
       rowNumber++;
     }
@@ -195,6 +272,7 @@ public class EffExecuteStatement extends Delay {
     }
     dataSource = (Expression<HikariDataSource>) exprs[1];
     Expression<?> expr = exprs[2];
+    isSync = parseResult.mark == 1;
     if (expr instanceof Variable) {
       Variable<?> varExpr = (Variable<?>) expr;
       var = SkriptUtil.getVariableName(varExpr);

src/main/java/com/btk5h/skriptdb/skript/ExprDBError.java

@@ -9,6 +9,14 @@ import ch.njol.skript.lang.SkriptParser;
 import ch.njol.skript.lang.util.SimpleExpression;
 import ch.njol.util.Kleenean;
 
+/**
+ * Stores the error from the last executed statement, if there was one.
+ *
+ * @name Last Data Source Error
+ * @pattern [the] [last] (sql|db|data(base|[ ]source)) error
+ * @return text
+ * @since 0.1.0
+ */
 public class ExprDBError extends SimpleExpression<String> {
   static {
     Skript.registerExpression(ExprDBError.class, String.class,

src/main/java/com/btk5h/skriptdb/skript/ExprDataSource.java

@@ -4,20 +4,41 @@ import com.zaxxer.hikari.HikariDataSource;
 
 import org.bukkit.event.Event;
 
+import java.util.HashMap;
+import java.util.Map;
+
 import ch.njol.skript.Skript;
 import ch.njol.skript.lang.Expression;
 import ch.njol.skript.lang.ExpressionType;
 import ch.njol.skript.lang.SkriptParser;
 import ch.njol.skript.lang.util.SimpleExpression;
+import ch.njol.skript.util.Timespan;
 import ch.njol.util.Kleenean;
 
+/**
+ * Stores the connection information for a data source. This should be saved to a variable in a
+ * `script load` event or manually through an effect command.
+ *
+ * The url format for your database may vary! The example provided uses a MySQL database.
+ *
+ * @name Data Source
+ * @index -1
+ * @pattern [the] data(base|[ ]source) [(of|at)] %string% [with [a] [max[imum]] [connection] life[ ]time of %timespan%]"
+ * @return datasource
+ * @example set {sql} to the database "mysql://localhost:3306/mydatabase?user=admin&password=12345&useSSL=false"
+ * @since 0.1.0
+ */
 public class ExprDataSource extends SimpleExpression<HikariDataSource> {
   static {
     Skript.registerExpression(ExprDataSource.class, HikariDataSource.class,
-        ExpressionType.COMBINED, "[the] data(base|[ ]source) [(of|at)] %string%");
+        ExpressionType.COMBINED, "[the] data(base|[ ]source) [(of|at)] %string% " +
+            "[with [a] [max[imum]] [connection] life[ ]time of %-timespan%]");
   }
 
+  private static Map<String, HikariDataSource> connectionCache = new HashMap<>();
+
   private Expression<String> url;
+  private Expression<Timespan> maxLifetime;
 
   @Override
   protected HikariDataSource[] get(Event e) {
@@ -30,10 +51,24 @@ public class ExprDataSource extends SimpleExpression<HikariDataSource> {
       jdbcUrl = "jdbc:" + jdbcUrl;
     }
 
+    if (connectionCache.containsKey(jdbcUrl)) {
+      return new HikariDataSource[]{connectionCache.get(jdbcUrl)};
+    }
+
     HikariDataSource ds = new HikariDataSource();
     ds.setJdbcUrl(jdbcUrl);
 
-    return new HikariDataSource[] {ds};
+    if (maxLifetime != null) {
+      Timespan l = maxLifetime.getSingle(e);
+
+      if (l != null) {
+        ds.setMaxLifetime(l.getMilliSeconds());
+      }
+    }
+
+    connectionCache.put(jdbcUrl, ds);
+
+    return new HikariDataSource[]{ds};
   }
 
   @Override
@@ -56,6 +91,7 @@ public class ExprDataSource extends SimpleExpression<HikariDataSource> {
   public boolean init(Expression<?>[] exprs, int matchedPattern, Kleenean isDelayed,
                       SkriptParser.ParseResult parseResult) {
     url = (Expression<String>) exprs[0];
+    maxLifetime = (Expression<Timespan>) exprs[1];
     return true;
   }
 }

src/main/java/com/btk5h/skriptdb/skript/ExprUnsafe.java

@@ -9,17 +9,32 @@ import ch.njol.skript.lang.SkriptParser;
 import ch.njol.skript.lang.util.SimpleExpression;
 import ch.njol.util.Kleenean;
 
+/**
+ * Opts out of automatic SQL injection protection for a specific expression in a statement.
+ *
+ * @name Unsafe Expression
+ * @pattern unsafe %text%
+ * @return text
+ * @example execute "select %unsafe {columns variable}% from %{table variable}%" in {sql}
+ * @example execute unsafe {fully dynamic query} in {sql}
+ * @since 0.1.0
+ */
 public class ExprUnsafe extends SimpleExpression<String> {
   static {
     Skript.registerExpression(ExprUnsafe.class, String.class, ExpressionType.COMBINED,
         "unsafe %string%");
   }
 
-  private Expression<String> str;
+  private Expression<String> stringExpression;
+  private String rawExpression;
+
+  public String getRawExpression() {
+    return rawExpression;
+  }
 
   @Override
   protected String[] get(Event e) {
-    return str.getArray(e);
+    return stringExpression.getArray(e);
   }
 
   @Override
@@ -34,14 +49,15 @@ public class ExprUnsafe extends SimpleExpression<String> {
 
   @Override
   public String toString(Event e, boolean debug) {
-    return "unsafe " + str.toString(e, debug);
+    return "unsafe " + stringExpression.toString(e, debug);
   }
 
   @SuppressWarnings("unchecked")
   @Override
   public boolean init(Expression<?>[] exprs, int matchedPattern, Kleenean isDelayed,
                       SkriptParser.ParseResult parseResult) {
-    str = (Expression<String>) exprs[0];
+    stringExpression = (Expression<String>) exprs[0];
+    rawExpression = parseResult.expr.substring("unsafe".length()).trim();
     return true;
   }
 }

src/main/resources/plugin.yml

@@ -1,4 +1,4 @@
 name: skript-db
-version: 0.1.0
+version: 0.2.0
 main: com.btk5h.skriptdb.SkriptDB
 depend: [Skript]