.. _auto_database_insert:

*CONNECTS TO A DATABASE AND INSERTS RECORDS BASED ON THE SQL-QUERY*
===================================================================

Connects to a relational database (currently MySQL) and inserts records into it using a user-supplied SQL INSERT query paired with an input dataset. Use this worker whenever a workflow needs to persist computed or transformed results back to an external database.

When to use
-----------

Tagged: ``database``, ``insert``, ``mysql``, ``persist``, ``records``, ``sql``, ``user``.

Inputs
------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20 20 20

   * - Label
     - ID
     - Type
     - Default
     - Required
     - Description
   * - Database Type
     - db_type
     - select
     - mysql
     - ✓
     - Database engine to connect to; currently only 'mysql' is supported — leave as default unless additional engines are enabled.
   * - Hostname
     - db_host
     - text
     - localhost
     - ✓
     - Hostname or IP address of the database server; defaults to 'localhost' for a co-located DB.
   * - Port
     - db_port
     - text
     - 3306
     - ✓
     - TCP port the database listens on; defaults to 3306 (standard MySQL port) — change only if the server is on a non-standard port.
   * - Username
     - db_user
     - text
     - mysql
     - ✓
     - Database username used to authenticate the connection; must have INSERT privileges on the target table.
   * - Password
     - db_password
     - password
     - —
     - ✓
     - Password for the specified database user; stored securely as a password field and never echoed in logs.
   * - Database
     - db_database
     - text
     - —
     - ✓
     - Name of the target database (schema) on the server that contains the table to be written to.
   * - Query
     - db_query
     - textarea
     - —
     - ✓
     - Parameterised SQL INSERT statement (e.g. INSERT INTO table (col1, col2) VALUES (?, ?)) that maps to the columns of the sibling dataset.

Outputs
-------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20

   * - Label
     - ID
     - Type
     - Description
   * - Records
     - records
     - dataset
     - Dataset echoing the rows that were successfully inserted into the database, useful for downstream validation or logging.
   * - Log
     - log
     - dataset
     - Execution log dataset containing per-row insert status, row counts, and any error messages returned by the database driver.

Disciplines
-----------

- data.io.sql

.. raw:: html

   <hr style="margin-top:2em">
   <p style="font-size:11px;color:#888">
   Auto-generated from <code>platform</code> schema. Worker id: <code>database_insert</code>. Schema hash: <code>5d419bb13b61</code>. Hand-curated docs in <code>workerexamples/</code> override this page when present.
   </p>