分类： Frappe

用法

bench trim-tables [OPTIONS]

说明

从某个 DocType 中移除的文档字段可能不会从其
数据库表中删除。这是 Frappe 的刻意设计，以防止数据过早丢失。
大多数情况下这不会造成问题，但到了某个时候，你可能会因为
这些残留数据而遇到麻烦。

定期清理表的一些好处包括：

• 更小的备份体积
• 缩短站点备份所需时间
• 减少站点数据库占用
• 在 SELECT * 的情况下优化查询
• 数据库干净整洁，没有隐藏或冗余的数据

此命令会修改你站点数据库中表的架构。默认情况下，它会在修改之前
对你的整个数据库进行完整备份。万一这些表
被错误地修改了，你可以使用恢复命令将站点
恢复到原始状态。

选项

• --format、-f 设置输出格式。可用选项为 JSON 和 TEXT。
  默认为 TEXT。

标志

• --dry-run 显示将要删除的内容
• --no-backup 不备份站点。不建议这样做，因为这是一个
  破坏性操作。

示例

1. 可能存在大量残留列占用空间。也许你是在自定义 DocType 时
   遇到行大小限制已达上限的错误，才发现了这个问题。为了
   确认没有任何幽灵列或旧的隐藏字段占用空间，你可以
   运行以下命令来确认

bench --site {site} trim-tables --dry-run

用法

bench trim-database [OPTIONS]

描述

从列表视图中删除 DocType 可能不会从数据库中删除它们对应的表。
迁移有时可能会在你的站点数据库中留下幽灵表。这样做可能是为了冗余、
在你的数据损坏或丢失时进行恢复，或者仅仅是因为人为错误。

此命令会删除任何看起来像是上述残留的表。在删除之前，它会尝试对这些表进行部分备份。
如果这些表是必需的，并且被错误地删除了，你可以使用 partial-restore 命令将它们恢复到你的站点数据库中。

选项

• --format、-f 设置输出格式。可用选项为 JSON 和 Table。默认为 Table。

标志

• --dry-run 显示将被删除的内容。
• --no-backup 在清理之前不要备份站点。

示例

1. 你想知道运行此命令会删除哪些数据吗？请使用
   --dry-run 标志运行它。

bench --site {site} trim-database --dry-run

1. 想在此基础上构建，并且需要数据可被机器解析？将输出
   --format 设置为 json。

bench --site {site} trim-database --format json

此命令在 版本 14 中添加，且仅支持 MariaDB

用法

bench transform-database [OPTIONS] table

描述

transform-database 命令允许你管理站点表的设置。目前，你可以为站点数据库中的选定表切换存储引擎和行格式设置。

MariaDB 10.6 弃用了 COMPRESSED 行格式，而该格式长期以来一直是 Frappe 的默认选项。添加此命令是为了处理升级到更高版本 MariaDB 的情况。有关更多信息，请参阅 PR。

选项

• --table 要转换的表的名称，以逗号分隔。要转换所有表，请传入 ‘all’ [必填]
• --engine 为上述表选择存储引擎。可用选项为 InnoDB 和 MyISAM。
• --row_format 为上述表设置 ROW_FORMAT 参数。可用选项为 DYNAMIC、COMPACT、REDUNDANT、COMPRESSED。

标志

• failfast 在首次失败时退出

示例

1. 假设你想将表 “tabAccess Record” 的引擎更改为 MyISAM。如果这是一个处理大量写入和极少读取的日志表，你可能会想这样做。

bench --site {site} transform-database --table 'tabAccess Record' --engine 'MyISAM'

2. 你已将当前服务器上的 MariaDB 从 10.3 升级到 10.7，并且你想将所有使用 COMPRESSED 行格式的表转换为新的默认格式，即 DYNAMIC。你需要运行以下命令。

bench --site {site} transform-database --table 'all' --row_format 'DYNAMIC'

用法

bench version [OPTIONS]

说明

version 命令会显示当前 bench 目录中所有已安装应用的编译信息。你可以选择自己喜欢的输出格式：纯文本、JSON 或 ASCII 表格。--format plain 选项会以纯文本形式显示版本信息，就像 bench version 一样，但会包含更多信息。

$ bench version --format plain
erpnext 14.0.3 version-14 (4e88dcf)
frappe 14.0.1 version-14 (f8ec3d7)

--format json 选项会以格式化 JSON 字符串的形式显示版本信息。如果你要在 bench CLI 之上构建工具，这会特别有用。

