delete-returning (#557)

Summary:

- Support for `DELETE RETURNING`
- Synchronous response publication **only**.
- Added robot test `Delete Returning Simple Projection`.
- Added robot test `Delete Returning Star`.
- Added robot test `Delete Await Returning Generates Error`.
- Added robot test `Delete Await Not Returning Functions as Expected`.
- Added operation type variation to `/*+ AWAIT */` robot tests.

Author: general-kroll-4-life

internal/stackql/parserutil/parser_util.go

@@ -137,6 +137,18 @@ func extractInsertReturningColumnNames(
 	return colNames, err
 }
 
+func ExtractDeleteReturningColumnNames(
+	deleteStmt *sqlparser.Delete,
+	starColumns []string,
+	formatter sqlparser.NodeFormatter,
+) ([]ColumnHandle, error) {
+	return extractInsertReturningColumnNames(
+		deleteStmt.SelectExprs,
+		starColumns,
+		formatter,
+	)
+}
+
 func ExtractUpdateReturningColumnNames(
 	updateStmt *sqlparser.Update,
 	starColumns []string,

internal/stackql/planbuilder/plan_builder.go

@@ -13,6 +13,7 @@ import (
 	"github.com/stackql/any-sdk/pkg/streaming"
 	"github.com/stackql/stackql/internal/stackql/acid/txn_context"
 	"github.com/stackql/stackql/internal/stackql/astanalysis/routeanalysis"
+	"github.com/stackql/stackql/internal/stackql/drm"
 	"github.com/stackql/stackql/internal/stackql/handler"
 	"github.com/stackql/stackql/internal/stackql/internal_data_transfer/builder_input"
 	"github.com/stackql/stackql/internal/stackql/internal_data_transfer/internaldto"
@@ -608,13 +609,18 @@ func (pgb *standardPlanGraphBuilder) handleDelete(pbi planbuilderinput.PlanBuild
 			return err
 		}
 		insertCtx := primitiveGenerator.GetPrimitiveComposer().GetInsertPreparedStatementCtx()
+		var selectCtx drm.PreparedStatementCtx
+		if len(node.SelectExprs) > 0 {
+			selectCtx = primitiveGenerator.GetPrimitiveComposer().GetSelectPreparedStatementCtx()
+		}
 		isPhysicalTable := tbl.IsPhysicalTable()
 		var bldr primitivebuilder.Builder
 		if !isPhysicalTable {
 			bldr = primitivebuilder.NewDelete(
 				pgb.planGraphHolder,
 				handlerCtx,
 				insertCtx,
+				selectCtx,
 				node,
 				tbl,
 				nil,

internal/stackql/primitivebuilder/delete.go

@@ -19,17 +19,20 @@ type Delete struct {
 	handlerCtx        handler.HandlerContext
 	drmCfg            drm.Config
 	root              primitivegraph.PrimitiveNode
+	tail              primitivegraph.PrimitiveNode
 	tbl               tablemetadata.ExtendedTableMetadata
 	node              sqlparser.SQLNode
 	commentDirectives sqlparser.CommentDirectives
 	isAwait           bool
 	insertCtx         drm.PreparedStatementCtx
+	selectCtx         drm.PreparedStatementCtx
 }
 
 func NewDelete(
 	graph primitivegraph.PrimitiveGraphHolder,
 	handlerCtx handler.HandlerContext,
 	insertCtx drm.PreparedStatementCtx,
+	selectCtx drm.PreparedStatementCtx,
 	node sqlparser.SQLNode,
 	tbl tablemetadata.ExtendedTableMetadata,
 	commentDirectives sqlparser.CommentDirectives,
@@ -44,6 +47,7 @@ func NewDelete(
 		commentDirectives: commentDirectives,
 		isAwait:           isAwait,
 		insertCtx:         insertCtx,
+		selectCtx:         selectCtx,
 	}
 }
 
@@ -52,7 +56,7 @@ func (ss *Delete) GetRoot() primitivegraph.PrimitiveNode {
 }
 
 func (ss *Delete) GetTail() primitivegraph.PrimitiveNode {
-	return ss.root
+	return ss.tail
 }
 
 func (ss *Delete) Build() error {
@@ -104,6 +108,22 @@ func (ss *Delete) Build() error {
 	graph := ss.graph
 	insertNode := graph.CreatePrimitiveNode(deletePrimitive)
 	ss.root = insertNode
-
+	ss.tail = insertNode
+	if ss.selectCtx != nil {
+		selectionBldr := NewSingleSelect(
+			ss.graph,
+			handlerCtx,
+			ss.selectCtx,
+			[]tableinsertioncontainer.TableInsertionContainer{insertContainer},
+			nil,
+			streaming.NewNopMapStream(),
+		)
+		err = selectionBldr.Build()
+		if err != nil {
+			return err
+		}
+		ss.graph.NewDependency(ss.tail, selectionBldr.GetRoot(), 1.0)
+		ss.tail = selectionBldr.GetTail()
+	}
 	return nil
 }

internal/stackql/primitivegenerator/statement_analyzer.go

@@ -1301,6 +1301,7 @@ func (pb *standardPrimitiveGenerator) inferHeirarchyAndPersist(
 	return err
 }
 
+//nolint:funlen,gocognit // acceptable for now
 func (pb *standardPrimitiveGenerator) analyzeDelete(
 	pbi planbuilderinput.PlanBuilderInput,
 ) error {
@@ -1331,6 +1332,13 @@ func (pb *standardPrimitiveGenerator) analyzeDelete(
 	if err != nil {
 		return err
 	}
+
+	if pb.PrimitiveComposer.IsAwait() && !method.IsAwaitable() {
+		return fmt.Errorf("method %s is not awaitable", method.GetName())
+	}
+	if pb.PrimitiveComposer.IsAwait() && len(node.SelectExprs) > 0 {
+		return fmt.Errorf("returning from asynchronous delete is disallowed")
+	}
 	svc, err := tbl.GetService()
 	if err != nil {
 		return err
@@ -1358,20 +1366,35 @@ func (pb *standardPrimitiveGenerator) analyzeDelete(
 	if err != nil {
 		return err
 	}
+	columnHandles := []parserutil.ColumnHandle{}
+	if len(node.SelectExprs) > 0 {
+		if pb.PrimitiveComposer.IsAwait() {
+			return fmt.Errorf("delete with returning not allowed in await mode")
+		}
+		starColumns, _ := methodAnalysisOutput.GetOrderedStarColumnsNames()
+		columnHandles, err = parserutil.ExtractDeleteReturningColumnNames(
+			node,
+			starColumns,
+			handlerCtx.GetASTFormatter(),
+		)
+		if err != nil {
+			return err
+		}
+	}
 	err = pb.analyzeUnaryAction(
 		pbi,
 		handlerCtx,
 		node,
 		node.Where,
 		tbl,
-		[]parserutil.ColumnHandle{},
+		columnHandles,
 		methodAnalysisOutput,
 	)
 	if err != nil {
 		return err
 	}
 	pb.PrimitiveComposer.SetTable(node, tbl)
-	return err
+	return nil
 }
 
 func (pb *standardPrimitiveGenerator) analyzeDescribe(pbi planbuilderinput.PlanBuilderInput) error {

test/python/stackql_test_tooling/flask/gcp/app.py

@@ -87,6 +87,9 @@ def _extrapolate_target_from_operation(operation_name: str, project_name: str, h
     if project_name == 'mutable-project' and operation_name == 'operation-100000000003-10000000003-10000003-10000003':
         firewall_name = 'updatable-firewall'
         return f'https://{host_name}:1080/compute/v1/projects/{ project_name }/global/firewalls/{ firewall_name }'
+    if project_name == 'mutable-project' and operation_name == 'operation-100000000004-10000000004-10000004-10000004':
+        firewall_name = 'deletable-firewall'
+        return f'https://{host_name}:1080/compute/v1/projects/{ project_name }/global/firewalls/{ firewall_name }'
     raise ValueError(f"Unsupported operation name: {operation_name} for project: {project_name}")
 
 @app.route('/compute/v1/projects/<project_name>/global/operations/<operation_name>', methods=['GET'])
@@ -103,7 +106,7 @@ def projects_testing_project_global_operation_detail(project_name: str, operatio
             project_name=project_name,
             host_name=host_name,
             kind='compute#operation',
-            operation_type='insert',
+            operation_type='insert' if operation_name == 'operation-100000000001-10000000001-10000001-10000001' else 'update' if operation_name == 'operation-100000000002-10000000002-10000002-10000002' else 'delete' if operation_name == 'operation-100000000004-10000000004-10000004-10000004' else 'patch',
             progress=100,
             end_time='2025-07-05T19:43:34.491-07:00',
         ), 200, {'Content-Type': 'application/json'}
@@ -318,7 +321,7 @@ def projects_testing_project_global_firewalls_replace(project_name: str, firewal
         project_name=project_name,
         host_name=host_name,
         kind='compute#operation',
-        operation_type='put',
+        operation_type='update',
         progress=0,
     ), 200, {'Content-Type': 'application/json'}
 
@@ -348,6 +351,29 @@ def projects_testing_project_global_firewalls_update(project_name: str, firewall
         progress=0,
     ), 200, {'Content-Type': 'application/json'}
 
+@app.route('/compute/v1/projects/<project_name>/global/firewalls/<firewall_name>', methods=['DELETE'])
+def projects_testing_project_global_firewalls_delete(project_name: str, firewall_name: str):
+    _permitted_combinations = (('mutable-project', 'deletable-firewall'),)
+    if (project_name, firewall_name) not in _permitted_combinations:
+        return '{"msg": "Disallowed"}', 500, {'Content-Type': 'application/json'}
+    operation_id = '1000000000004'
+    operation_name = 'operation-100000000004-10000000004-10000004-10000004'
+    host_name = 'host.docker.internal' if _IS_DOCKER else 'localhost'
+    target_link = f'https://{host_name}:1080/compute/v1/projects/{ project_name }/global/firewalls/{ firewall_name }'
+    if not project_name:
+        return '{"msg": "Invalid request: project not supplied"}', 400, {'Content-Type': 'application/json'}
+    return render_template(
+        'global-operation.jinja.json', 
+        target_link=target_link, 
+        operation_id=operation_id,
+        operation_name=operation_name,
+        project_name=project_name,
+        host_name=host_name,
+        kind='compute#operation',
+        operation_type='delete',
+        progress=0,
+    ), 200, {'Content-Type': 'application/json'}
+
 @app.route('/compute/v1/projects/<project_name>/global/firewalls/<firewall_name>', methods=['GET'])
 def projects_testing_project_global_firewalls_some_other_firewall(project_name: str, firewall_name: str):
     _permitted_combinations = (('testing-project', 'some-other-firewall'), ('mutable-project', 'updatable-firewall'), ('mutable-project', 'replacable-firewall'))

test/python/stackql_test_tooling/flask/gcp/templates/global-operation.jinja.json

@@ -2,7 +2,7 @@
   "kind": "{{ kind if kind else 'compute#operation' }}",
   "id": "{{ operation_id if operation_id else '1000000000001' }}",
   "name": "{{ operation_name }}",
-  "operationType": "insert",
+  "operationType": "{{ operation_type }}",
   "targetLink": "{{ target_link }}",
   "targetId": "{{ target_id if target_id else '2000000000002' }}",
   "status": "{{ 'DONE' if progress and progress > 99 else 'RUNNING' }}",