数据库

Joppa 为每种数据库引擎运行一个服务器，使用固定端口；每个项目在其中拥有自己的数据库。这比每个项目一个容器更轻量，你的工具也总是连接到同一个地方。

PostgreSQL、MySQL 和 MariaDB 属于免费版，每种一个服务器。同一引擎的多个服务器（例如两个不同版本的 PostgreSQL）需要 Joppa Pro。参见 许可证与方案。

创建数据库

在服务页面的 数据库 部分：点击 + 新建数据库。为它命名，选择要连接的项目；如果是 PostgreSQL，还可以选择扩展。

通常你甚至不需要这样做：在 环境 标签页中把服务接入项目时，如果项目的数据库不存在，Joppa 会自动创建。

数据库表格会显示每个数据库的大小、扩展和所属项目。每个数据库的菜单：扩展…、复制 URL、导出…、导入到此数据库…、复制…、快照…、删除…。

连接

引擎	URL
PostgreSQL	postgresql://postgres:[email protected]:5432/<base>
MySQL、MariaDB	mysql://root:[email protected]:3306/<base>

这些是开发用的凭据，所在的服务器只监听你的本机。

TablePlus

在 TablePlus 中打开（在服务或某个数据库上）会打开一个已命名为「Joppa · 数据库名」、并以绿色标记为本地环境的连接。

在终端中

joppa dbs postgres          # 数据库及其 URL
joppa dbs postgres --json   # 供脚本使用

PostgreSQL 扩展

安装在服务器上

有些扩展需要服务器上的文件。在 版本、端口和扩展… 中选择它们：Joppa 会在下次启动时构建一个包含这些扩展的本地 PostgreSQL 镜像（首次需要几分钟）。现有数据库会保留。

扩展	用途
pgvector（vector）	嵌入向量和相似度搜索
PostGIS	地理数据
pgRouting	路径规划（配合 PostGIS）
HypoPG	假设索引
pg_partman	分区
pg_stat_statements	查询统计（预加载）

始终可用

pg_trgm、uuid-ossp、pgcrypto、citext、hstore、unaccent、fuzzystrmatch。

按数据库

在数据库上使用 扩展… 可以启用或移除扩展。取消勾选扩展会将其从数据库中删除，连同依赖它的内容（vector 列、几何数据…）。

新数据库中默认启用 用于选择创建数据库时预先勾选的扩展；外部工具（迁移、createdb）创建的数据库中也会包含它们。

MySQL 和 MariaDB

MySQL 使用官方镜像（LTS 与 innovation 版本），MariaDB 是它的社区分支，兼容相同的客户端。两者默认都使用 3306 端口：如果同时运行两者，第二个会使用 3307。

导出单个数据库

数据库菜单中的 导出… 会把它保存到你选择的文件中：

格式	内容
.sql.gz（默认建议）	用 gzip 压缩的 SQL
.sql	可读的 SQL
.dump（PostgreSQL）	pg_dump -Fc 归档，由 pg_restore 读取

文件中不包含所有者和权限（pg_dump --no-owner --no-acl），也不包含 CREATE DATABASE（mysqldump --single-transaction --routines --triggers --events）：可以用任意名称重新载入，在这里或其他地方都可以。

导入文件

数据库列表上方的 导入… 会把文件载入服务器。数据库菜单中的 导入到此数据库… 做同样的事，但目标是该数据库。Joppa 可以读取：

• PostgreSQL、MySQL 或 MariaDB 的 .sql 或 .sql.gz 文件；
• PostgreSQL 的 .dump 归档（pg_dump -Fc）；
• 整个服务器的导出：来自 导出数据库 (.sql)…、pg_dumpall 或 mysqldump --all-databases。

在执行任何操作之前，Joppa 会读取文件并显示：

• 导入的目标数据库，按文件命名（acme-2026-10-23.sql.gz 得到 acme），可以修改。如果它已存在，请勾选 替换 acme，或使用建议的名称（以 acme_import 导入）；
• 对于整个服务器的导出，它会创建的数据库，以及已经存在、将被替换的数据库：请勾选 替换这些数据库；
• 文件中的 PostgreSQL 扩展：可用、请先在服务器上启用（在 版本、端口和扩展… 中），或 Joppa 不提供。依赖缺失扩展的内容不会被载入。

导入过程中，进度条跟随文件的读取。结束时，Joppa 会汇总途中跳过的错误（未知的角色、缺失的扩展）。如果恢复失败，会显示客户端（psql、pg_restore、mysql）的消息，并删除导入时创建的数据库。

Joppa 在读取时会调整文件：删除指向其他服务器账户的 OWNER TO 和 DEFINER=，为 MariaDB 把 MySQL 8 的 utf8mb4_0900_* 排序规则替换为 utf8mb4_unicode_ci，并且在整个服务器的导出中跳过系统数据库（mysql、sys…）和 Joppa 自己的账户。

复制数据库

复制… 会在同一服务器上创建一个副本，包含其表、数据和扩展（默认名称为 acme_copy）。没有任何连接时，PostgreSQL 直接复制数据库文件（CREATE DATABASE … TEMPLATE），否则通过导出再恢复；MySQL 和 MariaDB 始终通过导出完成。

快照

使用 Joppa Pro 时，数据库菜单中的 快照… 会打开它的快照：由 Joppa 保存的数据库副本，一键即可恢复。

• 创建快照，可以起个名字（“迁移之前”）。
• 恢复… 会让数据库回到该快照。它当前的内容会先保存为一个新快照，“恢复之前”。
• 垃圾桶图标会删除快照。
• 每个数据库保留：超过此数量（默认 10 个）后，最旧的快照会被删除。

自动快照

使用 Joppa Pro 时，Joppa 会在每次会删除数据的操作之前创建快照。如果快照失败，操作不会执行。

操作	快照标签
删除数据库	删除之前
导入替换某个数据库的文件	导入之前
从 Docker Compose 导入 并替换数据库	Compose 导入之前
恢复快照	恢复之前

已删除数据库的快照会保留：它们显示在列表下方的 已删除的数据库 中，恢复其中一个会重新创建该数据库。

快照位于 Joppa 的 snapshots/ 文件夹中（参见 文件和文件夹）：每个快照是一个 .dump（PostgreSQL）或 .sql.gz（MySQL、MariaDB）文件，旁边有一个描述它的 .json。没有 Joppa Pro 时，列表仍然可见，快照也可以删除，但不能创建或恢复。

在终端中使用

joppa db export postgres acme                       # ./acme-2026-10-23.sql.gz
joppa db export postgres acme ~/acme.dump           # PostgreSQL 归档
joppa db import postgres ~/acme.sql.gz --into acme_test
joppa db import postgres ~/acme.sql.gz --replace    # 替换 acme
joppa db clone postgres acme acme_feature
joppa db snapshot postgres acme --name "迁移之前"
joppa db snapshots postgres acme
joppa db restore postgres acme 20261023-142501

参见 joppa 命令。

导出数据库

PostgreSQL、MySQL 或 MariaDB 服务器的 ⋯ 菜单中的 导出数据库 (.sql)… 会把它的所有数据库保存到你选择位置的一个 SQL 文件中（pg_dumpall 或 mysqldump --all-databases）。已停止的服务器会在导出期间启动，导出后再次停止。

被免费版锁定的服务器同样可以导出（参见 许可证与方案）：你的数据始终属于你。要把这样的文件放回服务器：导入文件。