Description

INSERT insère de nouvelles lignes dans une table. Vous pouvez insérer une ou plusieurs lignes spécifiées par les expressions de valeur, ou zéro ou plusieurs lignes provenant d'une requête.

L'ordre des noms des colonnes n'a pas d'importance. Si aucune liste de noms de colonnes n'est donnée, toutes les colonnes de la table sont utilisée dans l'ordre de leur déclaration (les N premiers noms de colonnes si seules N valeurs de colonnes sont fournies dans la clause VALUES ou dans la requête). Les valeurs fournies par la clause VALUES ou par la requête sont associées à la liste explicite ou implicite des colonnes de gauche à droite.

Chaque colonne absente de la liste, implicite ou explicite, des colonnes se voit attribuer sa valeur par défaut, s'il y en a une, ou NULL dans le cas contraire.

Un transtypage automatique est entrepris lorsque l'expression d'une colonne ne correspond pas au type de donnée déclaré.

Des INSERT dans des tables pour lesquelles il manque des index d'unicité ne seront pas bloqués par des activités concurrentes. Les tables avec des index d'unicité pourraient bloquer si des sessions concurrentes réalisent des actions qui verrouillent ou modifient des lignes correspondant aux valeurs en cours d'insertion dans l'index ; les détails sont disponibles dans Section 62.5. ON CONFLICT peut être utilisé pour indiquer une action alternative lorsqu'une erreur sur une contrainte unique ou une contrainte d'exclusion est levée (voir Clause ON CONFLICT ci-dessous).

La clause RETURNING optionnelle fait que INSERT calcule et renvoie le(s) valeur(s) basée(s) sur chaque ligne en cours d'insertion (ou mises à jour si une clause ON CONFLICT DO UPDATE a été utilisée). C'est principalement utile pour obtenir les valeurs qui ont été fournies par défaut, comme un numéro de séquence. Néanmoins, toute expression utilisant les colonnes de la table est autorisée. La syntaxe de la liste RETURNING est identique à celle de la commande SELECT. Seules les lignes qui ont été insérées ou mises à jour avec succès sont retournées. Par exemple, si une ligne a été verrouillée mais non mise à jour parce que la condition de la clause ON CONFLICT DO UPDATE ... WHERE n'a pas été satisfaite, la ligne ne sera pas renvoyée.

Vous devez avoir le droit INSERT sur une table pour insérer des données dedans. Si ON CONFLICT DO UPDATE est indiqué, le droit UPDATE est aussi requis.

Si une liste de colonnes est indiquée, vous avez seulement besoin d'avoir le droit INSERT sur les colonnes spécifiées. De la même manière, lorsque ON CONFLICT DO UPDATE est indiqué, vous avez seulement besoin d'avoir le droit UPDATE sur les colonnes qui sont listées comme à mettre à jour. Cependant, ON CONFLICT DO UPDATE exige également le droit SELECT sur toutes les colonnes dont les valeurs sont lues dans l'expression de ON CONFLICT DO UPDATE ou la condition.

L'utilisation de la clause RETURNING requiert le droit SELECT sur toutes les colonnes mentionnées dans RETURNING. Si vous utilisez la clause requête pour insérer des lignes à partir d'une requête, vous avez bien sûr besoin d'avoir le droit SELECT sur toutes les tables ou colonnes référencées dans la requête.

Paramètres

Sorties

En cas de succès, la commande INSERT renvoie un code de la forme

INSERT oid nombre 

