#62: Make composition of SQL expression easier and safer

* Introduced a new class `SqlEntry` which represents a part of and SQL expression
* `SqlEntry` brings a number of methods and helper classes
* `SqlEntryComposition` offers a way to compose a full SQL expression as `SqlEntry` in SQL format (almost)
* `SqlEntry` is now leveraged in `SqlItem`, `DBFunction` and `DBTable`

Author: benedeki

balta/src/main/scala/za/co/absa/db/balta/classes/DBFunction.scala

@@ -19,6 +19,8 @@ package za.co.absa.db.balta.classes
 import za.co.absa.db.balta.classes.DBFunction.{DBFunctionWithNamedParamsToo, DBFunctionWithPositionedParamsOnly}
 import za.co.absa.db.balta.typeclasses.QueryParamType
 import za.co.absa.db.balta.classes.inner.Params.{NamedParams, OrderedParams}
+import za.co.absa.db.mag.core.SqlEntry
+import za.co.absa.db.mag.core.SqlEntryComposition._
 
 /**
  * A class that represents a database function call. It can be used to execute a function and verify the result.
@@ -32,18 +34,18 @@ import za.co.absa.db.balta.classes.inner.Params.{NamedParams, OrderedParams}
  * @param namedParams   - the list of parameters identified by their name (following the positioned parameters)
  *
  */
