diff --git a/jOOQ-website/src/main/resources/manual-2.5.xml b/jOOQ-website/src/main/resources/manual-2.5.xml index d59b27e8fd..ba912f73e7 100644 --- a/jOOQ-website/src/main/resources/manual-2.5.xml +++ b/jOOQ-website/src/main/resources/manual-2.5.xml @@ -1890,17 +1890,173 @@ create.selectFrom(AUTHOR)
The INSERT statement - + +

INSERT Statements

+

+ The INSERT statement is used to insert new records into a database table. Records can either be supplied using a VALUES() constructor, or a SELECT statement. jOOQ supports both types of INSERT statements. An example of an INSERT statement using a VALUES() constructor is given here: +

+ + + +INSERT INTO AUTHOR + (ID, FIRST_NAME, LAST_NAME) +VALUES (100, 'Hermann', 'Hesse'); +create.insertInto(AUTHOR, + AUTHOR.ID, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME) + .values(100, "Hermann", "Hesse"); + +

INSERT multiple rows with the VALUES() constructor

+

+ The SQL standard specifies that multiple rows can be supplied to the VALUES() constructor in an INSERT statement. Here's an example of a multi-record INSERT +

+ +INSERT INTO AUTHOR + (ID, FIRST_NAME, LAST_NAME) +VALUES (100, 'Hermann', 'Hesse'), + (101, 'Alfred', 'Döblin'); +create.insertInto(AUTHOR, + AUTHOR.ID, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME) + .values(100, "Hermann", "Hesse") + .values(101, "Alfred", "Döblin"); + +

+ jOOQ tries to stay close to actual SQL. In detail, however, Java's expressiveness is limited. That's why the values() clause is repeated for every record in multi-record inserts. +

+

+ Some RDBMS do not support inserting several records in a single statement. In those cases, jOOQ simulates multi-record INSERTs using the following SQL: +

+ + +INSERT INTO AUTHOR + (ID, FIRST_NAME, LAST_NAME) +SELECT 100, 'Hermann', 'Hesse' FROM DUAL UNION ALL +SELECT 101, 'Alfred', 'Döblin' FROM DUAL; +create.insertInto(AUTHOR, + AUTHOR.ID, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME) + .values(100, "Hermann", "Hesse") + .values(101, "Alfred", "Döblin"); + + +

INSERT using jOOQ's alternative syntax

+

+ MySQL (and some other RDBMS) allow for using a non-SQL-standard, UPDATE-like syntax for INSERT statements. This is also supported in jOOQ, should you prefer that syntax. The above INSERT statement can also be expressed as follows: +

+ +create.insertInto(AUTHOR) + .set(AUTHOR.ID, 100) + .set(AUTHOR.FIRST_NAME, "Hermann") + .set(AUTHOR.LAST_NAME, "Hesse") + .newRecord() + .set(AUTHOR.ID, 101) + .set(AUTHOR.FIRST_NAME, "Alfred") + .set(AUTHOR.LAST_NAME, "Döblin"); + +

+ As you can see, this syntax is a bit more verbose, but also more type-safe, as every field can be matched with its value. Internally, the two syntaxes are strictly equivalent. +

+ +

MySQL's INSERT .. ON DUPLICATE KEY UPDATE

+

+ The MySQL database supports a very convenient way to INSERT or UPDATE a record. This is a non-standard extension to the SQL syntax, which is supported by jOOQ and simulated in other RDBMS, where this is possible (i.e. if they support the SQL standard ). Here is an example how to use the ON DUPLICATE KEY UPDATE clause: +

+ +// Add a new author called "Koontz" with ID 3. +// If that ID is already present, update the author's name +create.insertInto(AUTHOR, AUTHOR.ID, AUTHOR.LAST_NAME) + .values(3, "Koontz") + .onDuplicateKeyUpdate() + .set(AUTHOR.LAST_NAME, "Koontz"); + +

The synthetic ON DUPLICATE KEY IGNORE clause

+ +

+ The MySQL database also supports an INSERT IGNORE INTO clause. This is supported by jOOQ using the more convenient SQL syntax variant of ON DUPLICATE KEY IGNORE, which can be equally simulated in other databases using a : +

+ +// Add a new author called "Koontz" with ID 3. +// If that ID is already present, ignore the INSERT statement +create.insertInto(AUTHOR, AUTHOR.ID, AUTHOR.LAST_NAME) + .values(3, "Koontz") + .onDuplicateKeyIgnore(); + +

Postgres's INSERT .. RETURNING

+

