diff --git a/CHANGELOG.md b/CHANGELOG.md index f74695c..6859b67 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,8 +2,8 @@ * 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). - * Address [#423](https://github.com/seancorfield/honeysql/issues/423) by supporting `DEFAULT` values and `DEFAULT` rows in `VALUES` clause -- NEEDS DOCUMENTATION! - * **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 [#423](https://github.com/seancorfield/honeysql/issues/423) by supporting `DEFAULT` values and `DEFAULT` rows in `VALUES`. + * 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`). * Fix [#392](https://github.com/seancorfield/honeysql/issues/392) by adding support for `WITH` / (`NOT`) `MATERIALIZED` -- via PR [#420](https://github.com/seancorfield/honeysql/issues/420) [@robhanlon22](https://github.com/robhanlon22). diff --git a/doc/clause-reference.md b/doc/clause-reference.md index 4b0385a..e2b789c 100644 --- a/doc/clause-reference.md +++ b/doc/clause-reference.md @@ -912,6 +912,7 @@ In the former case, all of the rows are augmented to have either `NULL` or `DEFAULT` values for any missing keys (columns). By default, `NULL` is used but you can specify a set of columns to get `DEFAULT` values, via the `:values-default-columns` option. +You can also be explicit and use `[:default]` as a value to generate `DEFAULT`. In the latter case -- a sequence of sequences -- all of the rows are padded to the same length by adding `nil` values if needed (since `:values` does not know how or if column @@ -936,6 +937,32 @@ user=> (sql/format '{insert-into table > Note: the `:values-default-columns` option must match how the columns are specified, i.e., as symbols or keywords. +For databases that allow it, you can insert an entire row of default values, +if appropriate, using one of the following syntaxes: + +```clojure +user=> (sql/format {:insert-into :table :values []}) +["INSERT INTO table VALUES ()"] +user=> (sql/format {:insert-into :table :values :default}) +["INSERT INTO table DEFAULT VALUES"] +``` + +Some databases support the empty `VALUES` clause, some support `DEFAULT VALUES`, some support neither. Consult your database's documentation to see which approach to use. + +For databases that allow it, when specifying multiple rows you use `:default` in +place of a row to insert default values for that row: + +```clojure +user=> (sql/format {:insert-into :table + :values [{:a 1 :b 2 :c 3} + :default + {:a 4 :b 5 :c 6}]}) +["INSERT INTO table (a, b, c) VALUES (?, ?, ?), DEFAULT, (?, ?, ?)" 6 5 4] +user=> (sql/format {:insert-into :table + :values [[1 2 3] :default [4 5 6]]}) +["INSERT INTO table VALUES (?, ?, ?), DEFAULT, (?, ?, ?)" 1 2 3 4 5 6] +``` + ## on-conflict, on-constraint, do-nothing, do-update-set These are grouped together because they are handled