Prisma 数据库连接器(Database Connectors)完全指南:多租户、迁移与 MySQL/Postgres 配置实战
Prisma 数据库连接器(Database Connectors)完全指南:多租户、迁移与 MySQL/Postgres 配置实战
本指南以 Prisma 1.11 文档 Database Connectors Overview 为主体,深入讲解连接器(Connector)如何将 Prisma 服务器与底层数据库对接,重点剖析两个决定性配置决策——多租户(Multitenancy) 与 迁移(Migrations)——并给出 MySQL 与 Postgres 两种连接器在
docker-compose.yml中的完整可运行配置。读完本文,你将能够独立决策数据库连接模式、编写正确的PRISMA_CONFIG配置,并通过 Prisma CLI 完成服务部署与已有数据库的接入。
连接器是什么
在 Prisma 架构中,连接器(Connector) 负责把 Prisma 服务器 连接到一台或多台数据库。Prisma 服务器为 Prisma API 提供运行环境,而连接器则是服务器与数据库之间的桥梁:它决定了服务器以何种方式读写数据库、以何种方式管理数据库结构。
从源码结构看,连接器在服务端被抽象为 deploy 侧与 api 侧两套体系,例如 server/connectors/deploy-connector 下的 DeployConnector.scala 定义了部署阶段与数据库交互的接口,其对应的 JDBC、Mongo、MySQL、Postgres、SQLite 等实现分布在 server/connectors/deploy-connector-* 与 server/connectors/api-connector-* 目录中。这印证了连接器并非单一模块,而是一组按数据库类型分化的实现族。
连接数据库时,你必须做出两个核心决策,它们将直接写入服务器配置:
- 多租户(Multitenancy):这台数据库是否需要支持多个相互隔离的 Prisma 服务?
- 迁移(Migrations):是否允许 Prisma 主动迁移(变更)数据库结构?
多租户与单租户模式
多租户模式(Multitenancy)
当数据库被配置为多租户模式时,每向该数据库部署一个服务,Prisma 就会为它创建一个新的数据库 schema,从而保证各个服务之间完全隔离。
- schema 的命名规则为:服务名(service)+ 阶段名(stage) 组合而成。
- 这是 Prisma 1.8 之前唯一可用的连接方式,也是最常用、最安全的方式——每个服务的表结构互不干扰,升级或删除某个服务不会影响其他服务。
单租户模式(Singletenancy)
当数据库运行在单租户模式时,你必须在配置 Prisma 服务器时显式指定数据库 schema 的名称,所有部署到该数据库的服务都会共用这一个 schema。
单租户模式的最大价值在于接入既有数据库:如果你的数据库已经被一个现有应用控制,你希望用 Prisma 为这个数据库生成 GraphQL API,而不是让 Prisma 接管它的结构,那么单租户模式就是为这种场景设计的。此时 Prisma 通过 introspection(内省) 学习数据库的真实 schema,并翻译成对应的数据模型。
从仓库中的迁移文档 Migrations 可以确认:目前一次只能配置一个数据库,且该数据库必须命名为 default;未来的版本计划支持配置多个命名数据库,并从同一个服务中同时使用它们。
迁移(Migrations)开关
启用迁移:让 Prisma 管理数据库结构
启用迁移后,每次执行 prisma deploy 部署服务时,Prisma 都会主动迁移所连接数据库的结构——建表、加列、删列、建立关系等动作都由 Prisma 依据数据模型自动完成。此时:
- Prisma CLI 成为管理数据库结构的主要界面;
- 数据库结构完全由 数据模型(data model).md) 驱动,你只需修改 SDL 并重新部署。
迁移在 Prisma 中默认开启,若想显式声明,可将 migrations 键设置为 true。
禁用迁移:只改变 API,不动数据库
对于已被现有应用控制的数据库,更合理的选择是关闭迁移。此时部署服务不会迁移底层数据库,而是改变生成的 GraphQL API 的形状——你可以通过修改数据模型来隐藏某些表、重命名某些列等,这些能力来自 introspection 生成的映射关系。
禁用迁移的配置方式如下(注意 schema 与 migrations 两个键):
port: 4466
databases:
default:
connector: postgres
host: localhost
port: 5432
user: root
password: prisma
database: prisma
schema: my_schema
migrations: false
注意:当前 Prisma 只能迁移运行在多租户模式下的数据库;单租户模式必须配合禁用迁移使用。该限制在 Migrations 文档 中有明确说明。
连接器能力矩阵
截至 Prisma 1.11,不同数据库连接器所支持的模式组合并不相同,这是配置时最容易踩坑的地方:
| 连接器 | 多租户 + 启用迁移 | 单租户 + 禁用迁移 |
|---|---|---|
| MySQL | ✅ 支持 | ❌ 不支持 |
| Postgres | ✅ 支持 | ✅ 支持 |
文档原话:"Currently MySQL only support multitennancy and enabled migrations. Postgres support multitennancy and enabled migrations as well as singletenancy with disabled migrations." 未来版本会逐步放开更多组合。
这个矩阵直接决定了你的选型:
- 想用 MySQL 接入已有数据库?目前不可行,请选择 Postgres,或先让 Prisma 管理结构、后续再切换。
- 全新项目、希望 Prisma 全权管理结构?MySQL 与 Postgres 均可。
通过 Docker Compose 配置连接器
自托管 Prisma 服务器的基础设施完全基于 Docker,连接器配置写在作为服务器基石的 docker-compose.yml 中,通过 PRISMA_CONFIG 环境变量传递给 Prisma 容器。完整的参数解析可参考 Docker 部署文档。
MySQL 连接器配置示例
version: '3'
services:
prisma:
image: prismagraphql/prisma:1.11
restart: always
ports:
- "4466:4466"
environment:
PRISMA_CONFIG: |
managementApiSecret: my-server-secret-123
port: 4466
databases:
default:
connector: mysql
host: mysql
port: 3306
user: root
password: prisma
migrations: true
managementSchema: management
mysql:
image: mysql
restart: always
environment:
MYSQL_USER: root
MYSQL_ROOT_PASSWORD: prisma
volumes:
- mysql:/var/lib/mysql
volumes:
mysql: ~
Postgres 连接器配置示例
version: '3'
services:
prisma:
image: prismagraphql/prisma:1.11
restart: always
ports:
- "4466:4466"
environment:
PRISMA_CONFIG: |
managementApiSecret: my-server-secret-123
port: 4466
databases:
default:
connector: postgres
host: postgres
port: 5432
user: root
password: prisma
migrations: true
managementSchema: management
database: prisma
postgres:
image: postgres
restart: always
environment:
POSTGRES_USER: root
POSTGRES_PASSWORD: prisma
volumes:
- postgres:/var/lib/postgresql/data
volumes:
postgres: ~
完整细节参见 MySQL 连接器文档 与 Postgres 连接器文档。
PRISMA_CONFIG 关键参数说明
以下参数按功能分组,均出现在上面的配置示例中:
| 参数 | 作用 | 说明 |
|---|---|---|
managementApiSecret |
服务器管理 API 密钥 | CLI 向服务器发起请求(如 prisma deploy)时需携带此密钥;若不设置,CLI 无需认证。也可改用 legacySecret 做非对称认证 |
port |
Prisma 服务器监听端口 | 示例中为 4466,与 ports: "4466:4466" 对应 |
databases.default.connector |
指定连接器类型 | 取值为 mysql 或 postgres |
databases.default.host |
数据库主机 | 在 Compose 网络中直接写服务名(如 mysql、postgres) |
databases.default.port |
数据库端口 | MySQL 为 3306,Postgres 为 5432 |
databases.default.user / password |
数据库认证凭据 | 必须与数据库容器侧的环境变量(MYSQL_ROOT_PASSWORD / POSTGRES_PASSWORD)保持一致 |
databases.default.migrations |
是否启用迁移 | true(默认)或 false |
databases.default.database |
目标数据库名 | Postgres 连接器必需,如 prisma |
databases.default.schema |
目标 schema 名 | 单租户模式接入已有数据库时指定(见上文禁用迁移示例) |
databases.default.managementSchema |
服务器管理元数据所在 schema | 示例中为 management |
仓库内部开发配置可以佐证上述结构:server/docker-compose/mysql/prisma.yml 中同样使用了 port、databases.default.connector: mysql、host、port、user、password 等键,并额外出现了 rawAccess: true 这类内部开发开关;配套的 dev-mysql.yml 则把 MySQL 容器端口绑定到 127.0.0.1:3306:3306。Postgres 侧的开发配置见 dev-postgres.yml。
实战:用 CLI 创建连接 MySQL/Postgres 的 Prisma 服务器
前提:已安装 Docker 与 prisma deploy。
- 运行
prisma init hello-world; - 选择 Create new database;
- 选择 MySQL(或 PostgreSQL);
- 进入新目录:
cd hello-world; - 启动 Prisma 服务器:
docker-compose up -d; - 执行
prisma deploy部署你的 Prisma API。
部署时,若 prisma.yml 中已指定 endpoint,CLI 会直接部署到该端点;若未指定,CLI 向导会询问若干问题、为你构造 endpoint 并写入 prisma.yml 作为后续默认值。想重新唤起向导可运行 prisma deploy --new,或手动删除 prisma.yml 中的 endpoint。
对于已有数据库的接入场景,还可以通过 prisma init 选择连接已有数据库,或在部署前运行专门的 prisma introspect 命令,让 CLI 基于真实 schema 生成 datamodel.graphql,再配合上文"禁用迁移"配置完成部署(目前 introspection 仅支持 Postgres)。
故障排查
连接本机非 Docker 数据库
Prisma 运行在 Docker 容器中,因此无法通过 localhost 直连本机数据库。Docker v18.03 起提供了一个会路由到本机的主机名:host.docker.internal,可将连接器配置中的 host 改为该值(在 Linux 上也可考虑 docker.for.mac.localhost 等变体,见 introspection 文档中的示例)。
端口冲突
如果你使用过旧版 Prisma CLI + Docker,直接运行 docker-compose up -d 可能遇到如下报错:
ERROR: for mysql_prisma_1 Cannot start service prisma: driver failed programming external connectivity on endpoint mysql_prisma_Creating mysql_db_1 ... done
ERROR: for prisma Cannot start service prisma: driver failed programming external connectivity on endpoint mysql_prisma_1 (b9aa3375c9374b77bab447b3777d1e5a7d78e0081106699b637065e6db4a5a88): Bind for 0.0.0.0:4466 failed: port is already allocated
ERROR: Encountered errors while bringing up the project.
根因是旧容器仍占用 4466 端口。先清理旧的 Docker 环境再启动:
docker kill $(docker ps -aq)
docker rm $(docker ps -aq)
提示:如果你使用
fish或其他 shell,可能需要按语法调整上述命令。
验证与重置服务器
- 查看容器日志定位问题:
docker-compose logs; - 确认容器是否在运行:
docker ps(若提示Error response from daemon: No such container,说明容器未启动); - 服务器进入不可恢复状态时,可硬重置(注意:以下命令会清空本地 Prisma 服务器中的全部数据):
docker-compose kill
docker-compose down
docker-compose up -d
相关阅读
- Prisma 服务器概览:服务器类型、stable/beta/alpha 渠道与认证方式
- Docker 部署 Prisma 服务器:
PRISMA_CONFIG完整参数解析与镜像说明 - MySQL 连接器配置
- Postgres 连接器配置
- 迁移(Migrations):多租户/单租户与迁移开关的完整说明
- Introspection(内省):接入已有数据库时如何生成数据模型