14.1.4 Syntaxe de INSERT

INSERT [LOW_PRIORITY | DELAYED] [IGNORE]         [INTO] tbl_name [(col_name,...)]         VALUES ((expression | DEFAULT),...),(...),...         [ ON DUPLICATE KEY UPDATE col_name=expression, ... ] ou  INSERT [LOW_PRIORITY | DELAYED] [IGNORE]         [INTO] tbl_name [(col_name,...)]         SELECT ... ou  INSERT [LOW_PRIORITY | DELAYED] [IGNORE]         [INTO] tbl_name         SET col_name=(expression | DEFAULT), ...         [ ON DUPLICATE KEY UPDATE col_name=expression, ... ]

INSERT insère une nouvelle ligne dans une table existante. La syntaxe INSERT ... VALUES insère une ligne à partir de valeurs explicitement fournies. La syntaxe INSERT ... SELECT insère des valeurs à partir d'une autre table. La syntaxe INSERT ... VALUES avec plusieurs valeurs est supportées à partir de MySQL Version 3.22.5 ou supérieure. la syntaxe nom_colonne=expression est supportée à partir de la version 3.22.10 de MySQL. nom_de_table est le nom de la table dans laquelle les valeurs seront insérées. La liste de noms de colonne ou la clause SET indiquent les colonnes qui seront affectées:

• Si vous ne spécifiez pas de liste de colonnes avec INSERT ... VALUES ou INSERT ... SELECT , les valeurs pour toutes les colonnes doivent être fournies dans la clause VALUES() ou par la commande SELECT . Si vous ne connaissez pas l'ordre des colonnes, utilisez la commande DESCRIBE nom_de_table pour le connaître.
• A chaque fois qu'on ne donne pas explicitement une valeur pour une colonne, celle prend la valeur par défaut. Par exemple, si on définit une liste de colonnes qui ne compte pas toutes les colonnes de la tables, toutes les colonnes qui ne sont pas nommées prendront leur valeur par défaut. La définition de la valeur par défaut se fait avec Syntaxe de CREATE TABLE .

  Il est également possible d'utiliser le mot DEFAULT pour qu'une colonne prenne sa valeur par défaut. (Nouveauté de MySQL 4.0.3) Il est ainsi plus simple d'écrire des requêtes INSERT qui donnent des valeurs à toutes les colonnes sauf quelques unes, car cela permet de ne pas avoir à écrire la liste incomplète de VALUES() (une liste qui ne comprend pas une valeur pour chaque colonne de la table). Sans cela, il faudrait écrire la liste des noms de colonnes correspondant a chaque valeur de la liste VALUES() .

  MySQL a toujours une valeur par défaut pour chaque champs. C'est obligatoire pour MySQL pour pouvoir fonctionner aussi bien avec des tables supportant les transactions qu'avec des tables ne les supportant pas.

  Nous pensons que le contrôle du contenu des champs devrait être fait pas l'application et non par le serveur de base de données.

• Une expression peut faire référence à n'importe quelle colonne qui a été définie précédemment dans une liste de valeurs. Par exemple, on peut dire ceci:

  mysql> INSERT INTO nom_de_table (col1,col2) VALUES(15,col1*2);

  Mais pas cela :

  mysql> INSERT INTO nom_de_table (col1,col2) VALUES(col2*2,15);