$ bench version --format json
[
 {
 "app": "erpnext",
 "branch": "version-14",
 "commit": "4e88dcf",
 "version": "14.0.3"
 },
 {
 "app": "frappe",
 "branch": "version-14",
 "commit": "ef0a5e9",
 "version": "14.0.1"
 }
]

--format table 选项会以 ASCII 表格的形式显示版本信息。

$ bench version --format table
+-------------------------+------------+------------------------------+---------+
| App | Version | Branch | Commit |
+-------------------------+------------+------------------------------+---------+
| erpnext | 14.0.3 | version-14 | 4e88dcf |
| frappe | 14.0.1 | version-14 | f8ec3d7 |
+-------------------------+------------+------------------------------+---------+

选项

• -f、--format 选择显示当前 bench 中已安装应用版本的格式。可用选项有 “plain”、”table”、”json”、”legacy”。该值默认为 “legacy”。

示例

1. 获取当前 bench 上已安装应用的人类可读信息，并包含提交消息。

bench version --format plain

1. 以 JSON 格式获取 bench 版本信息。

bench version -f json

用法

bench partial-restore [OPTIONS] SQL_FILE_PATH

说明

你可能只想恢复已备份到某个站点的特定数据表。你很可能使用了 bench backup 中的 --only、--exclude 选项进行了部分备份。

partial-restore 命令可用于通过部分备份来恢复站点。部分备份文件可以是 gzip 压缩文件或纯 SQL 文件。本质上，你可以使用此命令从 SQL 文件中恢复任何内容。

参数

• SQL_FILE_PATH 数据库源文件的路径。该路径可以是相对于 bench 目录根目录或 sites 文件夹的相对路径，也可以是绝对路径。

如需了解有关相对路径和绝对路径的更多信息，请在维基百科上点击此处。

选项

• -v、--verbose 增加详细输出

示例

1. 在站点上使用部分备份进行恢复。

bench --site {site} partial-restore -v {/path/to/sql/file}

用法

bench restore [OPTIONS] SQL_FILE_PATH

说明

Bench CLI 可用于将现有站点恢复到之前的状态。使用
bench restore 命令，可以通过指定的数据库和
文件恢复来还原站点。Frappe 站点不支持降级；当检测到降级时，
在站点恢复开始之前会弹出一个交互式提示。

执行恢复操作的最低要求是在本地文件系统上拥有数据库
文件。指定的路径可以是相对于 bench
或 sites 文件夹的路径，不过绝对路径通常效果最好。

指定的数据库备份文件可以具有 sql.gz 或 sql 扩展名。对于
公共和私有文件备份归档，默认是 tar，但自 版本
13 起，也支持扩展名为 tgz 的压缩归档。

注意：截至目前，无法使用此
命令仅恢复文件。

参数

• SQL_FILE_PATH 数据库源文件的路径。该路径可以相对于
  bench 目录根或 sites 文件夹。也可以是绝对路径。

要了解有关相对路径和绝对路径的更多信息，请在 Wikipedia 上点击此处。

选项

• --db-root-username MariaDB 或 Postgres 的 root 用户名
• --db-root-password MariaDB 或 Postgres 的 root 密码
• --db-name 站点数据库名称，如果它是新站点
• --admin-password 新站点的管理员密码
• --install-app 安装后安装应用
• --with-public-files 恢复站点的公共文件，给定其
  归档文件的路径
• --with-private-files 恢复站点的私有文件，给定其
  归档文件的路径

标志

• --force 忽略站点降级警告（如果适用）。除非你完全了解
  后果，否则不推荐这样做

示例

1. 使用文件恢复站点

bench --site {site} restore {path/to/database/file}
--with-public-files {path/to/public/archive}
--with-private-files {path/to/private/archive}

1. 通过在选项中传递值来绕过 DBMS root 交互式提示

bench --site {site} restore {path/to/database/file}
--db-root-username {db-user}
--db-root-password {db-pass}

1. 指定站点恢复后要安装的新应用

bench --site {site} restore {path/to/database/file}
--install-app {app}

1. 为恢复的站点指定自定义数据库名称

bench --site {site} restore {path/to/database/file}
--db-name {custom-db-name}

1. 重置恢复站点的管理员密码

bench --site {site} restore {path/to/database/file}
--admin-password {admin-pass}

bench execute 命令让你可以从命令行运行 Python 函数。这对于执行一次性任务、调试或运行自定义脚本非常有用。

该命令会自动建立数据库连接并为站点初始化 Frappe 框架，因此你可以直接调用与数据库交互的函数，无需编写任何初始化代码。

