Ошибка UNIQUE constraint failed: users.id в SQLite - причины и решение

При работе с SQLite через Python многие разработчики сталкиваются с ошибкой sqlite3.IntegrityError: UNIQUE constraint failed: users.id. Это происходит, когда вы пытаетесь вставить запись с идентификатором, который уже существует в таблице. В исходном коде проверка if user is None не гарантирует, что запись с таким user_id отсутствует - возможно, она была вставлена в другой транзакции или проверка не учитывает состояние базы данных. Разберём подробно причины и способы устранения.

Почему возникает ошибка UNIQUE constraint?

Ошибка UNIQUE constraint failed: users.id указывает на нарушение уникальности первичного ключа или уникального индекса. В таблице users поле id, скорее всего, объявлено как INTEGER PRIMARY KEY, что автоматически накладывает ограничение UNIQUE. Когда вы выполняете INSERT с уже существующим user_id, SQLite отклоняет операцию.

Основные причины:

• Некорректная проверка существования пользователя - запрос SELECT может вернуть None из-за ошибки или неправильного условия, но запись уже есть.
• Конкуренция транзакций - если несколько потоков или запросов одновременно пытаются вставить одного пользователя, один из них может пройти проверку, а другой - нет.
• Отсутствие обработки дубликатов - код не предусматривает альтернативу, если пользователь уже существует.

Как исправить ошибку: практические решения

1. Использовать INSERT OR IGNORE

Самый простой способ - заменить INSERT на INSERT OR IGNORE. Если запись с таким id уже есть, операция будет проигнорирована без ошибки:

cur.execute('INSERT OR IGNORE INTO users(id, name, balance) VALUES (?,?,?)', (user_id, call.message.chat.first_name, 0))

2. Использовать INSERT OR REPLACE

Если нужно обновить данные существующей записи, используйте INSERT OR REPLACE (аналог UPSERT). Он удалит старую строку и вставит новую:

cur.execute('INSERT OR REPLACE INTO users(id, name, balance) VALUES (?,?,?)', (user_id, call.message.chat.first_name, 0))

3. Реализовать корректную проверку с блокировкой

Для надёжной проверки используйте транзакцию с SELECT ... FOR UPDATE (в SQLite нет прямого аналога, но можно использовать BEGIN IMMEDIATE):

conn.execute('BEGIN IMMEDIATE') cur.execute('SELECT id FROM users WHERE id = ?', (user_id,)) if cur.fetchone() is None: cur.execute('INSERT INTO users(id, name, balance) VALUES (?,?,?)', (user_id, call.message.chat.first_name, 0)) conn.commit() else: # обновить баланс или выполнить другую логику conn.commit()

4. Использовать UPSERT (SQLite 3.24.0+)

Начиная с версии SQLite 3.24.0, поддерживается синтаксис ON CONFLICT:

cur.execute(''' INSERT INTO users(id, name, balance) VALUES (?,?,?) ON CONFLICT(id) DO UPDATE SET name = excluded.name, balance = excluded.balance ''', (user_id, call.message.chat.first_name, 0))

Проверка структуры таблицы

Убедитесь, что таблица создана правильно. Распространённая ошибка - объявление id как INTEGER PRIMARY KEY AUTOINCREMENT, но при этом ручная вставка значений. Если вы хотите, чтобы SQLite генерировал id автоматически, не передавайте user_id в INSERT:

CREATE TABLE users ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, balance INTEGER DEFAULT 0 );

Тогда вставка будет выглядеть так: INSERT INTO users(name, balance) VALUES (?,?).

Заключение

Ошибка UNIQUE constraint failed: users.id решается выбором подходящего метода вставки: INSERT OR IGNORE для пропуска дубликатов, INSERT OR REPLACE для замены, или UPSERT для гибкого обновления. Всегда проверяйте логику проверки существования пользователя и используйте транзакции для избежания гонок данных.