{
  "id": "php/pdo-sqlstate-23000-duplicate-entry-unique-constraint",
  "signature": "PDOException: SQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry 'john@example.com' for key 'users_email_unique'",
  "signature_zh": "PDOException：SQLSTATE[23000]：完整性约束违反：键 'users_email_unique' 的重复条目 'john@example.com'",
  "regex": "SQLSTATE\\[23000\\].*1062 Duplicate entry.*for key",
  "domain": "php",
  "category": "data_error",
  "subcategory": null,
  "root_cause": "An INSERT or UPDATE operation attempted to create a duplicate value in a column that has a UNIQUE constraint, usually due to race conditions, missing checks, or concurrent requests.",
  "root_cause_type": "generic",
  "root_cause_zh": "INSERT 或 UPDATE 操作尝试在具有 UNIQUE 约束的列中创建重复值，通常由于竞态条件、缺少检查或并发请求导致。",
  "versions": [
    {
      "version": "MySQL 8.0.34",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "MariaDB 10.11.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "PHP 8.2.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Removing the UNIQUE constraint on the column to allow duplicates",
      "why_fails": "This violates data integrity and can lead to application logic bugs; not a real fix but a workaround that breaks the schema.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    },
    {
      "action": "Wrapping every INSERT in a SELECT to check existence first without using transactions",
      "why_fails": "Race conditions still occur between SELECT and INSERT in concurrent environments; does not solve the problem reliably.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Use INSERT IGNORE or ON DUPLICATE KEY UPDATE to handle duplicates gracefully:\n$stmt = $pdo->prepare('INSERT INTO users (email, name) VALUES (:email, :name) ON DUPLICATE KEY UPDATE name = VALUES(name)');\n$stmt->execute([':email' => 'john@example.com', ':name' => 'John']);",
      "success_rate": 0.95,
      "how": "Use INSERT IGNORE or ON DUPLICATE KEY UPDATE to handle duplicates gracefully:\n$stmt = $pdo->prepare('INSERT INTO users (email, name) VALUES (:email, :name) ON DUPLICATE KEY UPDATE name = VALUES(name)');\n$stmt->execute([':email' => 'john@example.com', ':name' => 'John']);",
      "condition": "",
      "sources": []
    },
    {
      "action": "Implement a retry mechanism with a short delay if the exception occurs:\ntry { $stmt->execute(); } catch (PDOException $e) { if ($e->errorInfo[1] == 1062) { usleep(100000); $stmt->execute(); } else { throw $e; } }",
      "success_rate": 0.8,
      "how": "Implement a retry mechanism with a short delay if the exception occurs:\ntry { $stmt->execute(); } catch (PDOException $e) { if ($e->errorInfo[1] == 1062) { usleep(100000); $stmt->execute(); } else { throw $e; } }",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "使用 INSERT IGNORE 或 ON DUPLICATE KEY UPDATE 优雅处理重复：\n$stmt = $pdo->prepare('INSERT INTO users (email, name) VALUES (:email, :name) ON DUPLICATE KEY UPDATE name = VALUES(name)');\n$stmt->execute([':email' => 'john@example.com', ':name' => 'John']);",
    "实现带有短暂延迟的重试机制：\ntry { $stmt->execute(); } catch (PDOException $e) { if ($e->errorInfo[1] == 1062) { usleep(100000); $stmt->execute(); } else { throw $e; } }"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://dev.mysql.com/doc/refman/8.0/en/error-mysql-server.html#error_er_dup_entry",
  "official_doc_section": null,
  "error_code": "1062",
  "verification_tier": "ai_generated",
  "confidence": 0.9,
  "fix_success_rate": 0.85,
  "resolvable": "true",
  "first_seen": "2024-02-10",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}