OpenMetadata MySQL 连接器完整指南权限配置、四种认证方式与元数据/血缘/用量摄取实战【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata本篇技术指南以 OpenMetadata 官方 MySQL 连接器文档为主体结合仓库源码连接处理、摄取实现、JSON Schema 与集成测试进行纵深解读覆盖从最小权限账号创建、INFORMATION_SCHEMA访问授权到 Lineage Usage 所需的general_log/slow_log配置、Profiler 与数据质量测试的权限准备以及连接详情中每个配置项的含义与取值建议。读完本文你将掌握在 OpenMetadata 中正确创建并调优 MySQL 数据库服务的完整链路并能对照源码理解底层认证策略与连接诊断机制。一、连接器概述与支持范围MySQL 连接器用于将 MySQL 实例中的数据库、Schema、表、视图、存储过程等元数据抽取到 OpenMetadata 的 Database Service 层级中。从 服务规格定义 可以看到该连接器由一个完整的ServiceSpec组织元数据摄取MysqlSourcemetadata.py血缘摄取MysqlLineageSourcelineage.py用量摄取MysqlUsageSourceusage.py连接管理MySQLConnectionconnection.py版本要求OpenMetadata 支持 MySQL 版本8.0.0及以上。连接驱动使用 SQLAlchemy 的mysqlpymysqlscheme由 mysqlConnection.json 中的mySQLScheme枚举固定。二、元数据摄取的最小权限要求要抽取元数据连接所使用的用户必须能够访问INFORMATION_SCHEMA。默认情况下MySQL 用户只能看到INFORMATION_SCHEMA中与其访问权限对应的对象行因此需要显式授权。以下是官方推荐的授权 SQL-- 创建用户。若省略 hostName则默认使用 %允许任意主机连接 -- 更详细的语法参见 MySQL 官方 CREATE USER 文档8.0 参考手册 CREATE USER username[hostName] IDENTIFIED BY password; -- 授予对某个数据库的 SELECT 权限 GRANT SELECT ON world.* TO username; -- 授予对某个数据库的 SELECT 权限 GRANT SELECT ON world.* TO username; -- 授予对某个具体对象的 SELECT 权限 GRANT SELECT ON world.hello TO username;说明原文档中第二条GRANT SELECT ON world.* TO username;与第一条重复实际使用中按需保留一条即可按库授权db.*与按对象授权db.table可组合使用实现从粗粒度到细粒度的权限控制。在源码层面连接器测试连接时会通过 connection.py 中的MySQLChecks依次执行check_accessping、get_schemas、get_tables、get_views、get_queries五项检查其中get_tables/get_views会跳过information_schema、performance_schema、mysql、sys这四个 MySQL 8 系统库见SYSTEM_SCHEMAS常量。若用户权限不足测试连接会给出对应错误码诊断详见后文连接诊断小节。三、Lineage血缘与 Usage用量摄取配置要抽取血缘与用量需要开启 MySQL 的查询日志并且连接用户需要对mysql.general_log表拥有 SELECT 权限-- 开启日志记录 SET GLOBAL general_logON; SET GLOBAL log_outputtable; -- 授予对日志表的 SELECT 权限 GRANT SELECT ON mysql.general_log TO usernamehost;启用后usage.py 中的MysqlUsageSource与血缘源MysqlLineageSource会通过 queries.py 中定义的MYSQL_SQL_STATEMENT从{query_history_table}默认mysql.general_log查询command_type Query且位于start_time/end_time区间内的语句并按event_time desc排序、以resultLimit限制返回条数。查询会过滤掉 OpenMetadata 自身与 dbt 写入的带注释语句argument NOT LIKE /* {app: OpenMetadata, ...} */%避免自指污染。使用慢日志slow log作为日志来源连接配置中提供两个与查询历史相关的开关定义于 mysqlConnection.jsonuseSlowLogs布尔值默认false置为true时改用慢日志提取血缘与用量queryHistoryTable字符串自定义查询历史表名设置后将覆盖默认的mysql.general_log或启用慢日志时的mysql.slow_log。自定义表必须提供与所选日志路径兼容的列。对应实现位于 query_parser.pyuseSlowLogs为真时使用MYSQL_SQL_STATEMENT_SLOW_LOGS读取sql_text列否则使用MYSQL_SQL_STATEMENT读取argument列同时支持通过filterCondition追加额外过滤条件。四、Profiler 与数据质量Data Quality权限准备执行 Profiler 工作流或数据质量测试时需要用户具备以下权限对将要执行 Profiler/测试的表或 Schema 拥有SELECT权限允许查看数据库中所有对象的tables信息。即与元数据摄取的权限要求一致至少INFORMATION_SCHEMA访问 目标对象SELECT但范围应扩大到所有需要做数据画像和质量断言的对象。具体工作流搭建可参考仓库中的数据质量与 Profiler 相关实现如 profiler 模块 与 data_quality 模块。五、连接详情Connection Details逐项解读以下参数与官方文档的$$section定义一一对应均可在连接服务的 UI 表单或 YAML 配置中设置。SchemeSQLAlchemy 驱动 scheme 选项。当前仅支持mysqlpymysql默认值。若不确定直接使用默认值即可。Username连接 MySQL 的用户名。该用户需能访问INFORMATION_SCHEMA以抽取元数据其他工作流血缘、用量、Profiler、数据质量可能需要额外权限参见上文各节。Auth ConfigauthType认证配置支持以下类型对应 mysqlConnection.json 中authType的oneOfBasic Auth使用密码认证IAM based Auth使用 AWS IAM 认证连接 AWS 相关服务如 RDSAzure Based Auth使用 Azure AD 认证连接 Azure 相关服务GCP CloudSQL Config源码已支持通过 Cloud SQL Python Connector 建立安全隧道连接 GCP Cloud SQL 实例。密码Basic Auth 下的 Password连接 MySQL 的密码。IAM 认证配置IAM Auth Config使用 IAM 认证时官方要求额外添加如下连接参数以启用 SSLssl: {ssl-mode: allow}即写入 Connection Arguments。各字段说明如下AWS Access Key ID访问 AWS 时用于标识身份的安全凭证之一形如AKIAIOSFODNN7EXAMPLE。访问密钥由两部分组成Access Key ID 与 Secret Access Key二者必须同时使用才能完成认证AWS Secret Access Key与 Access Key ID 配对的密钥形如wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEYAWS RegionAWS 在每个地理区域独立部署数据中心需要指定目标服务所在区域。注意Region 是配置连接时唯一必填的 AWS 参数其余 AWS 配置可通过编程方式从凭证链中解析AWS Session Token使用临时凭证访问服务时提供。此时除 Access Key ID 与 Secret Access Key 外还需附带 Session TokenEndpoint URL以编程方式访问 AWS 服务时使用的入口 URL。AWS SDK 与 CLI 默认使用各区域的标准端点也可为 API 请求指定备用端点Profile NameAWS CLI 命名配置文件。若希望使用default以外的配置文件在此填写名称Assume Role ARN跨账户或账户内角色切换时使用的目标角色 ARN。使用AssumeRole的用户需由账户管理员附加允许调用AssumeRole的策略若需角色扮演此项必填Assume Role Session Name假定角色会话的标识符用于在多个主体以不同原因扮演同一角色时唯一区分会话。默认值为OpenMetadataSessionAssume Role Source Identity调用AssumeRole操作的主体所指定的源身份可用于在 CloudTrail 日志中追溯是谁以该角色执行了操作Bucket Name数据湖中用于组织与存储对象的唯一标识类似文件夹名但服务于对象存储Prefix数据路径的前缀部分用于标识数据的来源或归属帮助在容器内组织与分类数据。从源码看IAM 认证由 connection.py 中的_IamStrategy实现它基于hostPort解析出主机与端口使用RdsIamAuthTokenManager生成 RDS IAM 令牌并通过 SQLAlchemy 的do_connect事件监听器在每次新建连接时注入最新令牌——这是因为 IAM 令牌有效期约 15 分钟长时运行的摄取任务不能复用过期令牌。同时RDS IAM 要求 TLS策略会自动为未显式配置ssl的连接注入{check_hostname: True}。Azure 认证配置Azure Auth ConfigClient ID服务账号的唯一标识。在服务账号密钥文件中查找client_id键对应的值Client Secret客户端密钥。获取步骤登录 Azure 门户 → 搜索App registrations并进入 → 选择本次连接使用的 Azure AD 应用 →Manage下选择Certificates secrets→Client secrets下选择New client secret→ 在弹窗中填写描述并选择过期时间后Add→ 在Client secrets区复制新建密钥Value列的内容Tenant ID租户 ID。获取步骤登录 Azure 门户 →App registrations→ 选择使用的 Azure AD 应用 → 在Overview区复制Directory (tenant) IDStorage Account Name存储账号名称Key Vault Name密钥保管库名称Scopes为让 OpenMetadata 使用 Azure AD 应用调用认证 API需要添加 scope登录 Azure 门户 →App registrations→ 选择使用的应用 → 在Expose an API区复制Application ID URI→ 确保 URI 以/.default结尾否则手动追加。源码实现中_AzureStrategy通过get_azure_access_token获取访问令牌并将该令牌作为密码注入一个深拷贝的连接配置中connection.py因此不会改动调用方持有的原始service_connection且每次构建引擎都会获取新令牌规避令牌过期问题。Host PortMySQL 实例的主机与端口格式为hostname:port例如localhost:3306。注意若 OpenMetadata 摄取服务运行在 Docker 中而目标 MySQL 部署在宿主机localhost上则应使用host.docker.internal:3306作为取值。另外当使用 GCP CloudSQL 认证时hostPort需填写实例连接名格式为project_id:region:instance_name见 mysqlConnection.json 中hostPort的描述。Database NameOpenMetadata 中 Database Service 的层级结构为Database Service Database Schema TableMySQL 本身没有Database Service 之下的数据库这一层概念。若希望数据展示在default之外命名的数据库下可在此字段指定名称。Database Schema可选参数。设置后元数据读取将被限制为仅读取该值对应的单个数据库Schema留空时 OpenMetadata 会扫描所有数据库。SSL 相关参数SSL CA用于 SSL 校验的 CA 证书对应驱动参数ssl_caSSL Certificate用于客户端认证的 SSL 证书ssl_certSSL Key与该 SSL 证书关联的私钥ssl_key。在 JSON Schema 中SSL 配置通过sslConfig引用 verifySSLConfig.json 的sslConfig定义统一管理。Connection Options附加连接选项用于构建发送给服务端的连接 URL如驱动级参数。Connection Arguments附加连接参数例如安全或协议配置会在连接时发送给服务。典型的用法即上文 IAM 认证所需的ssl: {ssl-mode: allow}。过滤模式Filter Patterns连接器支持四类基于正则的过滤模式includes列表匹配即包含、excludes列表匹配即排除Default Database Filter PatterndatabaseFilterPattern正则匹配数据库名仅包含/排除匹配的数据库Default Schema Filter PatternschemaFilterPattern正则匹配 Schema 名。注意其默认值为includes: []、excludes: [^information_schema$, ^performance_schema$]即默认排除两个系统库见 mysqlConnection.jsonDefault Table Filter PatterntableFilterPattern正则匹配表名Default Stored Procedure Filter PatternstoredProcedureFilterPattern正则匹配存储过程名。需要说明的是在摄取实现中metadata.py存储过程抽取由get_stored_procedures通过MYSQL_GET_ROUTINES查询information_schema.ROUTINES完成仅当includeStoredProcedures开启并会逐一应用is_stored_procedure_filtered过滤抽取到的存储过程/函数代码会被包装为CreateStoredProcedureRequest映射其语言与类型见STORED_PROC_LANGUAGE_MAP、STORED_PROC_TYPE_MAP。六、源码级实现原理认证策略与连接构建EngineStrategy 模式connection.py 中MySQLConnection._engine_strategy()根据authType分发到四种策略认证类型策略类关键行为Basic Auth默认_BasicStrategy直接以 URL 方式构建引擎Azure AD_AzureStrategy获取令牌后作为密码注入深拷贝连接GCP CloudSQL_CloudSqlStrategy通过cloud-sql-python-connector建立安全隧道支持enableIamAuthAWS IAM_IamStrategy基于 RDS IAM 令牌do_connect事件逐连接注入新令牌其中 CloudSQL 策略要求安装cloud-sql-python-connectorpip install cloud-sql-python-connector[pymysql]1.0.0,2.0.0并在close()/__del__中释放连接器保证失败路径不留存活资源。连接诊断MySQL 错误码映射MYSQL_ERRORS将常见 MySQL 8 错误码映射为可读的诊断信息测试连接失败时直接提示用户错误码含义建议修复1045认证失败检查用户名、密码及该主机是否允许连接1044无数据库访问权限为用户授予所配置databaseSchema的访问权限1049数据库不存在确认配置的databaseSchema存在且用户可见1142/1143查询历史表不可访问授予mysql.general_log或启用慢日志时的mysql.slow_log的 SELECT 权限否则无法收集用量与血缘2003无法连接 MySQL 主机检查hostPort、服务是否运行、网络/IP 白名单2013连接丢失/读超时服务端应答后连接中断检查服务负载与读超时2026TLS/SSL 连接错误检查 SSL/TLS 配置与服务端证书3159 / Couldnt receive servers public keyMySQL 8caching_sha2_password要求安全连接启用 TLS/SSL或允许公钥获取明文连接下该默认认证插件不会发送密码这一映射说明多数连接失败的本质是权限或网络问题测试连接功能会把这些错误翻译成可直接执行的修复建议。七、连接验证与测试仓库提供了集成测试 test_mysql_connection.py展示了编程方式构建连接的最小样例from metadata.generated.schema.entity.services.connections.database.common.basicAuth import ( BasicAuth, ) from metadata.generated.schema.entity.services.connections.database.mysqlConnection import ( MysqlConnection, ) from metadata.ingestion.source.connections import get_connection, get_test_connection_fn service_connection MysqlConnection( usernamemysql_container.username, authTypeBasicAuth(passwordmysql_container.password), hostPortflocalhost:{mysql_container.get_exposed_port(3306)}, ) engine get_connection(service_connection) _test_connection_fn get_test_connection_fn(service_connection) _test_connection_fn(metadata)可见连接对象只需hostPort与username两个必填字段authType为 Basic 时补充password这也是 mysqlConnection.json 中required数组的约束。测试连接函数会依次执行MySQLChecks中的 ping、列 Schema、列表、列视图、查询历史可访问性五项检查。八、实战检查清单在 OpenMetadata 中成功配置 MySQL 服务可按以下顺序自检版本确认 MySQL ≥ 8.0.0元数据权限连接用户可访问INFORMATION_SCHEMA并对目标库/对象拥有SELECT血缘与用量如需要开启SET GLOBAL general_logON; SET GLOBAL log_outputtable;并授予mysql.general_log或改用useSlowLogsmysql.slow_log的 SELECT 权限Profiler / 数据质量如需要对被测表/Schema 授予SELECT并确保能查看tables信息认证方式按部署环境选择 Basic、AWS IAM记得配置ssl: {ssl-mode: allow}、Azure AD 或 GCP CloudSQL主机与端口Docker 摄取访问宿主机服务时使用host.docker.internal:3306过滤模式利用四类 Filter Pattern 控制摄取范围默认已排除information_schema与performance_schema测试连接运行 Test Connection依据错误码诊断信息逐项修复。完成上述配置后即可通过元数据摄取 Pipeline 将 MySQL 中的库表结构、视图、存储过程纳入 OpenMetadata 的统一数据目录并在此基础上开启 Profiler、数据质量、血缘与用量分析为数据治理与 AI 上下文构建提供可信的基础。【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考