跳到主要内容

故障排除

在使用 Prisma Accelerate 时，您可能会在开发和操作过程中遇到通常由特定错误代码突出显示的错误。为了确保应用程序的顺利运行，理解这些错误的含义、发生原因以及如何解决它们至关重要。本指南旨在提供有关如何排除 Prisma Accelerate 中遇到的特定错误代码的见解和步骤。

P6009 (ResponseSizeLimitExceeded - 响应大小超出限制)​

当数据库查询的响应大小超出配置的查询响应大小限制时，会触发此错误。我们实施此限制是为了保护您的应用程序性能，因为通过多个网络层检索超过 5MB 的数据可能会显著降低应用程序速度。通常，传输超过 5MB 数据常见于 ETL（提取、转换、加载）操作。然而，对于其他场景，如事务查询、用于用户界面的实时数据获取、批量数据更新或在 ETL 上下文之外汇总大型数据集进行分析，通常应避免此情况。虽然这些用例至关重要，但通常可以优化，使其在配置的查询响应大小限制内工作，从而确保更流畅的性能和更好的用户体验。

P6009 的可能原因​

在响应中传输图像/文件​

如果正在获取存储在表中的图像或文件，导致响应大小过大，则可能会出现此错误。通常不鼓励直接在数据库中存储资产，因为它会显著影响数据库性能和可伸缩性。除了性能之外，它还会使数据库备份变慢，并显著增加存储常规备份的成本。

建议的解决方案： 将查询响应大小限制配置得更大。如果仍然超出限制，请考虑将图像或文件存储在 BLOB 存储中，例如Cloudflare R2、AWS S3 或 Cloudinary。这些服务允许您以最佳方式存储资产并返回访问 URL。与其直接在数据库中存储资产，不如存储 URL，这将大幅减小响应大小。

过度获取数据​

在某些情况下，会无意中获取大量记录或字段，导致超出配置的查询响应大小限制。这可能发生在查询中的 where 子句不正确或完全缺失时。

建议的解决方案： 将查询响应大小限制配置得更大。如果仍然超出限制，请仔细检查 where 子句是否按预期筛选数据。为了防止获取过多记录，请考虑使用分页。此外，使用 select 子句仅返回必要的字段，以减小响应大小。

获取大量数据​

在许多数据处理工作流程中，尤其是涉及 ETL（提取-转换-加载）过程或计划的 CRON 作业的工作流程中，需要从数据源（如数据库、API 或文件系统）提取大量数据进行分析、报告或进一步处理。如果您正在运行获取大量数据进行分析处理的 ETL/CRON 工作负载，则可能会遇到此限制。

建议的解决方案： 将查询响应大小限制配置得更大。如果超出限制，请考虑将查询拆分成批次。这种方法确保每个批次仅获取部分数据，防止您超出单个操作的大小限制。

P6004 (QueryTimeout - 查询超时)​

当数据库查询未在配置的查询超时限制内返回响应时，会发生此错误。查询超时限制包括等待连接池中的连接、到数据库的网络延迟以及查询本身的执行时间。我们强制执行此限制是为了防止无意的长时间运行查询导致系统资源过载。

Accelerate 跨区域网络的时间不包含在配置的查询超时限制内。

P6004 的可能原因​

此错误可能由多种原因引起。其中一些突出原因如下：

高流量和连接不足​

如果应用程序正在接收非常高的流量，并且到数据库的可用连接数量不足，则查询需要等待连接可用。这种情况可能导致查询等待时间超过配置的查询超时限制，如果它们在此持续时间内未得到服务，最终会触发超时错误。

建议的解决方案：检查并可能增加在平台环境中设置 Accelerate 时连接字符串参数中指定的 connection_limit (参考)。此限制应与数据库的最大连接数对齐。

默认情况下，连接限制设置为 10，除非在数据库连接字符串中指定了不同的 connection_limit。

长时间运行的查询​

