How To Guides
How to use UPSERT in MySQL?

How to use UPSERT in MySQL?

In this article, we will explore the UPSERT feature in MySQL and how you can leverage it for effective database management. UPSERT, a combination of the words "UPDATE" and "INSERT," allows you to insert new records or update existing ones based on certain conditions. Understanding UPSERT and its syntax is crucial for efficiently manipulating data in your MySQL database.

Understanding UPSERT in MySQL

Before delving into the syntax and practical usage of UPSERT in MySQL, let's define what UPSERT actually means within the context of database management.

UPSERT is an operation that combines the functionalities of INSERT and UPDATE commands. It allows you to insert new records into a table or update an existing record if it already exists. This can be particularly useful when dealing with scenarios where you want to insert a new row into a table unless a specific condition is met, in which case you would update the existing row instead.

By using UPSERT, you can streamline your data manipulation processes and avoid cumbersome workarounds like checking for existing records separately before deciding whether to insert or update. It provides a concise and efficient way to handle these scenarios without sacrificing performance.

Definition of UPSERT

UPSERT is not a feature that is natively provided by all database management systems. In MySQL, UPSERT functionality can be achieved using a combination of INSERT and UPDATE queries. The INSERT statement is used to add new rows to a table, while the UPDATE statement modifies existing rows. The UPSERT operation effectively combines these two commands, allowing you to perform both actions in a single statement.

While UPSERT is not a standard SQL command, it has become a common term used to describe this type of operation. Several databases and programming languages provide their own implementation of UPSERT-like functionality.

Importance of UPSERT in Database Management

Database management systems play a crucial role in storing and organizing data, and efficiently manipulating this data is essential for many applications. UPSERT is an important feature in database management as it allows for optimized manipulation of records, reducing complexity and improving performance.

Consider a scenario where you have a table to store customer orders, and you want to keep track of both new orders and any updates to existing orders. Using UPSERT, you can easily handle this situation by inserting new records when a customer places a new order and updating existing records if any changes occur.

Without UPSERT, you would need to first check if a record exists for the particular order, and then decide whether to insert a new record or update the existing one. This additional step introduces unnecessary complexity and can impact performance, especially when handling large datasets.

By utilizing UPSERT, you can streamline your code and simplify your data manipulation processes, resulting in cleaner and more efficient database management.

Prerequisites for Using UPSERT

Before diving into the syntax and practical examples of UPSERT in MySQL, it's essential to have a basic knowledge of SQL and ensure that your MySQL environment is set up correctly.

Basic Knowledge of SQL

Since UPSERT relies on the combination of INSERT and UPDATE statements, having a solid understanding of these basic SQL commands is crucial. Familiarize yourself with the syntax and usage of both INSERT and UPDATE statements to effectively grasp how UPSERT works.

If you are new to SQL, several resources are available online that provide tutorials and guides to help you get started.

Setting Up Your MySQL Environment

Ensure that you have a functional MySQL environment to practice and implement UPSERT. You can either install MySQL locally or use an online tool that provides a MySQL database instance.

If you choose to install MySQL locally, make sure you have a compatible version installed and running. Verify that you can connect to the MySQL server using the credential details you have set up.

Syntax of UPSERT in MySQL

Now that we have covered the basics let's take a closer look at the syntax of UPSERT statements in MySQL.

Breaking Down the UPSERT Syntax

The UPSERT functionality in MySQL can be achieved using the INSERT INTO ... ON DUPLICATE KEY UPDATE statement. Let's break down the syntax:

  1. Start with the INSERT INTO statement, specifying the table name and the columns you want to populate.
  2. Follow with the VALUES statement, providing the values you want to insert into the specified columns.
  3. Include the ON DUPLICATE KEY UPDATE clause. This clause specifies the column(s) to be updated and the values to be assigned in case a duplicate key conflict occurs.

By using this syntax, you can insert new records into the specified table, and if a duplicate key conflict arises, the specified columns will be updated instead.

Common UPSERT Syntax Errors and How to Avoid Them

While the UPSERT syntax is relatively straightforward, there are a few common errors that beginners may encounter.

