SQL create operation

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

Create operations use a transactional SQL INSERT with generated-key handling and row read-back.

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 create

For a writable table, create works out of the box — no operation script is required. Keep the manifest’s operation list empty and define an SQL-backed __UID__ mapping (see SQL schema discovery and SQL schema customization).

The framework:

  1. Translates each creatable attribute value through its SQL value mapping

  2. Omits absent columns so database defaults apply

  3. Executes the INSERT inside a JDBC transaction

  4. Obtains the generated key for identity/auto-increment primary keys

  5. Reads the created row back within the same transaction and returns it as the created object

  6. If the object class has related-table attributes (see Multitable support: child tables and junction tables), the framework inserts the child-table rows for each embedded or multi-valued value, still within the same transaction (see Writing to child and junction tables)

UID handling

ConnId does not allow __UID__ in create requests, so the framework derives the key to insert from your configuration:

Primary key kind Behavior

Auto-increment / identity

The UID column is omitted from the INSERT; the generated key is fetched from the database and used as the object UID.

Explicit value in __NAME__

If __NAME__ is mapped to the same columns as the UID and the UID attribute is creatable, the __NAME__ value is used as the UID value on insert (natural key).

Natural / composite key without __NAME__

The connector auto-emulates __NAME__ from the UID mapping; provide the key in __NAME__.

Composite key

Provide the key parts joined with a . separator (e.g. tenant-1.account-42); the connector splits the value and populates each primary key column. For a composite key where one part is auto-generated, the generated part is combined with the supplied parts.

If the UID attribute is creatable and an explicit __UID__ value is nevertheless supplied, it is inserted directly and must result in exactly one affected row.

Providing a value for a non-creatable attribute (primary key or auto-increment column) fails with InvalidAttributeValueException.

Errors

All create operations run in a transaction that is rolled back on failure; SQL errors are translated to ConnId exceptions:

Condition Exception

Duplicate key / unique violation

AlreadyExistsException

Invalid value, not-null, foreign key, check constraint or type-conversion failure

InvalidAttributeValueException

Connection failure

ConnectionFailedException

Inserted row could not be read back

ConnectorException

Exactly-one-row check failed (an explicit UID value was supplied)

ConnectorException

Enabling / disabling create

For read-write tables create is enabled by default. Restrict it per object class in an operation handler script:

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

The same in YAML:

objectClasses:
  Employee:
    create:
      enabled: false

Object classes marked readOnly true, and views, never get a create handler. See Custom connector classes and bundles for registering fully custom create operations.

Was this page helpful?
YES NO
Thanks for your feedback