即使连接可用，查询响应也可能很慢，达到配置的查询超时限制。这可能发生在一个查询中获取的数据量非常大或者表中缺少适当索引的情况下。

建议的解决方案：将查询超时限制配置得更大。如果超出限制，找出慢运行的查询并只获取必要的数据。使用 select 子句检索特定字段并避免获取不必要的数据。此外，考虑添加适当的索引以提高查询效率。您也可以将长时间运行的查询隔离到单独的环境中，以防止它们影响事务查询。

数据库资源争用​

一个常见但具有挑战性的问题是当在同一数据库上运行的其他服务执行繁重的分析或数据处理任务时，会显著消耗数据库资源。这些操作会独占数据库连接和处理能力，导致即使简单的查询也无法及时执行。这种“繁忙”或“嘈杂”的数据库环境可能导致通常快速运行的查询变慢甚至超时，尤其是在其他服务活动频繁期间。

用户通常依靠 CPU 和内存使用率指标来衡量数据库负载，但这可能具有误导性。虽然这些是重要指标，但它们可能无法完全反映数据库的运行状态。直接指标（如读取次数、写入次数和等待时间）可以更清晰地了解数据库的性能，应密切监控。这些指标的显著下降，尤其是在查询或数据模型没有更改的情况下，表明外部压力正在影响数据库性能。

建议的解决方案：如果通常快速的查询间歇性地变慢或超时而没有任何修改，很可能是竞争性查询对同一数据库表造成压力。要诊断此问题，请采用监控工具或利用数据库固有的功能来观察读取、写入和等待时间。此类监控将揭示与观察到的性能下降相符的活动模式或峰值。

此外，定期仔细检查和优化关键查询，并验证表是否已正确索引至关重要。这种主动方法可以最大程度地降低这些查询受到竞争性工作负载导致的速度下降的影响。

对 P6009 和 P6004 错误的考量​

对于原生支持 Prisma ORM 的运行时，您可以考虑创建两个 PrismaClient 实例。一个使用 Accelerate 连接字符串（前缀为 prisma://），另一个使用直接数据库连接字符串（前缀为 postgres://、mysql:// 等）。这种方法的主要思想是绕过 Accelerate 处理某些特定查询。

但是，请注意，可用连接将分配到您的两个 PrismaClient 实例。理解管理多个实例的含义至关重要，特别是关于直接数据库连接。使用带有直接数据库连接字符串的 PrismaClient 实例意味着此连接将直接与您的数据库交互。

这种方法需要仔细考虑，因为直接连接和 Accelerate 管理的连接共享相同的底层数据库连接池。这可能导致资源竞争，从而潜在地影响数据库服务的性能和可用性。

此外，直接连接可能对数据库的性能和可用性产生显著影响。消耗大量资源的操作可能会降低依赖同一数据库的其他用户或进程的服务质量。

如果您的应用程序的运行时环境原生支持 Prisma ORM，并且您正在考虑此策略以规避 P6009 和 P6004 错误，您可以创建两个 PrismaClient 实例：

  1. 一个用于常规操作的实例，使用 Accelerate 连接字符串（前缀为 prisma://）。
  2. 另一个具有直接数据库连接字符串（例如，前缀为 postgres://、mysql:// 等）的实例，用于预期超出配置的查询超时限制或导致响应大于配置的查询响应大小限制的特定操作。
export const prisma = new PrismaClient({
  datasourceUrl: process.env.DIRECT_DB_CONNECTION,
})

export const prismaAccelerate = new PrismaClient({
  datasourceUrl: process.env.ACCELERATE_CONNECTION,
}).$extends(withAccelerate())

此设置允许您策略性地通过直接连接引导某些操作，从而降低遇到上述错误的风险。但是，在做出此决定时，应全面了解潜在后果，并评估您的数据库基础设施是否能够支持此额外负载，而不会影响整体性能和可用性。

另请参阅 为什么 Accelerate 在服务中断期间不会回退到直接连接字符串？

