Implement MySQL's ON DUPLICATE KEY UPDATE

Added support for MySQL's ON DUPLICATE KEY UPDATE
MySQL-specific :class:`.mysql.dml.Insert` object.
Pull request courtesy Michael Doronin.

Co-authored-by: Mike Bayer <mike_mp@zzzcomputing.com>
Resolves: #4009
Change-Id: Ic71424f3c88af6082b48a910a2efb7fbfc0a7eb4
Pull-request: https://github.com/zzzeek/sqlalchemy/pull/365

3 files changed, 57 insertions, 0 deletions

diff --git a/doc/build/changelog/changelog_12.rst b/doc/build/changelog/changelog_12.rst
index 7060d04db..0c3e3b5db 100644
--- a/doc/build/changelog/changelog_12.rst
+++ b/doc/build/changelog/changelog_12.rst
@@ -13,6 +13,18 @@
 .. changelog::
     :version: 1.2.0b1
 
+    .. change:: 4009
+        :tags: feature, mysql
+        :tickets: 4009
+
+        Added support for MySQL's ON DUPLICATE KEY UPDATE
+        MySQL-specific :class:`.mysql.dml.Insert` object.
+        Pull request courtesy Michael Doronin.
+
+        .. seealso::
+
+            :ref:`change_4009`
+
     .. change:: 4018
         :tags: bug, sql
         :tickets: 4018
diff --git a/doc/build/changelog/migration_12.rst b/doc/build/changelog/migration_12.rst
index b5594f07c..05c364312 100644
--- a/doc/build/changelog/migration_12.rst
+++ b/doc/build/changelog/migration_12.rst
@@ -1270,6 +1270,42 @@ itself will also be present::
 Dialect Improvements and Changes - MySQL
 ========================================
 
+.. _change_4009:
+
+Support for INSERT..ON DUPLICATE KEY UPDATE
+-------------------------------------------
+
+The ``ON DUPLICATE KEY UPDATE`` clause of ``INSERT`` supported by MySQL
+is now supported using a MySQL-specific version of the
+:class:`.Insert` object, via :func:`sqlalchemy.dialects.mysql.dml.insert`.
+This :class:`.Insert` subclass adds a new method
+:meth:`.Insert.on_duplicate_key_update` that implements MySQL's syntax::
+
+    from sqlalchemy.dialect.mysql import insert
+
+    insert_stmt = insert(my_table). \\
+        values(id='some_id', data='some data to insert')
+
+    on_conflict_stmt = insert_stmt.on_duplicate_key_update(
+        data=stmt.values.data,
+        status='U'
+    )
+
+    conn.execute(do_update_stmt)
+
+The above will render::
+
+    INSERT INTO my_table (id, data)
+    VALUES (:id, :data)
+    ON DUPLICATE KEY UPDATE data=VALUES(data), status=:status_1
+
+.. seealso::
+
+    :ref:`mysql_insert_on_duplicate_key_update`
+
+:ticket:`4009`
+
+
 Dialect Improvements and Changes - SQLite
 =========================================
 
diff --git a/doc/build/dialects/mysql.rst b/doc/build/dialects/mysql.rst
index ebfc8a31c..cfe7ec189 100644
--- a/doc/build/dialects/mysql.rst
+++ b/doc/build/dialects/mysql.rst
@@ -156,6 +156,15 @@ construction arguments, are as follows:
 .. autoclass:: YEAR
     :members: __init__
 
+MySQL DML Constructs
+-------------------------
+
+.. autofunction:: sqlalchemy.dialects.mysql.dml.insert
+
+.. autoclass:: sqlalchemy.dialects.mysql.dml.Insert
+  :members:
+
+
 
 MySQL-Python
 ------------