Reference：DBlink

dblink是一个支持在一个数据库会话中连接到其他数据库的扩展模块。可以实现在不同的数据库之间进行通信和交互。它可以让你在一个数据库中访问另一个数据库的表格和函数，甚至可以在不同的服务器之间进行数据交互。

DBLINK 安装

在使用dblink之前，需要确保已经安装了dblink扩展。可以使用以下命令进行安装

CREATE EXTENSION dblink;

通过如下命令查看已经安装的扩展

select * from pg_extension;

通过如下命令查看可用的扩展

select * from pg_available_extensions where name like '%dblink%';

DBLINK 使用

dblink_connect

dblink_connect 打开一个到远程数据库的持久连接，只有超级用户能够使用

• 语法： dblink_connect(text connstr) 返回 text dblink_connect(text connname, text connstr) 返回 text

• 描述：

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

• 参数： connname 要用于这个连接的名字。如果被忽略，将打开一个未命名连接并且替换掉任何现有的未命名连接。

connstr libpq-风格的连接信息串，例如 hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres password=mypasswd。此外，还可以是一个外部服务器的名字。 更详细的介绍请参考：https://www.postgresql.org/docs/14/libpq-connect.html#LIBPQ-CONNSTRING

• 返回值： 返回状态，它总是OK（因为任何错误会导致该函数抛出一个错误而不是返回）。

• 注解： 如果不可信用户能够访问一个没有采用安全方案使用模式的数据库，应该在开始每个会话时从search_path中移除公共可写的方案。例如，可以把options=-csearch_path=增加到connstr。 这种考虑不是特别针对dblink，它适用于每一种执行任意SQL命令的接口。 只有超级用户能够使用dblink_connect来创建无口令认证连接。如果非超级用户需要这种能力，使用dblink_connect_u。 选择包含等号的连接名是不明智的，因为这会产生与在其他dblink函数中的连接信息串混淆的风险。

• 举例：

localdb=# SELECT dblink_connect('mydblink','hostaddr=127.0.0.1 dbname=mydb port=7000 user=username password=123456 connect_timeout=5 options=-csearch_path=public,myschema');
 dblink_connect 
----------------
 OK
(1 row)

dblink_connect_u

dblink_connect_u 不安全地打开一个到远程数据库的持久连接

• 语法： dblink_connect_u(text connstr) 返回 text dblink_connect_u(text connname, text connstr) 返回 text

• 描述： dblink_connect_u()和dblink_connect()一样，不过它将允许非超级用户使用任意认证方式来连接。

dblink_disconnect

• 语法： dblink_disconnect(text connname) 返回 text

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

• 参数： connname 要被关闭的命名连接的名字。

• 返回值： 它总是OK（因为任何错误会导致该函数抛出一个错误而不是返回）

localdb=# SELECT dblink_disconnect('mydblink');
 dblink_disconnect 
-------------------
 OK
(1 row)

dblink

dblink在一个远程数据库中执行一个查询。

• 语法： 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]) 返回记录集

• 描述： dblink在一个远程数据库中执行一个查询（通常是一个SELECT，但是也可以是任意返回行的 SQL 语句）。 当给定两个text参数时，第一个被首先作为一个持久连接的名称进行查找；如果找到，该命令会在该连接上被执行。 如果没有找到，第一个参数被视作一个用于dblink_connect的连接信息字符串，并且被指出的连接只是在这个命令的持续期间被建立。

• 参数： connname 要使用的连接名。忽略这个参数将使用未命名连接。

connstr 如之前为dblink_connect所描述的一个连接信息字符串。

sql 你希望在远程数据库中执行的 SQL 查询，例如select * from foo。

fail_on_error 如果为真（忽略时的默认值），那么在连接的远端抛出的一个错误也会导致本地抛出一个错误。如果为假，远程错误只在本地被报告为一个 NOTICE，并且该函数不反回行。

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

localdb=# select * from  dblink('mydblink', 'select * from foo', true) as t1(f1 int,f2 text,f3 text[]) where f1 >= 6;
 f1 | f2 |     f3     
