Metabase 连接 MySQL 数据库实战指南配置详解、MySQL 8 认证兼容与 JSON 字段同步【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase本文以 Metabase 开源仓库当前工作目录metabase/中的 MySQL 连接官方文档 为主体结合 MySQL 驱动源码 与相关测试、文档系统讲解如何在 Metabase 管理界面中配置 MySQL 数据仓库连接、解决 MySQL 8 默认认证插件不兼容问题、处理 JSON 字段同步与展开、规避 Vitess 兼容性限制并厘清模型动作、模型持久化、可编辑表等高级功能对数据库账号权限的要求。读完本文你将能够独立完成一条 MySQL 连接的完整配置与排障掌握 MariaDB 驱动连接 MySQL 8 时的认证插件切换方案理解 JSON 展开与 500 行 schema 推断机制背后的实现原理并为可写功能Actions、模型持久化、表数据编辑准备具备正确权限的数据库账号。连接前的准备版本支持与入口Metabase 官方支持从 MySQL 社区仍维护的最老版本到最新稳定版本的所有 MySQL 版本详见文档原话 the oldest supported version through the latest stable version。在驱动源码层面src/metabase/driver/mysql.clj 定义了更精确的最低版本约束(def ^:private ^:const min-supported-mysql-version 5.7) (def ^:private ^:const min-supported-mariadb-version 10.2)也就是说MySQL 5.7 以下、MariaDB 10.2 以下会在建立连接时被检测并打出红色警告日志WARNING: Metabase only officially supports MySQL 5.7/MariaDB 10.2 and above.见 warn-on-unsupported-versions。MariaDB 与 MySQL 共用同一个驱动因此连接 MariaDB 时同样选择MySQL驱动见 MariaDB 文档。本页讨论的是把 MySQL 当作 Metabase 的数据仓库data warehouse来连接。若要把 MySQL 用作 Metabase 自身的应用数据库application database请参阅 配置 Metabase 应用数据库。添加数据库连接的入口点击右上角网格grid图标依次进入Admin管理员Databases数据库Add a database添加数据库数据库类型选择MySQL。编辑连接详细信息每个字段的含义与建议以下字段在建立连接后仍可随时修改修改后记得保存。Connection string连接字符串可以粘贴一段连接字符串来预填下方其余字段适合从已有配置迁移时使用。Display name显示名称该数据库在 Metabase 界面中的显示名称建议使用团队可识别的业务名称。Host主机数据库的 IP 地址或域名例如esc.mydatabase.com。Port端口数据库端口MySQL 默认3306。这也是驱动连接属性表单中的默认占位值见 connection-properties。Username用户名用于连接数据库的账号。可以针对同一数据库使用不同账号建立多条连接每条连接可拥有不同的 权限集合。Password密码对应账号的密码。Use an authentication provider使用认证提供方除了密码还可以使用受支持的认证提供方进行认证仅适用于自托管 Pro 与 Enterprise 套餐文档以 plans-blockquote 标注。IAM authenticationIAM 认证如需使用 IAM 认证连接 Amazon RDS 实例参见 AWS RDS 的 IAM 认证。从驱动源码看auth-provider为:aws-iam时连接规格会被改写为 AWS 包装驱动(subprotocol aws-wrapper:mysql :classname software.amazon.jdbc.ds.AwsWrapperDataSource :sslMode VERIFY_CA :wrapperPlugins iam)并强制要求必须启用 SSL否则抛异常 You must enable SSL in order to use AWS IAM authentication且sslMode必须为VERIFY_CA见 connection-details-spec。Use a secure connection (SSL)使用安全连接可在此粘贴服务器 SSL 证书链Server SSL certificate chainPEM 格式。源码中证书会被映射为 JDBC 参数serverSslCert见 default-ssl-cert-details 与连接规格构造逻辑。若使用 SSL 连接失败可尝试在附加 JDBC 选项中追加trustServerCertificatetrue见下文排障章节。Use an SSH tunnel使用 SSH 隧道通过 SSH 隧道访问数据库参见 SSH 隧道指南。Unfold JSON Columns展开 JSON 列MySQL 的JSON类型列可以在 Metabase 中被展开为组件字段component fields每个 JSON key 变成一列。JSON 展开默认开启如果性能不佳可以关闭。开启后还可以在 表元数据 中针对单个列单独切换展开与否。驱动源码佐证了这一点database-supports? :nested-field-columns 的实现是(and (driver/common/json-unfolding-default db) (not (mariadb? db)))——即 JSON 展开默认开启且MariaDB 不支持MariaDB 没有真正的 JSON 类型10.2.7 起JSON只是LONGTEXT的别名。这与 MariaDB 文档 中 JSON folding is not supported for MariaDB databases 的表述一致。在查询执行层面展开的 JSON 字段通过json_unquote(json_extract(...))生成 SQL并按目标类型做转换时间戳走str_to_date、布尔直接返回、浮点用 0.0技巧兼容旧版 MySQL见 json-query 实现。类型映射上MySQL 的JSON数据库类型被映射为:type/JSON见 database-type-base-type。Additional JDBC connection string options附加 JDBC 连接字符串选项可以追加 Metabase 连接数据库所用的 JDBC 连接字符串参数例如占位符中给出的tinyInt1isBitfalse——该参数控制tinyint(1)是否被当作布尔BIT处理驱动在同步与查询执行两个阶段都会检查它见 describe-fields-sql 与 db-type-name。驱动内置了一批默认连接参数见 default-connection-args供参考JDBC 参数值作用zeroDateTimeBehaviorconvertToNullMySQL 合法的0000-00-00日期在 Java 中非法转换为nulluseUnicode/characterEncoding/characterSetResultstrue/UTF8/UTF8强制结果集使用 UTF-8 编码useCompressiontrue在 Metabase 与 MySQL 之间对数据包做 GZIP 压缩useLocalSessionStatetrue本地记录事务隔离级别与自动提交避免每次查询命中数据库nullCatalogMeansCurrenttrue同步时仅枚举当前绑定的库不扫描用户有权限的所有库需要注意附加选项存在安全过滤。驱动会拒绝allowLoadLocalInfile、allowLoadLocalInfileInPath、allowUrlInLocalInfile、autoDeserialize、serverRSAPublicKeyFile等危险键见 validate-db-details!一旦命中会抛出 Potentially dangerous keys in additional options 异常。Re-run queries for simple explorations简单探索时重跑查询默认情况下只要在Summarize汇总菜单中选择分组选项、或在 钻取菜单 中选择过滤条件Metabase 就会立即执行查询。如果你的数据库较慢可以关闭此选项改为让用户先点击Run播放按钮再应用 汇总 或过滤选择避免每次点击都加载数据。Choose when syncs and scans happen选择同步与扫描时机具体选项说明参见 同步与扫描。开启后可配置数据库同步频率每小时默认或每天运行时刻以 Metabase 应用服务器所在时区为准。字段值扫描filter values用于在仪表板/问题中启用复选框过滤。可选按计划定期运行、仅在添加新过滤组件时按需扫描并缓存、从不需要时手动执行配合 手动重扫字段值 按钮使用。Periodically refingerprint tables定期为表重建指纹周期性重建指纹会增加数据库负载。开启后每次 Metabase 执行 同步 时都会抽样扫描列值。指纹查询会检查每列的前 10,000 行数据据此估算每列的唯一值数量、数值与时间戳列的最小/最大值等。若关闭Metabase 只会在初次设置时对列建立一次指纹。连接 MySQL 8 服务器认证插件兼容性Metabase 使用MariaDB 驱动连接 MySQL 服务器而该驱动不支持 MySQL 8 的默认认证插件caching_sha2_password。要连接 MySQL 8需要把 Metabase 所用账号的认证插件切换为mysql_native_passwordALTER USER metabase% IDENTIFIED WITH mysql_native_password BY thepassword;如果密码中包含了 MySQL 无法以 UTF-8 直接理解的字符可能需要在附加 JDBC 选项中追加passwordCharacterEncoding你的编码例如passwordCharacterEncodingISO-8859-1确保认证时 MySQL 能正确解析密码中的特殊字符见 Passwords with special characters。无法用正确的凭据登录Unable to log in with correct credentials如何识别Metabase 报错 Looks like the username or password is incorrect但你确信用户名和密码正确。原因可能是你创建的 MySQL 用户所允许的主机host与你实际连接的主机不一致。典型场景MySQL 跑在 Docker 容器里而metabase用户是用CREATE USER metabaselocalhost IDENTIFIED BY thepassword;创建的。此时localhost会被解析为 Docker 容器本身而不是宿主机导致访问被拒绝。在 Metabase 服务日志中会出现类似错误Access denied for user metabase172.17.0.1 (using password: YES).注意其中的主机名172.17.0.1此处是 Docker 网络 IP以及结尾的using password: YES。用命令行客户端也会得到相同错误mysql -h 127.0.0.1 -u metabase -p。如何修复用正确的主机名重建 MySQL 用户CREATE USER metabase172.17.0.1 IDENTIFIED BY thepassword;必要时也可用通配符%作为主机名CREATE USER metabase% IDENTIFIED BY thepassword;然后为该用户授权以只读 SELECT 为例GRANT SELECT ON targetdb.* TO metabase172.17.0.1; FLUSH PRIVILEGES;记得删除旧用户DROP USER metabaselocalhost;如果用户、主机、密码都正确仍然连不上可以在附加 JDBC 选项中追加trustServerCertificatetrue。该选项告诉驱动即使服务器证书缺少根证书也信任它从而建立安全连接。值得注意的是驱动日志会在未显式配置该选项而启用 SSL 时打印提示You may need to add trustServerCertificatetrue to the additional connection options to connect with SSL.见 connection-details-spec。另外驱动会把常见的连接错误人性化为可读提示见 humanize-connection-error-message原始错误人性化提示Communications link failure ...无法连接请检查主机和端口Unknown database ...数据库名称不正确Access denied for user...用户名或密码不正确Must specify port after : in connection string主机名不合法启动 MySQL 8 Docker 容器如果你要新建一个 MySQL 容器并且希望 Metabase 无需手动创建用户或切换认证机制即可连接或遇到了RSA public key is not available client side (option serverRsaPublicKeyFile not set)错误可以在运行容器时追加--default-authentication-pluginmysql_native_password启动参数。简单的docker run方式docker run -p 3306:3306 -e MYSQL_ROOT_PASSWORDxxxxxx mysql:8.xx.xx --default-authentication-pluginmysql_native_password或在 docker-compose 中mysql: image: mysql:8.xx.xx container_name: mysql hostname: mysql ports: - 3306:3306 environment: - MYSQL_ROOT_PASSWORDxxxxxx - MYSQL_USERmetabase - MYSQL_PASSWORDxxxxxx - MYSQL_DATABASEmetabase volumes: - $PWD/mysql:/var/lib/mysql command: [--default-authentication-pluginmysql_native_password]注意mysql_native_password在 MySQL 8.4 及以后版本默认被移除deprecated → removed生产环境更推荐按前文所述只对 Metabase 账号单独执行ALTER USER ... IDENTIFIED WITH mysql_native_password或评估升级驱动的可行性。同步包含 JSON 的记录500 行 schema 推断机制Metabase 会根据表的前五百行数据中出现的 JSON key 来推断 JSON 的schema。MySQL 的 JSON 字段本身没有 schemaMetabase 无法依靠表元数据来确定 JSON 字段包含哪些 key。作为变通Metabase 会取前 500 条记录并解析其中的 JSON 来推断schema。之所以限制为 500 条是为了避免同步元数据给数据库带来不必要的压力。由此带来的问题是如果 JSON 中的 key 逐条记录变化前 500 行可能无法覆盖该 JSON 字段用到的全部 key。要让 Metabase 推断出所有 key需要把缺失的 key 补充进前 500 行的 JSON 对象中例如临时插入包含这些 key 的样例记录完成同步后再删除。这与 MariaDB 形成对比由于 MySQL 与 MariaDB 实现上的差异JSON schema 推断在 MariaDB 上不生效见 MariaDB 文档。Vitess 系数据库的已知限制查询 Vitess 数据库如 PlanetScale时应在每个子查询内添加LIMIT子句。原因Metabase 通常会对最终查询结果施加行数限制如 2000 或 10000 行。但由于 Vitess 的一个已知 bugVitess 可能把这些限制施加到子查询上导致意外结果例如 Metabase 内不能显示全部结果行。变通办法就是在每个子查询中显式添加限制。还应与平台托管方确认Vitess 在返回 information_schema 元数据时可能出问题。Metabase 需要这些元数据来填充其应用数据库如果拿不到元数据字段可能不显示或显示为空。驱动源码同样体现了对 PlanetScale/Vitess 的关注同步表清单时不能传入getCatalog()的结果因为 Vitess 副本连接上getCatalog()会返回路由限定名dbreplica导致WHERE TABLE_SCHEMA dbreplica匹配不到任何行、同步到空库。因此驱动固定依赖nullCatalogMeansCurrenttrue并传入nilcatalog见 active-tables 与 default-connection-args。可写能力Writable connection 与账号权限要求Writable connection可写连接可另外设置一条专用于写操作的连接参见 可写连接。Model features模型相关功能选择是否启用与 Metabase 模型 相关的功能。这些功能通常要求用于连接的数据库账号同时具备读和写权限。Model actions模型操作开启后允许对基于该数据创建的模型执行 操作Actions。Actions 可以读取、写入和删除数据因此数据库用户需要写权限。驱动层面actions、actions/custom、actions/data-editing三个特性仅在驱动为:mysql时启用见 database-supports? 扩展相关实现位于 mysql/actions.clj。Model persistence模型持久化Metabase 会创建存放模型数据的表并按你定义的调度定期刷新。要启用 模型持久化需要授予该连接凭据在 Metabase 提供的 schema 上的读写权限。驱动特性表中:persist-models true表明该能力受支持见 特性声明。Editable table data可编辑表数据开启后管理员可以直接在 Metabase 界面中创建、更新、删除表中的记录。这要求连接数据库的账号具备相应表的写权限。参见 权限。驱动会通过SHOW GRANTS解析当前用户的表级权限SELECT/UPDATE/INSERT/DELETE用于判断表是否可写见 current-user-table-privileges 与 parse-grant。注意 MariaDB 因不允许普通用户查询角色权限而被跳过此外由于 MySQL 部分撤销partial revokes场景的解析错误metabase#38499表权限特性整体被禁用见 database-supports? :table-privileges可写性判定基于元数据表检查实现。另外uploads特性在 MySQL 上开启见 特性声明支持通过 CSV 上传建表当 MySQL 全局变量local_infile为ON时写入走LOAD DATA LOCAL INFILE批量导入否则回退到普通INSERT INTO见 insert-into!。进阶Database routing数据库路由启用数据库路由后管理员可以用一个数据库构建问题question而该问题会根据查看者身份针对具有相同 schema 的另一个数据库执行查询。参见 数据库路由。驱动特性表中:database-routing true见 特性声明确认 MySQL 驱动支持该能力。Danger zone危险区域涉及删除数据库等危险操作参见 Danger zone。驱动能力一览理解 MySQL 连接的上限结合 MySQL 驱动源码以下是该驱动声明的关键特性能力节选有助于判断哪些功能可在此连接上使用特性是否支持说明connection-impersonation是支持连接模拟需要角色connection-impersonation-requires-roleconvert-timezone/datetime-diff是时区转换与日期差函数基于convert_tz、timestampdiff实现full-join否MySQL 不支持 FULL JOINwindow-functions/offset否MySQL 不支持在含GROUP BY的查询中直接使用 lag/lead 实现 offsetpersist-models是模型持久化schemas否MySQL 无 schema 层其 database 即其他引擎的 schema驱动将:db槽位用于跨库路由uploads是CSV 上传建表case-sensitivity-string-filter-options否LIKE 大小写敏感度由服务器/列排序规则决定不提供 UI 开关nested-field-columns是MySQL/ 否MariaDBJSON 展开index/fetch、index/standalone-create是索引管理B-Tree 与 Full-text见 supported-index-methodsdatabase-routing是数据库路由同步相关实现也值得留意驱动从information_schema.columns读取字段元数据排除information_schema、performance_schema、sys、mysql等系统库及innodb_table_stats、innodb_index_stats表见 describe-fields-sqlMySQL 的DATETIME被映射为:type/DateTime、TIMESTAMP被映射为:type/DateTimeWithLocalTZ以 UTC 存储、YEAR映射为整数、TINYINT默认按布尔处理见 database-type-base-type。若时区相关查询异常可能需要把系统时区表导入 MySQLmysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql见 set-timezone-sql 注释。进一步阅读MariaDB 连接指南与 MySQL 共用驱动注意其 JSON 展开与 schema 推断的差异管理数据库元数据编辑含单列 JSON 展开开关JSON 展开详解模型设置数据访问权限同步与扫描驱动实现src/metabase/driver/mysql.clj、src/metabase/driver/mysql/actions.clj、src/metabase/driver/mysql/ddl.clj测试基座test/metabase/test/data/mysql.clj【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/11 2:48:05 · 阅读 1.2k Metabase 连接 MySQL 数据库实战指南：配置详解、MySQL 8 认证兼容与 JSON 字段同步
Metabase 连接 MySQL 数据库实战指南配置详解、MySQL 8 认证兼容与 JSON 字段同步【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase本文以 Metabase 开源仓库当前工作目录metabase/中的 MySQL 连接官方文档 为主体结合 MySQL 驱动源码 与相关测试、文档系统讲解如何在 Metabase 管理界面中配置 MySQL 数据仓库连接、解决 MySQL 8 默认认证插件不兼容问题、处理 JSON 字段同步与展开、规避 Vitess 兼容性限制并厘清模型动作、模型持久化、可编辑表等高级功能对数据库账号权限的要求。读完本文你将能够独立完成一条 MySQL 连接的完整配置与排障掌握 MariaDB 驱动连接 MySQL 8 时的认证插件切换方案理解 JSON 展开与 500 行 schema 推断机制背后的实现原理并为可写功能Actions、模型持久化、表数据编辑准备具备正确权限的数据库账号。连接前的准备版本支持与入口Metabase 官方支持从 MySQL 社区仍维护的最老版本到最新稳定版本的所有 MySQL 版本详见文档原话 the oldest supported version through the latest stable version。在驱动源码层面src/metabase/driver/mysql.clj 定义了更精确的最低版本约束(def ^:private ^:const min-supported-mysql-version 5.7) (def ^:private ^:const min-supported-mariadb-version 10.2)也就是说MySQL 5.7 以下、MariaDB 10.2 以下会在建立连接时被检测并打出红色警告日志WARNING: Metabase only officially supports MySQL 5.7/MariaDB 10.2 and above.见 warn-on-unsupported-versions。MariaDB 与 MySQL 共用同一个驱动因此连接 MariaDB 时同样选择MySQL驱动见 MariaDB 文档。本页讨论的是把 MySQL 当作 Metabase 的数据仓库data warehouse来连接。若要把 MySQL 用作 Metabase 自身的应用数据库application database请参阅 配置 Metabase 应用数据库。添加数据库连接的入口点击右上角网格grid图标依次进入Admin管理员Databases数据库Add a database添加数据库数据库类型选择MySQL。编辑连接详细信息每个字段的含义与建议以下字段在建立连接后仍可随时修改修改后记得保存。Connection string连接字符串可以粘贴一段连接字符串来预填下方其余字段适合从已有配置迁移时使用。Display name显示名称该数据库在 Metabase 界面中的显示名称建议使用团队可识别的业务名称。Host主机数据库的 IP 地址或域名例如esc.mydatabase.com。Port端口数据库端口MySQL 默认3306。这也是驱动连接属性表单中的默认占位值见 connection-properties。Username用户名用于连接数据库的账号。可以针对同一数据库使用不同账号建立多条连接每条连接可拥有不同的 权限集合。Password密码对应账号的密码。Use an authentication provider使用认证提供方除了密码还可以使用受支持的认证提供方进行认证仅适用于自托管 Pro 与 Enterprise 套餐文档以 plans-blockquote 标注。IAM authenticationIAM 认证如需使用 IAM 认证连接 Amazon RDS 实例参见 AWS RDS 的 IAM 认证。从驱动源码看auth-provider为:aws-iam时连接规格会被改写为 AWS 包装驱动(subprotocol aws-wrapper:mysql :classname software.amazon.jdbc.ds.AwsWrapperDataSource :sslMode VERIFY_CA :wrapperPlugins iam)并强制要求必须启用 SSL否则抛异常 You must enable SSL in order to use AWS IAM authentication且sslMode必须为VERIFY_CA见 connection-details-spec。Use a secure connection (SSL)使用安全连接可在此粘贴服务器 SSL 证书链Server SSL certificate chainPEM 格式。源码中证书会被映射为 JDBC 参数serverSslCert见 default-ssl-cert-details 与连接规格构造逻辑。若使用 SSL 连接失败可尝试在附加 JDBC 选项中追加trustServerCertificatetrue见下文排障章节。Use an SSH tunnel使用 SSH 隧道通过 SSH 隧道访问数据库参见 SSH 隧道指南。Unfold JSON Columns展开 JSON 列MySQL 的JSON类型列可以在 Metabase 中被展开为组件字段component fields每个 JSON key 变成一列。JSON 展开默认开启如果性能不佳可以关闭。开启后还可以在 表元数据 中针对单个列单独切换展开与否。驱动源码佐证了这一点database-supports? :nested-field-columns 的实现是(and (driver/common/json-unfolding-default db) (not (mariadb? db)))——即 JSON 展开默认开启且MariaDB 不支持MariaDB 没有真正的 JSON 类型10.2.7 起JSON只是LONGTEXT的别名。这与 MariaDB 文档 中 JSON folding is not supported for MariaDB databases 的表述一致。在查询执行层面展开的 JSON 字段通过json_unquote(json_extract(...))生成 SQL并按目标类型做转换时间戳走str_to_date、布尔直接返回、浮点用 0.0技巧兼容旧版 MySQL见 json-query 实现。类型映射上MySQL 的JSON数据库类型被映射为:type/JSON见 database-type-base-type。Additional JDBC connection string options附加 JDBC 连接字符串选项可以追加 Metabase 连接数据库所用的 JDBC 连接字符串参数例如占位符中给出的tinyInt1isBitfalse——该参数控制tinyint(1)是否被当作布尔BIT处理驱动在同步与查询执行两个阶段都会检查它见 describe-fields-sql 与 db-type-name。驱动内置了一批默认连接参数见 default-connection-args供参考JDBC 参数值作用zeroDateTimeBehaviorconvertToNullMySQL 合法的0000-00-00日期在 Java 中非法转换为nulluseUnicode/characterEncoding/characterSetResultstrue/UTF8/UTF8强制结果集使用 UTF-8 编码useCompressiontrue在 Metabase 与 MySQL 之间对数据包做 GZIP 压缩useLocalSessionStatetrue本地记录事务隔离级别与自动提交避免每次查询命中数据库nullCatalogMeansCurrenttrue同步时仅枚举当前绑定的库不扫描用户有权限的所有库需要注意附加选项存在安全过滤。驱动会拒绝allowLoadLocalInfile、allowLoadLocalInfileInPath、allowUrlInLocalInfile、autoDeserialize、serverRSAPublicKeyFile等危险键见 validate-db-details!一旦命中会抛出 Potentially dangerous keys in additional options 异常。Re-run queries for simple explorations简单探索时重跑查询默认情况下只要在Summarize汇总菜单中选择分组选项、或在 钻取菜单 中选择过滤条件Metabase 就会立即执行查询。如果你的数据库较慢可以关闭此选项改为让用户先点击Run播放按钮再应用 汇总 或过滤选择避免每次点击都加载数据。Choose when syncs and scans happen选择同步与扫描时机具体选项说明参见 同步与扫描。开启后可配置数据库同步频率每小时默认或每天运行时刻以 Metabase 应用服务器所在时区为准。字段值扫描filter values用于在仪表板/问题中启用复选框过滤。可选按计划定期运行、仅在添加新过滤组件时按需扫描并缓存、从不需要时手动执行配合 手动重扫字段值 按钮使用。Periodically refingerprint tables定期为表重建指纹周期性重建指纹会增加数据库负载。开启后每次 Metabase 执行 同步 时都会抽样扫描列值。指纹查询会检查每列的前 10,000 行数据据此估算每列的唯一值数量、数值与时间戳列的最小/最大值等。若关闭Metabase 只会在初次设置时对列建立一次指纹。连接 MySQL 8 服务器认证插件兼容性Metabase 使用MariaDB 驱动连接 MySQL 服务器而该驱动不支持 MySQL 8 的默认认证插件caching_sha2_password。要连接 MySQL 8需要把 Metabase 所用账号的认证插件切换为mysql_native_passwordALTER USER metabase% IDENTIFIED WITH mysql_native_password BY thepassword;如果密码中包含了 MySQL 无法以 UTF-8 直接理解的字符可能需要在附加 JDBC 选项中追加passwordCharacterEncoding你的编码例如passwordCharacterEncodingISO-8859-1确保认证时 MySQL 能正确解析密码中的特殊字符见 Passwords with special characters。无法用正确的凭据登录Unable to log in with correct credentials如何识别Metabase 报错 Looks like the username or password is incorrect但你确信用户名和密码正确。原因可能是你创建的 MySQL 用户所允许的主机host与你实际连接的主机不一致。典型场景MySQL 跑在 Docker 容器里而metabase用户是用CREATE USER metabaselocalhost IDENTIFIED BY thepassword;创建的。此时localhost会被解析为 Docker 容器本身而不是宿主机导致访问被拒绝。在 Metabase 服务日志中会出现类似错误Access denied for user metabase172.17.0.1 (using password: YES).注意其中的主机名172.17.0.1此处是 Docker 网络 IP以及结尾的using password: YES。用命令行客户端也会得到相同错误mysql -h 127.0.0.1 -u metabase -p。如何修复用正确的主机名重建 MySQL 用户CREATE USER metabase172.17.0.1 IDENTIFIED BY thepassword;必要时也可用通配符%作为主机名CREATE USER metabase% IDENTIFIED BY thepassword;然后为该用户授权以只读 SELECT 为例GRANT SELECT ON targetdb.* TO metabase172.17.0.1; FLUSH PRIVILEGES;记得删除旧用户DROP USER metabaselocalhost;如果用户、主机、密码都正确仍然连不上可以在附加 JDBC 选项中追加trustServerCertificatetrue。该选项告诉驱动即使服务器证书缺少根证书也信任它从而建立安全连接。值得注意的是驱动日志会在未显式配置该选项而启用 SSL 时打印提示You may need to add trustServerCertificatetrue to the additional connection options to connect with SSL.见 connection-details-spec。另外驱动会把常见的连接错误人性化为可读提示见 humanize-connection-error-message原始错误人性化提示Communications link failure ...无法连接请检查主机和端口Unknown database ...数据库名称不正确Access denied for user...用户名或密码不正确Must specify port after : in connection string主机名不合法启动 MySQL 8 Docker 容器如果你要新建一个 MySQL 容器并且希望 Metabase 无需手动创建用户或切换认证机制即可连接或遇到了RSA public key is not available client side (option serverRsaPublicKeyFile not set)错误可以在运行容器时追加--default-authentication-pluginmysql_native_password启动参数。简单的docker run方式docker run -p 3306:3306 -e MYSQL_ROOT_PASSWORDxxxxxx mysql:8.xx.xx --default-authentication-pluginmysql_native_password或在 docker-compose 中mysql: image: mysql:8.xx.xx container_name: mysql hostname: mysql ports: - 3306:3306 environment: - MYSQL_ROOT_PASSWORDxxxxxx - MYSQL_USERmetabase - MYSQL_PASSWORDxxxxxx - MYSQL_DATABASEmetabase volumes: - $PWD/mysql:/var/lib/mysql command: [--default-authentication-pluginmysql_native_password]注意mysql_native_password在 MySQL 8.4 及以后版本默认被移除deprecated → removed生产环境更推荐按前文所述只对 Metabase 账号单独执行ALTER USER ... IDENTIFIED WITH mysql_native_password或评估升级驱动的可行性。同步包含 JSON 的记录500 行 schema 推断机制Metabase 会根据表的前五百行数据中出现的 JSON key 来推断 JSON 的schema。MySQL 的 JSON 字段本身没有 schemaMetabase 无法依靠表元数据来确定 JSON 字段包含哪些 key。作为变通Metabase 会取前 500 条记录并解析其中的 JSON 来推断schema。之所以限制为 500 条是为了避免同步元数据给数据库带来不必要的压力。由此带来的问题是如果 JSON 中的 key 逐条记录变化前 500 行可能无法覆盖该 JSON 字段用到的全部 key。要让 Metabase 推断出所有 key需要把缺失的 key 补充进前 500 行的 JSON 对象中例如临时插入包含这些 key 的样例记录完成同步后再删除。这与 MariaDB 形成对比由于 MySQL 与 MariaDB 实现上的差异JSON schema 推断在 MariaDB 上不生效见 MariaDB 文档。Vitess 系数据库的已知限制查询 Vitess 数据库如 PlanetScale时应在每个子查询内添加LIMIT子句。原因Metabase 通常会对最终查询结果施加行数限制如 2000 或 10000 行。但由于 Vitess 的一个已知 bugVitess 可能把这些限制施加到子查询上导致意外结果例如 Metabase 内不能显示全部结果行。变通办法就是在每个子查询中显式添加限制。还应与平台托管方确认Vitess 在返回 information_schema 元数据时可能出问题。Metabase 需要这些元数据来填充其应用数据库如果拿不到元数据字段可能不显示或显示为空。驱动源码同样体现了对 PlanetScale/Vitess 的关注同步表清单时不能传入getCatalog()的结果因为 Vitess 副本连接上getCatalog()会返回路由限定名dbreplica导致WHERE TABLE_SCHEMA dbreplica匹配不到任何行、同步到空库。因此驱动固定依赖nullCatalogMeansCurrenttrue并传入nilcatalog见 active-tables 与 default-connection-args。可写能力Writable connection 与账号权限要求Writable connection可写连接可另外设置一条专用于写操作的连接参见 可写连接。Model features模型相关功能选择是否启用与 Metabase 模型 相关的功能。这些功能通常要求用于连接的数据库账号同时具备读和写权限。Model actions模型操作开启后允许对基于该数据创建的模型执行 操作Actions。Actions 可以读取、写入和删除数据因此数据库用户需要写权限。驱动层面actions、actions/custom、actions/data-editing三个特性仅在驱动为:mysql时启用见 database-supports? 扩展相关实现位于 mysql/actions.clj。Model persistence模型持久化Metabase 会创建存放模型数据的表并按你定义的调度定期刷新。要启用 模型持久化需要授予该连接凭据在 Metabase 提供的 schema 上的读写权限。驱动特性表中:persist-models true表明该能力受支持见 特性声明。Editable table data可编辑表数据开启后管理员可以直接在 Metabase 界面中创建、更新、删除表中的记录。这要求连接数据库的账号具备相应表的写权限。参见 权限。驱动会通过SHOW GRANTS解析当前用户的表级权限SELECT/UPDATE/INSERT/DELETE用于判断表是否可写见 current-user-table-privileges 与 parse-grant。注意 MariaDB 因不允许普通用户查询角色权限而被跳过此外由于 MySQL 部分撤销partial revokes场景的解析错误metabase#38499表权限特性整体被禁用见 database-supports? :table-privileges可写性判定基于元数据表检查实现。另外uploads特性在 MySQL 上开启见 特性声明支持通过 CSV 上传建表当 MySQL 全局变量local_infile为ON时写入走LOAD DATA LOCAL INFILE批量导入否则回退到普通INSERT INTO见 insert-into!。进阶Database routing数据库路由启用数据库路由后管理员可以用一个数据库构建问题question而该问题会根据查看者身份针对具有相同 schema 的另一个数据库执行查询。参见 数据库路由。驱动特性表中:database-routing true见 特性声明确认 MySQL 驱动支持该能力。Danger zone危险区域涉及删除数据库等危险操作参见 Danger zone。驱动能力一览理解 MySQL 连接的上限结合 MySQL 驱动源码以下是该驱动声明的关键特性能力节选有助于判断哪些功能可在此连接上使用特性是否支持说明connection-impersonation是支持连接模拟需要角色connection-impersonation-requires-roleconvert-timezone/datetime-diff是时区转换与日期差函数基于convert_tz、timestampdiff实现full-join否MySQL 不支持 FULL JOINwindow-functions/offset否MySQL 不支持在含GROUP BY的查询中直接使用 lag/lead 实现 offsetpersist-models是模型持久化schemas否MySQL 无 schema 层其 database 即其他引擎的 schema驱动将:db槽位用于跨库路由uploads是CSV 上传建表case-sensitivity-string-filter-options否LIKE 大小写敏感度由服务器/列排序规则决定不提供 UI 开关nested-field-columns是MySQL/ 否MariaDBJSON 展开index/fetch、index/standalone-create是索引管理B-Tree 与 Full-text见 supported-index-methodsdatabase-routing是数据库路由同步相关实现也值得留意驱动从information_schema.columns读取字段元数据排除information_schema、performance_schema、sys、mysql等系统库及innodb_table_stats、innodb_index_stats表见 describe-fields-sqlMySQL 的DATETIME被映射为:type/DateTime、TIMESTAMP被映射为:type/DateTimeWithLocalTZ以 UTC 存储、YEAR映射为整数、TINYINT默认按布尔处理见 database-type-base-type。若时区相关查询异常可能需要把系统时区表导入 MySQLmysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql见 set-timezone-sql 注释。进一步阅读MariaDB 连接指南与 MySQL 共用驱动注意其 JSON 展开与 schema 推断的差异管理数据库元数据编辑含单列 JSON 展开开关JSON 展开详解模型设置数据访问权限同步与扫描驱动实现src/metabase/driver/mysql.clj、src/metabase/driver/mysql/actions.clj、src/metabase/driver/mysql/ddl.clj测试基座test/metabase/test/data/mysql.clj【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考