dblink扩展（跨库查询）

dblink¶

dblink模块支持从数据库会话中连接到其他SeaboxMPP/SeaboxSQL数据库。这些数据库可以驻留在相同的SeaboxMPP数据库系统中，也可以驻留在远程系统中。

可以使用dblink连接到使用兼容libpq库的其他PostgreSQL生态数据库。

注意:

dblink适用于数据库用户在其他数据库中执行简短的临时查询。dblink不能替代外部表或copy之类的数据导入导出机制。
SeaboxMPP数据库dblink模块是PostgreSQL dblink模块的修改版本。在SeaboxMPP数据库中使用该模块时，存在一些限制。
在使用模块中定义的任何函数之前，必须在要使用这些函数的每个数据库中注册dblink扩展。
在SeaboxMPP/SeaboxSQL数据库中，修改表数据的语句不能使用命名或隐式dblink连接。而必须直接在dblink()函数中提供连接字符串。例如：

seabox=# CREATE TABLE testdbllocal (a int, b text) DISTRIBUTED BY (a);
CREATE TABLE
seabox=# INSERT INTO testdbllocal select * FROM dblink('dbname=seaboxsql', 'SELECT * FROM testdblink') AS dbltab(id int, product text);
INSERT 0 2

SeaboxMPP数据库中dblink禁用以下异步函数：
dblink_send_query()
dblink_is_busy()
dblink_get_result()

dblink函数¶

`dblink_connect()`¶

语法

sql
dblink_connect(text connstr) 返回 text
dblink_connect(text connname, text connstr) 返回 text

返回值

text

描述

dblink_connect()建立一个到远端SeaboxSQL数据库的连接。远端服务和源端数据库通过一个标准的libpq连接串来标识。可以选择将给该连接赋予一个名字。允许一次打开多个命名连接，但是一次只允许一个未命名连接。连接将会持续直到被关闭或者数据库会话结束。

连接串也可以是一个现存外部服务器的名字。在使用外部服务器时，推荐使用外部数据包装器dblink_fdw。

参数说明

dblink_connect()函数相关参数说明见下。

connname: 用于连接的名字。如果被忽略，将打开一个未命名连接并且替换掉任何现有的未命名连接。
connstr: libpq-风格的连接信息串，例如 hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres password=mypasswd。此外，还可以是一个外部服务器的名字。

示例

以下是SeaboxSQL/SeaboxMPP数据库中通过dblink_connect()连接的示例。

-- 验证未命名连接，到本地数据库
seaboxsql=# SELECT dblink_connect('host=mpp1 port=3000 dbname=seaboxsql connect_timeout=10');
 dblink_connect
----------------
 OK
(1 row)

以下是通过外部表连接器连接的方式，在SeaboxMPP数据库中使用dblink_connect()的例子，在SeaboxSQL中使用时，用户认证方面的操作方式不同，其他一致

创建用户，分配权限，创建外部表连接器

seaboxsql=# CREATE SERVER fdtest FOREIGN DATA WRAPPER dblink_fdw OPTIONS (hostaddr '10.1.2.27', port '3000',dbname 'seaboxsql');
CREATE SERVER
seaboxsql=# CREATE USER regress_dblink_user WITH PASSWORD 'secret';
NOTICE:  resource group required -- using default resource group "default_group"
CREATE ROLE
seaboxsql=# CREATE USER MAPPING FOR regress_dblink_user SERVER fdtest OPTIONS (user 'regress_dblink_user', password 'secret');
CREATE USER MAPPING
seaboxsql=# GRANT USAGE ON FOREIGN SERVER fdtest TO regress_dblink_user;
GRANT
seaboxsql=# GRANT SELECT ON TABLE users TO regress_dblink_user;
GRANT
seaboxsql=# GRANT CONNECT ON DATABASE seaboxsql TO regress_dblink_user;
GRANT

SeaboxMPP调用管理命令添加认证