nombre correspond au nombre de lignes insérées ou mises à jour. oid vaut toujours 0 (il s'agissait de l'OID affecté à la ligne insérée si count valait exactement 1 et que la table cible était déclarée WITH OIDS et 0 dans les autres cas, mais créer une table WITH OIDS n'est plus supporté).

Si la commande INSERT contient une clause RETURNING, le résultat sera similaire à celui d'une instruction SELECT contenant les colonnes et les valeurs définies dans la liste RETURNING, à partir de la liste des lignes insérées ou mises à jour par la commande.

Notes

Si la table spécifiée est une table partitionnée, chaque ligne est redirigée vers la partition appropriée et insérée dedans. Si la table spécifiée est une partition, une erreur sera remontée si une des lignes en entrée viole la contrainte de partition.

Vous pouvez aussi considérer l'utilisation de MERGE, vu qu'elle mixe des commandes INSERT, UPDATE et DELETE en une seule instruction. Voir MERGE.

Exemples

Insérer une ligne dans la table films :

INSERT INTO films
	VALUES ('UA502', 'Bananas', 105, '1971-07-13', 'Comédie', '82 minutes');
   

Dans l'exemple suivant, la colonne longueur est omise et prend donc sa valeur par défaut :

INSERT INTO films (code, titre, did, date_prod, genre)
    VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drame');
   

L'exemple suivant utilise la clause DEFAULT pour les colonnes date plutôt qu'une valeur précise :

INSERT INTO films VALUES
    ('UA502', 'Bananas', 105, DEFAULT, 'Comédie', '82 minutes');
INSERT INTO films (code, titre, did, date_prod, genre)
    VALUES ('T_601', 'Yojimbo', 106, DEFAULT, 'Drame');
   

Insérer une ligne constituée uniquement de valeurs par défaut :

INSERT INTO films DEFAULT VALUES;
   

Pour insérer plusieurs lignes en utilisant la syntaxe multi-lignes VALUES :

INSERT INTO films (code, titre, did, date_prod, genre) VALUES
    ('B6717', 'Tampopo', 110, '1985-02-10', 'Comedy'),
    ('HG120', 'The Dinner Game', 140, DEFAULT, 'Comedy');
   

Insérer dans la table films des lignes extraites de la table tmp_films (la disposition des colonnes est identique dans les deux tables) :

INSERT INTO films SELECT * FROM tmp_films WHERE date_prod < '2004-05-07';
   

Insérer dans des colonnes de type tableau :

-- Créer un jeu de 3 cases sur 3
INSERT INTO tictactoe (game, board[1:3][1:3])
    VALUES (1, '{{" "," "," "},{" "," "," "},{" "," "," "}}');
-- Les indices de l'exemple ci-dessus ne sont pas vraiment nécessaires
INSERT INTO tictactoe (game, board)
    VALUES (2, '{{X," "," "},{" ",O," "},{" ",X," "}}');
   

Insérer une ligne simple dans la table distributeurs, en renvoyant le numéro de séquence généré par la clause DEFAULT :

INSERT INTO distributeurs (did, dnom) VALUES (DEFAULT, 'XYZ Widgets')
   RETURNING did;
   

Augmenter le nombre de ventes du vendeur qui gère le compte Acme Corporation, et enregistrer la ligne complètement mise à jour avec l'heure courante dans une table de traçage :

WITH upd AS (
  UPDATE employees SET sales_count = sales_count + 1 WHERE id =
    (SELECT sales_person FROM accounts WHERE name = 'Acme Corporation')
    RETURNING *
)
INSERT INTO employees_log SELECT *, current_timestamp FROM upd;
   

Insérer ou mettre à jour de nouveaux distributeurs comme approprié. Suppose qu'un index unique a été défini qui contraint les valeurs apparaissant dans la colonne did. Notez que la table spéciale excluded est utilisée pour référencer les valeurs proposées à l'origine pour l'insertion :

INSERT INTO distributeurs (did, dnom)
    VALUES (5, 'Gizmo Transglobal'), (6, 'Associated Computing, Inc')
    ON CONFLICT (did) DO UPDATE SET dnom = EXCLUDED.dnom;
   

Insérer un distributeur, ou ne fait rien pour les lignes proposées à l'insertion lorsqu'une ligne existante, exclue (une ligne avec une contrainte correspondante sur une ou plusieurs colonnes après que les triggers après ou avant se soient déclenchés) existe. L'exemple suppose qu'un index unique a été défini qui contraint les valeurs apparaissant dans la colonne did :

INSERT INTO distributeurs (did, dnom) VALUES (7, 'Redline GmbH')
    ON CONFLICT (did) DO NOTHING;
   

Insérer ou mettre à jour de nouveaux distributeurs comme approprié. L'exemple suppose qu'un index unique a été défini qui contraint les valeurs apparaissant dans la colonne did. La clause WHERE est utilisée pour limiter les lignes mises à jour (toutes les lignes existantes non mises à jour seront tout de même verrouillées) :

-- Ne pas mettre à jour les distributeurs existants avec un certain code postal
INSERT INTO distributeurs AS d (did, dnom) VALUES (8, 'Anvil Distribution')
    ON CONFLICT (did) DO UPDATE
    SET dnom = EXCLUDED.dnom || ' (précédemment ' || d.dnom || ')'
    WHERE d.code_postal <> '21201';

-- Nomme une contrainte directement dans l'instruction (utilise
-- l'index associé pour décider de prendre l'action DO NOTHING)
INSERT INTO distributeurs (did, dnom) VALUES (9, 'Antwerp Design')
    ON CONFLICT ON CONSTRAINT distributeurs_pkey DO NOTHING;
   

Insérer un nouveau distributeur si possible ; sinon DO NOTHING. L'exemple suppose qu'un index unique a été défini qui contraint les valeurs apparaissant dans la colonne did à un sous-ensemble des lignes où la colonne booléenne est_actif est évaluée à true :

-- Cette instruction pourrait inférer un index unique partiel sur "did"
-- avec un prédicat de type "WHERE est_actif", mais il pourrait aussi
-- juste utiliser une contrainte unique régulière sur "did"
INSERT INTO distributeurs (did, dnom) VALUES (10, 'Conrad International')
    ON CONFLICT (did) WHERE est_actif DO NOTHING;
   

Compatibilité

INSERT est conforme au standard SQL, sauf la clause RETURNING qui est une extension PostgreSQL, comme la possibilité d'utiliser la clause WITH avec l'instruction INSERT, et de spécifier une action alternative avec ON CONFLICT. Le standard n'autorise toutefois pas l'omission de la liste des noms de colonnes alors qu'une valeur n'est pas affectée à chaque colonne, que ce soit à l'aide de la clause VALUES ou à partir de la requête. Si vous préférez une instruction plus conforme au standard SQL que ON CONFLICT, voir MERGE.

Le standard SQL spécifie que OVERRIDING SYSTEM VALUE ne peut être spécifié que si une colonne d'identité qui est toujours générée existe. PostgreSQL autorise cette clause dans tous les cas et l'ignore si elle ne s'applique pas.

Les limitations possibles de la clause requête sont documentées sous SELECT.