firebird-mirror/doc/sql.extensions/README.update_or_insert

-----------------
UPDATE OR INSERT statement
-----------------

  Function:
    Allow to update or insert a record based on the existence or not of it.

  Author:
    Adriano dos Santos Fernandes <adrianosf@uol.com.br>

  Syntax rules:
    UPDATE OR INSERT INTO <table or view> [(<column_list>)]
        VALUES (<value_list>)
        [MATCHING <column_list>]
        [RETURNING <column_list> [INTO <variable_list>]]

  Scope:
    DSQL, PSQL

  Examples:
    1. UPDATE OR INSERT INTO T1 (F1, F2) VALUES (:F1, :F2);
    2. UPDATE OR INSERT INTO EMPLOYEE (ID, NAME) VALUES (:ID, :NAME) RETURNING ID;
    3. UPDATE OR INSERT INTO T1 (F1, F2) VALUES (:F1, :F2) MATCHING (F1);
    4. UPDATE OR INSERT INTO EMPLOYEE (ID, NAME) VALUES (:ID, :NAME) RETURNING OLD.NAME;

  Notes:
    1. When MATCHING is omitted, the existence of a primary key is required.
    2. INSERT and UPDATE permissions are needed on <table or view>.
    3. If the RETURNING clause is present, then the statement is described as
       isc_info_sql_stmt_exec_procedure by the API. Otherwise it is described
       as isc_info_sql_stmt_insert.

  Limitation:
    1. A singleton error will be raised if the RETURNING clause is present and more than
       one record match the condition.