[seabox@mpp1 ~]$ seabox hbaconf --add -u regress_dblink_user -d seaboxsql -i 0.0.0.0/0
2023-03-07 10:52:24 CST [5374] seabox_hbaconf mpp1:seabox INFO: add 'host seaboxsql regress_dblink_user 0.0.0.0/0 md5' on host mpp1 for coordinator dbid 1
2023-03-07 10:52:24 CST [5374] seabox_hbaconf mpp1:seabox INFO: add 'host seaboxsql regress_dblink_user 0.0.0.0/0 md5' on host mpp2 for coordinator dbid 2
2023-03-07 10:52:25 CST [5374] seabox_hbaconf mpp1:seabox INFO: add 'host seaboxsql regress_dblink_user 0.0.0.0/0 md5' on host mpp3 for coordinator dbid 3

连接数据库，用指定用户连接dblink

seaboxsql=# \set ORIGINAL_USER :USER
seaboxsql=# \c - regress_dblink_user
You are now connected to database "seaboxsql" as user "regress_dblink_user".
seaboxsql=> SELECT dblink_connect('myconn', 'fdtest');
 dblink_connect
----------------
 OK
(1 row)

seaboxsql=> SELECT * FROM dblink('myconn','SELECT id,username FROM users') as t(a int,b text);
 a |  b
---+------
 4 | anne
 2 | anne
 6 | anne
 3 | tony
 1 | tony
 5 | tony
(6 rows)

`dblink_connect_u()`¶

语法: sql dblink_connect_u(text connstr) 返回 text dblink_connect_u(text connname, text connstr) 返回 text
返回值: text
描述: dblink_connect_u — 不安全地打开一个到远程数据库的持久连接。
参数说明: 同dblink_connect()函数相关参数。
示例: 无。

`dblink_disconnect()`¶

语法

sql
dblink_disconnect() 返回 text
dblink_disconnect(text connname) 返回 text

返回值

text

描述

dblink_disconnect() 关闭一个之前被dblink_connect()打开的连接。不带参数的形式关闭一个未命名连接。

参数说明

dblink_disconnect()函数相关参数说明见下。

connname: 要被关闭的命名连接的名字。

示例

``` sql seaboxsql=> SELECT dblink_disconnect('myconn'); dblink_disconnect

OK (1 row)

seaboxsql=# SELECT dblink_connect('host=mpp1 port=3000 dbname=seaboxsql connect_timeout=10'); dblink_connect

OK (1 row)

seaboxsql=# SELECT dblink_disconnect(); dblink_disconnect

OK (1 row) ```

`dblink()`¶

语法

sql
dblink(text connname, text sql [, bool fail_on_error]) 返回记录集
dblink(text connstr, text sql [, bool fail_on_error]) 返回记录集
dblink(text sql [, bool fail_on_error]) 返回记录集

返回值

set of record

描述

dblink() 函数在远端数据库中执行一个查询（通常是一个SELECT，但是也可以是任意返回行的 SQL 语句）。

当给定两个text参数时，第一个被首先作为一个持久连接的名称进行查找；如果找到，该命令会在该连接上被执行。如果没有找到，第一个参数被视作一个用于dblink_connect的连接信息字符串，并且被指出的连接只是在这个命令的持续期间被建立。

因为dblink能与任何查询一起使用，它被声明为返回record，而不是指定任意特定的列集合。这意味着必须指定在调用的查询中所期待的列集合, 否则数据库将不知道会得到什么。

参数说明

dblink()函数相关参数说明见下。

connname: 要使用的连接名。忽略这个参数将使用未命名连接。
connstr: 如之前为dblink_connect所描述的一个连接信息字符串。
sql: 在远程数据库中执行的 SQL 查询，例如select * from foo。
fail_on_error: 如果为真（忽略时的默认值），那么在连接的远端抛出的一个错误也会导致本地抛出一个错误。如果为假，远程错误只在本地被报告为一个 NOTICE，并且该函数不反回行。

示例

可将使用dblink的预定义查询创建为一个视图。此时，允许列类型信息被埋藏在该视图中，而不是在每一个查询中都拼写出来。例如：

