PostgreSQLLa base de données la plus sophistiquée au monde.
Documentation PostgreSQL 18 beta 2 » Référence » Commandes SQL » CREATE FOREIGN TABLE

CREATE FOREIGN TABLE

CREATE FOREIGN TABLE — crée une nouvelle table distante

Synopsis

CREATE FOREIGN TABLE [ IF NOT EXISTS ] nom_table ( [
  { nom_colonne type_donnee [ OPTIONS ( option 'valeur' [, ... ] ) ] [ COLLATE collation ] [ contrainte_colonne [ ... ] ]
    | contrainte_table
    | LIKE table_source [ option_like ... ] }
    [, ... ]
] )
  SERVER nom_serveur
[ OPTIONS ( option 'valeur' [, ... ] ) ]

CREATE FOREIGN TABLE [ IF NOT EXISTS ] nom_table
  PARTITION OF table_parente [ (
  { nom_colonne [ WITH OPTIONS ] [ contrainte_colonne [ ... ] ]
    | contrainte_table }
    [, ... ]
) ]
{ FOR VALUES spec_limites_partition | DEFAULT }
  SERVER nom_serveur
[ OPTIONS ( option 'value' [, ... ] ) ]

where contrainte_colonne is:

[ CONSTRAINT nom_contrainte ]
{ NOT NULL [ NO INHERIT ] |
  NULL |
  CHECK ( expression ) [ NO INHERIT ] |
  DEFAULT expr_defaut |
  GENERATED ALWAYS AS ( generation_expr ) [ STORED | VIRTUAL ] }
[ ENFORCED | NOT ENFORCED ]

et contrainte_table vaut :

[ CONSTRAINT nom_contrainte ]
{  NOT NULL nom_colonne [ NO INHERIT ] |
   CHECK ( expression ) [ NO INHERIT ] }
[ ENFORCED | NOT ENFORCED ]

et option_like vaut :

{ INCLUDING | EXCLUDING } { COMMENTS | CONSTRAINTS | DEFAULTS | GENERATED | STATISTICS | ALL }

et spec_limites_partition vaut :

IN ( expr_limites_partition [, ...] ) |
FROM ( { expr_limites_partition | MINVALUE | MAXVALUE } [, ...] )
  TO ( { expr_limites_partition | MINVALUE | MAXVALUE } [, ...] ) |
WITH ( MODULUS literal_numeric, REMAINDER literal_numeric )
  

Description

La commande CREATE FOREIGN TABLE crée une nouvelle table distante dans la base de données courante. La table distante appartient à l'utilisateur qui exécute cette commande.

Si un nom de schema est spécifié (par exemple, CREATE FOREIGN TABLE monschema.matable ...), alors la table sera créée dans le schéma spécifié. Dans les autres cas, elle sera créée dans le schéma courant. Le nom de la table distante doit être différent du nom des autres relations (tables, séquences, index, vues, vues matérialisées ou tables distantes) du même schéma.

La commande CREATE FOREIGN TABLE crée aussi automatiquement un type de donnée qui représente le type composite correspondant à une ligne de la table distante. En conséquence, une table distante ne peut pas avoir le même nom qu'un type de donnée existant dans le même schéma.

Si la clause PARTITION OF est spécifiée alors la table est crée comme une partition de table_parente avec les limites spécifiées.

Pour pouvoir créer une table distante, vous devez avoir le droit USAGE sur le serveur distant, ainsi que le droit USAGE sur tous les types de colonne utilisés dans la table.

Paramètres

IF NOT EXISTS

Permet de ne pas retourner d'erreur si une table distante de même nom existe déjà. Une simple notice est alors rapportée. À noter que la table distante existante n'a potentiellement aucun lien avec la table distante qui aurait pu être créée.

nom_table

Le nom de la table distante à créer. Il est aussi possible de spécifier le schéma qui contient cette table.

nom_colonne