-sealed abstract class DBFunction private(functionName: String,
+sealed abstract class DBFunction private(functionName: SqlEntry,
                                          orderedParams: OrderedParams,
                                          namedParams: NamedParams) extends DBQuerySupport {
 
-  private def sql(orderBy: String): String = {
+  private def sql(orderBy: Option[SqlEntry]): SqlEntry = {
     val positionedParamEntries = orderedParams.values.map(_.sqlEntry)
     val namedParamEntries = namedParams.items.map{ case (columnName, queryParamValue) =>
-      columnName.sqlEntry + " := " + queryParamValue.sqlEntry
+      columnName.sqlEntry := queryParamValue.sqlEntry
     }
     val paramEntries = positionedParamEntries ++ namedParamEntries
     val paramsLine = paramEntries.mkString(",")
-    s"SELECT * FROM $functionName($paramsLine) $orderBy"
+    SELECT(ALL) FROM functionName(paramsLine) ORDER BY (orderBy)
   }
 
   /**
@@ -92,7 +94,7 @@ sealed abstract class DBFunction private(functionName: String,
    * @return            - the result of the verify function
    */
   def execute[R](orderBy: String)(verify: QueryResult => R /* Assertion */)(implicit connection: DBConnection): R = {
-    val orderByPart = if (orderBy.nonEmpty) {s"ORDER BY $orderBy"} else ""
+    val orderByPart = SqlEntry(orderBy).toOption
     runQuery(sql(orderByPart), orderedParams.values ++ namedParams.values)(verify)
   }
 
@@ -140,15 +142,15 @@ object DBFunction {
    * @return              - a new instance of the DBFunction class
    */
   def apply(functionName: String): DBFunctionWithPositionedParamsOnly = {
-    DBFunctionWithPositionedParamsOnly(functionName)
+    DBFunctionWithPositionedParamsOnly(SqlEntry(functionName))
   }
 
   def apply(functionName: String, params: NamedParams): DBFunctionWithNamedParamsToo = {
-    DBFunctionWithNamedParamsToo(functionName, OrderedParams(), params)
+    DBFunctionWithNamedParamsToo(SqlEntry(functionName), OrderedParams(), params)
   }
 
   def apply(functionName: String, params: OrderedParams): DBFunctionWithPositionedParamsOnly = {
-    DBFunctionWithPositionedParamsOnly(functionName, params, NamedParams())
+    DBFunctionWithPositionedParamsOnly(SqlEntry(functionName), params, NamedParams())
   }
 
   /**
@@ -159,7 +161,7 @@ object DBFunction {
    * @param orderedParams - the list of parameters identified by their position (preceding the named parameters)
    * @param namedParams   - the list of parameters identified by their name (following the positioned parameters)
    */
-  sealed case class DBFunctionWithPositionedParamsOnly private(functionName: String,
+  sealed case class DBFunctionWithPositionedParamsOnly private(functionName: SqlEntry,
                                                                orderedParams: OrderedParams = OrderedParams(),
                                                                namedParams: NamedParams = NamedParams()
                                                               ) extends DBFunction(functionName, orderedParams, namedParams) {
@@ -195,7 +197,7 @@ object DBFunction {
    * @param orderedParams - the list of parameters identified by their position (preceding the named parameters)
    * @param namedParams   - the list of parameters identified by their name (following the positioned parameters)
    */
-  sealed case class DBFunctionWithNamedParamsToo private(functionName: String,
+  sealed case class DBFunctionWithNamedParamsToo private(functionName: SqlEntry,
                                                          orderedParams: OrderedParams = OrderedParams(),
                                                          namedParams: NamedParams = NamedParams()
                                                         ) extends DBFunction(functionName, orderedParams, namedParams)

balta/src/main/scala/za/co/absa/db/balta/classes/DBQuerySupport.scala

@@ -17,16 +17,17 @@
 package za.co.absa.db.balta.classes
 
 import za.co.absa.db.balta.typeclasses.QueryParamValue
+import za.co.absa.db.mag.core.SqlEntry
 
 /**
  * This is a based trait providing the ability to run an SQL query and verify the result via a provided function.
  */
 trait DBQuerySupport {
 
-  protected def runQuery[R](sql: String, queryValues: Vector[QueryParamValue])
+  protected def runQuery[R](sql: SqlEntry, queryValues: Vector[QueryParamValue])
                  (verify: QueryResult => R /* Assertion */)
                  (implicit connection: DBConnection): R = {
-    val preparedStatement = connection.connection.prepareStatement(sql)
+    val preparedStatement = connection.connection.prepareStatement(sql.entry)
 
     queryValues.foldLeft(1) { case (parameterIndex, queryValue) =>
       queryValue.assign match { // this is better readable-wise than map + getOrElse

balta/src/main/scala/za/co/absa/db/balta/classes/DBTable.scala

@@ -18,16 +18,18 @@ package za.co.absa.db.balta.classes
 
 import za.co.absa.db.balta.classes.inner.Params
 import za.co.absa.db.balta.classes.inner.Params.NamedParams
-import za.co.absa.db.balta.typeclasses.{QueryParamValue, QueryParamType}
+import za.co.absa.db.balta.typeclasses.{QueryParamType, QueryParamValue}
 import za.co.absa.db.balta.classes.inner.Params.OrderedParams
+import za.co.absa.db.mag.core.SqlEntry
+import za.co.absa.db.mag.core.SqlEntryComposition._
 
 /**
   * This class represents a database table. It allows to perform INSERT, SELECT and COUNT operations on the table easily.
   *
   * @param tableName  The name of the table
   */
 case class DBTable(tableName: String) extends DBQuerySupport{
-
+  private val table: SqlEntry = SqlEntry(tableName)
   /**
     * Inserts a new row into the table.
     *
@@ -42,7 +44,7 @@ case class DBTable(tableName: String) extends DBQuerySupport{
     }
 
     val paramStr = values.values.map(_.sqlEntry).mkString(",")
-    val sql = s"INSERT INTO $tableName $columns VALUES($paramStr) RETURNING *;"
+    val sql = INSERT INTO table(columns) VALUES(paramStr) RETURNING ALL
     runQuery(sql, values.values){_.next()}
   }
 
@@ -78,7 +80,7 @@ case class DBTable(tableName: String) extends DBQuerySupport{
    * @return            - the result of the verify function
    */
   def where[R](params: NamedParams)(verify: QueryResult => R)(implicit connection: DBConnection): R = {
-    composeSelectAndRun(strToOption(paramsToWhereCondition(params)), None, params.values)(verify)
+    composeSelectAndRun(paramsToWhereCondition(params).toOption, None, params.values)(verify)
   }
 
   /**
@@ -91,7 +93,7 @@ case class DBTable(tableName: String) extends DBQuerySupport{
    * @return            - the result of the verify function
    */
   def where[R](params: NamedParams, orderBy: String)(verify: QueryResult => R)(implicit connection: DBConnection): R = {
-    composeSelectAndRun(strToOption(paramsToWhereCondition(params)), strToOption(orderBy), params.values)(verify)
+    composeSelectAndRun(paramsToWhereCondition(params).toOption, SqlEntry(orderBy).toOption, params.values)(verify)
   }
 
   /**
@@ -103,7 +105,7 @@ case class DBTable(tableName: String) extends DBQuerySupport{
    * @return            - the result of the verify function
    */
   def where[R](condition: String)(verify: QueryResult => R)(implicit connection: DBConnection): R = {
-    composeSelectAndRun(strToOption(condition), None)(verify)
+    composeSelectAndRun(SqlEntry(condition).toOption, None)(verify)
   }
 
   /**
@@ -116,7 +118,7 @@ case class DBTable(tableName: String) extends DBQuerySupport{
    * @return            - the result of the verify function
    */
   def where[R](condition: String, orderBy: String)(verify: QueryResult => R)(implicit connection: DBConnection): R = {
-    composeSelectAndRun(strToOption(condition), strToOption(orderBy))(verify)
+    composeSelectAndRun(SqlEntry(condition).toOption, SqlEntry(orderBy).toOption)(verify)
   }
 
   /**
@@ -141,27 +143,27 @@ case class DBTable(tableName: String) extends DBQuerySupport{
    * @return            - the result of the verify function
    */
   def all[R](orderBy: String)(verify: QueryResult => R)(implicit connection: DBConnection): R = {
-    composeSelectAndRun(None, strToOption(orderBy))(verify)
+    composeSelectAndRun(None, SqlEntry(orderBy).toOption)(verify)
   }
 
   def deleteWithCheck[R](verify: QueryResult => R)(implicit connection: DBConnection): R = {
     composeDeleteAndRun(None)(verify)
   }
 
   def deleteWithCheck[R](whereParams: NamedParams)(verify: QueryResult => R)(implicit connection: DBConnection): R = {
-    composeDeleteAndRun(strToOption(paramsToWhereCondition(whereParams)), whereParams.values)(verify)
+    composeDeleteAndRun(paramsToWhereCondition(whereParams).toOption, whereParams.values)(verify)
   }
 
   def deleteWithCheck[R](whereCondition: String)(verify: QueryResult => R)(implicit connection: DBConnection): R = {
-    composeDeleteAndRun(strToOption(whereCondition))(verify)
+    composeDeleteAndRun(SqlEntry(whereCondition).toOption)(verify)
   }
 
   def delete(whereParams: NamedParams)(implicit connection: DBConnection): Unit = {
-    composeDeleteAndRun(strToOption(paramsToWhereCondition(whereParams)), whereParams.values)(_ => ())
+    composeDeleteAndRun(paramsToWhereCondition(whereParams).toOption, whereParams.values)(_ => ())
   }
 
   def delete(whereCondition: String = "")(implicit connection: DBConnection): Unit = {
-    composeDeleteAndRun(strToOption(whereCondition))(_ => ())
+    composeDeleteAndRun(SqlEntry(whereCondition).toOption)(_ => ())
   }
   /**
    * Counts the rows in the table.
@@ -180,7 +182,7 @@ case class DBTable(tableName: String) extends DBQuerySupport{
    */
   @deprecated("Use countOnCondition instead", "0.2.0")
   def count(params: NamedParams)(implicit connection: DBConnection): Long = {
-    composeCountAndRun(strToOption(paramsToWhereCondition(params)), params.values)
+    composeCountAndRun(paramsToWhereCondition(params).toOption, params.values)
   }
 
   /**
@@ -191,7 +193,7 @@ case class DBTable(tableName: String) extends DBQuerySupport{
    */
   @deprecated("Use countOnCondition instead", "0.2.0")
   def count(condition: String)(implicit connection: DBConnection): Long = {
-    composeCountAndRun(strToOption(condition))
+    composeCountAndRun(SqlEntry(condition).toOption)
   }
 
   /**
@@ -201,7 +203,7 @@ case class DBTable(tableName: String) extends DBQuerySupport{
    * @return            - the number of rows
    */
   def countOnCondition(params: NamedParams)(implicit connection: DBConnection): Long = {
-    composeCountAndRun(strToOption(paramsToWhereCondition(params)), params.values)
+    composeCountAndRun(paramsToWhereCondition(params).toOption, params.values)
   }
 
   /**
@@ -211,47 +213,36 @@ case class DBTable(tableName: String) extends DBQuerySupport{
    * @return            - the number of rows
    */
   def countOnCondition(condition: String)(implicit connection: DBConnection): Long = {
-    composeCountAndRun(strToOption(condition))
+    composeCountAndRun(SqlEntry(condition).toOption)
   }
 
-  private def composeSelectAndRun[R](whereCondition: Option[String], orderByExpr: Option[String], values: Vector[QueryParamValue] = Vector.empty)
+  private def composeSelectAndRun[R](whereCondition: Option[SqlEntry], orderBy: Option[SqlEntry], values: Vector[QueryParamValue] = Vector.empty)
                               (verify: QueryResult => R)
                               (implicit connection: DBConnection): R = {
-    val where = whereCondition.map("WHERE " + _).getOrElse("")
-    val orderBy = orderByExpr.map("ORDER BY " + _).getOrElse("")
-    val sql = s"SELECT * FROM $tableName $where $orderBy;"
+    val sql = SELECT(ALL) FROM table WHERE whereCondition ORDER BY(orderBy)
     runQuery(sql, values)(verify)
   }
 
-  private def composeDeleteAndRun[R](whereCondition: Option[String], values: Vector[QueryParamValue] = Vector.empty)
+  private def composeDeleteAndRun[R](whereCondition: Option[SqlEntry], values: Vector[QueryParamValue] = Vector.empty)
                                     (verify: QueryResult => R)
                                     (implicit connection: DBConnection): R = {
-    val where = whereCondition.map("WHERE " + _).getOrElse("")
-    val sql = s"DELETE FROM $tableName $where RETURNING *;"
+    val sql = DELETE FROM table WHERE whereCondition RETURNING ALL
     runQuery(sql, values)(verify)
   }
 
-  private def composeCountAndRun(whereCondition: Option[String], values: Vector[QueryParamValue] = Vector.empty)
+  private def composeCountAndRun(whereCondition: Option[SqlEntry], values: Vector[QueryParamValue] = Vector.empty)
                                    (implicit connection: DBConnection): Long = {
-    val where = whereCondition.map("WHERE " + _).getOrElse("")
-    val sql = s"SELECT count(1) AS cnt FROM $tableName $where;"
+    val sql = SELECT(COUNT_ALL) FROM table WHERE whereCondition
     runQuery(sql, values) {resultSet =>
       resultSet.next().getLong("cnt").getOrElse(0)
     }
   }
 
-  private def strToOption(str: String): Option[String] = {
-    if (str.isEmpty) {
-      None
-    } else {
-      Option(str)
-    }
-  }
-
-  private def paramsToWhereCondition(params: NamedParams): String = {
-    params.items.foldRight(List.empty[String]) {case ((columnName, value), acc) =>
-      val condition = s"${columnName.sqlEntry} ${value.equalityOperator} ${value.sqlEntry}"
+  private def paramsToWhereCondition(params: NamedParams): SqlEntry = {
+    val resultList = params.items.foldRight(List.empty[SqlEntry]) {case ((columnName, value), acc) =>
+      val condition = columnName.sqlEntry + value.equalityOperator + value.sqlEntry
       condition :: acc
-    }.mkString(" AND ")
+    }
+    resultList.toSqlEntry(" AND ")
   }
 }

balta/src/main/scala/za/co/absa/db/balta/typeclasses/QueryParamValue.scala

@@ -16,16 +16,21 @@
 
 package za.co.absa.db.balta.typeclasses
 
-import QueryParamValue.AssignFunc
+import QueryParamValue.{AssignFunc, sqlEquals, sqlQuestionMark}
+import za.co.absa.db.mag.core.SqlEntry
+
 import java.sql.PreparedStatement
 
 trait QueryParamValue {
   def assign: Option[AssignFunc]
-  def sqlEntry: String = "?"
-  def equalityOperator: String = "="
+  def sqlEntry: SqlEntry = sqlQuestionMark
+  def equalityOperator: SqlEntry = sqlEquals
 }
 
 object QueryParamValue {
+  private val sqlQuestionMark = SqlEntry("?")
+  private val sqlEquals = SqlEntry("=")
+
   type AssignFunc = (PreparedStatement, Int) => Unit
 
   class ObjectQueryParamValue(obj: Object) extends QueryParamValue {
@@ -41,8 +46,8 @@ object QueryParamValue {
 
   object NullParamValue extends QueryParamValue {
     override val assign: Option[AssignFunc] = None
-    override val sqlEntry: String = "NULL"
-    override val equalityOperator: String = "IS"
+    override val sqlEntry: SqlEntry = SqlEntry("NULL")
+    override val equalityOperator: SqlEntry = SqlEntry("IS")
   }
 
 }

balta/src/main/scala/za/co/absa/db/mag/core/ColumnReference.scala

@@ -16,20 +16,21 @@
 
 package za.co.absa.db.mag.core
 
-trait ColumnReference extends SqlItem
-
-abstract class ColumnName extends ColumnReference{
-  def enteredName: String
-  def sqlEntry: String
+trait ColumnReference extends SqlItem {
   override def equals(obj: Any): Boolean = {
     obj match {
-      case that: ColumnName => this.sqlEntry == that.sqlEntry
+      case that: ColumnReference => this.sqlEntry == that.sqlEntry
       case _ => false
     }
   }
   override def hashCode(): Int = sqlEntry.hashCode
 }
 
+abstract class ColumnName extends ColumnReference{
+  def enteredName: String
+  def sqlEntry: SqlEntry
+}
+
 object ColumnReference {
   private val regularColumnNamePattern = "^([a-z_][a-z0-9_]*)$".r
   private val quotedRegularColumnNamePattern = "^\"([a-z_][a-z0-9_]*)\"$".r
@@ -42,9 +43,9 @@ object ColumnReference {
     val trimmedName = name.trim
     trimmedName match {
       case regularColumnNamePattern(columnName) => ColumnNameSimple(columnName) // column name per SQL standard, no quoting needed
-      case quotedRegularColumnNamePattern(columnName) => ColumnNameExact(trimmedName, columnName) // quoted but regular name, remove quotes
+      case quotedRegularColumnNamePattern(columnName) => ColumnNameExact(trimmedName, SqlEntry(columnName)) // quoted but regular name, remove quotes
       case quotedColumnNamePattern(_)  => ColumnNameSimple(trimmedName) // quoted name, use as is
-      case _ => ColumnNameExact(trimmedName, quote(escapeQuote(trimmedName))) // needs quoting and perhaps escaping
+      case _ => ColumnNameExact(trimmedName, SqlEntry(quote(escapeQuote(trimmedName)))) // needs quoting and perhaps escaping
     }
   }
 
@@ -55,13 +56,13 @@ object ColumnReference {
   def unapply(columnName: ColumnName): String = columnName.enteredName
 
   final case class ColumnNameSimple private(enteredName: String) extends ColumnName {
-    override def sqlEntry: String = enteredName
+    override def sqlEntry: SqlEntry = SqlEntry(enteredName)
   }
 
-  final case class ColumnNameExact private(enteredName: String, sqlEntry: String) extends ColumnName
+  final case class ColumnNameExact private(enteredName: String, sqlEntry: SqlEntry) extends ColumnName
 
   final case class ColumnIndex private(index: Int) extends ColumnReference {
-    val sqlEntry: String = index.toString
+    val sqlEntry: SqlEntry = SqlEntry(index.toString)
   }
 }