``` sql
seaboxsql=# create view myremote_pg_proc as  SELECT *
FROM dblink('dbname=seaboxsql host=mpp1 port=3000',
            'select proname, prosrc from pg_proc')
  AS t1(proname name, prosrc text)
WHERE proname LIKE 'bytea%';
CREATE VIEW
seaboxsql=# select * from myremote_pg_proc;
         proname          |          prosrc
--------------------------+--------------------------
 byteain                  | byteain
 byteaout                 | byteaout
 bytea_string_agg_transfn | bytea_string_agg_transfn
 bytea_string_agg_finalfn | bytea_string_agg_finalfn
 byteaeq                  | byteaeq
 bytealt                  | bytealt
 byteale                  | byteale
 byteagt                  | byteagt
 byteage                  | byteage
 byteane                  | byteane
 byteacmp                 | byteacmp
 bytea_sortsupport        | bytea_sortsupport
 bytealike                | bytealike
 byteanlike               | byteanlike
 byteacat                 | byteacat
 bytearecv                | bytearecv
 byteasend                | byteasend
 bytea8in                 | byteain
 bytea8out                | byteaout
 bytea8recv               | bytearecv
 bytea8send               | byteasend
(21 rows)

以下是使用未命名dblink和命名dblink使用dblink()函数查询的示例：

seaboxsql=# SELECT dblink_connect('dbname=seaboxsql host=mpp1 port=3000');
 dblink_connect
----------------
 OK
(1 row)

seaboxsql=# SELECT * FROM dblink('select proname, prosrc from pg_proc')
seaboxsql-#   AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%';
         proname          |          prosrc
--------------------------+--------------------------
 byteain                  | byteain
 byteaout                 | byteaout
 bytea_string_agg_transfn | bytea_string_agg_transfn
 bytea_string_agg_finalfn | bytea_string_agg_finalfn
 byteaeq                  | byteaeq
 bytealt                  | bytealt
 byteale                  | byteale
 byteagt                  | byteagt
 byteage                  | byteage
 byteane                  | byteane
 byteacmp                 | byteacmp
 bytea_sortsupport        | bytea_sortsupport
 bytealike                | bytealike
 byteanlike               | byteanlike
 byteacat                 | byteacat
 bytearecv                | bytearecv
 byteasend                | byteasend
 bytea8in                 | byteain
 bytea8out                | byteaout
 bytea8recv               | bytearecv
 bytea8send               | byteasend
(21 rows)

seaboxsql=# SELECT dblink_connect('myconn', 'dbname=seaboxsql host=mpp1     port=3000');
 dblink_connect
----------------
 OK
(1 row)

seaboxsql=# SELECT * FROM dblink('myconn', 'select proname, prosrc from pg_proc')
seaboxsql-#   AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%';
         proname          |          prosrc
--------------------------+--------------------------
 byteain                  | byteain
 byteaout                 | byteaout
 bytea_string_agg_transfn | bytea_string_agg_transfn
 bytea_string_agg_finalfn | bytea_string_agg_finalfn
 byteaeq                  | byteaeq
 bytealt                  | bytealt
 byteale                  | byteale
 byteagt                  | byteagt
 byteage                  | byteage
 byteane                  | byteane
 byteacmp                 | byteacmp
 bytea_sortsupport        | bytea_sortsupport
 bytealike                | bytealike
 byteanlike               | byteanlike
 byteacat                 | byteacat
 bytearecv                | bytearecv
 byteasend                | byteasend
 bytea8in                 | byteain
 bytea8out                | byteaout
 bytea8recv               | bytearecv
 bytea8send               | byteasend
(21 rows)

`dblink_exec()`¶

语法

sql
dblink_exec(text connname, text sql [, bool fail_on_error]) returns text
dblink_exec(text connstr, text sql [, bool fail_on_error]) returns text
dblink_exec(text sql [, bool fail_on_error]) returns text

返回值

text,返回状态，可能是命令的状态字符串或ERROR。

描述

dblink_exec() 函数支持在一个远程数据库中执行一个命令（也就是，任何不返回行的 SQL 语句）

当给定两个text参数时，第一个被首先作为一个持久连接的名称进行查找；如果找到，该命令会在该连接上被执行。如果没有找到，第一个参数被视作一个用于dblink_connect的连接信息字符串，并且被指出的连接只是在这个命令的持续期间被建立。

参数说明

dblink_exec()函数相关参数说明见下。

connname: 要使用的连接名。忽略这个参数将使用未命名连接。
connstr: 如之前为dblink_connect所描述的一个连接信息字符串。
sql: 在远程数据库中执行的 SQL 命令，例如insert into foo values(0,'a','{"a0","b0","c0"}')。
fail_on_error: 如果为真（忽略时的默认值），那么在连接的远端抛出的一个错误也会导致本地抛出一个错误。如果为假，远程错误只在本地被报告为一个 NOTICE，并且该函数的返回值被设置为ERROR。

示例

``` sql seaboxsql=# SELECT dblink_connect('host=mpp1 port=3000 dbname=seaboxsql connect_timeout=10'); dblink_connect

OK (1 row)

seaboxsql=# SELECT dblink_exec('insert into users(id,username,password) values(12,''test'',''abc'');'); dblink_exec

INSERT 0 1 (1 row) seaboxsql=# SELECT dblink_exec('myconn', 'insert into pg_class values (''foo'')',false); NOTICE: invalid input syntax for type oid: "foo" dblink_exec

ERROR (1 row) ```

`dblink_open()`¶

语法

sql
dblink_open(text cursorname, text sql [, bool fail_on_error]) 返回 text
dblink_open(text connname, text cursorname, text sql [, bool fail_on_error]) 返回 text

返回值

text,返回状态，OK或者ERROR。

描述

dblink_open() 函数在远程数据库中打开一个游标。该游标能够随后使用dblink_fetch()和dblink_close()进行操纵。

参数说明

dblink_open()函数相关参数说明见下。

connname: 要使用的连接名。忽略这个参数将使用未命名连接。
cursorname: 要赋予给这个游标的名称。
sql: 在远程数据库中执行的SELECT语句，例如select * from pg_class。
fail_on_error: 如果为真（忽略时的默认值），那么在连接的远端抛出的一个错误也会导致本地抛出一个错误。如果为假，远程错误只在本地被报告为一个 NOTICE，并且该函数的返回值被设置为ERROR。

注解

因为游标只能在一个事务中持续，如果远端还没在事务中，dblink_open会在远端开始一个显式事务块（BEGIN）。当匹配的dblink_close被执行时，这个事务将再次被关闭。注意如果使用dblink_exec在dblink_open和dblink_close之间改变数据，并且接着发生了一个错误或者在dblink_close之前使用了dblink_disconnect，更改将被丢失，因为事务将被中止。

示例

``` sql seaboxsql=# SELECT dblink_connect('host=mpp1 port=3000 dbname=seaboxsql connect_timeout=10'); dblink_connect

OK (1 row)

seaboxsql=# SELECT dblink_open('foo', 'select proname, prosrc from pg_proc'); dblink_open

OK (1 row)

```

`dblink_fetch()`¶

语法: ``` sql dblink_fetch(text cursorname, int howmany [, bool fail_on_error]) 返回 record 集合

dblink_fetch(text connname, text cursorname, int howmany [, bool fail_on_error]) 返回 record 集合 ```

返回值

set of record,该函数返回从游标中取出的行。要使用该函数，需要指定想要的列集合，如dblink()函数。

描述

dblink_fetch() 函数从一个由dblink_open建立的游标中取得行。。

参数说明

dblink_fetch()函数相关参数说明见下。

connname: 要使用的连接名。忽略这个参数将使用未命名连接。
cursorname: 要从中取数据的游标名。
howmany: 要检索的最大行数。从当前游标位置向前的接下来howmany个行会被取出。一旦该游标已经到达了它的末端，将不会产生更多行。
fail_on_error: 如果为真（忽略时的默认值），那么在连接的远端抛出的一个错误也会导致本地抛出一个错误。如果为假，远程错误只在本地被报告为一个 NOTICE，并且该函数不反回行。

注解

当FROM子句中指定的返回列的数量和远程游标返回的实际列数不匹配时，将抛出一个错误。在这个事件中，远程游标仍会被前进错误没发生时应该前进的行数。对于远程FETCH完成之后在本地查询中发生的任何其他错误，情况也是一样。

示例

``` sql seaboxsql=# SELECT dblink_connect('host=mpp1 port=3000 dbname=seaboxsql connect_timeout=10'); dblink_connect

