// справочник ошибок SQL Server

Ошибка SQL Server 2627: нарушение ограничений PRIMARY KEY или UNIQUE KEY

INSERT или UPDATE приведут к дублированию значения в ограничении PRIMARY KEY или UNIQUE. В сообщении названы ограничение, таблица и дублирующееся значение ключа.

Номер ошибки
2627
Уровень серьёзности
14
Категория
Ограничения и ключи
Сообщение об ошибке
Violation of %ls constraint '%.*ls'. Cannot insert duplicate key in object '%.*ls'. The duplicate key value is %ls.

Что это значит

Ограничения первичного ключа и уникальные ограничения гарантируют, что никакие две строки не будут иметь одинаковый ключ. Когда операция записи создала бы дубликат, SQL Server прерывает инструкцию с ошибкой 2627, а затем 3621 («Выполнение инструкции было прервано»). В сообщении указано, какой тип ограничения (PRIMARY KEY или UNIQUE KEY), его имя, таблица, а начиная с SQL Server 2017 — само дублирующее значение.

Ошибка 2601 — это тот же сбой на уникальном индексе, который не является ограничением.

Распространённые причины

  • Вставка строки с уже существующим ключом, например повторная загрузка.
  • Вставка явных значений в столбец идентификаторов с IDENTITY_INSERT включённым, или сброс начального значения идентификатора ниже существующих значений.
  • Пакетная вставка из источника, который сам содержит дублирующиеся ключи.
  • Две сессии вставляют один и тот же ключ одновременно: шаблон проверки перед вставкой (IF NOT EXISTS ... INSERT) небезопасен без подсказок блокировки.

Как исправить

  1. Найдите существующую строку, используя значение, указанное в сообщении.

    SELECT * FROM dbo.Customers WHERE Email = N'[email protected]';
  2. Пропускайте строки, которые уже существуют при загрузке.

    INSERT INTO dbo.Customers (Email, Name)
    SELECT s.Email, s.Name
    FROM staging.Customers AS s
    WHERE NOT EXISTS (SELECT 1 FROM dbo.Customers AS c WHERE c.Email = s.Email);
  3. Ищите дубликаты в источнике перед вставкой.

    SELECT Email, COUNT(*) FROM staging.Customers GROUP BY Email HAVING COUNT(*) > 1;
  4. Чтобы upsert был безопасен при конкурентном доступе, сначала обновите строку, а если ничего не обновилось — вставьте её, удерживая блокировку диапазона.

    BEGIN TRANSACTION;
    UPDATE dbo.Customers WITH (UPDLOCK, SERIALIZABLE) SET Name = @Name WHERE Email = @Email;
    IF @@ROWCOUNT = 0
        INSERT INTO dbo.Customers (Email, Name) VALUES (@Email, @Name);
    COMMIT;
  5. Если значения столбца identity конфликтуют, проверьте и сбросьте его начальное значение (reseed).

    DBCC CHECKIDENT ('dbo.Customers', NORESEED);  -- shows current and max values
    DBCC CHECKIDENT ('dbo.Customers', RESEED);

Безопасное воспроизведение

CREATE TABLE #k (id int PRIMARY KEY);
INSERT INTO #k VALUES (1);
INSERT INTO #k VALUES (1);  -- Msg 2627 ... The duplicate key value is (1).
DROP TABLE #k;

Вопросы

В чем разница между ошибками 2627 и 2601?

2627 возникает из-за ограничения PRIMARY KEY или UNIQUE; 2601 — из-за уникального индекса, созданного с помощью CREATE UNIQUE INDEX. Причина и способы исправления одинаковы.

Можно ли заставить SQL Server игнорировать дублирующие ключи?

Уникальный индекс, созданный с WITH (IGNORE_DUP_KEY = ON), отбрасывает дубликаты при INSERT с предупреждением, а не завершает оператор ошибкой. Используйте его осознанно: он молча теряет данные.

Связанные ошибки

Больше ошибок ограничений и ключей

Код и текст сообщения взяты из Справочник по событиям и ошибкам Microsoft Database Engine. Смотрите весь Список ошибок SQL Server или поиск по всем ошибкам баз данных.

// меньше ошибок, быстрее исправления

Работа с SQL Server в SQLly

Нативный SQL-клиент для macOS, Windows и Linux с IntelliSense, который знает вашу схему, предохранителями для рискованных запросов и понятными сообщениями об ошибках — для SQL Server и других баз данных, которые вы используете.