Documentation PostgreSQL 14.22 » Référence » Commandes SQL » ALTER FOREIGN TABLE

Précédent | Niveau supérieur | Suivant
ALTER FOREIGN DATA WRAPPER | Sommaire | ALTER FUNCTION

## ALTER FOREIGN TABLE

ALTER FOREIGN TABLE — modifie la définition de la table distante

## Synopsis

    ALTER FOREIGN TABLE [ IF EXISTS ] [ ONLY ] nom [ * ]
        action [, ... ]
    ALTER FOREIGN TABLE [ IF EXISTS ] [ ONLY ] nom [ * ]
        RENAME [ COLUMN ] nom_colonne TO nouveau_nom_colonne
    ALTER FOREIGN TABLE [ IF EXISTS ] nom
        RENAME TO nouveau_nom
    ALTER FOREIGN TABLE [ IF EXISTS ] nom
        SET SCHEMA nouveau_schéma

    où action peut être :

        ADD [ COLUMN ] nom_colonne type_données [ COLLATE collation ] [ contrainte_colonne [ ... ] ]
        DROP [ COLUMN ] [ IF EXISTS ] nom_colonne [ RESTRICT | CASCADE ]
        ALTER [ COLUMN ] nom_colonne [ SET DATA ] TYPE type_données [ COLLATE collation ]
        ALTER [ COLUMN ] nom_colonne SET DEFAULT expression
        ALTER [ COLUMN ] nom_colonne DROP DEFAULT
        ALTER [ COLUMN ] nom_colonne { SET | DROP } NOT NULL
        ALTER [ COLUMN ] nom_colonne SET STATISTICS integer
        ALTER [ COLUMN ] nom_colonne SET ( option_attribut = valeur [, ... ] )
        ALTER [ COLUMN ] nom_colonne RESET ( option_attribut [, ... ] )
        ALTER [ COLUMN ] nom_colonne SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN }
        ALTER [ COLUMN ] nom_colonne OPTIONS ( [ ADD | SET | DROP ] option ['valeur'] [, ... ])
        ADD contrainte_table [ NOT VALID ]
        VALIDATE CONSTRAINT nom_contrainte
        DROP CONSTRAINT [ IF EXISTS ]  nom_contrainte [ RESTRICT | CASCADE ]
        DISABLE TRIGGER [ nom_trigger | ALL | USER ]
        ENABLE TRIGGER [ nom_trigger | ALL | USER ]
        ENABLE REPLICA TRIGGER nom_trigger
        ENABLE ALWAYS TRIGGER nom_trigger
        SET WITHOUT OIDS
        INHERIT table_parent
        NO INHERIT table_parent
        OWNER TO { nouveau_propriétaire | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
        OPTIONS ( [ ADD | SET | DROP ] option ['valeur'] [, ... ])

## Description

`ALTER FOREIGN TABLE` modifie la définition d'une table distante existante. Il existe plusieurs variantes :

`ADD COLUMN`

  Ajoute une nouvelle colonne à la table distante en utilisant une syntaxe identique à celle de `CREATE FOREIGN TABLE`. Contrairement au comportement de l'ajout d'une colonne à une table, rien ne se passe au niveau stockage : cette action déclare simplement qu'une nouvelle colonne est accessible via la table distante.

`DROP COLUMN [ IF EXISTS ]`

  Supprime une colonne de la table. L'option `CASCADE` doit être utilisée lorsque des objets en dehors de la table dépendant de cette colonne, comme par exemple des références de clés étrangères ou des vues. Si `IF EXISTS` est indiqué et que la colonne n'existe pas, aucune erreur n'est renvoyée. Dans ce cas, un message d'avertissement est envoyé à la place.

`SET DATA TYPE`

  Change le type d'une colonne de la table. Là-aussi, cela n'a aucun effet sur le stockage sous-jacent : cette action change simplement le type de la colonne, d'après PostgreSQL.

`SET`/`DROP DEFAULT`

  Ces clauses ajoutent ou suppriment une valeur par défaut pour une colonne. Les valeurs par défaut s'appliquent seulement pour les prochaines commandes `INSERT` et `UPDATE` ; elles ne changent rien aux lignes déjà présentes dans la table.

`SET`/`DROP NOT NULL`

  Autorise / refuse l'ajout de valeurs NULL dans la colonne. `SET NOT NULL` ne peut être utilisé que si la colonne ne contient pas de valeurs NULL.

`SET STATISTICS`

  Cette clause définit pour chaque colonne l'objectif de collecte de statistiques pour les opérations d'`ANALYZE` ultérieures. Voir les clauses correspondantes de l'instruction `ALTER TABLE` pour plus de détails.

`SET ( `option_attribut` = `valeur` [, ... ] )`
`RESET ( `option_attribut` [, ... ] )`

  Cette clause définit ou met à zéro des options propres à une colonne. Voir les clauses correspondantes de l'instruction `ALTER TABLE` pour plus de détails.

`SET STORAGE`

  Cette clause configure le mode de stockage pour une colonne. Voir la clause similaire de `ALTER TABLE` pour plus de détails. Notez que le mode de stockage n'a d'effet que si le wrapper de données distantes choisit de le prendre en compte.

`ADD `contrainte_table` [ NOT VALID ]`

  Cette clause ajoute une nouvelle contrainte à une table distante, en utilisant la même syntaxe que `CREATE FOREIGN TABLE`. Seules les contraintes `CHECK` sont actuellement supportées.

  Contrairement à l'ajout d'une contrainte sur une table standard, rien n'est tenté pour vérifier que la contrainte est vraie ; en fait, cette action déclare uniquement certaines conditions qui seront supposées vraies pour toutes les lignes de la table distante. (Voir la discussion dans `CREATE FOREIGN TABLE`..) Si la contrainte est marquée `NOT VALID`, alors elle n'est considérée vraie mais est enregistrée pour une utilisation future.

`VALIDATE CONSTRAINT`

  Cette clause marque la validité d'une contrainte précédemment invalide (`NOT VALID`). Aucune vérification n'est effectuée pour s'assurer de la véracité de cette indication. Les prochaines requêtes supposeront que les données respectent cette contrainte.

`DROP CONSTRAINT [ IF EXISTS ]`

  Cette clause supprime la contrainte indiquée sur la table distante. Si la clause `IF EXISTS` est précisée et que la contrainte n'existe pas, aucune erreur n'est renvoyée mais un message d'information apparait.

`DISABLE`/`ENABLE [ REPLICA | ALWAYS ] TRIGGER`

  Ces syntaxes configurent le déclenchement des triggers positionnés sur la table distante. Voir la syntaxe similaire de `ALTER TABLE` pour plus de détails.

`SET WITHOUT OIDS`

  Procure une compatibilité de syntaxe dans le cadre de la suppression de la colonne système `oid`. Comme les colonnes système `oid` ne peuvent plus être ajoutées, cela n'a aucun effet.

`INHERIT `parent_table``

  Cette forme ajoute la table distante cible comme nouvel enfant de la table parente spécifiée. Pour plus de détails, voir la forme similaire dans `ALTER TABLE`.

`NO INHERIT `parent_table``

  Cette forme supprime la table cible distante de la liste des enfants de la table parente spécifiée.

`OWNER`

  Change le propriétaire d'une table distante. Le nouveau propriétaire est celui passé en paramètre.

`OPTIONS ( [ ADD | SET | DROP ] `option` ['`value`'] [, ... ] )`

  Modifie les options de la table distante et de ses colonnes. L'action à effectuer est spécifiée par `ADD` (ajout), `SET` (définition) ou `DROP` (suppression). Si aucune action n'est mentionnée, `ADD` est utilisée.

  Les noms des options autorisées et leurs valeurs sont spécifiques à chaque 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 aie le même nom). Les noms d'option et leur valeur sont en outre validées par la bibliothèque du wrapper de données distantes.

`RENAME`

  Change le nom d'une table distante ou le nom d'une colonne individuelle de la table distante. Cela n'a aucun effet sur la donnée stockée.

`SET SCHEMA`

  Déplace la table distante dans un autre schéma.

À l'exception de `RENAME` et `SET SCHEMA`, toutes les actions peuvent être combinées en une liste de modifications appliquées parallèlement. Par exemple, il est possible d'ajouter plusieurs colonnes et/ou de modifier plusieurs colonnes en une seule commande.

Si la commande est écrite avec `ALTER FOREIGN TABLE IF EXISTS ...` et que la table distante n'existe pas, aucune erreur n'est émise. Un message d'attention est émis dans ce cas.

Il faut être propriétaire de la table pour utiliser `ALTER FOREIGN TABLE`. Pour modifier le schéma d'une table, le droit `CREATE` sur le nouveau schéma est requis. Pour modifier le propriétaire de la table, il est nécessaire d'être un membre direct ou indirect du nouveau rôle et ce dernier doit avoir le droit `CREATE` sur le schéma de la table (ces restrictions assurent que la modification du propriétaire ne diffère en rien de ce qu'il est possible de faire par la suppression et la re-création de la table. Néanmoins, dans tous les cas, un super-utilisateur peut modifier le propriétaire de n'importe quelle table). Pour ajouter une colonne ou modifier un type de colonne, vous devez aussi détenir le droit `USAGE` sur le type de donnée.