OK (1 row)

seaboxsql=# SELECT dblink_open('foo', 'select proname, prosrc from pg_proc where proname like ''bytea%'''); dblink_open

OK (1 row)

seaboxsql=# SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text); funcname | source --------------------------+-------------------------- bytea_string_agg_finalfn | bytea_string_agg_finalfn bytea_string_agg_transfn | bytea_string_agg_transfn byteacat | byteacat byteacmp | byteacmp byteaeq | byteaeq (5 rows)

seaboxsql=# SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text); funcname | source -----------+----------- byteasend | byteasend (1 row)

seaboxsql=# SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text); funcname | source ----------+-------- (0 rows)

```

`dblink_close()`¶

语法

sql
dblink_close(text cursorname [, bool fail_on_error]) 返回 text
dblink_close(text connname, text cursorname [, bool fail_on_error]) 返回 text

返回值

text,返回状态，OK或者ERROR。

描述

dblink_close() 函数关闭由dblink_open打开的游标。

参数说明

dblink_close()函数相关参数说明见下。

connname: 要使用的连接名。忽略这个参数将使用未命名连接。
cursorname: 要关闭的游标名。
fail_on_error: 如果为真（忽略时的默认值），那么在连接的远端抛出的一个错误也会导致本地抛出一个错误。如果为假，远程错误只在本地被报告为一个 NOTICE，并且该函数的返回值被设置为ERROR。

注解

如果dblink_open开始了一个显式事务块，并且这是这个连接中最后一个保持打开的游标，dblink_close将发出匹配的COMMIT。

示例

``` sql seaboxsql=# SELECT dblink_connect('host=mpp1 port=3000 dbname=seaboxsql connect_timeout=10'); dblink_connect

OK (1 row)

seaboxsql=# SELECT dblink_open('foo', 'select proname, prosrc from pg_proc where proname like ''bytea%'''); dblink_open

OK (1 row)

seaboxsql=# SELECT dblink_close('foo'); dblink_close

OK (1 row)

```

`dblink_get_connections()`¶

语法

sql
dblink_get_connections() 返回 text[]

返回值

text[],返回一个连接名称的文本数组，如果没有则为 NULL。

描述

dblink_get_connections() 函数返回所有打开的命名 dblink 连接的名称。

示例

``` sql seaboxsql=# SELECT dblink_connect('host=mpp1 port=3000 dbname=seaboxsql connect_timeout=10'); dblink_connect

OK (1 row)

seaboxsql=# SELECT dblink_get_connections(); dblink_get_connections

(1 row)

seaboxsql=# SELECT dblink_connect('myconn','host=mpp1 port=3000 dbname=seaboxsql connect_timeout=10'); dblink_connect

OK (1 row)

seaboxsql=# SELECT dblink_get_connections(); dblink_get_connections

{myconn} (1 row)

```

`dblink_error_message()`¶

语法

sql
dblink_error_message(text connname) 返回 text

返回值

text,返回最后一个错误消息，如果在这个连接上没有错误则返回一个OK。

描述

dblink_error_message() 函数为一个给定连接取得最近的远程错误消息。当异步查询由dblink_send_query启动时，与连接相关的错误消息可能不会得到更新，直到服务器的响应消息被用掉。这通常意味着dblink_is_busy或dblink_get_result应在dblink_error_message之前被调用，以使得异步查询产生的任何错误都是可见的。

参数

dblink_error_message()函数相关参数说明见下。

connname: 要使用的连接名。

示例

``` sql seaboxsql=# SELECT dblink_error_message('myconn'); dblink_error_message

OK (1 row)

```

`dblink_cancel_query()`¶

语法

sql
dblink_cancel_query(text connname) 返回 text

返回值

text,如果取消请求已经被发送，则返回OK；如果失败，则返回一个错误消息的文本。

描述

dblink_cancel_query() 函数尝试命名连接上正在进行的任何查询。注意这不一定会成功（例如，远程查询可能已经结束）。一个取消请求仅仅提高了该查询将很快失败的几率。

参数

dblink_cancel_query()函数相关参数说明见下。

connname: 要使用的连接名。

示例

``` sql seaboxsql=# SELECT dblink_cancel_query('myconn'); dblink_cancel_query

