From 473be4f088df2889572c0e4758bb90be57b5413b Mon Sep 17 00:00:00 2001
From: Brandon Rodriguez <brodriguez8774@gmail.com>
Date: Mon, 10 Oct 2022 14:18:55 -0400
Subject: [PATCH] Document new insert/update many queries
---
docs/source/creating_queries.rst | 122 ++++++++++++++++++++++++++++++-
1 file changed, 119 insertions(+), 3 deletions(-)
diff --git a/docs/source/creating_queries.rst b/docs/source/creating_queries.rst
index f768fb4..6e4bd09 100644
--- a/docs/source/creating_queries.rst
+++ b/docs/source/creating_queries.rst
@@ -420,6 +420,9 @@ Example:
INSERT new Records
------------------
+INSERT single Record
+^^^^^^^^^^^^^^^^^^^^
+
``connector.records.insert(table_name, values_clause, columns_clause=None)``
:param table_name: Name of table to select records from.
@@ -453,7 +456,55 @@ Example:
# some kind of reliable default value).
connector.records.insert(
'my_table',
- values_clause='"Regal Red Towel", "Red towel with yellow embroidery."',
+ "Regal Red Towel", "Red towel with yellow embroidery."',
+ columns_clause='name, description',
+ )
+
+
+INSERT multiple Records
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``connector.records.insert_many(table_name, values_clause, columns_clause=None)``
+
+:param table_name: Name of table to select records from.
+
+:param values_clause: Clause to provide values for new record(s).
+
+:param columns_clause: Optional clause to indicate what columns are being
+ provided, as well as what order they're in. If not
+ present, then query will assume all columns are being
+ provided, in the order they were originally added to the
+ table.
+
+:return: TODO: Honestly unsure of what this provides. Double check.
+
+
+Example:
+
+.. code-block:: python
+
+ # Import MySQL connector.
+ from py_dbcn.connectors import MysqlDbConnector
+
+ ...
+
+ # Initialize MySQL database connection.
+ connector = MysqlDbConnector(host, port, user, password, db_name)
+
+ # Generate new record values.
+ rows = [
+ ('Blue Towel', 'Soft blue towel.'),
+ ('Red Towel', 'Soft red towel.'),
+ ('Regal Red Towel', 'Red towel with yellow embroidery.'),
+ ]
+
+ # Run query.
+ # In this case, we insert records by giving a set of "name"s and "description"s.
+ # We omit "id" so it will be auto-provided (assuming it's a field with
+ # some kind of reliable default value).
+ connector.records.insert_many(
+ 'my_table',
+ rows,
columns_clause='name, description',
)
@@ -461,6 +512,9 @@ Example:
UPDATE existing Records
-----------------------
+UPDATE Single Record
+^^^^^^^^^^^^^^^^^^^^
+
``connector.records.update(table_name, values_clause, where_clause)``
:param table_name: Name of table to update records within.
@@ -494,8 +548,70 @@ Example:
# some kind of reliable default value).
connector.records.update(
'my_table',
- values_clause='description = "Refurbished item"',
- where_clause='name = "Refurbished"',
+ 'description = "Refurbished item"',
+ 'name = "Refurbished"',
+ )
+
+
+UPDATE Multiple Records
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``connector.records.update_many(table_name, columns_clause, values_clause, where_columns_clause)``
+
+:param table_name: Name of table to update records within.
+
+:param columns_clause: Clause to indicate what columns are being provided, as
+ well as what order they're in.
+
+:param values_clause: Clause to provide values for updated record.
+
+:param where_clause: NOT the standard WHERE clause used in other queries.
+
+ Clause to indicate what columns are being filtered on. All
+ columns present here should also be present in the
+ ``columns_clause`` param.
+
+:return: TODO: Honestly unsure of what this provides. Double check.
+
+
+Example:
+
+.. code-block:: python
+
+ # Import MySQL connector.
+ from py_dbcn.connectors import MysqlDbConnector
+
+ ...
+
+ # Initialize MySQL database connection.
+ connector = MysqlDbConnector(host, port, user, password, db_name)
+
+ # Columns to update with/on.
+ columns_clause = ['id', 'name']
+
+ # Desired values after query runs.
+ # Note: Since we match on "id", this should match what already exists
+ # in the database. The "name" field is not included in the WHERE so it can
+ # be set to whatever new value we want it to be. Meanwhile, record fields
+ # that are not used to match or update can be excluded.
+ values_clause = [
+ # (id, name)
+ (1599, 'Refurbished Item 1001'),
+ (16782, 'Refurbished Item 1002'),
+ (20909, 'Refurbished Item 1003'),
+ ]
+
+ # Columns to use to find existing record data.
+ where_columns_clause = ['id']
+
+ # Run query.
+ # In this case, we update record "name" values, using the id to match
+ # against existing records.
+ connector.records.update(
+ 'my_table',
+ columns_clause,
+ values_clause,
+ where_columns_clause,
)
--
GitLab