企业官网建设流程全解析

• 后端
• 数据库
• GraphQL

数据库连接器（Connector）是 Prisma server 与底层数据库之间的桥梁，它负责把 Prisma server 连接到 MySQL、PostgreSQL 等关系型数据库。在 Prisma 1.x 架构中，选择连接器意味着同时回答两个关键问题：数据库是否支持多租户（Multitenancy），以及数据库结构由谁来管理（Prisma 迁移还是外部应用）。读完本文，你将掌握连接器的两大核心决策模型、MySQL 与 Postgres 连接器的完整配置方式，以及如何在 Docker 环境下从零搭建一个可用的 Prisma server。

连接器是什么

连接器（Connector）是 Prisma server 与数据库之间的适配层。每当 Prisma server 需要对数据库执行读写、部署或结构迁移时，请求都会经过连接器转换为对应数据库方言的 SQL（或 MongoDB 的查询语句）。在 Prisma 1.x 中，数据库层面的能力差异被连接器抽象掉，使上层的 Prisma API 能以统一的 GraphQL 形式对外提供服务。

从当前仓库的源码结构可以印证这一点：连接器被划分为两类，分别服务于 Prisma 的两个核心子系统：

• API 连接器（server/connectors/api-connector-*）：负责 Prisma API 层的 CRUD、关系查询、聚合等运行时数据访问，例如 api-connector-mysql、api-connector-postgres、api-connector-mongo 等。
• 部署连接器（server/connectors/deploy-connector-*）：负责prisma deploy时对数据库 schema 的创建、修改与迁移，例如 deploy-connector-mysql、deploy-connector-postgres、deploy-connector-mongo。

连接器的具体加载逻辑集中在 ConnectorLoader.scala：它会读取 Prisma 配置中的connector字段，将mysql、postgres、sqlite、mongo等字符串分别映射到对应的 API 连接器与部署连接器实现；如果遇到未知的 connector 名称，则直接抛出Unknown connector错误。这也解释了为什么在配置文件中 connector 字段的值必须是mysql、postgres这类固定标识。

决策一：多租户还是单租户（Multitenancy vs Singletenancy）

连接数据库时首先要回答的问题：这个数据库是否需要支持多个相互隔离的 Prisma service？

多租户模式（Multitenancy）

如果一个数据库被配置为多租户模式，那么每当一个新的 service 被部署到该数据库时，Prisma 都会为它创建一个全新的 database schema。也就是说，每个 service 的数据都存放在自己独立的 schema 中，彼此完全隔离。这个 schema 的命名规则是：将 service 名称与 stage 名称组合而成。

例如，部署一个名为myservice、stage 为dev的 service，Prisma 会为该 service 生成一个类似myservice$dev的独立 schema，与myservice$prod等其它 stage 互不干扰。这种模式非常契合多环境、多服务的团队协作场景——同一台数据库服务器可以安全地承载多个 Prisma service，而无需担心表名冲突或数据串扰。

单租户模式（Singletenancy）

如果数据库运行在单租户模式，则必须在配置 Prisma server 时就明确指定 database schema 的名称，所有部署到该数据库的 service 都会共享同一个 schema。

单租户模式最典型的适用场景是：你已有一个被现有应用管理的存量数据库，希望用 Prisma 为该数据库生成一个 GraphQL API，而数据库本身的结构仍由原应用掌控。此时多租户的 schema 隔离反而是负担，直接指向已有的 schema 才能让 Prisma 与现有应用读写同一份数据。

从当前仓库的部署连接器实现（如 deploy-connector-jdbc）可以看出，Prisma 在启动时会基于连接配置初始化数据库 schema（例如managementSchema、数据库名等内部元数据），多租户与单租户的差异最终体现在 schema 的定位与创建策略上。

决策二：迁移还是内省（Migrations vs Introspection）

第二个决策决定了数据库结构由谁来治理。

启用迁移（Migrations）

当迁移被启用时，每次执行prisma deploy部署 service，Prisma 都会自动迁移已连接数据库的结构，使其与 Prisma API 的 数据模型（data model） 保持一致。在这种模式下，Prisma CLI 成为管理数据库结构的唯一主入口——你在数据模型文件（GraphQL SDL）中声明的 type、关系、枚举等，会被转换为对应数据库的建表、加列、建索引等操作。

这带来一个明显优势：开发者可以在数据模型中用声明式的方式演进数据库结构，配合prisma deploy完成应用与数据库的同步升级，无需手工编写 DDL。

关闭迁移，使用内省（Introspection）

对于已经归属现有应用的存量数据库，更合理的做法是配置 Prisma 不去迁移数据库结构。此时prisma deploy不会改动数据库，Prisma CLI 会转而使用**内省（introspection）**机制：读取数据库中真实的 schema，并将其翻译成一份对应的数据模型文件，供 Prisma API 使用。

这种"以数据库为准"的反向工作流，让 Prisma 可以优雅地接入遗留系统——数据库继续由原应用控制，Prisma 只负责在其上叠加一层 GraphQL API。