OK (1 row)
```

`dblink_get_pkey()`¶

语法

sql
dblink_get_pkey(text relname) 返回 dblink_pkey_results 集合

返回值

set of record,为每一个主键域返回一行，如果该关系没有主键则不返回行。结果行类型被定义为：

CREATE TYPE dblink_pkey_results AS (position int, colname text);

position列值可以从 1 到 N，它是该域在主键中的编号，而不是在表列中的编号。

描述

dblink_get_pkey() 函数提供有关于本地数据库中一个关系的主键的信息。这有时候有助于生成要被发送到远程数据库的查询。。

参数

dblink_get_pkey()函数相关参数说明见下。

relname: 一个本地关系的名称，例如foo或者myschema.mytab。如果该名称是大小写混合的或包含特殊字符，要包括双引号，例如"FooBar"；如果没有引号，字符串将被折叠到小写形式。

示例

``` sql seaboxsql=# CREATE TABLE foobar ( seaboxsql(# f1 int, seaboxsql(# f2 int, seaboxsql(# f3 int, seaboxsql(# PRIMARY KEY (f1, f2, f3) seaboxsql(# ); CREATE TABLE

seaboxsql=# SELECT * FROM dblink_get_pkey('foobar'); position | colname ----------+--------- 1 | f1 2 | f2 3 | f3 (3 rows)

```

`dblink_build_sql_insert()`¶

语法

sql
dblink_build_sql_insert(text relname,
                    int2vector primary_key_attnums,
                    integer num_primary_key_atts,
                    text[] src_pk_att_vals_array,
                    text[] tgt_pk_att_vals_array) 返回 text

返回值

text,将要求的 SQL 语句返回为文本。

描述

dblink_build_sql_insert() 函数在选择性地将一个本地表复制到一个远程数据库时很有用。它基于主键从本地表选择一行，并且接着构建一个复制该行的INSERT命令，但是其中主键值被替换为最后一个参数中的值（要创建该行的一个准确拷贝，只要为最后两个参数指定相同的值）。

参数

dblink_build_sql_insert()函数相关参数说明见下。

relname: 一个本地关系的名称，例如foo或者myschema.mytab。如果该名称是大小写混合的或包含特殊字符，要包括双引号，例如"FooBar"；如果没有引号，字符串将被折叠到小写形式。
primary_key_attnums: 主键域的属性号（从 1 开始），例如1 2。
num_primary_key_atts: 主键域的数量。
src_pk_att_vals_array: 要被用来查找本地元组的主键域值。每一个域都被表示为文本形式。如果没有行具有这些主键值，则抛出一个错误。
tgt_pk_att_vals_array: 要被替换到结果INSERT命令中的主键域值。每一个域被表示为文本形式。

示例

``` sql seaboxsql=# SELECT dblink_build_sql_insert('foo', '1 2', 2, '{"1", "a"}', '{"1", "b''a"}'); dblink_build_sql_insert

INSERT INTO foo(f1,f2,f3) VALUES('1','b''a','1') (1 row) ```

`dblink_build_sql_delete()`¶

语法

sql
dblink_build_sql_delete(text relname,
                    int2vector primary_key_attnums,
                    integer num_primary_key_atts,
                    text[] tgt_pk_att_vals_array) 返回 text

返回值

text,将要求的 SQL 语句返回为文本。

描述

dblink_build_sql_delete() 函数使用所提供的主键域值构建一个 DELETE 语句。

参数

dblink_build_sql_delete()函数相关参数说明见下。

relname: 一个本地关系的名称，例如foo或者myschema.mytab。如果该名称是大小写混合的或包含特殊字符，要包括双引号，例如"FooBar"；如果没有引号，字符串将被折叠到小写形式。
primary_key_attnums: 主键域的属性号（从 1 开始），例如1 2。
num_primary_key_atts: 主键域的数量。
tgt_pk_att_vals_array: 要被替换到结果INSERT命令中的主键域值。每一个域被表示为文本形式。

示例

``` sql seaboxsql=# SELECT dblink_build_sql_delete('"MyFoo"', '1 2', 2, '{"1", "b"}'); dblink_build_sql_delete

