PostgreSQLLa base de données la plus sophistiquée au monde.
Documentation PostgreSQL 18 beta 1 » Référence » Commandes SQL » CREATE FOREIGN TABLE
Précédent Niveau supérieur Suivant
CREATE FOREIGN DATA WRAPPER Sommaire CREATE FUNCTION

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 source_table [ like_option ... ] }
    [, ... ]
] )
  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 column_name [ NO INHERIT ] |
   CHECK ( expression ) [ NO INHERIT ] }
[ ENFORCED | NOT ENFORCED ]

and like_option is:

{ 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 source_table [ like_option ... ]

The LIKE clause specifies a table from which the new table automatically copies all column names, their data types, and their not-null constraints.

Unlike INHERITS, the new table and original table are completely decoupled after creation is complete. Changes to the original table will not be applied to the new table, and it is not possible to include data of the new table in scans of the original table.

Also unlike INHERITS, columns and constraints copied by LIKE are not merged with similarly named columns and constraints. If the same name is specified explicitly or in another LIKE clause, an error is signaled.

The optional like_option clauses specify which additional properties of the original table to copy. Specifying INCLUDING copies the property, specifying EXCLUDING omits the property. EXCLUDING is the default. If multiple specifications are made for the same kind of object, the last one is used. The available options are:

INCLUDING COMMENTS

Comments for the copied columns, constraints, and indexes will be copied. The default behavior is to exclude comments, resulting in the copied columns and constraints in the new table having no comments.

INCLUDING CONSTRAINTS

CHECK constraints will be copied. No distinction is made between column constraints and table constraints. Not-null constraints are always copied to the new table.

INCLUDING DEFAULTS

Default expressions for the copied column definitions will be copied. Otherwise, default expressions are not copied, resulting in the copied columns in the new table having null defaults. Note that copying defaults that call database-modification functions, such as nextval, may create a functional linkage between the original and new tables.

INCLUDING GENERATED

Any generation expressions of copied column definitions will be copied. By default, new columns will be regular base columns.

INCLUDING STATISTICS

Extended statistics are copied to the new table.

INCLUDING ALL

INCLUDING ALL is an abbreviated form selecting all the available individual options. (It could be useful to write individual EXCLUDING clauses after INCLUDING ALL to select all but some specific options.)

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.

A constraint marked with NO INHERIT will not propagate to child tables.

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é.

When VIRTUAL is specified, the column will be computed when it is read. (The foreign-data wrapper will see it as a null value in new rows and may choose to store it as a null value or ignore it altogether.) When STORED is specified, the column will be computed on write. (The computed value will be presented to the foreign-data wrapper for storage and must be returned on reading.) VIRTUAL is the default.

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. The LIKE clause, as supported in this command, is nonstandard.