Add documentation and change log

Author: sclubricants

user_guide_src/source/changelogs/v4.3.0.rst

@@ -141,6 +141,7 @@ Database
 - Added the ability to manually set index names. These methods include: ``Forge::addKey()``, ``Forge::addPrimaryKey()``, and ``Forge::addUniqueKey()``
 - Fixed ``Forge::dropKey()`` to allow droping unique indexes. This required the ``DROP CONSTRAINT`` SQL command.
 - Added ``upsert()`` and ``upsertBatch()`` methods to QueryBuilder. See :ref:`upsert-data`.
+- Added ``BaseBuilder::fromQuery()`` which allows insert, update, upsert from a query. See :ref:`insert-batch-data`.
 
 Model
 =====

user_guide_src/source/database/query_builder.rst

@@ -858,6 +858,8 @@ The reason the second query worked is that the first parameter is set to ``false
 
 .. note:: This method doesn't work for batch inserts.
 
+.. _insert-batch-data:
+
 insertBatch
 ===========
 
@@ -876,6 +878,10 @@ The first parameter is an associative array of values.
 
 .. warning:: When you use ``RawSql``, you MUST escape the data manually. Failure to do so could result in SQL injections.
 
+You can also insert from a query:
+
+.. literalinclude:: query_builder/117.php
+
 .. _upsert-data:
 
 **************
@@ -936,6 +942,10 @@ The first parameter is an associative array of values.
 
 .. note:: All values are escaped automatically producing safer queries.
 
+You can also upsert from a query:
+
+.. literalinclude:: query_builder/115.php
+
 $builder->onConstraint()
 ------------------------
 
@@ -1071,6 +1081,10 @@ The first parameter is an associative array of values, the second parameter is t
 .. note:: ``affectedRows()`` won't give you proper results with this method,
     due to the very nature of how it works. Instead, ``updateBatch()``
     returns the number of rows affected.
+    
+You can also update from a query:
+
+.. literalinclude:: query_builder/116.php
 
 $builder->getCompiledUpdate()
 -----------------------------
@@ -1358,6 +1372,14 @@ Class Reference
 
         Specifies the ``FROM`` clause of a query using a subquery.
 
+    .. php:method:: fromQuery($query)
+
+        :param mixed $query: Instance of the BaseBuilder or RawSql class or string
+        :returns:   ``BaseBuilder`` instance (method chaining)
+        :rtype:     ``BaseBuilder``
+
+        Sets a query as a datasource for ``insertBatch()``, ``updateBatch()``, ``upsertBatch()``.
+
     .. php:method:: join($table, $cond[, $type = ''[, $escape = null]])
 
         :param string $table: Table name to join

user_guide_src/source/database/query_builder/115.php

@@ -0,0 +1,22 @@
+<?php
+
+$query = $this->db->table('user2')
+    ->select('user2.name, user2.email, user2.country')
+    ->join('user', 'user.email = user2.email', 'left')
+    ->where('user.email IS NULL');
+
+$additionalUpdateField = ['updated_at' => new RawSql('CURRENT_TIMESTAMP')];
+
+$sql = $builder->onConstraint('email')->updateFields($additionalUpdateField, true)->upsertBatch($query);
+/* MySQLi produces:
+    INSERT INTO `db_user` (`country`, `email`, `name`)
+    SELECT user2.name, user2.email, user2.country
+    FROM user2
+    LEFT JOIN user ON user.email = user2.email
+    WHERE user.email IS NULL
+    ON DUPLICATE KEY UPDATE
+    `country` = VALUES(`country`),
+    `email` = VALUES(`email`),
+    `name` = VALUES(`name`),
+    `updated_at` = CURRENT_TIMESTAMP
+*/

user_guide_src/source/database/query_builder/116.php

@@ -0,0 +1,31 @@
+<?php
+
+$query = $this->db->table('user2')
+    ->select('user2.name, user2.email, user2.country')
+    ->join('user', 'user.email = user2.email', 'inner')
+    ->where('user2.country', 'US');
+
+$additionalUpdateField = ['updated_at' => new RawSql('CURRENT_TIMESTAMP')];
+
+$sql = $builder->table('user')
+    ->setAlias('u')
+    ->onConstraint('email')
+    ->updateFields($additionalUpdateField, true)
+    ->updateBatch($query);
+/*
+ * Produces:
+ * UPDATE `user`
+ * INNER JOIN (
+ * SELECT user2.name, user2.email, user2.country
+ * FROM user2
+ * INNER JOIN user ON user.email = user2.email
+ * WHERE user2.country = 'US'
+ * ) `u`
+ * ON `user`.`email` = `u`.`email`
+ * SET
+ * `mytable`.`name` = `u`.`name`,
+ * `mytable`.`email` = `u`.`email`,
+ * `mytable`.`country` = `u`.`country`,
+ * `mytable`.`updated_at` = CURRENT_TIMESTAMP()
+ */
+

user_guide_src/source/database/query_builder/117.php

@@ -0,0 +1,15 @@
+<?php
+
+$query = "SELECT user2.name, user2.email, user2.country
+          FROM user2
+          LEFT JOIN user ON user.email = user2.email
+          WHERE user.email IS NULL";
+
+$sql = $builder->ignore(true)->insertBatch($query);
+/* MySQLi produces:
+    INSERT IGNORE INTO `db_user` (`name`, `country`, `email`)
+    SELECT user2.name, user2.email, user2.country
+    FROM user2
+    LEFT JOIN user ON user.email = user2.email
+    WHERE user.email IS NULL
+*/