基本用法

bench --site [site-name] execute [path.to.method]

简单示例

bench --site frappe.test execute frappe.clear_cache

这会在你的站点上运行 frappe.clear_cache() 函数。

bench --site frappe.test execute frappe.utils.get_site_info

这会在你的站点上运行 frappe.utils.get_site_info() 函数并打印输出结果。

传递参数

你可以直接在方法名后面传递参数：

bench --site frappe.test execute frappe.get_doc User Administrator

这会调用 frappe.get_doc("User", "Administrator")。

bench --site frappe.test execute frappe.db.get_value DocType User name

这会调用 frappe.db.get_value("DocType", "User", "name")。

JSON 参数

参数会尽可能自动解析为 JSON：

bench --site frappe.test execute frappe.db.exists User Administrator

字符串 “Administrator” 会保持为字符串，但数字和布尔值会被转换：

bench --site frappe.test execute some_function 123 true false

这会传入整数 123 以及布尔值 True 和 False。

命名参数（kwargs）

使用 -- 前缀来指定命名参数：

bench --site frappe.test execute frappe.db.get_value --doctype User --filters '{"name":"Administrator"}' --fieldname email

这会调用：

frappe.db.get_value(doctype="User", filters={"name": "Administrator"}, fieldname="email")

布尔标志

不带值的命名参数会变为 True：

bench --site frappe.test execute frappe.get_list User --ignore_permissions

这会调用 frappe.get_list("User", ignore_permissions=True)。

混合使用位置参数和命名参数

bench --site frappe.test execute frappe.get_list User --limit 5

这会调用 frappe.get_list("User", limit=5)。

运行 Python 表达式

你可以直接运行 Python 表达式：

bench --site frappe.test execute "frappe.db.count('User')"

你可以调用不同类型的 Python 可调用对象：

# Method on a returned object
bench --site frappe.test execute "frappe.get_doc('User', 'Administrator').reload()"

更多示例

# Clear cache for a specific DocType
bench --site frappe.test execute frappe.clear_cache --doctype "Sales Order"

# Get a document
bench --site frappe.test execute frappe.get_doc User Administrator

# Count records
bench --site frappe.test execute frappe.db.count User

# Run a whitelisted method
bench --site frappe.test execute myapp.api.my_function --param1 value1 --param2 value2

# Check if a record exists
bench --site frappe.test execute frappe.db.exists User guest

# Get configuration value
bench --site frappe.test execute frappe.conf.get developer_mode

# Execute a DocType method
bench --site frappe.test execute "frappe.get_doc('User', 'Administrator').get_fullname()"

# Chain operations with Python expressions
bench --site frappe.test execute "frappe.get_doc('User', 'Administrator').add_roles('System Manager')"

性能分析

使用 --profile 标志来查看性能统计信息：

bench --site frappe.test execute frappe.db.get_list --profile --doctype "Sales Order" --limit 1000