----+----+------------
  6 | g  | {a6,b6,c6}
  7 | h  | {a7,b7,c7}
  8 | i  | {a8,b8,c8}
  9 | j  | {a9,b9,c9}
(4 rows)

FROM子句的“alias”部分必须指定函数将返回的列名及类型（在一个别名中指定列名实际上是标准 SQL 语法，但是指定列类型是一种DB扩展）。这允许系统在尝试执行该函数之前就理解*将展开成什么，以及WHERE子句中的proname指的什么。在运行时，如果来自远程数据库的实际查询结果和FROM子句中显示的列数不同，将会抛出一个错误。不过，列名不需要匹配，并且dblink并不坚持精确地匹配类型。只要被返回的数据字符串是FROM子句中声明的列类型的合法输入，它就将会成功。

• 注解： 一种将预定义查询用于dblink的方便方法是创建一个视图。这允许列类型信息被埋藏在该视图中，而不是在每一个查询中都拼写出来。 例如：

localdb=# create or replace view remote_foo_view as select * from  dblink('mydblink', 'select * from foo'
) as t1(f1 int,f2 text,f3 text[]);
CREATE VIEW
localdb=# select * from remote_foo_view where f1 >=6;
 f1 | f2 |     f3     
----+----+------------
  6 | g  | {a6,b6,c6}
  7 | h  | {a7,b7,c7}
  8 | i  | {a8,b8,c8}
  9 | j  | {a9,b9,c9}
(4 rows)

dblink_exec

dblink_exec 在一个远程数据库中执行一个命令

• 语法： 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

• 描述： dblink_exec在一个远程数据库中执行一个命令（也就是，任何不返回行的 SQL 语句）。 当给定两个text参数时，第一个被首先作为一个持久连接的名称进行查找；如果找到，该命令会在该连接上被执行。如果没有找到，第一个参数被视作一个用于dblink_connect的连接信息字符串，并且被指出的连接只是在这个命令的持续期间被建立。

• 参数： connname 要使用的连接名。忽略这个参数将使用未命名连接。

connstr 如之前为dblink_connect所描述的一个连接信息字符串。

sql 你希望在远程数据库中执行的 SQL 命令，例如insert into foo values(0, ‘a’, ‘{“a0”,“b0”,“c0”}’)。

fail_on_error 如果为真（忽略时的默认值），那么在连接的远端抛出的一个错误也会导致本地抛出一个错误。如果为假，远程错误只在本地被报告为一个 NOTICE，并且该函数的返回值被设置为ERROR。

• 返回值： 返回状态，可能是命令的状态字符串或ERROR。

• 例子

localdb=# SELECT dblink_exec('insert into foo values(21, ''z'', ''{"a0","b0","c0"}'');');
 dblink_exec 
-------------
 INSERT 0 1
(1 row)

localdb=# SELECT dblink_exec('insert into foo values(null, ''z'', ''{"a0","b0","c0"}'');', false);
NOTICE:  null value in column "f1" violates not-null constraint
DETAIL:  Failing row contains (null, z, {a0,b0,c0}).
 dblink_exec 
-------------
 ERROR
(1 row)

dblink_open

• 语法： dblink_open(text cursorname, text sql [, bool fail_on_error]) 返回 text dblink_open(text connname, text cursorname, text sql [, bool fail_on_error]) 返回 text

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

• 参数： connname 要使用的连接名。忽略这个参数将使用未命名连接。

cursorname 要赋予给这个游标的名称。

sql 你希望在远程数据库中执行的SELECT语句，例如select * from pg_class。

fail_on_error 如果为真（忽略时的默认值），那么在连接的远端抛出的一个错误也会导致本地抛出一个错误。如果为假，远程错误只在本地被报告为一个 NOTICE，并且该函数的返回值被设置为ERROR。

• 返回值： 返回状态，OK或者ERROR。

dblink_fetch

dblink_fetch 从一个远程数据库中的打开的游标返回行

