fix #425 by clarifying MySQL vs PostgreSQL

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Changes
 
 * 2.3.next in progress
+  * Address [#425](https://github.com/seancorfield/honeysql/issues/425) by clarifying that `INTERVAL` as special syntax may be MySQL-specific and PostgreSQL uses difference syntax (because `INTERVAL` is a data type there).
   * **WIP** Address [#422](https://github.com/seancorfield/honeysql/issues/422) by auto-quoting unusual entity names when `:quoted` (and `:dialect`) are not specified, making HoneySQL more secure by default.
   * Address [#419](https://github.com/seancorfield/honeysql/issues/419) by adding `honey.sql.protocols` and `InlineValue` with a `sqlize` function.
   * Address [#413](https://github.com/seancorfield/honeysql/issues/413) by flagging a lack of `WHERE` clause for `DELETE`, `DELETE FROM`, and `UPDATE` when `:checking :basic` (or `:checking :strict`).

README.md

@@ -530,6 +530,8 @@ vectors where the first element is either a keyword or a symbol:
 => ["SELECT * FROM foo WHERE date_created > DATE_ADD(NOW(), INTERVAL ? HOURS)" 24]
 ```
 
+> Note: The above example may be specific to MySQL but the general principle of vectors for function calls applies to all dialects.
+
 A shorthand syntax also exists for simple function calls:
 keywords that begin with `%` are interpreted as SQL function calls:
 

doc/differences-from-1-x.md

@@ -131,7 +131,7 @@ The following new syntax has been added:
 * `:default` -- for `DEFAULT` values (in inserts) and for declaring column defaults in table definitions,
 * `:escape` -- used to wrap a regular expression so that non-standard escape characters can be provided,
 * `:inline` -- used as a function to replace the `sql/inline` / `#sql/inline` machinery,
-* `:interval` -- used as a function to support `INTERVAL <n> <units>`, e.g., `[:interval 30 :days]`,
+* `:interval` -- used as a function to support `INTERVAL <n> <units>`, e.g., `[:interval 30 :days]` for databases that support it (e.g., MySQL),
 * `:lateral` -- used to wrap a statement or expression, to provide a `LATERAL` join,
 * `:lift` -- used as a function to prevent interpretation of a Clojure data structure as DSL syntax (e.g., when passing a vector or hash map as a parameter value) -- this should mostly be a replacement for `honeysql.format/value`,
 * `:nest` -- used as a function to add an extra level of nesting (parentheses) around an expression,

doc/special-syntax.md

@@ -198,6 +198,8 @@ that represents a time unit. Produces an `INTERVAL` expression:
 ;;=> ["DATE_ADD(NOW(), INTERVAL ? DAYS)" 30]
 ```
 
+> Note: PostgreSQL has an `INTERVAL` data type which is unrelated to this syntax. In PostgreSQL, the closet equivalent would be `[:cast "30 days" :interval]` which will lift `"30 days"` out as a parameter. In DDL, for PostgreSQL, you can use `:interval` to produce the `INTERVAL` data type (without wrapping it in a vector).
+
 ## lateral
 
 Accepts a single argument that can be a (`SELECT`) clause or