diff --git a/moor/lib/src/runtime/statements/insert.dart b/moor/lib/src/runtime/statements/insert.dart
index cc995660..339cb27d 100644
--- a/moor/lib/src/runtime/statements/insert.dart
+++ b/moor/lib/src/runtime/statements/insert.dart
@@ -18,9 +18,11 @@ class InsertStatement<DataClass> {
   ///
   /// All fields in the entity that don't have a default value or auto-increment
   /// must be set and non-null. Otherwise, an [InvalidDataException] will be
-  /// thrown. An insert will also fail if another row with the same primary key
-  /// or unique constraints already exists. If you want to override data in that
-  /// case, use [insertOrReplace] instead.
+  /// thrown.
+  ///
+  /// If [orReplace] is true and a row with the same primary key already exists,
+  /// the columns of that row will be updated and now new row will be written.
+  /// Otherwise, an exception will be thrown.
   ///
   /// If the table contains an auto-increment column, the generated value will
   /// be returned.
@@ -75,6 +77,7 @@ class InsertStatement<DataClass> {
   /// includes setting columns with null values back to null.
   ///
   /// However, if no such row exists, a new row will be written instead.
+  @Deprecated('Use insert with orReplace: true instead')
   Future<void> insertOrReplace(DataClass entity) async {
     return await insert(entity, orReplace: true);
   }
diff --git a/moor/lib/src/runtime/statements/update.dart b/moor/lib/src/runtime/statements/update.dart
index adff74a2..71ec9e1c 100644
--- a/moor/lib/src/runtime/statements/update.dart
+++ b/moor/lib/src/runtime/statements/update.dart
@@ -86,8 +86,8 @@ class UpdateStatement<T extends Table, D> extends Query<T, D>
   /// See also:
   ///  - [write], which doesn't apply a [where] statement itself and ignores
   ///    null values in the entity.
-  ///  - [InsertStatement.insertOrReplace], which behaves similar to this method
-  ///    but creates a new row if none exists.
+  ///  - [InsertStatement.insert] with the `orReplace` parameter, which behaves
+  ///  similar to this method but creates a new row if none exists.
   Future<bool> replace(D entity) async {
     // We set isInserting to true here although we're in an update. This is
     // because all the fields from the entity will be written (as opposed to a
diff --git a/moor/test/insert_test.dart b/moor/test/insert_test.dart
index f3f92e5a..c2d27d68 100644
--- a/moor/test/insert_test.dart
+++ b/moor/test/insert_test.dart
@@ -25,10 +25,12 @@ void main() {
   });
 
   test('generates insert or replace statements', () async {
-    await db.into(db.todosTable).insertOrReplace(TodoEntry(
+    await db.into(db.todosTable).insert(
+        TodoEntry(
           id: 113,
           content: 'Done',
-        ));
+        ),
+        orReplace: true);
 
     verify(executor.runInsert(
         'INSERT OR REPLACE INTO todos (id, content) VALUES (?, ?)',
@@ -58,6 +60,30 @@ void main() {
     verify(streamQueries.handleTableUpdates({db.todosTable}));
   });
 
+  test('runs bulk inserts with OR REPLACE', () async {
+    await db.into(db.todosTable).insertAll([
+      TodoEntry(content: 'a'),
+      TodoEntry(title: 'title', content: 'b'),
+      TodoEntry(title: 'title', content: 'c'),
+    ], orReplace: true);
+
+    final insertSimple = 'INSERT OR REPLACE INTO todos (content) VALUES (?)';
+    final insertTitle =
+        'INSERT OR REPLACE INTO todos (title, content) VALUES (?, ?)';
+
+    verify(executor.runBatched([
+      BatchedStatement(insertSimple, [
+        ['a']
+      ]),
+      BatchedStatement(insertTitle, [
+        ['title', 'b'],
+        ['title', 'c']
+      ]),
+    ]));
+
+    verify(streamQueries.handleTableUpdates({db.todosTable}));
+  });
+
   test('notifies stream queries on inserts', () async {
     await db.into(db.users).insert(User(
           name: 'User McUserface',