SQL update operation

Last modified 14 Sep 2026 07:59 UTC
Since 4.11
This functionality is available since version 4.11.
Table of Contents

Update operations apply ConnId deltas to the existing row with a single transactional SQL UPDATE.

This article is part of the SQL connector development reference and guidance materials. See How to develop connectors using the SQL framework for the section introduction.

Basic update

For a writable table, update works out of the box — no operation script is required.

The framework:

  1. Loads the current row using the full UID mapping.

  2. Applies each AttributeDelta (replace, add, and remove forms) on top of the current values.

  3. Writes the resulting column values in one UPDATE statement, using the UID mapping as the exact predicate.

  4. Verifies that exactly one row was affected. The predicate is the full UID (primary key), so at most one row can match — the zero-row case fails with UnknownUidException, and a defensive check raises ConnectorException if the affected count is anything other than zero or one.

If the delta contains no attributes that map to writable SQL columns, the update is a no-op. Connection failures are wrapped into ConnectionFailedException; failed transactions are rolled back.

If the object class has related-table attributes (see Multitable support: child tables and junction tables), update deltas for those attributes are handled in the same transaction:

  • add — inserts the new child-table rows

  • replace — replaces the existing child rows (physically delete + insert), preserving columns the connector does not manage

  • remove — deletes the matching child-table rows

A delta that would change the parent join column of an embedded value is rejected with ConnectorException. See Writing to child and junction tables for the full semantics.

Not-updatable attributes

The following attribute kinds cannot appear in an update delta. The update operation fails with InvalidAttributeValueException if they do:

  • UID columns (primary key mapping)

  • Auto-increment / identity columns

  • Attributes marked read-only by the built-in mapping rules

Attributes whose columns are not writable by the database (for example, view-backed columns) are not part of any object class update in the first place.

Errors

Condition Exception

No row matches the UID

UnknownUidException

Invalid value or constraint violation (not-null, foreign key, check)

InvalidAttributeValueException

Connection failure

ConnectionFailedException

Exactly-one-row check failed

ConnectorException

A delta would change the parent join column of an embedded value

ConnectorException

Updates run in a transaction that is rolled back before the exception is returned. Unlike some REST/SCIM connectors, the SQL framework has a single update mode (partial delta) — there is no separate PUT/patch mode to configure.

Enabling / disabling update

objectClass("Employee") {
  update {
    enabled false
  }
}

The declaration mirrors disabling delete — the same enabled false operation block, under update instead of delete.

Unlike object-class-level readOnly true (which disables create, update and delete at once and is applied automatically to views), this disables only the update handler: the object class stays creatable and deletable. That is the right choice for immutable-but-deletable object classes — records that must not change once created but can still be removed — or when updates are intentionally routed elsewhere while create and delete remain available.

The same in YAML:

objectClasses:
  Employee:
    update:
      enabled: false

Object classes marked readOnly true, and views, never get an update handler. See also built-in mapping rules.

Was this page helpful?
YES NO
Thanks for your feedback