semtech/mu-migrations-service

mu-migrations-service

镜像概述和主要用途

mu-migrations-service是一款用于在数据库上运行迁移的服务，目前支持SPARQL查询（.sparql）和Turtle文件（.ttl）格式，未来计划扩展支持更多格式。该服务确保迁移按序执行、状态可追踪，适用于RDF数据库（如Virtuoso）的数据更新、初始化及模式变更场景。

核心功能和特性

• 多格式支持：当前支持SPARQL查询文件（.sparql）和Turtle文件（.ttl）
• 有序执行：按文件名中数字前缀的升序顺序执行迁移
• 执行保障：前一迁移成功后才执行下一迁移，失败时停止后续操作，已完成迁移不会重复执行
• 状态跟踪：在数据库中记录迁移完成状态，包含文件名和执行时间
• 配置灵活：通过环境变量调整批处理大小等参数

使用场景和适用范围

适用于需要对RDF数据库进行结构化数据迁移的项目，包括但不限于：

• 数据模型变更（如谓词替换、类定义更新）
• 初始化基础数据（如系统配置、枚举值）
• 批量数据更新或清洗
• 版本化数据迁移管理

详细使用方法和配置说明

教程

将迁移服务添加到项目栈

在mu-project的docker-compose.yml中添加以下配置，将迁移服务集成到项目：

yaml
migrations:
  image: semtech/mu-migrations-service
  links:
    - triplestore:database  # "triplestore"为数据库服务名称（通常是Virtuoso实例）
  volumes:
    - ./config/migrations:/data/migrations  # 本地迁移文件目录映射到容器内

使用docker-compose up -d启动服务栈，通过docker-compose logs -ft migrations查看日志，确认服务启动成功（初始无迁移执行）。

编写迁移以更新数据集中的谓词

以下示例将数据集中所有schema:name谓词替换为foaf:name：

1. 创建迁移文件：./config/migrations/20200329140538-replace-schema-name-with-foaf-name.sparql
2. 写入SPARQL查询：

sparql
PREFIX schema: <http://schema.org/>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>

DELETE {
  GRAPH ?g { ?s schema:name ?o . }
} INSERT {
  GRAPH ?g { ?s foaf:name ?o . }
} WHERE {
  GRAPH ?g { ?s schema:name ?o . }
}

执行docker-compose restart migrations重启服务，通过docker-compose logs -ft migrations查看迁移执行状态及结果。

操作指南

使用SPARQL查询操作数据

创建SPARQL迁移文件（如./config/migrations/20160808225103-statuses.sparql），示例内容：

sparql
PREFIX dct: <http://purl.org/dc/terms/>
PREFIX tac: <http://tasks-at-hand.com/vocabularies/core/>
PREFIX mu: <http://mu.semte.ch/vocabularies/core/>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>

INSERT DATA {
  GRAPH <http://mu.semte.ch/application> {
    <http://tasks-at-hand.com/resources/statuses/not_started>
      a tac:Status;
      mu:uuid "wellknown-status-not_started";
      dct:title "not started".
    <http://tasks-at-hand.com/resources/statuses/ongoing>
      a tac:Status;
      mu:uuid "wellknown-status-ongoing";
      dct:title "ongoing".
    <http://tasks-at-hand.com/resources/statuses/done>
      a tac:Status;
      mu:uuid "wellknown-status-done";
      dct:title "done".
  }
}

使用Turtle文件在默认图中插入数据

创建Turtle迁移文件（如./config/migrations/20160808225103-statuses.ttl），示例内容：

turtle
@prefix dct: <http://purl.org/dc/terms/> .
@prefix tac: <http://tasks-at-hand.com/vocabularies/core/> .
@prefix mu: <http://mu.semte.ch/vocabularies/core/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

<http://tasks-at-hand.com/resources/statuses/not_started>
      a tac:Status;
      mu:uuid "wellknown-status-not_started";
      dct:title "not started".
<http://tasks-at-hand.com/resources/statuses/ongoing>
      a tac:Status;
      mu:uuid "wellknown-status-ongoing";
      dct:title "ongoing".
<http://tasks-at-hand.com/resources/statuses/done>
      a tac:Status;
      mu:uuid "wellknown-status-done";
      dct:title "done".

默认情况下，Turtle数据将导入到图<http://mu.semte.ch/application>中。

使用Turtle文件在特定图中插入数据（实验性）

创建与Turtle文件同名的.graph文件（如20160808225103-statuses.graph），文件内容为目标图名称：

http://mu.semte.ch/graphs/custom-graph

参考

迁移的命名和组织

• 命名规则：文件名必须以数字开头且全局唯一，建议格式为[Unix时间戳]-[描述].sparql或.ttl（如20200329140538-replace-schema-name-with-foaf-name.sparql）
• 文件组织：迁移文件需放在/data/migrations目录（可通过卷映射），支持子文件夹，执行状态仅与文件名相关，与路径无关

执行保证

• 按文件名中首个数字的升序顺序执行
• 串行执行：前一迁移成功后才开始下一迁移，无并发
• 失败阻断：任一迁移失败，后续迁移停止执行
• 幂等性：已完成的迁移（按文件名识别）不会重复执行

数据库中的迁移管理

迁移完成状态存储在MU_APPLICATION_GRAPH（默认：<http://mu.semte.ch/application>）中，每条记录为类型muMigr:Migration的资源，包含：

• muMigr:filename：迁移文件名
• muMigr:executedAt：执行完成时间戳
  （使用前缀：muMigr: <http://mu.semte.ch/vocabularies/migrations/>）

配置

支持通过环境变量配置：

• BATCH_SIZE：Turtle迁移的单次插入三元组数量（默认：***）
• MINIMUM_BATCH_SIZE：批处理大小下限，低于此值时报错（默认：100）
• COUNT_BATCH_SIZE：单次从数据库查询的已执行迁移数量（默认：***）
  注：基于https://github.com/mu-semtech/mu-ruby-template%EF%BC%8C%E6%94%AF%E6%8C%81%E5%85%B6%E6%96%87%E6%A1%A3%E4%B8%AD%E7%9A%84%E5%85%B6%E4%BB%96%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F

讨论

大型数据集和批处理大小

三元组存储通常有单次请求数据量限制，服务通过批处理拆分大型数据集。配置BATCH_SIZE控制单次插入量，失败时自动减半重试，直至达到MINIMUM_BATCH_SIZE。数据先导入临时图，成功后通过SPARQL Graph查询合并到目标图，确保完整性。

与mu-authorization配合使用（实验性）

可与mu-authorization集成，服务会添加mu-auth-sudo头以提升权限执行迁移。此功能为实验性，欢迎反馈以改进。