Merge pull request #28 from ttafsir/release/1.4.0

Release/1.4.0

Author: ttafsir

.github/workflows/ci.yml

@@ -51,4 +51,6 @@ jobs:
       - name: Run tests
         run: |
           cd tests
+          echo "Running tests on Ansible $(ansible --version)"
           ansible-playbook test_lookup.yml
+          ansible-playbook test_modules.yml

CHANGELOG.rst

@@ -4,6 +4,25 @@ ttafsir.sqlite_utils Release Notes
 
 .. contents:: Topics
 
+v1.4.0:
+========
+
+Release Summary
+---------------
+
+This release adds new modules to database and table creation and for loading data into tables.
+
+New Modules
+-----------
+* `ttafsir.sqlite_utils.create`
+* `ttafsir.sqlite_utils.insert`
+* `ttafsir.sqlite_utils.insert_json`
+
+Minor Changes
+--------------
+* move common boilerplate to module_utils to simplify current modules and make it easier to add new modules
+* adds new parameter to `ttafsir.sqlite_utils.run_sql` to switch between `query` and `execute` methods
+
 v1.3.0:
 ========
 

README.md

@@ -18,6 +18,9 @@ A collection of Ansible plugins to manage SQLite databases leveraging the `sqlit
 ### Modules
 
 * `ttafsir.sqlite_utils.run_sql`: Ansible module to query a sqlite database and return list of dictionaries.
+* `ttafsir.sqlite_utils.create`: Ansible module create a table. The module will also create a database file if it doesn't exist.
+* `ttafsirsqlite_utils.insert`: Ansible module to insert records into a database table. Supports inserting single and multiple records with a single dictionary or list of dictionaries.
+* `ttafsirsqlite_utils.insert_json`: Ansible module to insert records into a database table from JSON files.
 
 #### Lookup Plugins
 
@@ -26,7 +29,7 @@ A collection of Ansible plugins to manage SQLite databases leveraging the `sqlit
 
 ## Usage Examples
 
-### `query` module
+### `run_sql` module
 
 ```yaml
 - name: Fetch data from database
@@ -70,6 +73,31 @@ A collection of Ansible plugins to manage SQLite databases leveraging the `sqlit
 - debug: var=query_3.rows_affected
 ```
 
+### Create a table and insert data
+
+```yaml
+- name: Create database
+  ttafsir.sqlite_utils.create:
+    db_path: database.db
+    table: emails
+    columns: {"email_id": "int", "subject": "str", "body": "str"}
+    pk: email_id
+
+- name: Insert single records into database
+  ttafsir.sqlite_utils.insert:
+    db_path: database.db
+    table: emails
+    records: {"email_id": 2, "subject": "Hello World 2", "body": "body of the email"}
+
+- name: Insert from json file
+  ttafsir.sqlite_utils.insert_json:
+    db_path: network.db
+    table: interfaces
+    file_path: interfaces.json
+    flatten: true
+    alter: true
+```
+
 ###  Lookup
 
 ```yaml

galaxy.yml

@@ -1,7 +1,7 @@
 ---
 namespace: ttafsir
 name: sqlite_utils
-version: "1.3.0"
+version: "1.4.0"
 readme: README.md
 
 authors:

plugins/module_utils/common.py

@@ -0,0 +1,104 @@
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2023, Tafsir Thiam (@ttafsir) <ttafsir@gmail.com>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+
+import traceback
+from ansible.module_utils.basic import missing_required_lib
+from pathlib import Path
+
+
+IMPORT_ERROR = None
+try:
+    from sqlite_utils import Database
+    from sqlite_utils.cli import insert_upsert_implementation
+
+    HAS_SQLITE_UTILS = True
+except ImportError:
+    HAS_SQLITE_UTILS = False
+    IMPORT_ERROR = traceback.format_exc()
+
+
+def insert_arg_spec():
+    return dict(
+        db_path=dict(type="str", required=True),
+        table=dict(type="str", required=True),
+        records=dict(type="raw", required=True),
+        pk=dict(type="str", default=None),
+        column_order=dict(type="list", elements="raw", default=None),
+        not_null=dict(type="list", elements="raw", default=None),
+        defaults=dict(type="dict", default=None),
+        hash_id=dict(type="str", default=None),
+        alter=dict(type="bool", default=False),
+        ignore=dict(type="bool", default=False),
+        replace=dict(type="bool", default=False),
+        extracts=dict(type="raw", default=None),
+        conversions=dict(type="dict", default=None),
+        columns=dict(type="dict", default=None),
+    )
+
+
+def file_insert_arg_spec():
+    return dict(
+        db_path=dict(type="str", required=True),
+        table=dict(type="str", required=True),
+        file_path=dict(type="str", required=True),
+        pk=dict(type="str", default=None),
+        empty_null=dict(type="bool", default=False),
+        lines=dict(type="bool", default=False),
+        text=dict(type="bool", default=False),
+        convert=dict(type="dict", default=None),
+        imports=dict(type="list", elements="raw", default=None),
+        batch_size=dict(type="int", default=100),
+        stop_after=dict(type="int", default=None),
+        alter=dict(type="bool", default=False),
+        upsert=dict(type="bool", default=False),
+        ignore=dict(type="bool", default=False),
+        replace=dict(type="bool", default=False),
+        truncate=dict(type="bool", default=False),
+        not_null=dict(type="list", elements="raw", default=None),
+        analyze=dict(type="bool", default=False),
+        silent=dict(type="bool", default=False),
+    )
+
+
+class SqliteUtilsModule:
+    def __init__(self, module):
+        self.module = module
+        self.result = dict(changed=False, message="")
+        self.params = module.params
+
+        if not HAS_SQLITE_UTILS:
+            module.fail_json(
+                msg=missing_required_lib("sqlite-utils"), exception=IMPORT_ERROR
+            )
+
+    def exit_json(self, **kwargs):
+        self.result.update(**kwargs)
+        self.module.exit_json(**self.result)
+
+    def fail_json(self, msg, **kwargs):
+        self.result.update(**kwargs)
+        self.module.fail_json(msg=msg, **self.result)
+
+    def get_db(self, **kwargs):
+        return Database(self.params["db_path"], **kwargs)
+
+
+class SqliteUtilsInsertModule(SqliteUtilsModule):
+    def __init__(self, module):
+        super(SqliteUtilsInsertModule, self).__init__(module)
+
+        file_path = module.params["file_path"]
+        if not Path(file_path).exists():
+            module.fail_json(
+                msg=f"File path {file_path} does not exist or is not accessible."
+            )
+        self.file = Path(file_path)
+
+    def insert_upsert(self, *args, **kwargs):
+        return insert_upsert_implementation(*args, **kwargs)