平台

升级指南

Supabase 以快速交付著称，我们致力于尽可能将新功能添加到现有项目中。在某些情况下，使用新功能可能需要升级或迁移您的 Supabase 项目。

您可以通过原地升级或暂停后恢复项目的方式来完成升级。

原地升级

原地升级使用 pg_upgrade 工具。对于超过 1GB 的项目，此方法通常比暂停-恢复周期更快，且随着数据库规模增大，速度优势更加明显。

  1. 规划合适的停机时间窗口，执行升级前请确保已阅读本文档的注意事项部分
  2. 在控制面板的基础设施部分使用"升级项目"按钮

此外，如果升级失败，您的原始数据库将被重新上线并能够继续处理请求。

根据经验法则，pg_upgrade 的处理速度约为每秒 100MB（在执行数据升级时）。您可以根据数据库大小使用此指标来估算升级所需的停机时间窗口。在此窗口期间，您应规划数据库及相关服务不可用的情况。

暂停与恢复项目

当您暂停并恢复项目时，恢复后的数据库将包含最新功能。这种方法确实会导致服务中断，请注意您的项目将有短暂时间不可访问。

  1. 在控制面板的常规设置页面，点击暂停项目。项目暂停过程中您将被重定向至首页，此过程可能需要几分钟。
  2. 项目暂停后，点击恢复项目。恢复时间取决于数据库中的数据量，可能需要几分钟。恢复完成后您将收到邮件通知。

请注意，暂停+恢复升级方式会先销毁项目资源再重新创建。如果恢复过程失败，需要Supabase技术支持人员手动干预才能使项目重新上线。

注意事项

无论采用哪种升级方式，都存在以下注意事项：

逻辑复制

如果您使用了逻辑复制(logical replication)，升级过程不会保留复制槽(replication slots)。升级后您需要使用pg_create_logical_replication_slot方法手动重新创建。有关该方法的详细信息，请参阅Postgres文档中的复制管理函数。

重大变更

服务的新版本可能会破坏现有功能或改变您所依赖的性能特征。如果您的项目符合升级条件，您可以在 Supabase 仪表盘 中查看当前使用的服务版本。

重大变更通常只出现在 Postgres 和 PostgREST 的主版本升级中。您可以在以下位置查阅它们各自的发布说明：

如果您是从较旧的版本升级，还需要考虑所有中间版本的发布说明。

时间限制

自2024年06月24日起，当项目被暂停后，用户有90天的时间窗口可以通过Supabase Studio在平台上恢复该项目。

这90天的窗口期允许Supabase引入可能与旧备份不兼容的平台变更。与活跃项目不同，静态备份无法更新以适应这些变更。

在90天的恢复窗口期内，可以通过Studio控制面板一键恢复被暂停的项目。

90天恢复窗口期结束后，您可以从项目控制面板下载项目备份文件和存储对象。关于如何本地加载该备份以恢复数据，请参阅本地恢复下载的备份。

如果在项目暂停期间升级到付费计划，任何已过期的一键恢复选项将重新启用。由于备份是在向后兼容窗口期外创建的，恢复可能会失败。如果在升级后恢复备份时遇到问题，请联系技术支持。

磁盘大小调整

升级时，Supabase平台会根据数据库当前大小"智能调整"磁盘容量。例如，如果您的数据库大小为100GB，而您拥有200GB的磁盘，升级操作会将磁盘容量缩减至120GB（数据库大小的1.2倍）。

依赖于Postgres扩展的对象

原地升级不支持升级包含引用系统OID的reg*数据类型的数据库。如果您创建了以下扩展依赖的任何对象，升级后需要重新创建它们。

pg_cron记录

pg_cron不会自动清理历史记录。如果不定期修剪这些记录，可能会导致cron.job_run_details表变得极其庞大；在升级前您应该清理该表中不必要的记录。

在就地升级过程中，pg_cron扩展会被删除并重新创建。在此过程之前，cron.job_run_details表会被复制以避免丢失历史日志。复制一个极其庞大的详情表会立即产生磁盘压力，轻则导致不必要的性能下降，重则可能导致升级过程失败。

扩展

当前原地升级不支持升级使用低于以下版本的扩展的数据库：

  • TimescaleDB 2.16.1
  • plv8 3.1.10

要升级到新版本的Postgres，您需要在升级前删除这些扩展，并在升级后重新创建它们。

认证方法变更 - 弃用 md5 改用 scram-sha-256

md5 哈希方法存在已知弱点，使其不适合用于加密场景。因此，我们将弃用 md5 并改用 scram-sha-256，这是最新版 PostgreSQL 默认且最安全的认证方法。

在升级过程中，我们会自动将 Supabase 托管角色的密码迁移至 scram-sha-256，但您需要手动迁移所有自定义角色的密码，否则升级后将无法使用这些角色进行连接。

要识别使用 md5 哈希方法的角色并迁移其密码，您可以在升级后执行以下 SQL 语句：

1
2
3
4
5
6
7
8
9
-- 列出使用 md5 哈希方法的角色SELECT  rolnameFROM pg_authidWHERE rolcanlogin = true  AND rolpassword LIKE 'md5%';-- 将角色密码迁移至 scram-sha-256ALTER ROLE <role_name> WITH PASSWORD '<password>';

数据库容量缩减

作为升级流程的一部分，系统会执行真空清理等维护操作，这可能导致报告的数据库容量减少。

升级后验证

Supabase 会执行全面的升级前和升级后验证，确保数据库正确升级。但您仍应规划应用层面的验证，因为可能存在未预期的变更，在规划停机窗口时应为此预留时间。

具体升级说明

升级至 Postgres 17

在使用 Postgres 17 的项目中，以下扩展已被弃用：

  • plcoffee
  • plls
  • plv8
  • timescaledb

低版本 Postgres 上的现有项目不受影响，这些扩展将继续在 Postgres 15 项目上获得支持，直到 Postgres 15 在 Supabase 平台终止支持。

计划从 Postgres 15 升级至 Postgres 17 的项目需要通过在 Supabase 仪表盘中禁用这些扩展来移除它们。