## Paramètres

`nom`

  Le nom (éventuellement qualifié du nom du schéma) de la table à modifier. Si `ONLY` est spécifié avant le nom de la table, la table seule est modifiée. Si `ONLY` n'est pas spécifié, la table et toutes ses tables filles (s'il y en a) sont modifiées. Optionnellement, `*` peut être spécifié après le nom de la table pour indiquer explicitement que les tables filles sont incluses.

`nom_colonne`

  Le nom d'une colonne, existante ou nouvelle.

`nouveau_nom_colonne`

  Le nouveau nom d'une colonne existante.

`nouveau_nom`

  Le nouveau nom de la table.

`type_données`

  Le type de données de la nouvelle colonne, ou le nouveau type de données d'une colonne existante.

`table_constraint`

  Nouvelle contrainte au niveau table pour la table distante.

`constraint_name`

  Nom d'une contrainte existante à supprimer.

`CASCADE`

  Les objets qui dépendent de la colonne ou de la contrainte supprimée sont automatiquement supprimés (par exemple, les vues référençant la colonne), ainsi que tous les objets dépendants de ces objets (voir Section 5.14).

`RESTRICT`

  La colonne ou la contrainte n'est pas supprimée si des objets en dépendent. C'est le comportement par défaut.

`nom_trigger`

  Nom du trigger à activer ou désactiver.

`ALL`

  Désactive ou active tous les triggers appartenant à la table distante. (Ceci requiert l'attribut super-utilisateur si un des triggers est un trigger interne. Le moteur n'ajoute pas de tels triggers sur les tables distantes mais du code externe pourrait le faire.)

`USER`

  Désactive ou active tous les triggers appartenant à la table distante, sauf pour les triggers internes.

`parent_table`

  Une table parente à associer ou dissocier de cette table distante.

`nouveau_propriétaire`

  Le nom d'utilisateur du nouveau propriétaire de la table distante.

`nouveau_schéma`

  Le nom du schéma vers lequel la table distante sera déplacée.

## Notes

Le mot clé `COLUMN` n'est pas nécessaire. Il peut être omis.

La cohérence avec le serveur distant n'est pas vérifiée lorsqu'une colonne est ajoutée ou supprimée avec la commande `ADD COLUMN` ou `DROP COLUMN`, lorsqu'une contrainte `CHECK` ou `NOT NULL` est ajoutée, ou encore lorsqu'un type de colonne est modifié avec l'action `SET DATA TYPE`. Il est ainsi de la responsabilité de l'utilisateur de s'assurer que la définition de la table distante est compatible avec celle du serveur distant.

Voir la commande `CREATE FOREIGN TABLE` pour une description plus complète des paramètres valides.

## Exemples

Pour interdire les valeurs NULL sur une colonne :

    ALTER FOREIGN TABLE distributeurs ALTER COLUMN rue SET NOT NULL;

Pour modifier les options d'une table distante :

    ALTER FOREIGN TABLE mon_schema.distributeurs OPTIONS (ADD opt1 'valeur', SET opt2 'valeur2', DROP opt3);

## Compatibilité

Les actions `ADD`, `DROP`, et `SET DATA TYPE` sont conformes au standard SQL. Les autres actions sont des extensions PostgreSQL du standard SQL. De plus, la possibilité de combiner de multiples modifications en une seule commande `ALTER FOREIGN TABLE` est une extension PostgreSQL.

La commande `ALTER FOREIGN TABLE DROP COLUMN` peut être utilisée pour supprimer jusqu'à la dernière colonne d'une table distante, permettant ainsi d'obtenir une table sans colonne. Il s'agit d'une extension du standard SQL, qui ne permet pas de gérer des tables sans colonnes.

## Voir aussi

CREATE FOREIGN TABLE, DROP FOREIGN TABLE