Schema前缀隔离是最易落地的租户隔离方案，无需改表结构、不依赖tenant_id字段、不增加查询条件，仅需连接层动态切换schema名即可实现物理级隔离。
直接用 schema 前缀隔离是最容易落地、也最接近“开箱即用”的方案——它不需要改表结构、不依赖 tenant_id 字段、不增加查询条件，只要在连接层动态切换 schema 名，就能实现租户间物理级隔离。
为什么选 schema 前缀而不是 tenant_id 字段过滤
行级隔离（tenant_id）看似简单，但实际踩坑极多：漏加 where tenant_id = ? 就导致数据越界；软删除、关联查询、聚合统计容易出错；权限控制必须层层校验；审计和备份也难按租户粒度操作。而 schema 隔离由数据库原生保障，连 DBA 都能一眼看出哪个 schema 属于哪个租户，运维、迁移、权限分配都更可控。
Hyperf 的 hyperf/database 支持运行时覆盖 schema 配置，配合协程上下文，完全可做到请求级隔离，无需为每个租户建独立连接池。
常见错误现象：
- 手动拼接表名如
"{$schema}.user"写死在 SQL 中 → 无法走 Query Builder，丢失预处理、防注入、ORM 关联能力 - 在
Model::getTable()里返回带 schema 的全名 → Laravel 风格写法在 Hyperf 中会破坏连接绑定逻辑 - 未清除协程上下文，导致异步任务或定时器复用上一个租户的
schema→ 数据写错库
Hyperf 中动态设置 PostgreSQL / MySQL schema 的正确姿势
核心是重写数据库连接的 schema 配置项，而非改表名或 SQL。Hyperf 的 Connection 实例在初始化时会读取配置中的 schema 值，且该值支持运行时修改（前提是连接未建立或已释放）。
实操建议：
- 在租户解析中间件（如
TenantResolveMiddleware）中调用TenantContext::set($tenantId, $tenantCode) - 在模型基类
BaseTenantModel的构造函数中，通过$this->getConnection()->getConfig('schema')获取当前连接配置，并用setConfig('schema', $tenantCode)覆盖 - 确保每次请求只初始化一次连接：Hyperf 默认使用连接池，需在
onConnect回调或首次查询前完成schema设置，避免并发请求争抢同一连接 - MySQL 用户注意：
schema等价于database，配置中写'database' => env('DB_DATABASE', 'saas')后，运行时设setConfig('database', $tenantCode)即可
示例（PostgreSQL）：
class BaseTenantModel extends Model
{
public function __construct(array $attributes = [])
{
parent::__construct($attributes);
$tenantCode = TenantContext::code();
if ($tenantCode) {
$connection = $this->getConnection();
$connection->setConfig('schema', $tenantCode);
}
}
}
连接池与 schema 切换的性能陷阱
Hyperf 的连接池默认复用连接，但 schema 是连接级别的状态。如果两个不同租户的请求被分配到同一个连接，后一个请求会覆盖前一个的 schema，造成数据错乱。
解决方式不是禁用连接池，而是让连接“感知租户”：
- 在
config/autoload/databases.php中开启'pool' => ['max_idle_time' => 10.0]，缩短空闲连接存活时间 - 在中间件末尾显式调用
$this->getConnection()->close()（仅限短生命周期请求），强制归还连接前重置状态 - 更稳妥的做法：使用
Connection::using($name, fn() => {...})包裹租户专属查询，Hyperf 会自动创建并销毁临时连接 - 避免在
go协程中跨租户调用 DB —— 协程上下文不继承，TenantContext::code()可能为空
迁移、测试与部署时 schema 隔离的盲区
开发期用 php bin/hyperf.php migrate 默认跑在 public schema，不会自动为每个租户执行迁移。这会导致新租户 schema 为空，或字段缺失。
必须做三件事：
- 迁移命令需指定
--schema=tenant_a参数（Hyperf 3.2+ 支持），或封装脚本循环执行：for schema in $(get_tenant_schemas); do php bin/hyperf.php migrate --schema=$schema; done - 单元测试不能共用
test数据库的publicschema，应为每个测试用例动态创建临时 schema 并在tearDown中DROP SCHEMA - 生产部署时，
schema名必须符合数据库命名规范（如 PostgreSQL 不允许大写、空格、特殊字符），建议统一小写 + 下划线，从租户注册流程就校验并标准化
最容易被忽略的一点：PostgreSQL 的 search_path 默认包含 public，即使设置了 schema，某些未限定表名的查询仍可能落到 public。务必在连接初始化时执行 SET search_path TO $tenant_schema，或在 pg_hba.conf 中限制用户默认 schema。