这会按累计时间排序列出前 50% 的函数调用。

        42084 function calls (41224 primitive calls) in 0.094 seconds

   Ordered by: cumulative time
   List reduced from 801 to 401 due to restriction <0.5>

   ncalls  tottime  percall  cumtime  percall filename:lineno(function)
      3/2    0.000    0.000    0.091    0.046 {built-in method builtins.eval}
        1    0.000    0.000    0.091    0.091 <bench execute>:1(<module>)
        1    0.000    0.000    0.091    0.091 ~/frappe-bench/apps/frappe/frappe/database/database.py:830(get_list)
     11/1    0.000    0.000    0.091    0.091 ~/frappe-bench/apps/frappe/frappe/__init__.py:1337(get_list)
       31    0.000    0.000    0.073    0.002 ~/frappe-bench/apps/frappe/frappe/database/database.py:183(sql)
       29    0.000    0.000    0.072    0.002 ~/frappe-bench/apps/frappe/frappe/query_builder/utils.py:126(execute_query)
     18/5    0.000    0.000    0.071    0.014 ~/frappe-bench/apps/frappe/frappe/utils/caching.py:125(site_cache_wrapper)
    20/12    0.000    0.000    0.070    0.006 ~/frappe-bench/apps/frappe/frappe/model/meta.py:72(get_meta)
      7/3    0.000    0.000    0.070    0.023 ~/frappe-bench/apps/frappe/frappe/model/utils/__init__.py:132(is_virtual_doctype)
        2    0.000    0.000    0.069    0.034 ~/frappe-bench/apps/frappe/frappe/model/meta.py:149(__init__)
       31    0.000    0.000    0.066    0.002 ~/frappe-bench/apps/frappe/frappe/database/database.py:371(execute_query)
       31    0.000    0.000    0.066    0.002 ~/frappe-bench/env/lib/python3.14/site-packages/MySQLdb/cursors.py:162(execute)
       31    0.000    0.000    0.066    0.002 ~/frappe-bench/env/lib/python3.14/site-packages/MySQLdb/cursors.py:325(_query)
       31    0.000    0.000    0.065    0.002 ~/frappe-bench/env/lib/python3.14/site-packages/MySQLdb/connections.py:276(query)
       31    0.065    0.002    0.065    0.002 {function Connection.query at 0x10be545c0}
       16    0.000    0.000    0.056    0.003 ~/frappe-bench/apps/frappe/frappe/database/database.py:592(get_values)
        2    0.000    0.000    0.034    0.017 ~/frappe-bench/apps/frappe/frappe/model/meta.py:166(process)
     31/2    0.000    0.000    0.034    0.017 ~/frappe-bench/apps/frappe/frappe/model/document.py:187(__init__)
        2    0.000    0.000    0.034    0.017 ~/frappe-bench/apps/frappe/frappe/model/meta.py:157(load_from_db)
        2    0.000    0.000    0.034    0.017 ~/frappe-bench/apps/frappe/frappe/model/document.py:233(load_from_db)
     11/1    0.000    0.000    0.025    0.025 ~/frappe-bench/apps/frappe/frappe/model/qb_query.py:26(execute)
    27/13    0.000    0.000    0.022    0.002 ~/frappe-bench/apps/frappe/frappe/query_builder/utils.py:62(get_query)
        2    0.000    0.000    0.021    0.011 ~/frappe-bench/apps/frappe/frappe/model/meta.py:422(apply_property_setters)
        2    0.000    0.000    0.018    0.009 ~/frappe-bench/apps/frappe/frappe/model/document.py:304(load_children_from_db)
    27/13    0.000    0.000    0.018    0.001 ~/frappe-bench/apps/frappe/frappe/database/query.py:215(get_query)
        2    0.000    0.000    0.016    0.008 ~/frappe-bench/apps/frappe/frappe/database/database.py:514(get_value)
    27/13    0.000    0.000    0.015    0.001 ~/frappe-bench/apps/frappe/frappe/database/query.py:344(apply_fields)
        1    0.000    0.000    0.014    0.014 ~/frappe-bench/apps/frappe/frappe/database/query.py:1280(apply_field_permissions)
        1    0.000    0.000    0.013    0.013 ~/frappe-bench/apps/frappe/frappe/database/query.py:928(_get_cached_permitted_fields)
        1    0.000    0.000    0.013    0.013 ~/frappe-bench/apps/frappe/frappe/model/__init__.py:216(get_permitted_fields)
        1    0.000    0.000    0.013    0.013 ~/frappe-bench/apps/frappe/frappe/model/meta.py:677(get_permitted_fieldnames)
        1    0.000    0.000    0.013    0.013 ~/frappe-bench/apps/frappe/frappe/model/meta.py:720(get_permlevel_access)
        2    0.000    0.000    0.013    0.007 ~/frappe-bench/apps/frappe/frappe/__init__.py:384(get_roles)
        2    0.000    0.000    0.013    0.007 ~/frappe-bench/apps/frappe/frappe/permissions.py:522(get_roles)
        2    0.000    0.000    0.013    0.007 ~/frappe-bench/apps/frappe/frappe/utils/redis_wrapper.py:230(hget)
        1    0.000    0.000    0.013    0.013 ~/frappe-bench/apps/frappe/frappe/permissions.py:530(get)
        1    0.000    0.000    0.012    0.012 ~/frappe-bench/env/lib/python3.14/site-packages/redis/client.py:1163(get_message)
        1    0.000    0.000    0.012    0.012 ~/frappe-bench/env/lib/python3.14/site-packages/redis/client.py:979(parse_response)
        1    0.000    0.000    0.012    0.012 ~/frappe-bench/env/lib/python3.14/site-packages/redis/client.py:960(_execute)
       13    0.000    0.000    0.009    0.001 ~/frappe-bench/apps/frappe/frappe/model/meta.py:108(get_table_columns)
       13    0.000    0.000    0.009    0.001 ~/frappe-bench/apps/frappe/frappe/database/database.py:1356(get_table_columns)
       13    0.000    0.000    0.009    0.001 ~/frappe-bench/apps/frappe/frappe/database/database.py:1337(get_db_table_columns)