DELETE FROM "MyFoo" WHERE f1='1' AND f2='b' (1 row)
```

`dblink_build_sql_update()`¶

语法

sql
dblink_build_sql_update(text relname,
                    int2vector primary_key_attnums,
                    integer num_primary_key_atts,
                    text[] src_pk_att_vals_array,
                    text[] tgt_pk_att_vals_array) 返回 text

返回值

text,将要求的 SQL 语句返回为文本。

描述

dblink_build_sql_update() 函数在选择性地将一个本地表复制到一个远程数据库时很有用。它从本地表基于主键选择一行，并且接着构建一个 SQL UPDATE命令来复制该行，但是其中的主键值被替换为最后一个参数中的值（要创建该行的一个准确拷贝，只要为最后两个参数指定相同的值）。UPDATE命令总是为该行的所有域赋值 — 这个函数与dblink_build_sql_insert之间的主要区别是它假定目标行已经存在于远程表中。

参数

dblink_build_sql_update()函数相关参数说明见下。

relname: 一个本地关系的名称，例如foo或者myschema.mytab。如果该名称是大小写混合的或包含特殊字符，要包括双引号，例如"FooBar"；如果没有引号，字符串将被折叠到小写形式。
primary_key_attnums: 主键域的属性号（从 1 开始），例如1 2。
num_primary_key_atts: 主键域的数量。
src_pk_att_vals_array: 要被用来查找本地元组的主键域值。每一个域都被表示为文本形式。如果没有行具有这些主键值，则抛出一个错误。
tgt_pk_att_vals_array: 要被替换到结果INSERT命令中的主键域值。每一个域被表示为文本形式。

示例

``` sql seaboxsql=# SELECT dblink_build_sql_update('foo', '1 2', 2, '{"1", "a"}', '{"1", "b"}'); dblink_build_sql_update

UPDATE foo SET f1='1',f2='b',f3='1' WHERE f1='1' AND f2='b' (1 row)
```

使用dblink实例¶

以下过程是SeaboxMPP数据库中配置和使用dblink的基本步骤。

这些示例使用dblink_connect()创建与数据库的连接，并使用dblink()执行SQL查询。

首先创建一个示例表以使用dblink函数进行查询。这些命令在seaboxsql数据库中创建一个小表，稍后您将使用dblink从testdb数据库中查询该表：

$ ssql -d seaboxsql
ssql (9.4.20)
Type "help" for help.

seaboxsql=# CREATE TABLE testdblink (a int, b text) DISTRIBUTED BY (a);
CREATE TABLE
seaboxsql=# INSERT INTO testdblink VALUES (1, 'Cheese'), (2, 'Fish');
INSERT 0 2
seaboxsql=# \q
$

以超级用户身份登录到另一个数据库。在此示例中，超级用户seabox登录到数据库testdb。

如果dblink函数尚不可用，请在数据库中注册dblink扩展：
```
$ ssql -d testdb
ssql (9.4beta1)
Type "help" for help.

testdb=# CREATE EXTENSION dblink;
CREATE EXTENSION
```
使用dblink_connect()函数创建与另一个数据库的隐式或命名连接。

提供的连接字符串应该是libpq样式的关键字/值字符串。

本示例创建一个名为mylocalconn的连接到本地SeaboxMPP数据库系统上的seaboxsql数据库：
```
testdb=# SELECT dblink_connect('mylocalconn', 'dbname=seaboxsql user=seabox');
 dblink_connect
----------------
 OK
(1 row)
```
- 注意: 如果未指定user，则在启动SeaboxMPP数据库时，dblink_connect()将使用SDUSER环境变量的值。如果未设置SDUSER，则默认值为启动SeaboxMPP数据库的系统用户。
使用dblink()函数可使用已配置的连接查询数据库。

注意，此函数返回记录类型，因此必须分配dblink()查询中返回的列。

例如，以下命令使用命名连接来查询先前创建的表：
```
testdb=# SELECT * FROM dblink('mylocalconn', 'SELECT * FROM testdblink') AS dbltab(id int, product text);
 id | product
----+---------
  1 | Cheese
  2 | Fish