P6008 (ConnectionError|EngineStartError - 连接错误|引擎启动错误)​

此错误表示 Prisma Accelerate 无法与您的数据库建立连接，可能由多种原因导致。

P6008 的可能原因​

数据库无法公开访问​

如果您的数据库位于 VPC 内或访问权限限制为特定 IP 地址，则如果未为 Accelerate 启用静态 IP 或数据库防火墙中不允许静态 IP，则可能会遇到此错误。

建议的解决方案： 为 Accelerate 启用静态 IP，并配置数据库防火墙以允许来自提供的静态 IP 地址的访问。

数据库主机/端口不可达​

如果数据库的服务器地址（主机名）和端口不正确或不可达，则可能会遇到此错误。

建议的解决方案： 验证创建 Prisma Accelerate 项目时提供的数据库连接字符串的主机名/端口。此外，尝试使用数据库 GUI 工具（例如 Prisma Studio、TablePlus 或 DataGrip）连接到数据库以进行进一步调查。

不正确的用户名/密码/数据库名称​

当向 Prisma Accelerate 提供了错误的凭据，阻止其与数据库建立连接时，可能会发生此错误。

建议的解决方案： 验证提供给 Prisma Accelerate 的连接字符串中数据库的用户名、密码和名称的正确性。确保这些凭据与您的数据库所需的凭据匹配。使用直接数据库 GUI 工具测试连接也有助于确认提供的凭据是否正确。

数据库响应时间过长​

如果数据库响应连接请求的时间过长，Prisma Accelerate 可能会超时并抛出此错误。这可能发生在数据库不活动或从睡眠模式唤醒时。

建议的解决方案： 验证数据库是否处于活动状态且可访问。如果数据库处于睡眠模式，尝试使用直接数据库 GUI 工具发送请求或使用数据库的管理控制台唤醒它。

P5011 (TooManyRequests - 请求过多)​

当 Prisma Accelerate 检测到超过允许阈值的高流量请求时，会发生此错误。它是一种保护措施，用于保护 Prisma Accelerate 和您的底层数据库免受过度负载。

P5011 的可能原因​

激进的重试循环​

如果您的应用程序立即或以最小延迟重试查询，尤其是在收到某些错误后，则请求的快速累积可能会超出阈值。

建议的解决方案

  • 实施指数退避策略。不要立即或以固定延迟重试，而是在每次失败尝试后逐渐增加延迟时间。
  • 这允许系统有时间恢复，并降低压倒 Prisma Accelerate 和您的数据库的可能性。

突然的流量高峰​

不可预测的流量激增（例如，产品发布、闪购或病毒式增长事件期间）可能导致达到阈值并导致 P5011 错误。

建议的解决方案

  • 考虑 Prisma Accelerate 和您的数据库的主动扩展策略。
  • 监控流量和资源使用情况。如果您预计流量激增，请联系支持部门进行容量规划和潜在的配置调整。

长时间或计划内的高工作负载​

某些过程，例如批量数据导入、ETL 操作或扩展的 CRON 作业，会随着时间的推移生成持续的高查询量。

建议的解决方案

  • 使用批处理或分块技术将大型操作分解成更小的部分。
  • 建立节流或调度机制，以便更均匀地分配负载。

其他错误​

MySQL (Aiven) 错误：“我们无法处理您的请求。请刷新后重试。”​

问题​

使用包含 ?ssl-mode=REQUIRED 参数的 Aiven MySQL 连接字符串时，可能会遇到以下错误：

We were unable to process your request. Please refresh and try again.

原因​

ssl-mode=REQUIRED 参数与 Accelerate 不兼容，这会导致连接问题。

建议的解决方案​

要解决此错误，请从您的 MySQL 连接字符串中移除 ?ssl-mode=REQUIRED 参数。

示例​

  • 原始连接字符串：mysql://username:password@host:port/database?ssl-mode=REQUIRED
  • 更新后的连接字符串：mysql://username:password@host:port/database