keelson_psql/insert.rs
1//! Mods for [`psql::insert`](crate::insert()).
2//!
3//! ```
4//! use keelson_psql as psql;
5//! use keelson_psql::{arg, insert};
6//!
7//! let q = psql::insert((
8//! insert::into("users").columns(["id", "name"]),
9//! insert::values((arg(1i32), arg("ada"))),
10//! insert::on_conflict("id").do_update(insert::set_excluded(["name"])),
11//! insert::returning("*"),
12//! ));
13//! ```
14//!
15//! # The mods that are not for the `INSERT` itself
16//!
17//! [`set`], [`set_col`], [`set_excluded`] and [`where_`] apply to a
18//! [`ConflictClause`](keelson_core::clause::ConflictClause), not to an
19//! `InsertQuery` — an `INSERT` has no `SET` and no `WHERE`. They are here because
20//! this is where they are used: inside
21//! [`on_conflict(..).do_update(..)`](crate::shared::ConflictChain::do_update). An
22//! `InsertQuery` does not implement the traits they need, so misplacing one is a
23//! compile error rather than a surprise.
24//!
25//! The two `WHERE`s of an `ON CONFLICT` are easy to conflate and behave nothing
26//! alike: `on_conflict(..).where_(..)` is the *index* predicate, matched against a
27//! partial unique index's own definition, while [`where_`] inside `do_update`
28//! filters which conflicting rows are updated.
29
30use keelson_core::{Mod, mod_fn};
31
32use crate::extras::Overriding;
33use crate::statement::InsertQuery;
34
35pub use crate::shared::{
36 from_item as into, on_conflict, on_conflict_on_constraint, recursive, returning, rows, set,
37 set_col, set_excluded, values, values_from_query as query, where_, with,
38};
39
40/// `OVERRIDING SYSTEM VALUE` — write the supplied value into a
41/// `GENERATED ALWAYS AS IDENTITY` column, which otherwise refuses one.
42pub fn overriding_system() -> impl Mod<InsertQuery> {
43 mod_fn(|q: &mut InsertQuery| q.overriding = Some(Overriding::System))
44}
45
46/// `OVERRIDING USER VALUE` — ignore the supplied value and take the sequence's,
47/// for a `GENERATED BY DEFAULT AS IDENTITY` column.
48pub fn overriding_user() -> impl Mod<InsertQuery> {
49 mod_fn(|q: &mut InsertQuery| q.overriding = Some(Overriding::User))
50}