thoth-storage 0.19.17

安装和使用

该库可以通过pip或Pipenv从PyPI安装。

pipenv install thoth-storages

该库不提供任何CLI，它是一个低级库，支持Thoth的其他部分。

您可以通过以下命令运行准备好的测试套件

pipenv install --dev
pipenv run python3 setup.py test

# To generate docs:
pipenv run python3 setup.py build_sphinx

本地运行PostgreSQL

您可以使用此存储库中提供的docker-compose.yaml来运行本地PostgreSQL实例，(请确保您已安装podman-compose)

$ podman-compose up

运行上述命令后，您应该能够通过localhost:5432访问本地PostgreSQL实例。这也是PostgreSQL适配器的默认配置 - 您不需要明确提供GRAPH_SERVICE_HOST。默认配置使用名为postgres的数据库，可以使用postgres用户和postgres密码访问（SSL已禁用）。

提供的docker-compose.yaml还启用了PGweb，以便对数据库内容有用户界面。要访问它，请访问http://localhost:8081/。

提供的docker-compose.yaml没有使用任何卷。在您重启容器后，内容将不再可用。

如果您想通过编程方式与PostgreSQL进行实验，可以使用以下代码片段作为起点

from thoth.storages import GraphDatabase

graph = GraphDatabase()
graph.connect()
# To clear database:
# graph.drop_all()
# To initialize schema in the graph database:
# graph.initialize_schema()

在部署中生成迁移和模式调整

如果您对主PostgreSQL数据库的数据模型进行任何更改，您需要生成迁移。这些迁移说明如何调整现有数据库以适应部署中的数据。为此，使用Alembic迁移。Alembic可以（部分）自动检测已更改的内容以及如何调整部署中的现有数据库。

Alembic使用增量版本控制，其中每个迁移都是版本化的，并说明如何将数据库从先前状态迁移到所需的状态 - 这些版本存在于alembic/versions目录中，并按照以下描述的步骤自动生成。

如果您进行任何更改，请按照以下步骤进行，这将为您生成版本：

1. 确保您的本地PostgreSQL实例正在运行（遵循上述在本地运行PostgreSQL的说明）

$ podman-compose up

2. 运行Alembic CLI以为您生成版本

# Make sure you have your environment setup:
# pipenv install --dev
# Make sure you are running the most recent version of schema:
$ PYTHONPATH=. pipenv run alembic upgrade head
# Actually generate a new version:
$ PYTHONPATH=. pipenv run alembic revision --autogenerate -m "Added row to calculate sum of sums which will be divided by 42"

3. 查看Alembic生成的迁移。注意：并非所有更改都能由Alembic自动检测。

4. 确保生成的迁移是您pull request的一部分，以便更改可以传播到部署中

$ git add thoth/storages/data/alembic/versions/

4. 在部署中，使用管理API和其/graph/initialize端点传播部署中的数据库模式更改（管理API必须包含新thoth-storages版本中填充的最新模式更改）。

5. 如果您在本地运行并希望传播更改，请运行以下Alembic命令以更新迁移到最新版本

$ PYTHONPATH=. pipenv run alembic upgrade head

如果您想以编程方式更新模式，请运行以下Python代码

from thoth.storages import GraphDatabase

graph = GraphDatabase()
graph.connect()
graph.initilize_schema()

生成模式图像

您可以使用提供的CLI thoth-storages自动从当前模型生成模式图像

# First, make sure you have dev packages installed:
pipenv install --dev
PYTHONPATH=. pipenv run python3 ./thoth-storages generate-schema

上述命令将生成两个名为schema.png和schema_cache.png的图像。第一个PNG文件显示了主PostgreSQL实例的模式，后者，正如其名称所示，显示了缓存模式的外观。

如果上述命令失败并出现以下异常

FileNotFoundError: [Errno 2] "dot" not found in path.

请确保已安装graphviz包

dnf install -y graphviz

创建自己的性能指标

