August 1, 2023
Summary: in this tutorial, you will learn how to use PostgreSQL upsert feature to insert or update data if the row that is being inserted already exists in the table.
Introduction to the PostgreSQL upsert
In relational databases, the term upsert is referred to as merge. The idea is that when you insert a new row into the table, PostgreSQL will update the row if it already exists, otherwise, it will insert the new row. That is why we call the action is upsert (the combination of update or insert).
To use the upsert feature in PostgreSQL, you use the
INSERT ON CONFLICT statement as follows:
INSERT INTO table_name(column_list) VALUES(value_list) ON CONFLICT target action;
PostgreSQL added the
ON CONFLICT target action clause to the
INSERT statement to support the upsert feature.
In this statement, the
target can be one of the following:
(column_name)– a column name.
ON CONSTRAINT constraint_name– where the constraint name could be the name of the UNIQUE constraint.
WHERE predicate– a WHERE clause with a predicate.
action can be one of the following:
DO NOTHING– means do nothing if the row already exists in the table.
DO UPDATE SET column_1 = value_1, .. WHERE condition– update some fields in the table.
Notice that the
ON CONFLICTclause is only available from PostgreSQL 9.5. If you are using an earlier version, you will need a workaround to have the upsert feature.
If you are also working with MySQL, you will find that the upsert feature is similar to the
insert on duplicate key update statement in MySQL.
PostgreSQL upsert examples
The following statement creates a new table called
customers to demonstrate the PostgreSQL upsert feature.
DROP TABLE IF EXISTS customers; CREATE TABLE customers ( customer_id serial PRIMARY KEY, name VARCHAR UNIQUE, email VARCHAR NOT NULL, active bool NOT NULL DEFAULT TRUE );
customers table consists of four columns:
name column has a unique constraint to guarantee the uniqueness of customer names.
The following INSERT statement inserts some rows into the
INSERT INTO customers (name, email) VALUES ('IBM', 'firstname.lastname@example.org'), ('Microsoft', 'email@example.com'), ('Intel', 'firstname.lastname@example.org');
Suppose Microsoft changes the contact email from “email@example.com” to “firstname.lastname@example.org”, we can update it using the UPDATE statement. However, to demonstrate the upsert feature, we use the following
INSERT ON CONFLICT statement:
INSERT INTO customers (NAME, email) VALUES('Microsoft','email@example.com') ON CONFLICT ON CONSTRAINT customers_name_key DO NOTHING;
The statement specified that if the customer name exists in the
customers table, just ignore it (do nothing).
The following statement is equivalent to the above statement but it uses the
name column instead of the unique constraint name as the target of the
INSERT INTO customers (name, email) VALUES('Microsoft','firstname.lastname@example.org') ON CONFLICT (name) DO NOTHING;
Suppose, you want to concatenate the new email with the old email when inserting a customer that already exists, in this case, you use the
UPDATE clause as the action of the
INSERT statement as follows:
INSERT INTO customers (name, email) VALUES('Microsoft','email@example.com') ON CONFLICT (name) DO UPDATE SET email = EXCLUDED.email || ';' || customers.email;
INSERT 0 1
The following statement verifies the upsert:
In this tutorial, you have learned about the PostgreSQL upsert feature using the
INSERT ON CONFLICT statement.