keelson_sqlite/insert.rs
1//! Mods for [`sqlite::insert`](crate::insert()).
2//!
3//! ```
4//! use keelson_sqlite as sqlite;
5//! use keelson_sqlite::{arg, insert};
6//!
7//! let q = sqlite::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 upsert are easy to conflate and behave nothing alike:
26//! `on_conflict(..).where_(..)` is the *index* predicate, matched against a partial
27//! unique index's own definition, while [`where_`] inside `do_update` filters which
28//! conflicting rows are updated.
29//!
30//! # Several upserts
31//!
32//! [`on_conflict`] appends. SQLite 3.35 and later try each `ON CONFLICT` clause in
33//! turn, and only the last may omit its conflict target — so
34//! `on_conflict("id").do_update(..)` followed by `on_conflict(()).do_nothing()` is a
35//! statement, and the reverse order is not.
36
37pub use crate::shared::{
38 into_table as into, on_conflict, or_abort, or_fail, or_ignore, or_replace, or_rollback,
39 recursive, returning, rows, set, set_col, set_excluded, values, values_from_query as query,
40 where_, with,
41};