• Si vous spécifiez l'option DELAYED , le serveur met la ligne ou les lignes à insérer dans un buffer, et le client qui a émis la commande INSERT DELAYED est immédiatement libéré. Si la table est occupée, le serveur conserve les lignes. Lorsque la table se libère, il va insérer les lignes, tout en vérifiant périodiquement s'il n'y a pas de lectures dans la table. Si une lecture arrive, l'insertion est suspendue jusqu'à la prochaine libération.
• Si on spécifie le mot LOW_PRIORITY , l'exécution de INSERT sera retardé jusqu'à ce qu'il n'y ait plus de clients qui lisent la table. Dans ce cas le client doit attendre jusqu'à la fin de l'opération d'insertion, ce qui peut prendre beaucoup de temps si la table est fréquemment accédée. C'est la grande différence avec INSERT DELAYED , qui laisse le client continuer tout de suite. INSERT DELAYED. On peut remarquer que LOW_PRIORITY ne devrait en principe pas être utiliser avec des tables de type MyISAM , étant donné que celle si n'autorisent pas les inserts concurrents. Tables MyISAM .
• Si on spécifie le mot IGNORE dans un INSERT avec les valeurs de plusieurs lignes, chaque ligne qui qui ferait doublon avec une clé PRIMARY ou UNIQUE existante dans la table sera ignoré et ne sera pas insérée. Si on ne spécifie pas IGNORE , l'insert est abandonné si quelque ligne que ce soit fait doublon avec une clé existante. La fonction mysql_info() de l'API C permet de savoir combien de lignes ont été insérées dans la table.
• Si vous spécifiez la clause ON DUPLICATE KEY UPDATE (nouveau en MySQL 4.1.0), et qu'une ligne insérée engendre un doublon pour une clé PRIMARY ou UNIQUE , une commande UPDATE sera faite à la place de l'insertion. Par exemple, la commande :

  mysql> INSERT INTO table (a,b,c) VALUES (1,2,3)     -> ON DUPLICATE KEY UPDATE c=c+1;

  dans le cas où a est déclaré comme UNIQUE et contient déjà 1 , revient à faire

  mysql> UPDATE table SET c=c+1 WHERE a=1;

  Notez : que si la colonne b est aussi unique, la commande UPDATE sera réécrite telle que

  mysql> UPDATE table SET c=c+1 WHERE a=1 OR b=2 LIMIT 1;

  et si a=1 OR b=2 trouve plusieurs lignes, uniquement une ligne sera mise à jour! En général, il faut éviter d'utiliser la clause ON DUPLICATE KEY sur des tables avec des clés UNIQUE multiples.

  Depuis MySQL version 4.1.1, on peut utiliser la fonction VALUES(col_name) pour faire référence à la valeur de la colonne dans la clause INSERT d'une commande INSERT ... UPDATE : c'est la valeur qui serat inserée s'il n'y a pas de conflit de clé. Cette valeur est particulièrement utilise dans les commandes INSERT ... UPDATE et retourne NULL sinon.

  Exemple :

  mysql> INSERT INTO table (a,b,c) VALUES (1,2,3),(4,5,6)     -> ON DUPLICATE KEY UPDATE c=VALUES(a)+VALUES(b);

  La commande ci-dessus est identique à :

  mysql> INSERT INTO table (a,b,c) VALUES (1,2,3)     -> ON DUPLICATE KEY UPDATE c=3; mysql> INSERT INTO table (a,b,c) VALUES (4,5,6)     -> ON DUPLICATE KEY UPDATE c=9;

  Lors de l'utilisation de ON DUPLICATE KEY UPDATE , l'option DELAYED est ignorée.
• Si MySQL a été configuré avec l'option DONT_USE_DEFAULT_FIELDS , les opérations INSERT génère une erreur tant que les valeurs de toutes les colonnes qui attendent une valeur autre que NULL ne sont pas spécifiées explicitement. Les options habituelles de configure .
• Il est possible de récupérer la valeur utilisée pour une colonne AUTO_INCREMENT avec la fonction mysql_insert_id . mysql_insert_id() .

Si on fait une opération INSERT ... SELECT ou INSERT ... VALUES avec plusieurs listes de valeurs, la fonction mysql_info() de l'API C permet d'obtenir des informations relatives à la requête. Le format de la chaîne d'information est la suivante:

Records: 100 Duplicates: 0 Warnings: 0

• Insertion de NULL dans une colonne déclarée NOT NULL . Cette colonne a été enregistrée avec sa valeur par défaut.
• Enregistrement dans une colonne numérique d'une valeur qui déborde de la taille de la colonnes. Cette valeur a été tronquée à l'extrémité la plus adaptée de la colonne.
• Attribution à une colonne numérique d'une valeur telle que '10.34 a' . Celle valeur refusée est séparée, et la partie numérique résultante est insérée. Si cette valeur n'a pas une valeur numérique sensée, la valeur 0 est insérée.
• L'insertion d'une chaîne dans une colonne CHAR , VARCHAR , TEXT , ou BLOB qui dépasse la taille maximale de la colonne. La valeur est tronquée à la taille maximale de la colonne.
• L'insertion d'une valeur illégale pour une colonne de type date ou time. La colonne est alors enregistrée avec la valeur de zero appropriée pour le type.

Sommaire :

• Syntaxe de INSERT ... SELECT
• Syntaxe de INSERT DELAYED