应直接安装活跃维护的jupysql而非已停更的ipython-sql，因其兼容Python 3.12+和最新Jupyter，支持多数据库引擎，但需额外安装对应驱动（如psycopg2-binary、pymysql、duckdb-engine等）才能连接真实数据库。
直接装 jupysql，别用已停更的 ipython-sql —— 后者在 Python 3.12+ 和最新 Jupyter 中大概率报错或不识别 %%sql 魔法命令。
安装 jupysql 与对应数据库驱动
jupysql 是当前维护活跃、兼容性好、支持多引擎（SQLite/PostgreSQL/MySQL/Oracle/DuckDB）的 SQL 扩展。它依赖底层数据库驱动才能连真实库，不是装完就能查任意数据库。
- 基础安装：
%pip install jupysql --quiet（在 notebook 单元中运行，用%pip而非!pip，避免内核路径错乱） - SQLite 不需额外驱动（Python 自带），可立刻试用
- PostgreSQL：额外装
psycopg2-binary或pg8000 - MySQL：装
pymysql或mysql-connector-python - Oracle：必须装
cx_Oracle，且注意 Oracle Client 版本匹配（常见报错DPI-1047就卡在这） - DuckDB：推荐搭配
duckdb-engine（%pip install duckdb-engine），轻量快，适合本地分析
连接数据库的三种写法及坑点
连接字符串格式、用户名密码暴露、连接复用——这几步写错，%%sql 直接报 OperationalError 或静默失败。
- 推荐用
%sql sqlite:///example.db（文件路径用绝对路径更稳，相对路径易因 notebook 工作目录变动失效） - 连远程库时，URL 中密码不能含特殊字符（如
@、/），否则解析失败；应先用urllib.parse.quote_plus()编码 - 别每次查询都新建连接：
%sql第一次执行会缓存连接，后续单元直接写%%sql即可复用；若想换库，得先%sql close再连新地址 - Oracle 连接示例：
%sql oracle://user:password@host:port/service_name，注意 service_name 不是 SID（尤其在 12c+ 上）
写 SQL 单元时的实际限制
%%sql 单元默认只返回查询结果（SELECT），其他语句（CREATE、INSERT、UPDATE）不会报错但也不显示影响行数，容易误以为没生效。
- 确认 DDL/DML 是否成功：在语句后加
; -- echo（jupysql 支持），或单独跑%sql SELECT count(*) FROM table_name - 不支持跨行注释
/* ... */，只认--行尾注释；多行 SQL 用反斜杠\续行，但不如拆成多个单元清晰 - 变量注入用
{var_name}，不是:var_name（后者是 SQLAlchemy 原生语法，jupysql 不认） - 想把结果转成 DataFrame？加
-r参数：result = %sql -r SELECT * FROM users
为什么连上了却查不出数据？
最常被忽略的是数据库路径权限和 schema 可见性，而非 SQL 语法本身。
- SQLite 文件路径写错或 notebook 进程无读写权限 → 报错
unable to open database file - PostgreSQL 默认只查
publicschema，表在其他 schema（如sales）得写全名：SELECT * FROM sales.orders - MySQL 用户没授
SELECT权限，或 host 限制为localhost但 notebook 连的是127.0.0.1（二者在 MySQL 权限系统里不同） - Oracle 用户默认 schema 不是当前登录用户，得显式指定：
SELECT * FROM scott.emp，而不是只写emp
真正麻烦的从来不是装插件，而是驱动版本、连接字符串细节、权限范围这三块拼图对不上——它们不报明显错误，只让查询静默空转或返回空结果集。