在多个站点上运行

在所有站点上执行命令：

bench --site all execute frappe.clear_cache

或在指定站点上执行：

bench --site site1.local --site site2.local execute frappe.clear_cache

注意事项

• 数据库：成功时更改会自动提交，出错时会回滚
• 返回值：返回值会以 JSON 格式打印；None 不打印任何内容
• 错误处理：出错时会以错误码退出并打印完整的堆栈跟踪
• 安全性：任何 Python 函数都可以执行，不仅限于白名单中的函数——在生产环境中请谨慎使用

使用 –args 和 –kwargs 选项（旧版）

> 注意：--args 和 --kwargs 选项是旧格式，不推荐使用。请改用上面展示的直接传参方式。

你必须使用 Python 语法来配合 --args 和 --kwargs 选项。这些值必须用引号括起来，并且会作为 Python 代码进行求值（使用 eval()），而不是作为 JSON 解析。

传递参数列表

bench --site frappe.test execute frappe.db.get_value --args "['User', 'Administrator', 'email']"

传递关键字参数字典

bench --site frappe.test execute frappe.db.set_value --kwargs "{'doctype': 'User', 'name': 'Administrator', 'fieldname': 'enabled', 'value': 1}"

组合使用

bench --site frappe.test execute frappe.db.get_value --args "['User', 'Administrator']" --kwargs "{'fieldname': 'email'}"

用法

bench set-config [OPTIONS] KEY VALUE

说明

Bench 提供了一个包装命令，用于在站点配置文件中插入或更新值。
你可以通过同一个命令更新站点中的 site_config.json，以及
bench 目录中的 common_site_config.json。

如需了解更多关于站点配置和键优先级的内容，请参阅
此处的文档。

参数

• -g, --global 在 Bench 的通用站点配置中设置值
• -p, --parse 解析给定的值而不是按字符串处理。你可以用它来设置
  字典和列表类型的值。在早期版本中，这个参数是 --as-dict。

示例

1. 为指定站点启用测试。

bench --site {site} set-config allow_tests true

1. 为所有站点启用测试。

bench --site all set-config allow_tests true

使用上面的命令，每个站点的 site_config.json 中都会有
键值对 "allow_tests": true。这样就可以在所有
站点上运行测试了。

bench set-config -g allow_tests true

使用上面的命令，bench 的 common_site_config.json 中会有
键值对 "allow_tests": true。这样 bench 上的每个站点都可以
运行测试，除非它们在 site_config.json 中为 sma 定义了
值。

1. 在站点的 frappe.conf 中设置一个字典值

bench --site {site} set-config backup '{"includes": ["Not", "ToDo"]}' --parse

现在你可以在代码中通过 frappe.conf.backup.get("includes") 来访问这个列表。

用法

bench show-config [OPTIONS]

说明

你站点的生效配置是由 bench 目录下的 common_site_config.json 和站点自身的 site_config.json 组合而成的。Bench 提供了一个界面，可以查看你站点当前生效的 frappe.conf 值。你可以选择以表格或 JSON 格式来查看这些信息。

想进一步了解站点配置以及键的优先级规则，请参阅这里的文档。

参数选项

• -f、--format 选择列出指定站点上已安装应用的格式，可选值为 “text” 和 “json”。默认为 “text”。

示例

1. 以 JSON 格式显示所有站点的配置。

bench --site all show-config -f json

2. 以表格形式显示站点配置。

bench --site {site} show-config --format text

bench --site {site} show-config -f text

bench --site {site} show-config

用法

bench uninstall-app [OPTIONS] APP

说明

从站点中移除应用程序及其关联的文档类型和模块。执行
原生命令时，会先检查站点上是否存在该应用，然后再尝试删除
其模块和文档类型。运行 uninstall-app 命令时，该应用不一定
已安装在 bench 上。

选项

• -y、--yes 跳过卸载应用的确认提示
• --dry-run 列出所有将被删除的文档类型
• --no-backup 不备份站点
• --force 强制从站点移除该应用

示例

1. 执行一次试运行，查看在特定站点上运行会发生什么。

bench --site {site} uninstall-app {app} --dry-run

1. 在卸载应用操作之前不进行备份。

bench --site {site} uninstall-app {app} --no-backup

1. 使用强制方式从站点卸载应用。

bench --site {site} uninstall-app {app} --force

2. 跳过卸载确认的交互式提示。

bench --site {site} uninstall-app {app} --yes