Thoth项目中的存储和数据库适配器
项目描述
此库提供用于Thoth项目的thoth-storages库。该库公开了针对PostgreSQL数据库的核心查询和方法，以及通过其S3兼容API操作Ceph的适配器。
快速入门
先决条件
确保您已安装podman和podman-compose。您可以通过运行dnf install -y podman podman-compose
请确保您在一个使用 pipenv install --dev
首次本地开发时
拥有可以从 AWS S3 检索 的 pg dump
从以下位置获取最新的 PostgreSQL 容器镜像： https://catalog.redhat.com/software/containers/rhel8/postgresql-13/5ffdbdef73a65398111b8362?container-tabs=gti>i-tabs=red-hat-login
运行 podman-compose up 以扩展数据库和 pgweb 的 pod。更多详细信息，请参阅 本地运行 PostgreSQL 部分
运行此命令以将 pg dump 同步到本地数据库
psql -h localhost -p 5432 --username=postgres < pg_dump.sql
现在您可以为测试新的查询或 创建新的迁移 准备好了
如果您已经有一个本地数据库，请确保它没有过时，并在测试任何更改之前记住遵循 部署中的迁移生成和模式调整 部分。
安装和用法
该库可以通过 pip 或 Pipenv 从 PyPI 安装
pipenv install thoth-storages该库提供了一个 CLI，可以帮助您探索模式和数据处理
thoth-storages --help
# In a cloned repo, run:
PYTHONPATH=. pipenv run python3 thoth-storages --help您可以使用以下命令运行准备好的测试套件
pipenv install --dev
pipenv run python3 setup.py test本地运行 PostgreSQL
您可以使用此存储库中存在的 docker-compose.yaml 运行本地 PostgreSQL 实例，（确保您已安装 podman-compose）
$ dnf install -y podman podman-compose
$ # Also available from PyPI: pip install podman-compose
$ podman-compose up运行上述命令后，您应该能够在 localhost:5432 访问本地 PostgreSQL 实例。这也是 PostgreSQL 适配器连接到 localhost 的默认配置，除非明确提供了 KNOWLEDGE_GRAPH_HOST（有关配置连接的更多信息，请参阅适配器构造函数中的其他环境变量）。默认配置使用名为 postgres 的数据库，可以使用 postgres 用户和 postgres 密码访问（SSL已禁用）。
提供的 docker-compose.yaml 还启用了 PGweb，以便通过 UI 使用数据探索。要访问它，请访问 localhost:8081。
提供的 docker-compose.yaml 不使用任何卷。在您的容器重启后，内容将不再可用。
您可以使用 pgsql 同步您的本地实例
$ psql -h localhost -p 5432 --username=postgres < pg_dump.sql如果您想以编程方式实验 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 目录中，并使用以下描述的进程自动生成。
如果您进行了任何更改，请遵循以下步骤，这将为您生成版本
确保您的本地 PostgreSQL 实例正在运行（遵循上述 本地运行 PostgreSQL 指令）
$ podman-compose up运行 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"审查 Alembic 生成的迁移。注意：Alembic 并非自动检测所有变更。
确保生成的迁移包含在您的 pull request 中，以便将更改传播到部署
$ git add thoth/storages/data/alembic/versions/在部署中，使用 Management API 和其 /graph/initialize 端点来传播部署中的数据库模式更改（Management API 必须有最近的模式更改，并使用带有新 thoth-storages 发布的更改填充）。
如果您在本地运行并希望传播更改，请运行以下 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 的图像。使用 --help 获取有关可用选项的更多信息。
如果上述命令失败并出现以下异常
FileNotFoundError: [Errno 2] "dot" not found in path.请确保已安装 graphviz 包
dnf install -y graphviz创建自己的性能指标
性能指标在 Amun 上报告库的性能方面，如果遵守以下程序，结果可以自动同步。
要创建自己的性能指标，创建一个测试库所需功能的功能的脚本。一个示例是位于 thoth-station/performance 存储库中的矩阵乘法脚本。此脚本可以提供给 Dependency Monkey 以验证在所需的运行时和构建时环境中的一定组合的库。请遵循 性能存储库的 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)查询的在线调试
您可以将对 PostgreSQL 实例执行的所有查询打印到记录器中。为此，设置以下环境变量
export THOTH_STORAGES_DEBUG_QUERIES=1内存使用统计信息
您可以将有关 PostgreSQL 适配器及其内存缓存使用统计信息的信息打印到记录器（它必须至少设置 INFO 级别）。为此，设置以下环境变量
export THOTH_STORAGES_LOG_STATS=1这些统计信息将在数据库适配器被销毁时打印。
Thoth 部署的自动备份
在每次部署中，都会运行一个自动的知识 graph backup cronjob，通常每天运行一次。自动备份的结果存储在 Ceph 上 - 您可以在 s3://<bucket-name>/<prefix>/<deployment-name>/graph-backup/pg_dump-<timestamp>.sql 中找到它们。有关路径中参数的扩展，请参阅部署配置。
要从备份文件创建数据库实例，请运行一个新的本地PostgreSQL实例并从中填充备份文件
$ cd thoth-station/storages
$ aws s3 --endpoint <ceph-s3-endpoint> cp s3://<bucket-name>/<prefix>/<deployment-name>/graph-backup/pg_dump-<timestamp> pg_dump-<timestamp>.sql
$ podman-compose up
$ psql -h localhost -p 5432 --username=postgres < pg_dump-<timestamp>.sql
password: <type password "postgres" here>
<logs will show up>Thoth部署的手动备份
您可以使用pg_dump和psql工具来创建转储并从转储中恢复数据库内容。此工具已预安装在运行PostgreSQL的容器镜像中，因此您需要做的只是执行Thoth部署中的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>您可以忽略与所有者错误相关的错误消息
STATEMENT: ALTER TABLE public.python_software_stack OWNER TO thoth;
ERROR: role "thoth" does not existPostgreSQL容器默认使用用户“postgres”，这与集群中运行的用户（“thoth”）不同。角色分配将不会创建，但数据将可用。
同步集群中工作流运行的成果
集群中的每个工作流任务都会报告一个JSON，其中包含关于任务运行（元数据）和实际结果的信息。这些工作流任务的结果通过S3兼容API存储在对象存储Ceph上，并通过图同步同步到知识图谱。负责图同步的组件是graph-sync-job，它编写得足够通用，可以同步任何数据并报告同步数据的指标，因此您不需要在每个新注册到系统的工作负载中提供此类逻辑。要同步集群中完成的工作负载（工作）的结果，请在sync.py中实现相关的同步逻辑，并在同一文件的HANDLERS_MAPPING中注册处理程序。映射将文档ID的前缀映射到负责将数据同步到知识库的处理程序（函数）（请注意现有同步函数的签名，以自动与从graph-sync-job调用的sync_documents函数集成）。
Thoth中的查询命名约定
有关查询命名约定，请参阅查询命名约定中的所有文档。
访问Ceph上的数据
要访问Ceph上的数据，您需要知道您要连接的端点的aws_access_key_id和aws_secret_access_key凭据。
您要访问的数据的绝对文件路径构造如下：s3://<bucket_name>/<prefix_name>/<file_path>
初始化数据处理程序有两种方式
配置环境变量
变量名称
内容
S3_ENDPOINT_URL
Ceph主机名
CEPH_BUCKET
Ceph桶名称
CEPH_BUCKET_PREFIX
Ceph前缀
CEPH_KEY_ID
Ceph Key ID
CEPH_SECRET_KEY
Ceph Secret Key
from thoth.storages.ceph import CephStore ceph = CephStore()直接使用参数初始化对象
from thoth.storages.ceph import CephStore ceph = CephStore( key_id=<aws_access_key_id>, secret_key=<aws_secret_access_key>, prefix=<prefix_name>, host=<endpoint_url>, bucket=<bucket_name>)
初始化后，您即可检索数据
ceph.connect()
try:
# For dictionary stored as json
json_data = ceph.retrieve_document(<file_path>)
# For general blob
blob = ceph.retrieve_blob(<file_path>)
except NotFoundError:
# File does not exist访问Operate-First公共桶上的Thoth数据
Thoth数据库的公共实例可在Operate-First公共桶上找到，供外部贡献者开始开发Thoth的组件。
有关访问该桶的说明，请参阅文档中的说明，该文档位于thoth/datasets存储库中。
请注意，不要在此桶中存储任何机密或有价值的信息，因为其内容可能随时被删除。
下载文件
下载适合您平台的文件。如果您不确定选择哪个，请了解有关安装包的更多信息。
