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 (checked with IS NOT DISTINCT) or not of it.

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

  Syntax rules:
    UPDATE OR INSERT INTO <table or view> [(<column_list>)]
        VALUES (<value_list>)
        [MATCHING (<column_list>)]
        [<plan clause>]
        [<order by clause>]
        [<rows clause>]
        [RETURNING <value_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_select by the API. Otherwise it is described
       as isc_info_sql_stmt_insert.

  Limitation:
    1. There is no "UPDATE OR INSERT ... SELECT ..." as "INSERT ... SELECT". Use MERGE for
       this type of functionality.