ebuilder-sql-mutation

name

ebuilder-sql-mutation

description

Generation playbook for mutation-* envelopes in configs/sql.*.yml. USE FOR: define mutation-level structure, inputParams, datasource and authorize, transaction isolation, response and callbacks, and orchestration strategy across steps. DO NOT USE FOR: step-level SQL step authoring details (use ebuilder-sql-step), query authoring (use ebuilder-sql-query), or symbol catalog (use ebuilder-eb-sql-symbols).

eBuilder Mutation Envelope Generation Playbook

Purpose

Use this skill when generating or reviewing mutation-* definitions in configs/sql.*.yml at the mutation level.

This skill governs:

• mutation envelope shape
• input contracts
• datasource and authorization
• transaction policy
• response and callback behavior
• orchestration intent for steps

For detailed authoring of each step inside steps, use ebuilder-sql-step.

Scope

• File target: configs/sql.*.yml
• Root key: mutation (not query)
• Mutation names match: mutation-[a-zA-Z0-9-]+
• Mutations are data-modifying operations with one or more orchestrated steps

Generation Order

1. Set root key mutation.
2. Define stable mutation name: mutation-<action>-<entity>.
3. Define inputParams with type and validation rules.
4. Configure datasource and authorize.
5. Set transactionIsolationLevel.
6. Design ordered steps chain (delegate step internals to ebuilder-sql-step).
7. Define response (statusCode, optional message, body).
8. Add catchErrors and on.success / on.error when needed.
9. Validate cross-references (queries/tasks/mutations/policies).

Mutation Blueprint

mutation:
  mutation-update-item:
    datasource: main
    authorize:
      policy: eClient

    inputParams:
      itemId:
        type: int
        rules:
          - required: true
      title:
        type: string
        rules:
          - required: true

    transactionIsolationLevel: read-committed

    steps:
      - key: validateItem
        query: query-item-exists
        queryParams:
          inputParams:
            itemId: ${itemId}
      - key: updateItem
        command: |
          UPDATE ec_item
          SET title = ${title}, updated_at = $EB_DATETIME_NOW
          WHERE id_item = ${itemId}
      - key: result
        command: |
          SELECT id_item AS "itemId", title, updated_at AS "updatedAt"
          FROM ec_item
          WHERE id_item = ${itemId}
        save: first-row-as-object

    response:
      statusCode: 200
      body:
        item: ${result}

Mutation Object Properties

Property	Type	Required	Notes
inputParams	object	No	Request input schema.
datasource	string	No	Target datasource key.
authorize	object or array	No	Policy/role based access control.
transactionIsolationLevel	enum or engine object	No	default, read-committed, repeatable-read, serializable.
steps	array of sqlStep	No	Ordered execution chain. Use ebuilder-sql-step for internals.
command	string or engine object	No	Direct single-command mutation path.
response	object	No	Custom output contract.
placeholders	object	No	Named SQL fragments for $EB_PLACEHOLDER(...).
checksBefore	array	No	Global pre-mutation guards.
checksAfter	array	No	Global post-mutation guards.
catchErrors	object	No	Error-code mapping at mutation level.
on	object	No	success and error callback hooks.

Input Rule Notes

• Use rules on a parameter for top-level constraints such as required, nullable, min, and max.
• For primitive arrays, put item-level constraints under items.rules.
• Typical item-level constraints are allowEmpty, min, and max.

Transaction Isolation Levels

Level	PostgreSQL	Oracle	MSSQL	MySQL	Use Case
default	READ COMMITTED	SERIALIZABLE	READ COMMITTED	REPEATABLE READ	Engine default behavior
read-committed	READ COMMITTED	READ COMMITTED	READ COMMITTED	READ COMMITTED	Typical business mutations
repeatable-read	REPEATABLE READ	SERIALIZABLE	REPEATABLE READ	REPEATABLE READ	Stronger read stability
serializable	SERIALIZABLE	SERIALIZABLE	SERIALIZABLE	SERIALIZABLE	Maximum consistency

Response and Callback Patterns

Custom response

response:
  statusCode: 201
  message: Item created successfully
  body:
    itemId: ${createItem}

Mutation callbacks

on:
  success:
    - task: task-log-activity
      params:
        action: item_created
  error:
    - task: task-alert-admin
      params:
        errorCode: ${errorCode}

Deterministic Checklist (Mutation Level)

1. Mutation name matches ^mutation-[a-zA-Z0-9-]+$.
2. datasource exists in configs/app.yml.
3. authorize policy/roles exist and are valid.
4. inputParams types and validation rules are explicit.
5. transactionIsolationLevel is valid.
6. Step keys are unique and step references are consistent.
7. Response contract is explicit (statusCode, body shape).
8. Referenced query/task/mutation names exist.
9. Use parameter binding for all user inputs.
10. Avoid deprecated keys (param, op, value, throw, silentThrow).

Skill Boundaries

• Use ebuilder-sql-step for step-level authoring (save, guards, step-level catchErrors, jsExpression, subSteps).
• Use ebuilder-sql-query for query-* roots.
• Use ebuilder-eb-sql-symbols for $EB_* portability guidance.

Do Not Generate

• Query root definitions in this skill output.
• Step-internal deep guidance duplicated from ebuilder-sql-step.
• Unknown top-level keys outside mutation.
• Raw SQL interpolation from unsanitized input.