SQLite 不支持通过 ALTER TABLE ... ADD PRIMARY KEY 直接为现有表添加主键；正确做法是重建表并迁移数据，同时在新表定义中声明主键。本文详解完整实现步骤与注意事项。
sqlite 不支持通过 `alter table ... add primary key` 直接为现有表添加主键；正确做法是重建表并迁移数据，同时在新表定义中声明主键。本文详解完整实现步骤与注意事项。
SQLite 是一个轻量级嵌入式数据库，其 ALTER TABLE 语句功能受限——不支持添加、删除或修改主键约束（即使该列已存在且数据唯一）。因此，当你执行如下 Python 代码时：
import sqlite3
conn = sqlite3.connect(':memory:') # 或实际文件路径
c = conn.cursor()
c.execute("CREATE TABLE Persons (ID INTEGER, Name TEXT)")
c.execute("ALTER TABLE Persons ADD PRIMARY KEY (ID)") # ❌ 报错：near "PRIMARY": syntax error会触发 OperationalError，因为 SQLite 的 ALTER TABLE 仅允许重命名表或添加新列（ADD COLUMN），但不能添加约束（如 PRIMARY KEY、UNIQUE、NOT NULL 等）。
✅ 正确解决方案：原子化重建表（Table Recreation）
需分四步完成：
- 启用外键（可选但推荐）：确保完整性约束生效；
- 重命名原表；
- 用含主键的新结构创建同名表；
- 将数据从旧表插入新表，并提交事务。
以下是完整、健壮的 Python 实现示例：
import sqlite3
def add_primary_key(conn, table_name, pk_column):
c = conn.cursor()
try:
conn.execute("BEGIN TRANSACTION")
# 1. 重命名原表
temp_table = f"{table_name}_backup"
c.execute(f"ALTER TABLE {table_name} RENAME TO {temp_table}")
# 2. 查询原表结构（获取所有列及类型）
c.execute(f"PRAGMA table_info({temp_table})")
columns = c.fetchall() # [(cid, name, type, notnull, dflt_value, pk), ...]
# 构建新 CREATE TABLE 语句：确保 pk_column 被标记为 PRIMARY KEY
col_defs = []
for col in columns:
name, type_, notnull, dflt, pk = col[1], col[2], col[3], col[4], col[5]
if name == pk_column:
# 主键列：INTEGER 类型优先设为 INTEGER PRIMARY KEY（自动 ROWID 别名，且高效）
if type_.upper().startswith('INTEGER'):
col_def = f"{name} INTEGER PRIMARY KEY"
else:
col_def = f"{name} {type_} PRIMARY KEY"
else:
# 其他列保留原定义（含 NOT NULL / DEFAULT）
modifiers = ""
if notnull:
modifiers += " NOT NULL"
if dflt is not None:
modifiers += f" DEFAULT {dflt!r}"
col_def = f"{name} {type_}{modifiers}"
col_defs.append(col_def)
create_sql = f"CREATE TABLE {table_name} ({', '.join(col_defs)})"
c.execute(create_sql)
# 3. 迁移数据（显式指定列名，避免顺序/默认值问题）
all_cols = [col[1] for col in columns]
placeholders = ', '.join(['?' for _ in all_cols])
c.execute(f"INSERT INTO {table_name} ({', '.join(all_cols)}) SELECT {', '.join(all_cols)} FROM {temp_table}")
# 4. 删除备份表
c.execute(f"DROP TABLE {temp_table}")
conn.commit()
print(f"✅ 主键已成功添加到表 '{table_name}' 的列 '{pk_column}'")
except Exception as e:
conn.rollback()
raise RuntimeError(f"添加主键失败：{e}")
# 使用示例
conn = sqlite3.connect(':memory:')
c = conn.cursor()
c.execute("CREATE TABLE Persons (ID INTEGER, Name TEXT, Age INTEGER)")
c.execute("INSERT INTO Persons VALUES (1, 'Alice', 30), (2, 'Bob', 25)")
add_primary_key(conn, "Persons", "ID") # ✅ 成功
# 验证主键是否生效
c.execute("PRAGMA table_info(Persons)")
print("新表结构：", c.fetchall()) # 可见 ID 的 pk 字段为 1⚠️ 重要注意事项：
立即学习“Python免费学习笔记（深入）”；
- 数据一致性：务必在事务中执行，避免中途失败导致数据丢失；
- 主键列要求：目标列必须已存在、非空、值唯一，否则 INSERT 阶段将因主键冲突报错；
- INTEGER PRIMARY KEY 特性：若列类型为 INTEGER，建议直接使用 INTEGER PRIMARY KEY，它将自动成为 ROWID 的别名，提升查询性能；
- 索引与外键：重建表后，原表上的索引、外键约束均丢失，需手动重建；
- 生产环境慎用：对大表操作可能耗时较长，建议在维护窗口执行，并提前备份。
总结：SQLite 的设计哲学是“简单可靠”，而非“功能完备”。面对 DDL 局限，开发者应拥抱“重建+迁移”这一标准范式——它虽稍显繁琐，却完全可控、可测试、可回滚，是 SQLite 生态中最被广泛验证的实践方案。