Le nom de la colonne à créer dans cette nouvelle table distante.

type_donnee

le type de donnée de la colonne. cela peut inclure des spécificateurs de tableaux. pour plus d'information sur les types de données supportés par postgresql, se référer à Chapitre 8.

COLLATE collation

La clause COLLATE affecte un collationnement à la colonne (qui doit être d'un type de données acceptant le collationnement). Si ce n'est pas spécifié, le collationnement par défaut du type de données de la colonne est utilisé.

INHERITS ( table_parent [, ... ] )

La clause optionnelle INHERITS indique une liste de tables à partir desquelles la nouvelle table distante hérite automatiquement de toutes les colonnes. Les tables parents sont des tables simples ou des tables distantes. Voir la forme similaire de CREATE TABLE pour plus de détails. Notez que ceci n'est pas accepté pour créer la table distante en tant que partition de la table parent s'il existe des index UNIQUE sur la table parent. (Voir aussi ALTER TABLE ATTACH PARTITION.)

PARTITION OF table_parent { FOR VALUES spec_limites_partition | DEFAULT }

Cette syntaxe peut être utilisée pour créer la table distante en tant que partition de la table parent indiquée avec les valeurs limites de la partition. Voir la syntaxe similaire de CREATE TABLE pour plus de détails.

LIKE table_source [ option_like ... ]

La clause LIKE spécifie une table à partir de laquelle la nouvelle table copie automatiquement tous les noms de colonne, leurs types de données et leurs contraintes NOT NULL.

Contrairement à INHERITS, la nouvelle table et la table originale sont complètement découplées à la fin de la création. Les changements sur la table originale ne seront pas appliquées à la nouvelle table, et il n'est pas possible d'inclure des données de la nouvelle table dans des parcours de la table originale.

De plus, contrairement à INHERITS, les colonnes et contraintes copiées par LIKE ne sont pas fusionnées avec les colonnes et contraintes de nom similaire. Si le même nom est précisé explicitement ou dans une autre clause LIKE, une erreur est signalée.

Les clauses optionnelles option_like indiquent les propriétés supplémentaires de la table originale copiée. Indiquer INCLUDING copie la propriété, indiquer EXCLUDING ignore la propriété. EXCLUDING est la valeur par défaut. Si plusieurs indications sont faites pour le même type d'objet, la dernière est utilisée. Les options disponibles sont :

INCLUDING COMMENTS

Les commentaires des colonnes et contraintes seront copiés. Le comportement par défaut est d'exclure les commentaires, résultant à ce que les colonnes et contraintes copiées dans la nouvelle table n'ont pas de commentaires.

INCLUDING CONSTRAINTS

Les contraintes CHECK seront copiées. Aucune distinction n'est faite entre les contraintes de colonne et les contraintes de table. Les contraintes NOT NULL sont toujours copiées dans la nouvelle table.

INCLUDING DEFAULTS

Les expressions par défaut pour les définitions des colonnes seront copiées. Sinon, les expressions par défaut ne sont pas copiés, ce qui se solderait par des colonnes copiées avec une valeur NULL par défaut. Notez que copier les valeurs par défaut qui appellent des fonctions de modification de la base, comme nextval, pourrait créer un lien fonctionnel entre la table origine et la nouvelle table.

INCLUDING GENERATED

Toute expression générée d'une colonne copiée sera copiée. Par défaut, les nouvelles colonnes seront des colonnes standards.

INCLUDING STATISTICS

Les statistiques étendues sont copiées dans la nouvelle table.

INCLUDING ALL

INCLUDING ALL est une forme raccourcie correspondant à la sélection de toutes les options individuelles. (il pourrait être utile d'écrire les clauses EXCLUDING individuelles après INCLUDING ALL pour sélectionner toutes les options sauf quelques-unes.)

CONSTRAINT nom_contrainte

Un nom optionnel pour une contrainte de colonne ou de table. Si la contrainte est violée, le nom de la contrainte est présent dans les messages d'erreur, donc des noms de contrainte comme col doit être positif peuvent être utilisés pour communiquer des informations intéressantes sur les contraintes aux applications clientes. (Les guillemets doubles sont nécessaires pour indiquer les noms de contraintes qui contiennent des espaces.) Si un nom de contrainte n'est pas indiqué, le système en génère un.

NOT NULL [ NO INHERIT ]

Interdit des valeurs NULL dans la colonne.

Une contrainte marquée avec NO INHERIT ne se propagera pas aux tables filles.

NULL

Les valeurs NULL sont autorisées pour la colonne. il s'agit du comportement par défaut.

Cette clause n'est fournie que pour des raisons de compatibilité avec les bases de données SQL non standard. Son utilisation n'est pas encouragée dans les nouvelles applications.

CHECK ( expression ) [ NO INHERIT ]

La clause CHECK précise une expression produisant un résultat booléen que chaque ligne de la table distante est attendu satisfaire. Autrement dit, l'expression doit renvoyer TRUE ou UNKNOWN, jamais FALSE, pour toutes les lignes de la table distante. Une contrainte de vérification spécifiée comme contrainte de colonne doit seulement référencer la valeur de la colonne alors qu'une expression apparaissant dans une contrainte de table peut référencer plusieurs colonnes.

Actuellement, les expressions CHECK ne peuvent pas contenir de sous-requêtes. Elles ne peuvent pas non plus faire référence à des variables autres que les colonnes de la ligne courante. La colonne système tableoid peut être référencée, mais aucune autre colonne système ne peut l'être.

Une contrainte marquée avec NO INHERIT ne sera pas propagée aux tables enfants.

DEFAULT expr_defaut

La clause default affecte une valeur par défaut pour la colonne dont il est l'objet. la valeur est toute expression sans variable (les sous-requêtes et les références croisées à d'autres colonnes de la même table ne sont pas autorisées). le type de données de l'expression doit correspondre au type de données de la colonne.

L'expression par défaut sera utilisée dans toute opération d'insertion qui n'indique pas de valeur pour la colonne. s'il n'y a pas de valeur par défaut pour une colonne, la valeur par défaut implicite est null.

GENERATED ALWAYS AS ( generation_expr ) [ STORED | VIRTUAL ]

Cette clause crée la colonne en tant que colonne générée. La colonne ne peut pas faire l'objet d'une écriture, et quand elle est lue, c'est le résultat de l'expression spécifiée qui est renvoyé.

Quand VIRTUAL est indiqué, la colonne sera calculée quand elle sera lue. (Le wrapper de données distantes la verra comme une valeur NULL dans les nouvelles lignes, et pourrait l'enregistrer comme une valeur NULL ou l'ignorer.) Quand STORED est indiqué, la colonne sera calculée lors de son écriture. (La valeur calculée sera présentée au wrapper de données distante pour enregistrement et devra être renvoyée à la lecture.) VIRTUAL est la valeur par défaut.

L'expression de génération peut se référer à d'autres colonnes de la table, mais pas à d'autres colonnes générées. Toutes les fonctions et opérateurs qu'elle utilise doivent être immuables. Les références à d'autres tables ne sont pas autorisées.

nom_serveur

Le nom d'un serveur distant existant à utiliser pour la table distante. Pour les détails sur la définition d'un serveur, voir CREATE SERVER.

OPTIONS ( option 'valeur' [, ...] )

Options qui peuvent être associés à la nouvelle table distante ou à une de ses colonnes. Les noms des options autorisées et leurs valeurs sont spécifiques à chaque wrapper de données distantes et sont validées en utilisant la fonction de validation du wrapper de données distantes. L'utilisation répétée de la même option n'est pas autorisée (bien qu'il soit possible qu'une option de table et de colonne ait le même nom).

Notes

Les contraintes sur les tables distantes (comme les clauses CHECK ou NOT NULL) ne sont pas vérifiées par le système PostgreSQL, et la plupart des wrappers de données distantes ne cherchent pas non plus à les vérifier. La contrainte est supposée être vraie. Il y aurait peu de raisons de la vérifier car elles ne s'appliqueraient qu'aux lignes insérées ou mises à jour via la table distante, et pas aux lignes modifiées d'une autre façon, comme directement sur le serveur distant. À la place, une contrainte attachée à une table distante doit représenter une contrainte vérifiée par le serveur distant.

Certains wrappers de données distantes, dont le but est très spécifique, pourraient être le seul mécanisme d'accès aux données accédées. Dans ce cas, il pourrait être approprié au wrapper de données distantes de s'assurer de la vérification de la contrainte. Mais vous ne devez pas supposer qu'un wrapper le fait, sauf si sa documentation le précise.

Bien que PostgreSQL ne tente pas de vérifier les contraintes sur les tables distantes, il suppose qu'elles sont vérifiées et les utilise pour optimiser les requêtes. S'il y a des lignes visibles dans la table distante qui ne satisfont pas une contrainte déclarée, les requêtes sur la table pourraient produire des erreurs ou des réponses incorrectes. C'est de la responsabilité de l'utilisateur de s'assurer que la définition de la contrainte correspond à la réalité.

Attention

Quand une table distante est utilisée comme partition d'une table partitionnée, il existe une contrainte implicite que son contenu doit satisfaire la règle de partitionnement. Là aussi, c'est de la responsabilité de l'utilisateur que de s'assurer que cela est vrai, ce qui se fait en installer une contrainte correspondante sur le serveur distant.

Dans une table partitionnée contenant des tables distantes comme partitions, une requête UPDATE pouvant modifier la valeur de la clé de partitionnement peut causer le déplacement de la ligne d'une partition locale à une partition distante, à condition que le Foreign Data Wrapper réalise le routage de la ligne. Néanmoins, il n'est actuellement pas possible de déplacer une ligne d'une partition distante vers une autre partition. Une requête UPDATE qui devra le faire échouera à cause de la contrainte de partitionnement, en supposant que c'est correctement assurée par le serveur distant.

Des considérations similaires s'appliquent aux colonnes générées. Les colonnes générées stockées sont calculées au moment de l'insertion et des mises à jour sur le serveur PostgreSQL local, et passés au wrapper de données distantes pour les écrire dans le stockage distant, mais il n'est pas garanti qu'une requête sur la table distante renvoie des valeurs pour les colonnes générées en cohérence avec l'expression de génération. A nouveau, cela peut engendrer des résultats de requête incorrects.

Exemples

Créer une table distante films qui sera parcourue via le serveur serveur_film :

CREATE FOREIGN TABLE films (
    code        char(5) NOT NULL,
    title       varchar(40) NOT NULL,
    did         integer NOT NULL,
    date_prod   date,
    kind        varchar(10),
    len         interval hour to minute
)
SERVER serveur_films;
   

Créer une table distante measurement_y2016m07, qui sera accédée au travers du serveur server_07, comme une partition de la table partitionnée par intervalles measurement :

CREATE FOREIGN TABLE measurement_y2016m07
    PARTITION OF measurement FOR VALUES FROM ('2016-07-01') TO ('2016-08-01')
    SERVER server_07;
   

Compatibilité

La commande CREATE FOREIGN TABLE est conforme au standard SQL. Toutefois, tout comme la commande CREATE TABLE, l'usage de la contrainte NULL et des tables distantes sans colonnes sont autorisés. La possibilité de spécifier des valeurs par défaut pour les colonnes est aussi une extension de PostgreSQL. L'héritage de table, dans la forme définie par PostgreSQL, n'est pas standard. La clause LIKE de cette command n'est pas standard.