PostgreSQL Docker镜像大版本升级

随遇而安 2026-06-03 09:03:24 累计浏览 2 次

本机暂存

内容概览

针对PostgreSQL 14官方支持即将到期及所用PostGIS镜像版本（14-3.2）的后续维护问题，本文详述了如何在Docker环境中将数据库从14版本升级至17版本。作者澄清了Docker容器内同样可以使用pg_upgrade工具进行大版本升级。升级流程主要分为三个阶段：首先进行周密准备，包括停止旧容器、打包备份旧数据卷、从旧容器中拷贝出PostgreSQL 14的二进制文件（lib与share目录），并使用新版本镜像初始化空的新数据目录。核心的升级步骤是通过一条挂载了旧数据、新数据以及旧版二进制目录的Docker命令，以postgres用户运行目标版本镜像中的pg_upgrade工具，指定新旧数据目录和二进制路径来执行升级。升级完成后，需要执行清理与优化工作，包括重命名新数据目录、启动新版本容器、运行vacuumdb命令分析优化数据库统计信息，确认无误后方可删除旧容器及相关的数据、二进制备份文件。整个过程提供了一套可在容器化部署中安全完成数据库跨大版本升级的可操作方案。

最近，我发现 <code>PostgreSQL 14</code> 的官方支持在 <code>2026年11月12日</code> 就要结束了，我正在使用的 <code>postgis/postgis:14-3.2</code> 镜像也即将失去官方支持。为了保持系统的安全性和稳定性，我决定将数据库升级到 <code>PostgreSQL 17</code>。有人说 Docker 镜像没有办法用 <code>pg_upgrade</code> 来升级数据库，但实际上是可以的。今天，我就来记录一下我的升级过程。<h2 id="一-升级前的准备"><a class="markdownIt-Anchor" href="#一-升级前的准备"></a> 一、升级前的准备</h2><h3 id="1-初始目录结构参考"><a class="markdownIt-Anchor" href="#1-初始目录结构参考"></a> 1. 初始目录结构参考</h3>我当前的目录结构如下：<figure class="highlight plaintext"><table><tr><td class="gutter"><pre>1 2 3 </pre></td><td class="code"><pre>├── docker-compose.yml ├── data │ └── postgres-old-data </pre></td></tr></table></figure><h3 id="2-备份数据"><a class="markdownIt-Anchor" href="#2-备份数据"></a> 2. 备份数据</h3>首先在备份前一定要先停止容器，防止备份时还在写入，造成数据不一致。<figure class="highlight bash"><table><tr><td class="gutter"><pre>1 </pre></td><td class="code"><pre>docker stop postgres-old </pre></td></tr></table></figure>我选择直接备份volume目录，直接打一个tar包。<figure class="highlight bash"><table><tr><td class="gutter"><pre>1 2 3 </pre></td><td class="code"><pre>cd data tar cvf postgres-old.tar postgres-old-data cd .. </pre></td></tr></table></figure>当前目录结构如下：<figure class="highlight plaintext"><table><tr><td class="gutter"><pre>1 2 3 4 </pre></td><td class="code"><pre>├── docker-compose.yml ├── data │ ├── postgres-old-data │ └── postgres-old.tar </pre></td></tr></table></figure><h3 id="3-拷贝二进制目录"><a class="markdownIt-Anchor" href="#3-拷贝二进制目录"></a> 3. 拷贝二进制目录</h3>接下来，我需要拷贝 <code>PostgreSQL 14</code> 的二进制目录，以便在升级过程中使用。我使用的镜像是 <code>postgis/postgis:14-3.2</code>，注意<code>alpine</code>镜像的路径不一样，此处仅做参考。<figure class="highlight bash"><table><tr><td class="gutter"><pre>1 2 3 4 5 6 </pre></td><td class="code"><pre>cd data mkdir postgres-old-bin chown 999 postgres-old-bin docker cp postgres-old:/usr/lib/postgresql/14 ./postgres-old-bin/lib docker cp postgres-old:/usr/share/postgresql/14 ./postgres-old-bin/share cd .. </pre></td></tr></table></figure>当前目录结构如下：<figure class="highlight plaintext"><table><tr><td class="gutter"><pre>1 2 3 4 5 6 7 </pre></td><td class="code"><pre>├── docker-compose.yml ├── data │ ├── postgres-old-data │ ├── postgres-old.tar │ ├── postgres-old-bin | | ├── lib | | └── share </pre></td></tr></table></figure><h3 id="4-初始化新目录"><a class="markdownIt-Anchor" href="#4-初始化新目录"></a> 4. 初始化新目录</h3>接下来，我需要初始化一个新的目录来存放升级后的数据。<figure class="highlight bash"><table><tr><td class="gutter"><pre>1 2 3 4 5 6 7 8 </pre></td><td class="code"><pre>cd data mkdir postgres-new-data chown 999 postgres-new-data cd .. docker run -it --rm --name postgres-new \ -v ./data/postgres-new-data:/var/lib/postgresql/data \ -e POSTGRES_PASSWORD=mysecretpassword \ postgres:17 </pre></td></tr></table></figure>数据库创建完成按 <code>Ctrl + C</code> 停止，现在 <code>postgres-new-data</code> 目录已经初始化好了。<figure class="highlight plaintext"><table><tr><td class="gutter"><pre>1 2 3 4 5 6 </pre></td><td class="code"><pre>├── docker-compose.yml ├── data │ └── postgres-old-data │ └── postgres-old.tar │ └── postgres-old-bin │ └── postgres-new-data </pre></td></tr></table></figure><h2 id="二-执行升级"><a class="markdownIt-Anchor" href="#二-执行升级"></a> 二、执行升级</h2>这里要使用需要升级的目标镜像，保证对应的插件在新版本中都包含。<figure class="highlight bash"><table><tr><td class="gutter"><pre>1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 </pre></td><td class="code"><pre>docker run -it --rm --name postgres-upgrade \ -v ./data/postgres-old-data:/data \ -v ./data/postgres-new-data:/var/lib/postgresql/data \ -v ./data/postgres-old-bin/lib:/usr/lib/postgresql/14 \ -v ./data/postgres-old-bin/share:/usr/share/postgresql/14 \ --workdir /var/lib/postgresql/data \ --user postgres \ -e POSTGRES_PASSWORD=mysecretpassword \ -e PGUSER=postgres \ -e PGPASSWORD=mysecretpassword \ postgis/postgis:17-3.5 \ pg_upgrade \ --old-datadir=/data \ --new-datadir=/var/lib/postgresql/data \ --old-bindir=/usr/lib/postgresql/14/bin \ --new-bindir=/usr/lib/postgresql/17/bin </pre></td></tr></table></figure>参数说明：<ul><li><code>-v ./data/postgres-old-data:/data</code>：将旧数据目录挂载到容器内的 <code>/data</code>。</li><li><code>-v ./data/postgres-new-data:/var/lib/postgresql/data</code>：将新数据目录挂载到容器内的 PostgreSQL 数据目录。</li><li><code>-v ./data/postgres-old-bin/lib:/usr/lib/postgresql/14</code>：将旧版本的二进制文件挂载到容器内的 <code>/usr/lib/postgresql/14</code>。</li><li><code>-v ./data/postgres-old-bin/share:/usr/share/postgresql/14</code>：将旧版本的共享文件挂载到容器内的 <code>/usr/share/postgresql/14</code>。</li><li><code>--workdir /var/lib/postgresql/data</code>：设置工作目录为新数据目录。</li><li><code>--user postgres</code>：以 postgres 用户身份运行容器。</li><li><code>-e POSTGRES_PASSWORD=mysecretpassword</code>：设置 PostgreSQL 密码环境变量。</li><li><code>-e PGUSER=postgres</code>：设置 PostgreSQL 用户环境变量。</li><li><code>-e PGPASSWORD=mysecretpassword</code>：设置 PostgreSQL 密码环境变量。</li></ul>运行完成后，可以根据日志提示进行一些补充工作。<ol><li>会生成一个升级插件的sql脚本，可以执行一下，或者后续自行在数据库里执行升级对应的插件版本。</li><li>会生成一个移除旧目录的脚本，鉴于我们后面直接不挂载旧目录了，可以不管。</li><li>还提示推荐执行一下优化查询统计的命令：<code>vacuumdb --all --analyze-in-stages</code>。</li></ol><h2 id="三-升级后的清理工作"><a class="markdownIt-Anchor" href="#三-升级后的清理工作"></a> 三、升级后的清理工作</h2>运行新镜像<figure class="highlight bash"><table><tr><td class="gutter"><pre>1 2 </pre></td><td class="code"><pre>mv data/postgres-new-data data/postgres docker run --name postgres -v ./data/postgres:/var/lib/postgresql/data -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -d postgis/postgis:17-3.5 </pre></td></tr></table></figure>执行优化<figure class="highlight bash"><table><tr><td class="gutter"><pre>1 </pre></td><td class="code"><pre>docker exec -it -u postgres postgres vacuumdb --all --analyze-in-stages </pre></td></tr></table></figure>确认无误后可以删除旧数据了。<figure class="highlight bash"><table><tr><td class="gutter"><pre>1 2 3 4 </pre></td><td class="code"><pre>docker rm postgres-old rm -rf data/postgres-old-data rm -rf data/postgres-old-bin rm -rf data/postgres-old.tar </pre></td></tr></table></figure>

建议继续学习

公司倒了，请让领导先走（累计阅读 13,341）
【2014年版】异地购房提取北京公积金（累计阅读 9,083）
个人开公司的流程，以后用得着（累计阅读 7,862）
一个程序员的血泪史（累计阅读 6,181）
性能测试工具sysbench简介（累计阅读 5,962）
献给有裸辞想法的朋友们（累计阅读 5,482）
也谈PostgreSQL的同步配置(Slony) （累计阅读 5,460）
谈谈与数据打交道的工作（累计阅读 5,300）
大公司与风险管理（累计阅读 5,242）
豆瓣是啥？（累计阅读 5,001）