(2 rows)
```

要以另一个用户身份连接到本地数据库，请在连接字符串中指定该用户。本示例以用户test_user的身份连接到数据库。使用dblink_connect()，超级用户无需指定密码即可创建与另一个本地数据库的连接。

testdb=# SELECT dblink_connect('localconn2', 'dbname=seaboxsql user=test_user');

要建立与远程数据库系统的连接，请在连接字符串中包含主机和密码信息。例如，要创建到远程系统的隐式dblink连接：

testdb=# SELECT dblink_connect('host=remotehost port=5432 dbname=seaboxsql user=seabox password=secret');

作为非超级用户使用dblink¶

要使用dblink_connect()与数据库建立连接，非超级用户必须在连接字符串中包含主机，用户和密码信息。即使连接到本地数据库，也必须包括主机，用户和密码信息。

例如，用户test_user可以使用以下命令创建到本地系统mdw的dblink连接：

testdb=> SELECT dblink_connect('host=mdw port=5432 dbname=seaboxsql user=test_user password=secret');

如果非超级用户需要创建不需要密码的dblink连接，则可以使用dblink_connect_u()函数。dblink_connect_u()函数与dblink_connect()相同，区别在于它允许非超级用户创建不需要密码的连接。

最初安装dblink_connect_u()时，它具有从PUBLIC撤消的所有权限，因此除超级用户外，它无法调用。在某些情况下，将dblink_connect_u()的EXECUTE权限授予被认为可信任的特定用户可能是适当的，但是应格外小心。

重要提示: 如果SeaboxMPP数据库系统为用户配置了不涉及密码的身份验证方法，那么当非超级用户执行dblink_connect_u()时，可能会冒充他人，并随后升级权限。 dblink连接似乎源自该函数指定的用户。例如，非超级用户可以执行dblink_connect_u()并指定使用trust认证配置的用户。

同样，即使dblink连接需要密码，也可以从服务器环境中提供该密码，例如属于服务器用户的~/.sdpass文件。建议所有属于服务器用户的~/.sdpass文件都不要包含任何指定通配符主机名的记录。

作为超级用户，对用户数据库中的dblink_connect_u()函数授予EXECUTE权限。

本示例向具有创建隐式或命名dblink连接的签名的函数的非超级用户test_user授予权限。
```
testdb=# GRANT EXECUTE ON FUNCTION dblink_connect_u(text) TO test_user;
testdb=# GRANT EXECUTE ON FUNCTION dblink_connect_u(text, text) TO test_user;
```
现在，test_user无需密码即可创建到另一个本地数据库的连接。

例如，test_user可以登录到testdb数据库并执行此命令以创建一个名为testconn的连接到本地seaboxsql数据库。
```
testdb=> SELECT dblink_connect_u('testconn', 'dbname=seaboxsql user=test_user');
```
test_user可以使用dblink()函数通过dblink连接执行查询。

例如，此命令使用在上一步中创建的名为testconn的dblink连接。 test_user必须具有对该表的适当访问权限。
```
testdb=> SELECT * FROM dblink('testconn', 'SELECT * FROM testdblink') AS dbltab(id int, product text);
```

dblink扩展（跨库查询）

dblink¶

dblink函数¶

dblink_connect()¶

dblink_connect_u()¶

dblink_disconnect()¶

dblink()¶

dblink_exec()¶

dblink_open()¶

dblink_fetch()¶

dblink_close()¶

dblink_get_connections()¶

dblink_error_message()¶

dblink_cancel_query()¶

dblink_get_pkey()¶

dblink_build_sql_insert()¶

dblink_build_sql_delete()¶

dblink_build_sql_update()¶

使用dblink实例¶

作为非超级用户使用dblink¶

`dblink_connect()`¶

`dblink_connect_u()`¶

`dblink_disconnect()`¶

`dblink()`¶

`dblink_exec()`¶

`dblink_open()`¶

`dblink_fetch()`¶

`dblink_close()`¶

`dblink_get_connections()`¶

`dblink_error_message()`¶

`dblink_cancel_query()`¶

`dblink_get_pkey()`¶

`dblink_build_sql_insert()`¶

`dblink_build_sql_delete()`¶

`dblink_build_sql_update()`¶