docs(DOC-1806): document sql_insert static fields and sql_raw for dynamic SQL (#389)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: 3 people

docs-data/connect-diff-4.79.0_to_4.81.0.json

@@ -2,7 +2,7 @@
   "comparison": {
     "oldVersion": "4.79.0",
     "newVersion": "4.81.0",
-    "timestamp": "2026-03-13T22:52:48.391Z"
+    "timestamp": "2026-03-17T19:12:59.240Z"
   },
   "summary": {
     "newComponents": 0,

modules/components/pages/outputs/sql_insert.adoc

@@ -41,6 +41,35 @@ include::components:example$advanced/outputs/sql_insert.yaml[]
 
 include::redpanda-connect:components:partial$examples/outputs/sql_insert.adoc[]
 
+== Dynamic SQL operations
+
+The `table` and `columns` fields are static strings — they do not support Bloblang interpolation. For dynamic table names, dynamic column lists, DELETE operations, or any other SQL that `sql_insert` cannot express, use the xref:components:outputs/sql_raw.adoc[`sql_raw` output] instead.
+
+There is no dedicated `sql_delete` output. To delete rows, use `sql_raw` with a DELETE statement:
+
+[source,yaml]
+----
+output:
+  sql_raw:
+    driver: postgres
+    dsn: postgres://user:pass@localhost:5432/mydb?sslmode=disable
+    query: "DELETE FROM my_table WHERE id = $1"
+    args_mapping: root = [ this.id ]
+----
+
+To insert into a table determined at runtime, use `sql_raw` with `unsafe_dynamic_query: true`, which enables Bloblang interpolation in the `query` field. Use this with caution: interpolating user-supplied values into a query can introduce SQL injection risks. Always validate or sanitize the interpolated value beforehand.
+
+[source,yaml]
+----
+output:
+  sql_raw:
+    driver: postgres
+    dsn: postgres://user:pass@localhost:5432/mydb?sslmode=disable
+    unsafe_dynamic_query: true
+    query: 'INSERT INTO ${! this.table_name } (id, value) VALUES ($1, $2)'
+    args_mapping: root = [ this.id, this.value ]
+----
+
 include::redpanda-connect:components:partial$fields/outputs/sql_insert.adoc[]
 
 // end::single-source[]

modules/components/pages/processors/sql_insert.adoc

@@ -43,6 +43,10 @@ If the insert fails to execute then the message will still remain unchanged and
 
 include::redpanda-connect:components:partial$examples/processors/sql_insert.adoc[]
 
+== Dynamic SQL operations
+
+The `table` and `columns` fields are static strings — they do not support Bloblang interpolation. For dynamic table names, dynamic column lists, DELETE operations, or any other SQL that `sql_insert` cannot express, use the xref:components:processors/sql_raw.adoc[`sql_raw` processor] instead. To use Bloblang interpolation inside `sql_raw`'s `query` field, you must enable `unsafe_dynamic_query: true`. Use this with caution, as interpolating unsanitized values into a query can introduce SQL injection risks.
+
 include::redpanda-connect:components:partial$fields/processors/sql_insert.adoc[]
 
 // end::single-source[]