配置：MySQL 与 Postgres 连接器

在 Prisma 1.x 中，连接器的配置位于启动 Prisma server 所用的docker-compose.yml文件内，通过PRISMA_CONFIG环境变量注入。配置的核心部分是databases节点，每个数据库条目描述一个连接器实例。

版本能力说明（以本仓库对应文档为准）：在本版本中，MySQL 连接器目前仅支持多租户 + 启用迁移的组合；Postgres 连接器支持多租户 + 启用迁移，也支持单租户 + 关闭迁移。更多组合方式在后续版本中才会逐步开放。

MySQL 连接器配置

以下是一个完整的 MySQL 连接器配置示例（来源：02-MySQL.md）：

version: '3' services: prisma: image: prismagraphql/prisma:1.13 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 连接器配置

以下是 Postgres 连接器的完整配置示例（来源：03-Postgres.md）：

version: '3' services: prisma: image: prismagraphql/prisma:1.13 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: root postgres: image: postgres restart: always environment: POSTGRES_USER: root POSTGRES_PASSWORD: prisma volumes: - postgres:/var/lib/postgresql/data volumes: postgres: ~

与 MySQL 配置相比，Postgres 连接器多了一个database参数（此处为root），用于指定连接器指向的数据库名，这也是单租户模式下定位既有 schema 的基础。Postgres 默认端口为5432。

仓库中的实际配置参考

除了文档中的示例，当前仓库自身也提供了多套可直接参考的连接器配置，它们体现了同样的配置结构并补充了额外参数：

• server/docker-compose/mysql/prisma.yml：MySQL 连接器配置，额外展示了rawAccess: true（允许通过 API 对数据库执行原生访问）等参数；
• server/docker-compose/postgres/prisma.yml：Postgres 连接器配置，同样包含rawAccess: true；
• server/docker-compose/mongo/prisma.yml：MongoDB 连接器配置，其连接方式为uri: mongodb://prisma:prisma@127.0.0.1:27017/?authSource=admin&ssl=false——可见 Mongo 连接器使用完整的uri字符串而非分散的 host/port/user 字段；
• server/docker-compose/mysql/dev-mysql.yml 与 server/docker-compose/postgres/dev-postgres.yml：配套的 MySQL 5.6 / PostgreSQL 10 数据库容器定义，展示了MYSQL_ROOT_PASSWORD、POSTGRES_USER、POSTGRES_PASSWORD等环境变量的设置方式。

从零搭建：创建连接 MySQL / Postgres 的 Prisma server

使用 Prisma CLI（需要先安装 Docker）可以快速搭建一个连接 MySQL 或 Postgres 的 Prisma server：

1. 运行prisma init hello-world初始化项目；
2. 选择Create new database（创建新数据库）；
3. 选择MySQL或PostgreSQL（按你的目标数据库选择）；
4. 进入新生成的目录：cd hello-world；
5. 启动 Prisma server：docker-compose up -d；
6. 执行prisma deploy部署你的 Prisma API。

执行完上述步骤后，Prisma server 会通过连接器与数据库建立连接，并按照docker-compose.yml中PRISMA_CONFIG的配置创建必要的 schema。之后，你可以通过prisma.yml中的endpoint（如http://localhost:4466/default/default）访问生成的 GraphQL API。关于prisma.yml中datamodel、endpoint、secret等字段的完整定义，可参考 02-YAML-Structure.md。

常见问题与排障（Troubleshooting）

连接本机（非 Docker）运行的数据库

由于 Prisma server 运行在 Docker 容器中，它无法通过localhost直接访问宿主机上运行的数据库。Docker v18.03 引入了host.docker.internal这一特殊主机名，它会被路由到宿主机本机。因此，当数据库运行在宿主机而非容器中时，应将连接器配置中的host改为host.docker.internal。

Docker 端口占用：port is already allocated

如果你之前使用过旧版本的 Prisma CLI 与 Docker，在运行docker-compose up -d前需要先清理旧的 Docker 环境，否则可能遇到如下报错：

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 kill $(docker ps -aq) docker rm $(docker ps -aq)

注意：如果使用的是fish等其它 shell，可能需要相应调整上述命令的语法。

总结

连接器是 Prisma server 与数据库之间不可替代的适配层。使用连接器时，你需要依次回答两个核心问题：数据库是否按 service 隔离 schema（多租户 vs 单租户），以及数据库结构由 Prisma 迁移还是由现有应用掌控（迁移 vs 内省）。在当前版本中，MySQL 支持"多租户 + 迁移"，Postgres 在此基础上还支持"单租户 + 关闭迁移"，后者正是接入存量数据库、叠加 GraphQL API 的推荐路径。通过docker-compose.yml中的PRISMA_CONFIG配置连接器参数，再配合prisma init、docker-compose up -d、prisma deploy三步，即可完成一个可用的 Prisma server 搭建。对于更深入的实现细节，可以继续阅读仓库中 api-connector-* 与 deploy-connector-* 系列模块的源码。

• 后端
• 数据库
• GraphQL