fix: better error detail for failed sql

Add reflection.IsEmptyValue to detect nil, empty string, and zero numbers.
Use it in recursive CUD processing to skip update/delete when the primary
key is absent, logging a warning instead of proceeding with an invalid operation.

pkg/common/adapters/database/bun.go

@@ -300,6 +300,7 @@ type BunSelectQuery struct {
 	inJoinContext        bool                                                     // Track if we're in a JOIN relation context
 	joinTableAlias       string                                                   // Alias to use for JOIN conditions
 	skipAutoDetect       bool                                                     // Skip auto-detection to prevent circular calls
+	preloadRelationAlias string                                                   // Relation alias used in separate-query preloads (e.g. "tprp" for relation "TPRP")
 	customPreloads       map[string][]func(common.SelectQuery) common.SelectQuery // Relations to load with custom implementation
 	metricsEnabled       bool
 }
@@ -346,12 +347,14 @@ func (b *BunSelectQuery) ColumnExpr(query string, args ...interface{}) common.Se
 }
 
 func (b *BunSelectQuery) Where(query string, args ...interface{}) common.SelectQuery {
-	// If we're in a JOIN context, add table prefix to unqualified columns
 	if b.inJoinContext && b.joinTableAlias != "" {
 		query = addTablePrefix(query, b.joinTableAlias)
+	} else if b.preloadRelationAlias != "" && b.tableName != "" {
+		// Separate-query preload: the caller may have written conditions using the
+		// relation name as a prefix (e.g. "TPRP.col"). Bun uses the real table name
+		// as the alias, so rewrite any such references to use tableName instead.
+		query = replaceRelationAlias(query, b.preloadRelationAlias, b.tableName)
 	} else if b.tableAlias != "" && b.tableName != "" {
-		// If we have a table alias defined, check if the query references a different alias
-		// This can happen in preloads where the user expects a certain alias but Bun generates another
 		query = normalizeTableAlias(query, b.tableAlias, b.tableName)
 	}
 	b.query = b.query.Where(query, args...)
@@ -487,6 +490,30 @@ func normalizeTableAlias(query, expectedAlias, tableName string) string {
 	return modified
 }
 
+// replaceRelationAlias rewrites WHERE conditions written with a relation alias prefix
+// (e.g. "TPRP.col") to use the real table name that bun uses in separate queries
+// (e.g. "t_proposalinstance.col"). Only called for separate-query preload wrappers.
+func replaceRelationAlias(query, relationAlias, tableName string) string {
+	if relationAlias == "" || tableName == "" || query == "" {
+		return query
+	}
+	parts := strings.FieldsFunc(query, func(r rune) bool {
+		return r == ' ' || r == '(' || r == ')' || r == ','
+	})
+	modified := query
+	for _, part := range parts {
+		if dotIndex := strings.Index(part, "."); dotIndex > 0 {
+			prefix := part[:dotIndex]
+			column := part[dotIndex+1:]
+			if strings.EqualFold(prefix, relationAlias) {
+				logger.Debug("Replacing relation alias '%s' with table name '%s' in preload WHERE condition", prefix, tableName)
+				modified = strings.ReplaceAll(modified, part, tableName+"."+column)
+			}
+		}
+	}
+	return modified
+}
+
 func isJoinKeyword(word string) bool {
 	switch strings.ToUpper(word) {
 	case "JOIN", "INNER", "LEFT", "RIGHT", "FULL", "OUTER", "CROSS":
@@ -676,8 +703,20 @@ func (b *BunSelectQuery) PreloadRelation(relation string, apply ...func(common.S
 				wrapper.tableAlias = provider.TableAlias()
 				logger.Debug("Preload relation '%s' using table alias: %s", relation, wrapper.tableAlias)
 			}
+
 		}
 
+		// Fallback: if the model didn't provide a table name, ask bun directly.
+		if wrapper.tableName == "" {
+			wrapper.schema, wrapper.tableName = parseTableName(sq.GetTableName(), b.driverName)
+		}
+
+		// For separate-query preloads (has-many), bun aliases the related table using
+		// the actual table name, not the relation name. Record the relation alias so
+		// Where() can rewrite conditions like "TPRP.col" to "t_proposalinstance.col".
+		wrapper.preloadRelationAlias = strings.ToLower(relation)
+		logger.Debug("Preload relation '%s' registered alias '%s' for separate-query WHERE rewriting", relation, wrapper.preloadRelationAlias)
+
 		// Start with the interface value (not pointer)
 		current := common.SelectQuery(wrapper)
 
@@ -1276,6 +1315,7 @@ func (b *BunSelectQuery) Scan(ctx context.Context, dest interface{}) (err error)
 	if err != nil {
 		sqlStr := b.query.String()
 		logger.Error("BunSelectQuery.Scan failed. SQL: %s. Error: %v", sqlStr, err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	return err
 }
@@ -1332,7 +1372,7 @@ func (b *BunSelectQuery) ScanModel(ctx context.Context) (err error) {
 	if err != nil {
 		sqlStr := b.query.String()
 		logger.Error("BunSelectQuery.ScanModel failed. SQL: %s. Error: %v", sqlStr, err)
-		return err
+		return common.WrapSQLError(err, sqlStr)
 	}
 
 	// After main query, load custom preloads using separate queries
@@ -1362,6 +1402,7 @@ func (b *BunSelectQuery) Count(ctx context.Context) (count int, err error) {
 		if err != nil {
 			sqlStr := b.query.String()
 			logger.Error("BunSelectQuery.Count failed. SQL: %s. Error: %v", sqlStr, err)
+			err = common.WrapSQLError(err, sqlStr)
 		}
 		return
 	}
@@ -1375,6 +1416,7 @@ func (b *BunSelectQuery) Count(ctx context.Context) (count int, err error) {
 	if err != nil {
 		sqlStr := countQuery.String()
 		logger.Error("BunSelectQuery.Count (subquery) failed. SQL: %s. Error: %v", sqlStr, err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	return
 }
@@ -1392,6 +1434,7 @@ func (b *BunSelectQuery) Exists(ctx context.Context) (exists bool, err error) {
 	if err != nil {
 		sqlStr := b.query.String()
 		logger.Error("BunSelectQuery.Exists failed. SQL: %s. Error: %v", sqlStr, err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	return
 }
@@ -1580,6 +1623,7 @@ func (b *BunUpdateQuery) Exec(ctx context.Context) (res common.Result, err error
 		// Log SQL string for debugging
 		sqlStr := b.query.String()
 		logger.Error("BunUpdateQuery.Exec failed. SQL: %s. Error: %v", sqlStr, err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	recordQueryMetrics(b.metricsEnabled, "UPDATE", b.schema, b.entity, b.tableName, startedAt, err)
 	return &BunResult{result: result}, err
@@ -1631,6 +1675,7 @@ func (b *BunDeleteQuery) Exec(ctx context.Context) (res common.Result, err error
 		// Log SQL string for debugging
 		sqlStr := b.query.String()
 		logger.Error("BunDeleteQuery.Exec failed. SQL: %s. Error: %v", sqlStr, err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	recordQueryMetrics(b.metricsEnabled, "DELETE", b.schema, b.entity, b.tableName, startedAt, err)
 	return &BunResult{result: result}, err

pkg/common/adapters/database/gorm.go

@@ -583,6 +583,7 @@ func (g *GormSelectQuery) Scan(ctx context.Context, dest interface{}) (err error
 			return tx.Find(dest)
 		})
 		logger.Error("GormSelectQuery.Scan failed. SQL: %s. Error: %v", sqlStr, err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	recordQueryMetrics(g.metricsEnabled, "SELECT", g.schema, g.entity, g.tableName, startedAt, err)
 	return err
@@ -613,6 +614,7 @@ func (g *GormSelectQuery) ScanModel(ctx context.Context) (err error) {
 			return tx.Find(g.db.Statement.Model)
 		})
 		logger.Error("GormSelectQuery.ScanModel failed. SQL: %s. Error: %v", sqlStr, err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	recordQueryMetrics(g.metricsEnabled, "SELECT", g.schema, g.entity, g.tableName, startedAt, err)
 	return err
@@ -642,6 +644,7 @@ func (g *GormSelectQuery) Count(ctx context.Context) (count int, err error) {
 			return tx.Count(&count64)
 		})
 		logger.Error("GormSelectQuery.Count failed. SQL: %s. Error: %v", sqlStr, err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	recordQueryMetrics(g.metricsEnabled, "COUNT", g.schema, g.entity, g.tableName, startedAt, err)
 	return int(count64), err
@@ -671,6 +674,7 @@ func (g *GormSelectQuery) Exists(ctx context.Context) (exists bool, err error) {
 			return tx.Limit(1).Count(&count)
 		})
 		logger.Error("GormSelectQuery.Exists failed. SQL: %s. Error: %v", sqlStr, err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	recordQueryMetrics(g.metricsEnabled, "EXISTS", g.schema, g.entity, g.tableName, startedAt, err)
 	return count > 0, err
@@ -931,6 +935,7 @@ func (g *GormUpdateQuery) Exec(ctx context.Context) (res common.Result, err erro
 			return tx.Updates(g.updates)
 		})
 		logger.Error("GormUpdateQuery.Exec failed. SQL: %s. Error: %v", sqlStr, result.Error)
+		return &GormResult{result: result}, common.WrapSQLError(result.Error, sqlStr)
 	}
 	recordQueryMetrics(g.metricsEnabled, "UPDATE", g.schema, g.entity, g.tableName, startedAt, result.Error)
 	return &GormResult{result: result}, result.Error
@@ -992,6 +997,7 @@ func (g *GormDeleteQuery) Exec(ctx context.Context) (res common.Result, err erro
 			return tx.Delete(g.model)
 		})
 		logger.Error("GormDeleteQuery.Exec failed. SQL: %s. Error: %v", sqlStr, result.Error)
+		return &GormResult{result: result}, common.WrapSQLError(result.Error, sqlStr)
 	}
 	recordQueryMetrics(g.metricsEnabled, "DELETE", g.schema, g.entity, g.tableName, startedAt, result.Error)
 	return &GormResult{result: result}, result.Error

pkg/common/adapters/database/pgsql.go

@@ -138,7 +138,7 @@ func (p *PgSQLAdapter) Exec(ctx context.Context, query string, args ...interface
 	if err != nil {
 		logger.Error("PgSQL Exec failed: %v", err)
 		recordQueryMetrics(p.metricsEnabled, operation, schema, entity, table, startedAt, err)
-		return nil, err
+		return nil, common.WrapSQLError(err, query)
 	}
 	recordQueryMetrics(p.metricsEnabled, operation, schema, entity, table, startedAt, nil)
 	return &PgSQLResult{result: result}, nil
@@ -164,7 +164,7 @@ func (p *PgSQLAdapter) Query(ctx context.Context, dest interface{}, query string
 	if err != nil {
 		logger.Error("PgSQL Query failed: %v", err)
 		recordQueryMetrics(p.metricsEnabled, operation, schema, entity, table, startedAt, err)
-		return err
+		return common.WrapSQLError(err, query)
 	}
 	defer rows.Close()
 
@@ -511,7 +511,7 @@ func (p *PgSQLSelectQuery) Scan(ctx context.Context, dest interface{}) (err erro
 	if err != nil {
 		logger.Error("PgSQL SELECT failed: %v", err)
 		recordQueryMetrics(p.metricsEnabled, "SELECT", p.schema, p.entity, p.tableName, startedAt, err)
-		return err
+		return common.WrapSQLError(err, query)
 	}
 	defer rows.Close()
 
@@ -534,8 +534,8 @@ func (p *PgSQLSelectQuery) ScanModel(ctx context.Context) error {
 	return p.Scan(ctx, p.model)
 }
 
-// countInternal executes the COUNT query and returns the result without recording metrics.
+// countInternal executes the COUNT query and returns the result and the SQL string without recording metrics.
-func (p *PgSQLSelectQuery) countInternal(ctx context.Context) (int, error) {
+func (p *PgSQLSelectQuery) countInternal(ctx context.Context) (rowCount int, querySQL string, retErr error) {
 	var sb strings.Builder
 	sb.WriteString("SELECT COUNT(*) FROM ")
 	sb.WriteString(p.tableName)
@@ -571,9 +571,9 @@ func (p *PgSQLSelectQuery) countInternal(ctx context.Context) (int, error) {
 
 	var count int
 	if err := row.Scan(&count); err != nil {
-		return 0, err
+		return 0, query, err
 	}
-	return count, nil
+	return count, query, nil
 }
 
 func (p *PgSQLSelectQuery) Count(ctx context.Context) (count int, err error) {
@@ -584,9 +584,11 @@ func (p *PgSQLSelectQuery) Count(ctx context.Context) (count int, err error) {
 		}
 	}()
 	startedAt := time.Now()
-	count, err = p.countInternal(ctx)
+	var sqlStr string
+	count, sqlStr, err = p.countInternal(ctx)
 	if err != nil {
 		logger.Error("PgSQL COUNT failed: %v", err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	recordQueryMetrics(p.metricsEnabled, "COUNT", p.schema, p.entity, p.tableName, startedAt, err)
 	return count, err
@@ -600,9 +602,11 @@ func (p *PgSQLSelectQuery) Exists(ctx context.Context) (exists bool, err error)
 		}
 	}()
 	startedAt := time.Now()
-	count, err := p.countInternal(ctx)
+	var sqlStr string
+	count, sqlStr, err := p.countInternal(ctx)
 	if err != nil {
 		logger.Error("PgSQL EXISTS failed: %v", err)
+		err = common.WrapSQLError(err, sqlStr)
 	}
 	recordQueryMetrics(p.metricsEnabled, "EXISTS", p.schema, p.entity, p.tableName, startedAt, err)
 	return count > 0, err
@@ -702,7 +706,7 @@ func (p *PgSQLInsertQuery) Exec(ctx context.Context) (res common.Result, err err
 
 	if err != nil {
 		logger.Error("PgSQL INSERT failed: %v", err)
-		return nil, err
+		return nil, common.WrapSQLError(err, query)
 	}
 
 	return &PgSQLResult{result: result}, nil
@@ -750,7 +754,10 @@ func (p *PgSQLInsertQuery) Scan(ctx context.Context, dest interface{}) (err erro
 		row = p.db.QueryRowContext(ctx, query, args...)
 	}
 
-	return row.Scan(dest)
+	if err := row.Scan(dest); err != nil {
+		return common.WrapSQLError(err, query)
+	}
+	return nil
 }
 
 // PgSQLUpdateQuery implements UpdateQuery for PostgreSQL
@@ -929,7 +936,7 @@ func (p *PgSQLUpdateQuery) Exec(ctx context.Context) (res common.Result, err err
 
 	if err != nil {
 		logger.Error("PgSQL UPDATE failed: %v", err)
-		return nil, err
+		return nil, common.WrapSQLError(err, query)
 	}
 
 	return &PgSQLResult{result: result}, nil
@@ -1007,7 +1014,7 @@ func (p *PgSQLDeleteQuery) Exec(ctx context.Context) (res common.Result, err err
 
 	if err != nil {
 		logger.Error("PgSQL DELETE failed: %v", err)
-		return nil, err
+		return nil, common.WrapSQLError(err, query)
 	}
 
 	return &PgSQLResult{result: result}, nil
@@ -1088,7 +1095,7 @@ func (p *PgSQLTxAdapter) Exec(ctx context.Context, query string, args ...interfa
 	if err != nil {
 		logger.Error("PgSQL Tx Exec failed: %v", err)
 		recordQueryMetrics(p.metricsEnabled, operation, schema, entity, table, startedAt, err)
-		return nil, err
+		return nil, common.WrapSQLError(err, query)
 	}
 	recordQueryMetrics(p.metricsEnabled, operation, schema, entity, table, startedAt, nil)
 	return &PgSQLResult{result: result}, nil
@@ -1102,7 +1109,7 @@ func (p *PgSQLTxAdapter) Query(ctx context.Context, dest interface{}, query stri
 	if err != nil {
 		logger.Error("PgSQL Tx Query failed: %v", err)
 		recordQueryMetrics(p.metricsEnabled, operation, schema, entity, table, startedAt, err)
-		return err
+		return common.WrapSQLError(err, query)
 	}
 	defer rows.Close()
 

pkg/common/recursive_crud.go

@@ -125,6 +125,13 @@ func (p *NestedCUDProcessor) ProcessNestedCUD(
 			result.AffectedRows = 1
 			result.Data = regularData
 
+			// Re-select the inserted row so result.Data reflects DB-generated defaults.
+			if row, err := p.processSelect(ctx, tableName, id); err != nil {
+				logger.Warn("Select after insert failed: table=%s, id=%v, error=%v", tableName, id, err)
+			} else if len(row) > 0 {
+				result.Data = row
+			}
+
 			// Process child relations after parent insert (to get parent ID)
 			if err := p.processChildRelations(ctx, "insert", id, relationFields, result.RelationData, modelType, parentIDs); err != nil {
 				logger.Error("Failed to process child relations after insert: table=%s, parentID=%v, relations=%+v, error=%v", tableName, id, relationFields, err)
@@ -134,8 +141,12 @@ func (p *NestedCUDProcessor) ProcessNestedCUD(
 			logger.Debug("Skipping insert for %s - no data columns besides _request", tableName)
 		}
 
-	case "update":
+	case "update", "change":
 		// Only perform update if we have data to update
+		if reflection.IsEmptyValue(data[pkName]) {
+			logger.Warn("Skipping update for %s - no primary key", tableName)
+			return result, nil
+		}
 		if hasData {
 			rows, err := p.processUpdate(ctx, regularData, tableName, data[pkName])
 			if err != nil {
@@ -146,9 +157,16 @@ func (p *NestedCUDProcessor) ProcessNestedCUD(
 			result.AffectedRows = rows
 			result.Data = regularData
 
+			// Re-select the updated row so result.Data reflects current DB state.
+			if row, err := p.processSelect(ctx, tableName, result.ID); err != nil {
+				logger.Warn("Select after update failed: table=%s, id=%v, error=%v", tableName, result.ID, err)
+			} else if len(row) > 0 {
+				result.Data = row
+			}
+
 			// Process child relations for update
 			if err := p.processChildRelations(ctx, "update", data[pkName], relationFields, result.RelationData, modelType, parentIDs); err != nil {
-				logger.Error("Failed to process child relations after update: table=%s, parentID=%v, relations=%+v, error=%v", tableName, data[pkName], relationFields, err)
+				logger.Error("Failed to process child relations after update: table=%s, parentID=%v, relations=%+v, error=%v", tableName, data[pkName], regularData, err)
 				return nil, fmt.Errorf("failed to process child relations: %w", err)
 			}
 		} else {
@@ -157,10 +175,15 @@ func (p *NestedCUDProcessor) ProcessNestedCUD(
 		}
 
 	case "delete":
+		if reflection.IsEmptyValue(data[pkName]) {
+			logger.Warn("Skipping delete for %s - no primary key", tableName)
+			return result, nil
+		}
+
 		// Process child relations first (for referential integrity)
 		if err := p.processChildRelations(ctx, "delete", data[pkName], relationFields, result.RelationData, modelType, parentIDs); err != nil {
 			logger.Error("Failed to process child relations before delete: table=%s, id=%v, relations=%+v, error=%v", tableName, data[pkName], relationFields, err)
-			return nil, fmt.Errorf("failed to process child relations before delete: %w", err)
+			return nil, fmt.Errorf("failed to process child relations: %w", err)
 		}
 
 		rows, err := p.processDelete(ctx, tableName, data[pkName])
@@ -234,6 +257,8 @@ func (p *NestedCUDProcessor) injectForeignKeys(data map[string]interface{}, mode
 		return
 	}
 
+	pkCol := reflection.GetPrimaryKeyName(reflect.New(modelType).Interface())
+
 	for parentKey, parentID := range parentIDs {
 		dbColNames := reflection.GetForeignKeyColumn(modelType, parentKey)
 
@@ -255,6 +280,9 @@ func (p *NestedCUDProcessor) injectForeignKeys(data map[string]interface{}, mode
 		}
 
 		for _, dbColName := range dbColNames {
+			if pkCol != "" && strings.EqualFold(dbColName, pkCol) {
+				continue
+			}
 			if _, exists := data[dbColName]; !exists {
 				logger.Debug("Injecting foreign key: %s = %v", dbColName, parentID)
 				data[dbColName] = parentID
@@ -289,6 +317,20 @@ func (p *NestedCUDProcessor) processInsert(
 	return id, nil
 }
 
+// processSelect fetches the row identified by id from tableName into a flat map.
+// Used to populate result.Data with the actual DB state after insert/update.
+func (p *NestedCUDProcessor) processSelect(ctx context.Context, tableName string, id interface{}) (map[string]interface{}, error) {
+	pkName := reflection.GetPrimaryKeyName(tableName)
+	var row map[string]interface{}
+	if err := p.db.NewSelect().
+		Table(tableName).
+		Where(fmt.Sprintf("%s = ?", QuoteIdent(pkName)), id).
+		Scan(ctx, &row); err != nil {
+		return nil, fmt.Errorf("select after write failed: %w", err)
+	}
+	return row, nil
+}
+
 // processUpdate handles update operation
 func (p *NestedCUDProcessor) processUpdate(
 	ctx context.Context,

pkg/common/types.go

@@ -1,5 +1,23 @@
 package common
 
+// SQLError wraps a database error together with the SQL that caused it,
+// so callers can surface the query in API error responses for easier debugging.
+type SQLError struct {
+	Err error
+	SQL string
+}
+
+func (e *SQLError) Error() string { return e.Err.Error() }
+func (e *SQLError) Unwrap() error { return e.Err }
+
+// WrapSQLError wraps err with the given SQL. If err is nil it returns nil.
+func WrapSQLError(err error, sql string) error {
+	if err == nil {
+		return nil
+	}
+	return &SQLError{Err: err, SQL: sql}
+}
+
 type RequestBody struct {
 	Operation string         `json:"operation"`
 	Data      interface{}    `json:"data"`
@@ -104,6 +122,7 @@ type APIError struct {
 	Message string      `json:"message"`
 	Details interface{} `json:"details,omitempty"`
 	Detail  string      `json:"detail,omitempty"`
+	SQL     string      `json:"sql,omitempty"`
 }
 
 type Column struct {

pkg/funcspec/function_api.go

@@ -3,6 +3,7 @@ package funcspec
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -1071,6 +1072,10 @@ func sendError(w http.ResponseWriter, status int, code, message string, err erro
 	}
 	if err != nil {
 		errObj.Detail = err.Error()
+		var sqlErr *common.SQLError
+		if errors.As(err, &sqlErr) {
+			errObj.SQL = sqlErr.SQL
+		}
 	}
 
 	data, _ := json.Marshal(map[string]interface{}{

pkg/reflection/helpers.go

@@ -51,6 +51,31 @@ func ExtractTableNameOnly(fullName string) string {
 	return fullName[startIndex:]
 }
 
+// IsEmptyValue reports whether v is nil, an empty string, or a zero number.
+func IsEmptyValue(v any) bool {
+	if v == nil {
+		return true
+	}
+	rv := reflect.ValueOf(v)
+	if rv.Kind() == reflect.Ptr {
+		if rv.IsNil() {
+			return true
+		}
+		rv = rv.Elem()
+	}
+	switch rv.Kind() {
+	case reflect.String:
+		return rv.String() == ""
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		return rv.Int() == 0
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
+		return rv.Uint() == 0
+	case reflect.Float32, reflect.Float64:
+		return rv.Float() == 0
+	}
+	return false
+}
+
 // GetPointerElement returns the element type if the provided reflect.Type is a pointer.
 // If the type is a slice of pointers, it returns the element type of the pointer within the slice.
 // If neither condition is met, it returns the original type.

pkg/reflection/model_utils.go

@@ -974,16 +974,21 @@ func GetRelationType(model interface{}, fieldName string) RelationType {
 }
 
 // GetForeignKeyColumn returns the DB column names of the foreign key(s) that
-// the relation field identified by parentKey owns on modelType. Composite keys
+// relate parentKey to modelType. Composite keys (e.g. bun "join:a=b,join:c=d"
-// (e.g. bun "join:a=b,join:c=d" or GORM "foreignKey:ColA,ColB") yield multiple
+// or GORM "foreignKey:ColA,ColB") yield multiple entries. Returns nil when no
-// entries. Returns nil when no tag is found (caller should fall back to
+// tag is found (caller should fall back to convention).
-// convention).
 //
-// It checks tags in priority order:
+// Two lookup strategies are tried in order:
-//  1. Bun join: tag — e.g. `bun:"rel:belongs-to,join:department_id=id"` → ["department_id"]
-//  2. GORM foreignKey: tag — e.g. `gorm:"foreignKey:DepartmentID"` → [column of DepartmentID field]
 //
-// parentKey is matched case-insensitively against the field name and JSON tag.
+//  1. Relation-field match: find a field whose name/json equals parentKey, then
+//     read its bun join: or GORM foreignKey: tag and return the local columns.
+//     e.g. parentKey="department", field `Department bun:"join:dept_id=id"` → ["dept_id"]
+//
+//  2. Join left-side scan: scan every bun join tag in the struct for pairs whose
+//     left side equals parentKey and return the right-side (child FK) columns.
+//     e.g. parentKey="rid_mastertaskitem", field `Children bun:"join:rid_mastertaskitem=rid_parentmastertaskitem"` → ["rid_parentmastertaskitem"]
+//     Strategy 1 is skipped if the matched field is a declared relation (rel:) or
+//     has a GORM tag but carries no explicit FK — callers should use convention.
 func GetForeignKeyColumn(modelType reflect.Type, parentKey string) []string {
 	for modelType.Kind() == reflect.Ptr || modelType.Kind() == reflect.Slice {
 		modelType = modelType.Elem()
@@ -992,6 +997,7 @@ func GetForeignKeyColumn(modelType reflect.Type, parentKey string) []string {
 		return nil
 	}
 
+	// Strategy 1: match parentKey against a field's name/json tag.
 	for i := 0; i < modelType.NumField(); i++ {
 		field := modelType.Field(i)
 
@@ -1001,9 +1007,11 @@ func GetForeignKeyColumn(modelType reflect.Type, parentKey string) []string {
 			continue
 		}
 
+		bunTag := field.Tag.Get("bun")
+
 		// Bun: join:local_col=foreign_col (one join: part per pair)
 		var bunCols []string
-		for _, part := range strings.Split(field.Tag.Get("bun"), ",") {
+		for _, part := range strings.Split(bunTag, ",") {
 			part = strings.TrimSpace(part)
 			if strings.HasPrefix(part, "join:") {
 				pair := strings.TrimPrefix(part, "join:")
@@ -1033,10 +1041,38 @@ func GetForeignKeyColumn(modelType reflect.Type, parentKey string) []string {
 			}
 		}
 
+		// The field matched by name/json but has no explicit FK tag. If it is a
+		// declared relation field (rel:) or carries a GORM tag, the caller should
+		// use naming convention — don't fall through to strategy 2. Otherwise the
+		// matched field is a plain scalar column; proceed to the join left-side scan.
+		if strings.Contains(bunTag, "rel:") || field.Tag.Get("gorm") != "" {
 			return nil
 		}
+		break
+	}
 
-	return nil
+	// Strategy 2: scan every field's bun join tag for pairs whose left side (the
+	// parent's column) matches parentKey; the right side is the child FK column.
+	// This handles cases where parentKey is a raw column name rather than a
+	// relation field name (e.g. self-referential or has-many relationships).
+	seen := map[string]bool{}
+	var cols []string
+	for i := 0; i < modelType.NumField(); i++ {
+		for _, part := range strings.Split(modelType.Field(i).Tag.Get("bun"), ",") {
+			part = strings.TrimSpace(part)
+			if strings.HasPrefix(part, "join:") {
+				pair := strings.TrimPrefix(part, "join:")
+				if idx := strings.Index(pair, "="); idx > 0 {
+					left, right := pair[:idx], pair[idx+1:]
+					if strings.EqualFold(left, parentKey) && !seen[right] {
+						seen[right] = true
+						cols = append(cols, right)
+					}
+				}
+			}
+		}
+	}
+	return cols // nil if empty
 }
 
 // GetRelationModel gets the model type for a relation field

pkg/reflection/model_utils_foreign_key_test.go

@@ -37,6 +37,17 @@ type gormCompositeEmployee struct {
 	Department *fkDept `gorm:"foreignKey:DeptID,TenantID" json:"department"`
 }
 
+// selfRefItem mimics a self-referential model (like mastertaskitem) where the
+// parent PK column appears as the left side of a has-many join tag.
+type selfRefItem struct {
+	RidItem       int32        `json:"rid_item" bun:"rid_item,type:integer,pk"`
+	RidParentItem int32        `json:"rid_parentitem" bun:"rid_parentitem,type:integer"`
+	// has-one (single parent pointer)
+	Parent   *selfRefItem   `json:"Parent,omitempty" bun:"rel:has-one,join:rid_item=rid_parentitem"`
+	// has-many (child collection) — same join, duplicate right-side must be deduped
+	Children []*selfRefItem `json:"Children,omitempty" bun:"rel:has-many,join:rid_item=rid_parentitem"`
+}
+
 // conventionEmployee has no explicit FK tag — relies on naming convention.
 type conventionEmployee struct {
 	DepartmentID string  `json:"department_id"`
@@ -101,6 +112,14 @@ func TestGetForeignKeyColumn(t *testing.T) {
 			want:      []string{"dept_id", "tenant_id"},
 		},
 
+		// Join left-side scan (parentKey is a raw column name, not a relation field name)
+		{
+			name:      "self-referential: parent PK column returns child FK column",
+			modelType: reflect.TypeOf(selfRefItem{}),
+			parentKey: "rid_item",
+			want:      []string{"rid_parentitem"},
+		},
+
 		// Pointer and slice unwrapping
 		{
 			name:      "pointer to struct is unwrapped",

pkg/resolvespec/handler.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"database/sql"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net/http"
 	"reflect"
@@ -1757,18 +1758,21 @@ func (h *Handler) sendResponse(w common.ResponseWriter, data interface{}, metada
 }
 
 func (h *Handler) sendError(w common.ResponseWriter, status int, code, message string, details interface{}) {
-	w.SetHeader("Content-Type", "application/json")
+	apiErr := &common.APIError{
-	w.WriteHeader(status)
-	err := w.WriteJSON(common.Response{
-		Success: false,
-		Error: &common.APIError{
 		Code:    code,
 		Message: message,
 		Details: details,
 		Detail:  fmt.Sprintf("%v", details),
-		},
+	}
-	})
+	if asErr, ok := details.(error); ok {
-	if err != nil {
+		var sqlErr *common.SQLError
+		if errors.As(asErr, &sqlErr) {
+			apiErr.SQL = sqlErr.SQL
+		}
+	}
+	w.SetHeader("Content-Type", "application/json")
+	w.WriteHeader(status)
+	if err := w.WriteJSON(common.Response{Success: false, Error: apiErr}); err != nil {
 		logger.Error("Error sending response: %v", err)
 	}
 }

pkg/restheadspec/empty_result_test.go

@@ -9,29 +9,29 @@ import (
 	"github.com/bitechdev/ResolveSpec/pkg/common"
 )
 
-// Test that normalizeResultArray returns empty array when no records found without ID
+// Test that normalizeResultArray returns empty object when no records found (single-record mode)
 func TestNormalizeResultArray_EmptyArrayWhenNoID(t *testing.T) {
 	handler := &Handler{}
 
 	tests := []struct {
 		name             string
 		input            interface{}
-		shouldBeEmptyArr bool
+		shouldBeEmptyObj bool
 	}{
 		{
-			name:             "nil should return empty array",
+			name:             "nil should return empty object",
 			input:            nil,
-			shouldBeEmptyArr: true,
+			shouldBeEmptyObj: true,
 		},
 		{
-			name:             "empty slice should return empty array",
+			name:             "empty slice should return empty object",
 			input:            []*EmptyTestModel{},
-			shouldBeEmptyArr: true,
+			shouldBeEmptyObj: true,
 		},
 		{
 			name:             "single element should return the element",
 			input:            []*EmptyTestModel{{ID: 1, Name: "test"}},
-			shouldBeEmptyArr: false,
+			shouldBeEmptyObj: false,
 		},
 		{
 			name: "multiple elements should return the slice",
@@ -39,7 +39,7 @@ func TestNormalizeResultArray_EmptyArrayWhenNoID(t *testing.T) {
 				{ID: 1, Name: "test1"},
 				{ID: 2, Name: "test2"},
 			},
-			shouldBeEmptyArr: false,
+			shouldBeEmptyObj: false,
 		},
 	}
 
@@ -47,25 +47,25 @@ func TestNormalizeResultArray_EmptyArrayWhenNoID(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			result := handler.normalizeResultArray(tt.input)
 
-			// For cases that should return empty array
+			// For cases that should return empty object
-			if tt.shouldBeEmptyArr {
+			if tt.shouldBeEmptyObj {
-				emptyArr, ok := result.([]interface{})
+				emptyObj, ok := result.(map[string]interface{})
 				if !ok {
-					t.Errorf("Expected empty array []interface{}{}, got %T: %v", result, result)
+					t.Errorf("Expected empty object map[string]interface{}{}, got %T: %v", result, result)
 					return
 				}
-				if len(emptyArr) != 0 {
+				if len(emptyObj) != 0 {
-					t.Errorf("Expected empty array with length 0, got length %d", len(emptyArr))
+					t.Errorf("Expected empty object with length 0, got length %d", len(emptyObj))
 				}
 
-				// Verify it serializes to [] and not null
+				// Verify it serializes to {} and not null
 				jsonBytes, err := json.Marshal(result)
 				if err != nil {
 					t.Errorf("Failed to marshal result: %v", err)
 					return
 				}
-				if string(jsonBytes) != "[]" {
+				if string(jsonBytes) != "{}" {
-					t.Errorf("Expected JSON '[]', got '%s'", string(jsonBytes))
+					t.Errorf("Expected JSON '{}', got '%s'", string(jsonBytes))
 				}
 			}
 		})
@@ -138,12 +138,12 @@ func TestSendResponseWithOptions_NoDataFoundHeader(t *testing.T) {
 		t.Errorf("Expected X-No-Data-Found header to be 'true', got '%s'", mockWriter.headers["X-No-Data-Found"])
 	}
 
-	// Check status code is 200
+	// Check status code is 200 even when no records found
 	if mockWriter.statusCode != 200 {
 		t.Errorf("Expected status code 200, got %d", mockWriter.statusCode)
 	}
 
-	// Verify the body is an empty array
+	// Verify the body is an empty array (list request, SingleRecordAsObject not set)
 	if mockWriter.body == nil {
 		t.Error("Expected body to be set, got nil")
 	} else {

pkg/restheadspec/handler.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"database/sql"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net/http"
 	"reflect"
@@ -579,8 +580,8 @@ func (h *Handler) handleRead(ctx context.Context, w common.ResponseWriter, id st
 	// preload LEFT JOIN (to prevent "table name specified more than once" errors).
 	if len(options.CustomSQLJoin) > 0 {
 		preloadAliasSet := make(map[string]bool, len(options.Preload))
-		for _, p := range options.Preload {
+		for i := range options.Preload {
-			if alias := common.RelationPathToBunAlias(p.Relation); alias != "" {
+			if alias := common.RelationPathToBunAlias(options.Preload[i].Relation); alias != "" {
 				preloadAliasSet[alias] = true
 			}
 		}
@@ -619,16 +620,19 @@ func (h *Handler) handleRead(ctx context.Context, w common.ResponseWriter, id st
 		logger.Debug("FetchRowNumber: Row number %d for PK %s = %s", rowNum, pkName, fetchRowNumberPKValue)
 
 		// Now filter the main query to this specific primary key
-		query = query.Where(fmt.Sprintf("%s = ?", common.QuoteIdent(pkName)), fetchRowNumberPKValue)
+		tableAlias := reflection.ExtractTableNameOnly(tableName)
+		query = query.Where(fmt.Sprintf("%s.%s = ?", common.QuoteIdent(tableAlias), common.QuoteIdent(pkName)), fetchRowNumberPKValue)
 	} else if id != "" {
 		// If ID is provided (and not FetchRowNumber), filter by ID
 		pkName := reflection.GetPrimaryKeyName(model)
 		logger.Debug("Filtering by ID=%s: %s", pkName, id)
 
-		query = query.Where(fmt.Sprintf("%s = ?", common.QuoteIdent(pkName)), id)
+		tableAlias := reflection.ExtractTableNameOnly(tableName)
+		query = query.Where(fmt.Sprintf("%s.%s = ?", common.QuoteIdent(tableAlias), common.QuoteIdent(pkName)), id)
 	}
 
 	// Apply sorting
+	tableAlias := reflection.ExtractTableNameOnly(tableName)
 	for _, sort := range options.Sort {
 		direction := "ASC"
 		if strings.EqualFold(sort.Direction, "desc") {
@@ -640,9 +644,12 @@ func (h *Handler) handleRead(ctx context.Context, w common.ResponseWriter, id st
 		if strings.HasPrefix(sort.Column, "(") && strings.HasSuffix(sort.Column, ")") {
 			// For expressions, pass as raw SQL to prevent auto-quoting
 			query = query.OrderExpr(fmt.Sprintf("%s %s", sort.Column, direction))
+		} else if strings.Contains(sort.Column, ".") {
+			// Already qualified (e.g. alias.column) - pass as raw expression to preserve the dot
+			query = query.OrderExpr(fmt.Sprintf("%s %s", sort.Column, direction))
 		} else {
-			// Regular column - let Bun handle quoting
+			// Unqualified column - prefix with main table alias to avoid ambiguity on JOINs
-			query = query.Order(fmt.Sprintf("%s %s", sort.Column, direction))
+			query = query.OrderExpr(fmt.Sprintf("%s.%s %s", common.QuoteIdent(tableAlias), common.QuoteIdent(sort.Column), direction))
 		}
 	}
 
@@ -2502,14 +2509,12 @@ func (h *Handler) sendResponseWithOptions(w common.ResponseWriter, data interfac
 		w.SetHeader("X-No-Data-Found", "true")
 	}
 
-	w.WriteHeader(http.StatusOK)
-
 	// Normalize single-record arrays to objects if requested
 	if options != nil && options.SingleRecordAsObject {
 		data = h.normalizeResultArray(data)
 	}
 
-	// Return data as-is without wrapping in common.Response
+	w.WriteHeader(http.StatusOK)
 
 	if err := w.WriteJSON(data); err != nil {
 		logger.Error("Failed to write JSON response: %v", err)
@@ -2520,7 +2525,7 @@ func (h *Handler) sendResponseWithOptions(w common.ResponseWriter, data interfac
 // Returns the single element if data is a slice/array with exactly one element, otherwise returns data unchanged
 func (h *Handler) normalizeResultArray(data interface{}) interface{} {
 	if data == nil {
-		return []interface{}{}
+		return map[string]interface{}{}
 	}
 
 	// Use reflection to check if data is a slice or array
@@ -2535,15 +2540,15 @@ func (h *Handler) normalizeResultArray(data interface{}) interface{} {
 			// Return the single element
 			return dataValue.Index(0).Interface()
 		} else if dataValue.Len() == 0 {
-			// Keep empty array as empty array, don't convert to empty object
+			// Single-record request with no result → empty object
-			return []interface{}{}
+			return map[string]interface{}{}
 		}
 	}
 
 	if dataValue.Kind() == reflect.String {
 		str := dataValue.String()
 		if str == "" || str == "null" {
-			return []interface{}{}
+			return map[string]interface{}{}
 		}
 
 	}
@@ -2552,9 +2557,6 @@ func (h *Handler) normalizeResultArray(data interface{}) interface{} {
 
 // sendFormattedResponse sends response with formatting options
 func (h *Handler) sendFormattedResponse(w common.ResponseWriter, data interface{}, metadata *common.Metadata, options ExtendedRequestOptions) {
-	// Normalize single-record arrays to objects if requested
-	httpStatus := http.StatusOK
-
 	// Handle nil data - convert to empty array
 	if data == nil {
 		data = []interface{}{}
@@ -2591,7 +2593,7 @@ func (h *Handler) sendFormattedResponse(w common.ResponseWriter, data interface{
 	switch options.ResponseFormat {
 	case "simple":
 		// Simple format: just return the data array
-		w.WriteHeader(httpStatus)
+		w.WriteHeader(http.StatusOK)
 		if err := w.WriteJSON(data); err != nil {
 			logger.Error("Failed to write JSON response: %v", err)
 		}
@@ -2603,7 +2605,7 @@ func (h *Handler) sendFormattedResponse(w common.ResponseWriter, data interface{
 		if metadata != nil {
 			response["count"] = metadata.Total
 		}
-		w.WriteHeader(httpStatus)
+		w.WriteHeader(http.StatusOK)
 		if err := w.WriteJSON(response); err != nil {
 			logger.Error("Failed to write JSON response: %v", err)
 		}
@@ -2614,7 +2616,7 @@ func (h *Handler) sendFormattedResponse(w common.ResponseWriter, data interface{
 			Data:     data,
 			Metadata: metadata,
 		}
-		w.WriteHeader(httpStatus)
+		w.WriteHeader(http.StatusOK)
 		if err := w.WriteJSON(response); err != nil {
 			logger.Error("Failed to write JSON response: %v", err)
 		}
@@ -2644,6 +2646,12 @@ func (h *Handler) sendError(w common.ResponseWriter, statusCode int, code, messa
 		"_error":  errorMsg,
 		"_retval": 1,
 	}
+
+	var sqlErr *common.SQLError
+	if errors.As(err, &sqlErr) {
+		response["_sql"] = sqlErr.SQL
+	}
+
 	w.SetHeader("Content-Type", "application/json")
 	w.WriteHeader(statusCode)
 	if jsonErr := w.WriteJSON(response); jsonErr != nil {

pkg/websocketspec/handler.go

@@ -3,6 +3,7 @@ package websocketspec
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net/http"
 	"reflect"
@@ -17,6 +18,17 @@ import (
 	"github.com/bitechdev/ResolveSpec/pkg/reflection"
 )
 
+// newErrorResponseFromErr creates an error response from a Go error, including the SQL
+// query in the error info when the error is a database SQLError.
+func newErrorResponseFromErr(id, code string, err error) *ResponseMessage {
+	resp := NewErrorResponse(id, code, err.Error())
+	var sqlErr *common.SQLError
+	if errors.As(err, &sqlErr) {
+		resp.Error.SQL = sqlErr.SQL
+	}
+	return resp
+}
+
 // Handler handles WebSocket connections and messages
 type Handler struct {
 	db                  common.Database
@@ -236,7 +248,7 @@ func (h *Handler) handleRead(conn *Connection, msg *Message, hookCtx *HookContex
 
 	if err != nil {
 		logger.Error("[WebSocketSpec] Read operation failed: %v", err)
-		errResp := NewErrorResponse(msg.ID, "read_error", err.Error())
+		errResp := newErrorResponseFromErr(msg.ID, "read_error", err)
 		_ = conn.SendJSON(errResp)
 		return
 	}
@@ -272,7 +284,7 @@ func (h *Handler) handleCreate(conn *Connection, msg *Message, hookCtx *HookCont
 	data, err := h.create(hookCtx)
 	if err != nil {
 		logger.Error("[WebSocketSpec] Create operation failed: %v", err)
-		errResp := NewErrorResponse(msg.ID, "create_error", err.Error())
+		errResp := newErrorResponseFromErr(msg.ID, "create_error", err)
 		_ = conn.SendJSON(errResp)
 		return
 	}
@@ -310,7 +322,7 @@ func (h *Handler) handleUpdate(conn *Connection, msg *Message, hookCtx *HookCont
 	data, err := h.update(hookCtx)
 	if err != nil {
 		logger.Error("[WebSocketSpec] Update operation failed: %v", err)
-		errResp := NewErrorResponse(msg.ID, "update_error", err.Error())
+		errResp := newErrorResponseFromErr(msg.ID, "update_error", err)
 		_ = conn.SendJSON(errResp)
 		return
 	}
@@ -348,7 +360,7 @@ func (h *Handler) handleDelete(conn *Connection, msg *Message, hookCtx *HookCont
 	err := h.delete(hookCtx)
 	if err != nil {
 		logger.Error("[WebSocketSpec] Delete operation failed: %v", err)
-		errResp := NewErrorResponse(msg.ID, "delete_error", err.Error())
+		errResp := newErrorResponseFromErr(msg.ID, "delete_error", err)
 		_ = conn.SendJSON(errResp)
 		return
 	}

pkg/websocketspec/message.go

@@ -99,6 +99,9 @@ type ErrorInfo struct {
 
 	// Details contains additional error context
 	Details map[string]interface{} `json:"details,omitempty"`
+
+	// SQL is the query that caused the error, populated for database errors
+	SQL string `json:"sql,omitempty"`
 }
 
 // RequestMessage represents a client request