Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[8.x] Clarify insertOrIgnore is not just duplicate record errors #7308

Merged
merged 4 commits into from
Sep 14, 2021
Merged

[8.x] Clarify insertOrIgnore is not just duplicate record errors #7308

merged 4 commits into from
Sep 14, 2021

Conversation

shrink
Copy link
Contributor

@shrink shrink commented Sep 14, 2021

The insertOrIgnore method is very helpful, but it is important to understand the consequences. The method is accurately described in code as:

/**
 * Insert new records into the database while ignoring errors.
 */
public function insertOrIgnore(array $values)

However, the documentation describes it in the context of duplicate errors:

The insertOrIgnore method will ignore duplicate record errors while inserting records into the database:

The statement may be interpreted as insertOrIgnore being equivalent to something like skipOnDuplicate. Unfortunately, insertOrIgnore has a number of consequences -- depending on database engine -- such as bypassing multiple MySQL Strict-mode restrictions: it is important that it is not considered equivalent to something like skipOnDuplicate.

The link in the warning to the MySQL documentation is without version (i.e: a link to the latest documentation) because this behaviour has been stable across multiple versions (5.7, 8.0) but we could change the link to 5.7 since that is the minimum recommended version for Laravel 8.0 -- if a link to external documentation must be pinned to a version.

[1] List of errors ignored by ignore as of MySQL version 5.7:

ER_BAD_NULL_ERROR
ER_DUP_ENTRY
ER_DUP_ENTRY_WITH_KEY_NAME
ER_DUP_KEY
ER_NO_PARTITION_FOR_GIVEN_VALUE
ER_NO_PARTITION_FOR_GIVEN_VALUE_SILENT
ER_NO_REFERENCED_ROW_2
ER_ROW_DOES_NOT_MATCH_GIVEN_PARTITION_SET
ER_ROW_IS_REFERENCED_2
ER_SUBQUERY_NO_1_ROW
ER_VIEW_CHECK_FAILED

@shrink shrink changed the title Clarify insertOrIgnore is not just duplicate record errors [8.x] Clarify insertOrIgnore is not just duplicate record errors Sep 14, 2021
@taylorotwell taylorotwell merged commit 5af5c42 into laravel:8.x Sep 14, 2021
@dunhamjared
Copy link
Contributor

Thank you for the contribution @shrink!

The clarification and note is really good to have in the docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants