From 528b5762a6c114a26cd7fa6b17f3cb28192cc05d Mon Sep 17 00:00:00 2001
From: Simon Binder <oss@simonbinder.eu>
Date: Tue, 25 Jan 2022 13:39:24 +0100
Subject: [PATCH] Improve docs on `DoUpdate.target`.

---
 drift/lib/src/runtime/api/connection_user.dart            | 2 +-
 drift/lib/src/runtime/query_builder/on_table.dart         | 4 ++++
 .../lib/src/runtime/query_builder/statements/insert.dart  | 8 ++++++++
 3 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/drift/lib/src/runtime/api/connection_user.dart b/drift/lib/src/runtime/api/connection_user.dart
index 71037607..3620f967 100644
--- a/drift/lib/src/runtime/api/connection_user.dart
+++ b/drift/lib/src/runtime/api/connection_user.dart
@@ -163,7 +163,7 @@ abstract class DatabaseConnectionUser {
   /// This method is deprecated. For an even easier access, the methods that
   /// were made available here are now available on the [table] or view instance
   /// directly.
-  @Deprecated('Experiment ended - use the methods on the [table] direclty')
+  @Deprecated('Experiment ended - use the methods on the [table] directly')
   TableOrViewOperations<T, D> from<T extends HasResultSet, D>(
       ResultSetImplementation<T, D> table) {
     return TableOrViewOperations._(this, table);
diff --git a/drift/lib/src/runtime/query_builder/on_table.dart b/drift/lib/src/runtime/query_builder/on_table.dart
index 1d2ceaf5..e36deba2 100644
--- a/drift/lib/src/runtime/query_builder/on_table.dart
+++ b/drift/lib/src/runtime/query_builder/on_table.dart
@@ -48,6 +48,10 @@ extension TableStatements<Tbl extends Table, Row> on TableInfo<Tbl, Row> {
   ///
   /// Please note that this method is only available on recent sqlite3 versions.
   /// See also [InsertStatement.insertOnConflictUpdate].
+  /// By default, only the primary key is used for detect uniqueness violations.
+  /// If you have further uniqueness constraints, please use the general
+  /// [insertOne] method with a [DoUpdate] including those columns in its
+  /// [DoUpdate.target].
   Future<int> insertOnConflictUpdate(Insertable<Row> row) {
     return insert().insertOnConflictUpdate(row);
   }
diff --git a/drift/lib/src/runtime/query_builder/statements/insert.dart b/drift/lib/src/runtime/query_builder/statements/insert.dart
index 56cae8b4..2c7b98b5 100644
--- a/drift/lib/src/runtime/query_builder/statements/insert.dart
+++ b/drift/lib/src/runtime/query_builder/statements/insert.dart
@@ -51,6 +51,10 @@ class InsertStatement<T extends Table, D> {
   /// Be aware that upsert clauses and [onConflict] are not available on older
   /// sqlite versions.
   ///
+  /// By default, the [onConflict] clause will only consider the table's primary
+  /// key. If you have additional columns with uniqueness constraints, you have
+  /// to manually add them to the clause's [DoUpdate.target].
+  ///
   /// Returns the `rowid` of the inserted row. For tables with an auto-increment
   /// column, the `rowid` is the generated value of that column. The returned
   /// value can be inaccurate when [onConflict] is set and the insert behaved
@@ -104,6 +108,10 @@ class InsertStatement<T extends Table, D> {
   ///
   /// Be aware that [insertOnConflictUpdate] uses an upsert clause, which is not
   /// available on older sqlite implementations.
+  /// Note: By default, only the primary key is used for detect uniqueness
+  /// violations. If you have further uniqueness constraints, please use the
+  /// general [insert] method with a [DoUpdate] including those columns in its
+  /// [DoUpdate.target].
   Future<int> insertOnConflictUpdate(Insertable<D> entity) {
     return insert(entity, onConflict: DoUpdate((_) => entity));
   }