One common mistake is forgetting to define the primary key constraint on the table. Without a primary key or unique constraint, MySQL cannot determine whether a new record should be inserted or an existing record should be updated, resulting in an error.

To avoid this error, ensure that your table has a primary key or a unique constraint defined on the column(s) that you want to use as the basis for determining duplicate records.

Another potential error is providing incorrect column names or values for the INSERT or UPDATE portion of the UPSERT statement. To avoid this, double-check your column names and values, ensuring they match the table definition and data types.

By doing so, you can minimize syntax errors and achieve successful UPSERT operations.

Step-by-Step Guide to Using UPSERT

Now that we have covered the syntax and prerequisites, let's walk through a step-by-step guide to using UPSERT in MySQL.

Creating a Sample Database for UPSERT

First, let's create a sample database to work with. Use the CREATE DATABASE statement along with the desired database name. For example:

CREATE DATABASE sample_database;

Once the database is created, make sure to use it in your subsequent commands by using the USE statement:

USE sample_database;

Writing Your First UPSERT Statement

Now that we have set up the sample database, let's write our first UPSERT statement. Suppose we have a table named "customers" with columns "id," "name," and "email."

Our goal is to UPSERT a new customer or update an existing customer based on their email address. Here is an example UPSERT statement:

INSERT INTO customers (name, email) VALUES ('John Doe', '') ON DUPLICATE KEY UPDATE name = 'John Doe';

This statement attempts to insert a new customer with the name "John Doe" and email "" into the "customers" table.

If a duplicate key conflict occurs (i.e., another customer with the same email already exists), the statement updates the existing record, setting the name to "John Doe".

By executing this UPSERT statement, you can insert new customers or update existing ones based on their email addresses.

Troubleshooting Common UPSERT Issues

As with any database operation, UPSERT statements can encounter a few issues that may require troubleshooting. Let's look at some common problems and how to handle them.

Dealing with Duplicate Key Error

When performing an UPSERT operation, encountering a duplicate key error is a possibility. This error occurs when you attempt to insert a record with a value that conflicts with an existing record's primary key or unique constraint.

To handle this error, you can choose to either update the existing record or ignore the duplicate entirely. You can modify the UPSERT statement by specifying the appropriate action in the ON DUPLICATE KEY UPDATE clause.

For example, to ignore the duplicate and keep the existing record unchanged, you can use the following syntax:

INSERT INTO customers (name, email) VALUES ('John Doe', '') ON DUPLICATE KEY UPDATE name = name;

By setting the name column to its current value, the statement effectively disregards the duplicate key error and leaves the existing record untouched.

Handling Null Values in UPSERT

Another challenge you may face when working with UPSERT is handling null values. Null values can cause unexpected behavior, especially when you attempt to insert or update a column with a non-nullable constraint.

To tackle this issue, ensure that your UPSERT statement provides valid and non-null values for all required columns. Avoid setting null values for columns that cannot accept nulls, as this will result in an error.

If you encounter a situation where null values are acceptable, you can use conditional statements within your UPSERT query to handle them appropriately. By validating and assigning appropriate default values in such cases, you can avoid conflicts and ensure the smooth execution of your UPSERT operations.


In conclusion, UPSERT is a valuable feature in MySQL that streamlines data manipulation processes by combining the functionalities of INSERT and UPDATE statements. By understanding the UPSERT syntax and troubleshooting common issues, you can effectively utilize this feature to insert new records or update existing ones based on specific conditions.

Remember to have a solid understanding of SQL, ensure your MySQL environment is set up correctly, and double-check your UPSERT syntax to avoid errors. By following these guidelines, you can leverage UPSERT to enhance your database management practices and optimize your data manipulation workflows.

Mastering UPSERT will undoubtedly empower you with a powerful tool for efficient and effective database management in MySQL.

New Release

Get in Touch to Learn More

See Why Users Love CastorDoc
Fantastic tool for data discovery and documentation

“[I like] The easy to use interface and the speed of finding the relevant assets that you're looking for in your database. I also really enjoy the score given to each table, [which] lets you prioritize the results of your queries by how often certain data is used.” - Michal P., Head of Data