        (mapv (partial isql/encode-result-type sql) result-types)])))
 
 
-(defn build-sql-source
+(defn compile-sql-template
+  "Given a SQL template (SQL tokens and result types) compile it into a more efficient SQL source with following
+  enhancements:
+    - associated params-setter
+    - associated row-maker
+    - associated column-reader
+    - associated conn-worker
+    - act as arity-2 function (f conn-source params)
+  See:
+    `parse-sql` for SQL-template format"
   [sql-tokens result-types
    {:keys [make-params-setter
            make-row-maker

  * sql-tokens is a vector of alternating string and param-pair vectors
  * param-pair is a vector of two elements [param-key param-type] (param keys are used to extract map params)
  * result-types is a vector of result types
  See asphalt.type for supported SQL types."
  ([^String sql]
    (parse-sql sql {}))
  ([^String sql {:keys [sql-name escape-char param-start-char type-start-char name-encoder]



(defmacro defsql
  "Define a parsed/compiled SQL template that can be used to execute it later."
  ([var-symbol sql]
    (when-not (symbol? var-symbol)
      (i/expected "a symbol" var-symbol))
