Documentation PostgreSQL 14.22 » Annexes » Modules supplémentaires fournis » dblink » dblink

Précédent | Niveau supérieur | Suivant
dblink_disconnect | Sommaire | dblink_exec

## dblink

dblink — exécute une requête sur une base de données distante

## Synopsis

        dblink(text connname, text sql [, bool fail_on_error]) returns setof record
        dblink(text connstr, text sql [, bool fail_on_error]) returns setof record
        dblink(text sql [, bool fail_on_error]) returns setof record

## Description

`dblink` exécute une requête (habituellement un `SELECT`, mais toute instruction SQL qui renvoie des lignes est valable) sur une base de données distante.

Si deux arguments `text` sont présents, le premier est d'abord considéré comme nom de connexion persistante ; si cette connexion est trouvée, la commande est exécutée sur cette connexion. Dans le cas contraire, le premier argument est considéré être une chaîne de connexion comme dans le cas de `dblink_connect`, et la connexion indiquée n'est conservée que pour la durée d'exécution de cette commande.

## Arguments

`connname`

  Le nom de la connexion à utiliser ; ce paramètre doit être omis pour utiliser une connexion sans nom.

`connstr`

  Une chaîne de connexion similaire à celle décrite précédemment pour `dblink_connect`.

`sql`

  L'instruction SQL à exécuter sur l'hôte distant, par exemple `select * from foo`.

`fail_on_error`

  Si true (valeur par défaut en cas d'omission), une erreur distante est reportée localement comme une erreur. Dans le cas contraire, un message d'erreur distant est traité localement comme un message de type NOTICE, et la fonction ne retourne aucune ligne.

## Valeur de retour

La fonction renvoie les lignes produites par la requête. Comme `dblink` peut être utilisée avec toute requête, elle est déclarée comme renvoyant le type `record`, plutôt que de préciser un ensemble particulier de colonnes. Cela signifie que l'ensemble des colonnes attendues doit être précisé dans la requête appelante -- sinon PostgreSQL ne sait pas quoi attendre. Voici un exemple :

    SELECT *
        FROM dblink('dbname=mydb options=-csearch_path=',
                    'select proname, prosrc from pg_proc')
          AS t1(proname name, prosrc text)
        WHERE proname LIKE 'bytea%';

La partie « alias » de la clause `FROM` doit spécifier les noms et types des colonnes retournés par la fonction. (La précision des noms des colonnes dans un alias est une syntaxe du standard SQL mais la précision des types des colonnes est une extension PostgreSQL.) Cela permet au système de savoir comment étendre `*`, et à quoi correspond `proname` dans la clause `WHERE` avant de tenter l'exécution de la fonction. À l'exécution, une erreur est renvoyée si le nombre de colonnes du résultat effectif de la requête sur la base de données distante diffère de celui indiqué dans la clause `FROM`. Les noms de colonnes n'ont pas besoin de correspondre et `dblink` n'impose pas une correspondance exacte des types. L'opération réussit si les chaînes de données renvoyées sont valides pour le type déclaré dans la clause `FROM`.

## Notes

Il est souvent plus pratique de créer une vue pour utiliser `dblink` avec des requêtes prédéterminées. Cela permet de laisser la vue gérer le type de la colonne plutôt que d'avoir à le saisir pour chaque requête. Par exemple :

    CREATE VIEW myremote_pg_proc AS
      SELECT *
        FROM dblink('dbname=postgres options=-csearch_path=',
                    'select proname, prosrc from pg_proc')
        AS t1(proname name, prosrc text);

    SELECT * FROM myremote_pg_proc WHERE proname LIKE 'bytea%';

## Exemple

    SELECT * FROM dblink('dbname=postgres options=-csearch_path=',
                         'select proname, prosrc from pg_proc')
      AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%';
      proname   |   prosrc
    ------------+------------
     byteacat   | byteacat
     byteaeq    | byteaeq
     bytealt    | bytealt
     byteale    | byteale
     byteagt    | byteagt
     byteage    | byteage
     byteane    | byteane
     byteacmp   | byteacmp
     bytealike  | bytealike
     byteanlike | byteanlike
     byteain    | byteain
     byteaout   | byteaout
    (12 rows)

    SELECT dblink_connect('dbname=postgres');
     dblink_connect
    ----------------
     OK
    (1 row)

    SELECT * FROM dblink('select proname, prosrc from pg_proc')
      AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%';
      proname   |   prosrc
    ------------+------------
     byteacat   | byteacat
     byteaeq    | byteaeq
     bytealt    | bytealt
     byteale    | byteale
     byteagt    | byteagt
     byteage    | byteage
     byteane    | byteane
     byteacmp   | byteacmp
     bytealike  | bytealike
     byteanlike | byteanlike
     byteain    | byteain
     byteaout   | byteaout
    (12 rows)

    SELECT dblink_connect('myconn', 'dbname=regression options=-csearch_path=');
     dblink_connect
    ----------------
     OK
    (1 row)

    SELECT * FROM dblink('myconn', 'select proname, prosrc from pg_proc')
      AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%';
      proname   |   prosrc
    ------------+------------
     bytearecv  | bytearecv
     byteasend  | byteasend
     byteale    | byteale
     byteagt    | byteagt
     byteage    | byteage
     byteane    | byteane
     byteacmp   | byteacmp
     bytealike  | bytealike
     byteanlike | byteanlike
     byteacat   | byteacat
     byteaeq    | byteaeq
     bytealt    | bytealt
     byteain    | byteain
     byteaout   | byteaout
    (14 rows)