+ The Postgres database has native support for an INSERT .. RETURNING clause. This is a very powerful concept that is simulated for all other dialects using JDBC's method. Take this example: +

+ + record = +create.insertInto(AUTHOR, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME) + .values("Charlotte", "Roche") + .returning(AUTHOR.ID) + .fetchOne(); + +System.out.println(record.getValue(AUTHOR.ID)); + +// For some RDBMS, this also works when inserting several values +// The following should return a 2x2 table +Result result = +create.insertInto(AUTHOR, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME) + .values("Johann Wolfgang", "von Goethe") + .values("Friedrich", "Schiller") + // You can request any field. Also trigger-generated values + .returning(AUTHOR.ID, AUTHOR.CREATION_DATE) + .fetch();]]> + +

+ Some databases have poor support for returning generated keys after INSERTs. In those cases, jOOQ might need to issue another in order to fetch an @@identity value. Be aware, that this can lead to race-conditions in those databases that cannot properly return generated ID values. For more information, please consider the jOOQ Javadoc for the returning() clause. +

+ +

The INSERT SELECT statement

+ +

+ In some occasions, you may prefer the INSERT SELECT syntax, for instance, when you copy records from one table to another: +

+ +create.insertInto(AUTHOR_ARCHIVE) + .select(create.selectFrom(AUTHOR).where(AUTHOR.DECEASED.isTrue())); + +
The UPDATE statement - + +

UPDATE Statements

+

+ The UPDATE statement is used to modify one or several pre-existing records in a database table. UPDATE statements are only possible on single tables. Support for multi-table updates will be implemented in the near future. An example update query is given here: +

+ + +UPDATE AUTHOR + SET FIRST_NAME = 'Hermann', + LAST_NAME = 'Hesse' + WHERE ID = 3; +create.update(AUTHOR) + .set(AUTHOR.FIRST_NAME, "Hermann") + .set(AUTHOR.LAST_NAME, "Hesse") + .where(AUTHOR.ID.equal(3)); + + +
The DELETE statement - + +

DELETE Statements

+

+ The DELETE statement physically removes records from a database table. DELETE statements are only possible on single tables. Support for multi-table deletes will be implemented in the near future. An example delete query is given here: +

+ + +DELETE AUTHOR + WHERE ID = 100; +create.delete(AUTHOR) + .where(AUTHOR.ID.equal(100)); + + +
@@ -1917,21 +2073,18 @@ create.selectFrom(AUTHOR) -- Check if there is already an author called 'Hitchcock' -- If there is, rename him to John. If there isn't add him. - -MERGE INTO T_AUTHOR +MERGE INTO AUTHOR USING (SELECT 1 FROM DUAL) ON (LAST_NAME = 'Hitchcock') WHEN MATCHED THEN UPDATE SET FIRST_NAME = 'John' -WHEN NOT MATCHED THEN INSERT (LAST_NAME) - VALUES ('Hitchcock') -create.mergeInto(T_AUTHOR) +WHEN NOT MATCHED THEN INSERT (LAST_NAME) VALUES ('Hitchcock') +create.mergeInto(AUTHOR) .using(create().selectOne()) - .on(T_AUTHOR.LAST_NAME.equal("Hitchcock")) + .on(AUTHOR.LAST_NAME.equal("Hitchcock")) .whenMatchedThenUpdate() - .set(T_AUTHOR.FIRST_NAME, "John") - .whenNotMatchedThenInsert(T_AUTHOR.LAST_NAME) - .values("Hitchcock") - .execute(); + .set(AUTHOR.FIRST_NAME, "John") + .whenNotMatchedThenInsert(AUTHOR.LAST_NAME) + .values("Hitchcock"); @@ -1944,13 +2097,13 @@ WHEN NOT MATCHED THEN INSERT (LAST_NAME) -- Check if there is already an author called 'Hitchcock' -- If there is, rename him to John. If there isn't add him. -MERGE INTO T_AUTHOR (FIRST_NAME, LAST_NAME) +MERGE INTO AUTHOR (FIRST_NAME, LAST_NAME) KEY (LAST_NAME) VALUES ('John', 'Hitchcock') -create.mergeInto(T_AUTHOR, - T_AUTHOR.FIRST_NAME, - T_AUTHOR.LAST_NAME) - .key(T_AUTHOR.LAST_NAME) +create.mergeInto(AUTHOR, + AUTHOR.FIRST_NAME, + AUTHOR.LAST_NAME) + .key(AUTHOR.LAST_NAME) .values("John", "Hitchcock") .execute();