• 语法： dblink_fetch(text cursorname, int howmany [, bool fail_on_error]) 返回 record 集合 dblink_fetch(text connname, text cursorname, int howmany [, bool fail_on_error]) 返回 record 集合

• 描述： dblink_fetch从一个之前由dblink_open建立的游标中取得行。

• 参数： connname 要使用的连接名。忽略这个参数将使用未命名连接。

cursorname 要从中取数据的游标名。

howmany 要检索的最大行数。从当前游标位置向前的接下来howmany个行会被取出。一旦该游标已经到达了它的末端，将不会产生更多行。

fail_on_error 如果为真（忽略时的默认值），那么在连接的远端抛出的一个错误也会导致本地抛出一个错误。如果为假，远程错误只在本地被报告为一个 NOTICE，并且该函数不反回行。

• 返回值 该函数返回从游标中取出的行。要使用这个函数，你将需要指定想要的列集合，如前面dblink中所讨论的。

dblink_close

dblink_close 关闭一个远程数据库中的游标

• 语法： dblink_close(text cursorname [, bool fail_on_error]) 返回 text dblink_close(text connname, text cursorname [, bool fail_on_error]) 返回 text

• 描述： dblink_close关闭一个之前由dblink_open打开的游标。

• 参数： connname 要使用的连接名。忽略这个参数将使用未命名连接。

cursorname 要关闭的游标名。

fail_on_error 如果为真（忽略时的默认值），那么在连接的远端抛出的一个错误也会导致本地抛出一个错误。如果为假，远程错误只在本地被报告为一个 NOTICE，并且该函数的返回值被设置为ERROR。

• 返回值 返回状态，OK或者ERROR。

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

localdb=# select * from dblink_fetch('foo_cur',8,false) as t1(f1 int,f2 text,f3 text[]);
 f1 | f2 |     f3     
----+----+------------
  0 | a  | {a0,b0,c0}
  1 | b  | {a1,b1,c1}
  2 | c  | {a2,b2,c2}
  3 | d  | {a3,b3,c3}
  4 | e  | {a4,b4,c4}
  5 | f  | {a5,b5,c5}
  6 | g  | {a6,b6,c6}
  7 | h  | {a7,b7,c7}
(8 rows)

localdb=# select * from dblink_fetch('foo_cur',3,false) as t1(f1 int,f2 text,f3 text[]);
 f1 | f2 |     f3     
----+----+------------
  8 | i  | {a8,b8,c8}
  9 | j  | {a9,b9,c9}
 21 | z  | {a0,b0,c0}
(3 rows)

localdb=# select * from dblink_fetch('foo_cur',2,false) as t1(f1 int,f2 text,f3 text[]);
 f1 | f2 | f3 
----+----+----
(0 rows)

localdb=# select dblink_close('foo_cur');
 dblink_close 
--------------
 OK
(1 row)

dblink_get_connections

dblink_get_connections 返回所有打开的命名 dblink 连接的名称

• 语法： dblink_get_connections() 返回 text[]

• 描述： dblink_get_connections返回一个数组，其中是所有打开的命名dblink连接的名称。

• 返回值： 返回一个连接名称的文本数组，如果没有则为 NULL。

• 例子：

localdb=# SELECT dblink_get_connections();
 dblink_get_connections 
------------------------
 {mydblink}
(1 row)

dblink_error_message

dblink_error_message 得到在命名连接上的最后一个错误消息

• 语法： dblink_error_message(text connname) 返回 text

• 描述： dblink_error_message为一个给定连接取得最近的远程错误消息。

• 参数： connname 要使用的连接名。

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

• 例子：

localdb=# SELECT dblink_error_message('mydblink');
 dblink_error_message 
----------------------
 OK
(1 row)

dblink_get_pkey

dblink_get_pkey 返回一个关系的主键域的位置和域名称

• 语法： dblink_get_pkey(text relname) 返回 dblink_pkey_results 集合

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

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