您可以创建自己的性能指标。要创建自己的性能指标，创建一个测试库所需功能功能的脚本。一个例子可以在性能存储库中找到的矩阵乘法脚本。此脚本可以提供给Dependency Monkey以验证在所需运行时和构建时环境中或直接在Amun API上运行的特定库组合或直接在Amun API上运行，该API将使用所需的软件和硬件配置运行给定脚本。请按照性能存储库的README中显示的创建性能脚本说明进行操作。

要创建相关的模型，调整thoth/storages/graph/models_performance.py文件并添加您的模型。描述参数（在性能指标结果的@parameters部分中报告）和结果（在@result部分中报告）。类的名称应与性能指标运行报告的name相匹配。

class PiMatmul(Base, BaseExtension, PerformanceIndicatorBase):
    """A class for representing a matrix multiplication micro-performance test."""

    # Device used during performance indicator run - CPU/GPU/TPU/...
    device = Column(String(128), nullable=False)
    matrix_size = Column(Integer, nullable=False)
    dtype = Column(String(128), nullable=False)
    reps = Column(Integer, nullable=False)
    elapsed = Column(Float, nullable=False)
    rate = Column(Float, nullable=False)

所有模型都使用SQLAlchemy。有关更多信息，请参阅文档。

查询的在线调试

您可以将所有对PostgreSQL实例执行的查询打印到日志记录器中。为此，设置以下环境变量

export THOTH_STORAGES_DEBUG_QUERIES=1

查询的在线调试

您可以将有关PostgreSQL适配器以及图形缓存和内存缓存使用情况的信息打印到日志记录器中（它必须至少设置有INFO级别）。为此，设置以下环境变量

export THOTH_STORAGES_LOG_STATS=1

这些统计信息将在数据库适配器销毁时打印。

从Thoth部署创建备份

您可以使用 pg_dump 和 psql 工具创建数据库备份并从备份中恢复数据库内容。此工具已预安装在运行 PostgreSQL 的容器镜像中，因此您只需要在 PostgreSQL 容器中执行 pg_dump 以创建备份，使用 oc cp 获取备份（或直接使用 oc exec 并从集群创建备份），然后使用 psql 恢复数据库内容。此操作的前提是您有权访问正在运行的容器（编辑权限）。

# Execute the following commands from the root of this Git repo:
# List PostgreSQL pods running:
$ oc get pod -l name=postgresql
NAME                 READY     STATUS    RESTARTS   AGE
postgresql-1-glwnr   1/1       Running   0          3d
# Open remote shell to the running container in the PostgreSQL pod:
$ oc rsh -t postgresql-1-glwnr bash
# Perform dump of the database:
(cluster-postgres) $ pg_dump > pg_dump-$(date +"%s").sql
(cluster-postgres) $ ls pg_dump-*.sql   # Remember the current dump name
(cluster-postgres) pg_dump-1569491024.sql
(cluster-postgres) $ exit
# Copy the dump to the current dir:
$ oc cp thoth-test-core/postgresql-1-glwnr:/opt/app-root/src/pg_dump-1569491024.sql  .
# Start local PostgreSQL instance:
$ podman-compose up --detach
<logs will show up>
$ psql -h localhost -p 5432 --username=postgres < pg_dump-1569491024.sql
password: <type password "postgres" here>
<logs will show up>

同步集群中运行作业的结果

集群中的每个作业都会报告一个 JSON，其中包含作业运行所需的必要信息（元数据）和实际的作业结果。这些作业结果通过兼容 S3 的 API 存储在对象存储 Ceph 中，然后通过图同步同步到知识图谱。负责图同步的组件是 graph-sync-job，它编写得足够通用，可以同步任何数据并报告同步数据的指标，因此您不需要在系统注册的每个新工作负载中提供此类逻辑。要同步集群中完成的工作负载的作业结果（工作负载），请在 sync.py 中实现相关的同步逻辑，并在同一文件中的 _HANDLERS_MAPPING 中注册处理器。映射将文档 ID 的前缀映射到负责将数据同步到知识库的处理器（函数）（请注意现有同步函数的签名，以便自动与从 graph-sync-job 调用的 sync_documents 函数集成）。