begriffs open source - ai-pg/blob - full-docs/txt/contrib-dblink-build-sql-update.txt

   1
   2 dblink_build_sql_update
   3
   4    dblink_build_sql_update — builds an UPDATE statement using a local
   5    tuple, replacing the primary key field values with alternative supplied
   6    values
   7
   8 Synopsis
   9
  10 dblink_build_sql_update(text relname,
  11                         int2vector primary_key_attnums,
  12                         integer num_primary_key_atts,
  13                         text[] src_pk_att_vals_array,
  14                         text[] tgt_pk_att_vals_array) returns text
  15
  16 Description
  17
  18    dblink_build_sql_update can be useful in doing selective replication of
  19    a local table to a remote database. It selects a row from the local
  20    table based on primary key, and then builds an SQL UPDATE command that
  21    will duplicate that row, but with the primary key values replaced by
  22    the values in the last argument. (To make an exact copy of the row,
  23    just specify the same values for the last two arguments.) The UPDATE
  24    command always assigns all fields of the row — the main difference
  25    between this and dblink_build_sql_insert is that it's assumed that the
  26    target row already exists in the remote table.
  27
  28 Arguments
  29
  30    relname
  31           Name of a local relation, for example foo or myschema.mytab.
  32           Include double quotes if the name is mixed-case or contains
  33           special characters, for example "FooBar"; without quotes, the
  34           string will be folded to lower case.
  35
  36    primary_key_attnums
  37           Attribute numbers (1-based) of the primary key fields, for
  38           example 1 2.
  39
  40    num_primary_key_atts
  41           The number of primary key fields.
  42
  43    src_pk_att_vals_array
  44           Values of the primary key fields to be used to look up the local
  45           tuple. Each field is represented in text form. An error is
  46           thrown if there is no local row with these primary key values.
  47
  48    tgt_pk_att_vals_array
  49           Values of the primary key fields to be placed in the resulting
  50           UPDATE command. Each field is represented in text form.
  51
  52 Return Value
  53
  54    Returns the requested SQL statement as text.
  55
  56 Notes
  57
  58    As of PostgreSQL 9.0, the attribute numbers in primary_key_attnums are
  59    interpreted as logical column numbers, corresponding to the column's
  60    position in SELECT * FROM relname. Previous versions interpreted the
  61    numbers as physical column positions. There is a difference if any
  62    column(s) to the left of the indicated column have been dropped during
  63    the lifetime of the table.
  64
  65 Examples
  66
  67 SELECT dblink_build_sql_update('foo', '1 2', 2, '{"1", "a"}', '{"1", "b"}');
  68                    dblink_build_sql_update
  69 -------------------------------------------------------------
  70  UPDATE foo SET f1='1',f2='b',f3='1' WHERE f1='1' AND f2='b'
  71 (1 row)