• 返回值： 为每一个主键域返回一行，如果该关系没有主键则不返回行。结果行类型被定义为： CREATE TYPE dblink_pkey_results AS (position int, colname text); position列值可以从 1 到 N，它是该域在主键中的编号，而不是在表列中的编号。

• 例子：

mydb=# select * from dblink_get_pkey('foo');
 position | colname 
----------+---------
        1 | f1
        2 | f2
(2 rows)

dblink_build_sql_insert

dblink_build_sql_insert 使用一个本地元组构建一个 INSERT 语句，将主键域值替换为提供的值

• 语法： 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

• 描述： dblink_build_sql_insert在选择性地将一个本地表复制到一个远程数据库时很有用。它基于主键从本地表选择一行，并且接着构建一个复制该行的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 语句返回为文本。 注解： 自PostgreSQL 9.0 开始，primary_key_attnums中的属性号被解释为逻辑列号，对应于列在SELECT * FROM relname中的位置。之前的版本将属性号解释为物理列位置。如果指示出的列的左边有任意列在该表的生存期内被删除，这两种解释就有区别。

• 例子：

mydb=# SELECT dblink_build_sql_insert('foo', '1 2', 2, '{"0", "a"}', '{"100", "x"}');
                 dblink_build_sql_insert                  
----------------------------------------------------------
 INSERT INTO foo(f1,f2,f3) VALUES('100','x','{a0,b0,c0}')
(1 row)

dblink_build_sql_delete

dblink_build_sql_delete 使用所提供的主键域值构建一个 DELETE 语句

• 语法： dblink_build_sql_delete( text relname, int2vector primary_key_attnums, integer num_primary_key_atts, text[] tgt_pk_att_vals_array) 返回 text

• 描述： dblink_build_sql_delete在选择性地将一个本地表复制到一个远程数据库时很有用。它构建一个 SQL DELETE命令用来删除具有给定主键值的行。

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

• 返回值： 将要求的 SQL 语句返回为文本。

• 注解： 自PostgreSQL 9.0 开始，primary_key_attnums中的属性号被解释为逻辑列号，对应于列在SELECT * FROM relname中的位置。之前的版本将属性号解释为物理列位置。如果指示出的列的左边有任意列在该表的生存期内被删除，这两种解释就有区别。

• 例子：

mydb=# SELECT dblink_build_sql_delete('foo', '1 2', 2, '{"0", "a"}');
           dblink_build_sql_delete           
---------------------------------------------
 DELETE FROM foo WHERE f1 = '0' AND f2 = 'a'
(1 row)

dblink_build_sql_update

dblink_build_sql_update 使用一个本地元组构建一个 UPDATE 语句，将主键域值替换为提供的值 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

• 描述： dblink_build_sql_update在选择性地将一个本地表复制到一个远程数据库时很有用。它从本地表基于主键选择一行，并且接着构建一个 SQL UPDATE命令来复制该行，但是其中的主键值被替换为最后一个参数中的值（要创建该行的一个准确拷贝，只要为最后两个参数指定相同的值）。UPDATE命令总是为该行的所有域赋值 这个函数与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 要用在结果UPDATE命令中的主键域值。每一个域都被表示为文本形式。

• 返回值： 将要求的 SQL 语句返回为文本。

• 注解： 自PostgreSQL 9.0 开始，primary_key_attnums中的属性号被解释为逻辑列号，对应于列在SELECT * FROM relname中的位置。之前的版本将属性号解释为物理列位置。如果指示出的列的左边有任意列在该表的生存期内被删除，这两种解释就有区别。

mydb=# SELECT dblink_build_sql_update('foo', '1 2', 2, '{"0", "a"}', '{"100", "x"}');
                               dblink_build_sql_update                                
--------------------------------------------------------------------------------------
 UPDATE foo SET f1 = '100', f2 = 'x', f3 = '{a0,b0,c0}' WHERE f1 = '100' AND f2 = 'x'
(1 row)

使用dblink加载数据示例及使用限制

• 使用dblink加载数据示例及使用限制