存储管理简介
===============

OushuDB 原生支持 HDFS 和自研分布式表存储 Magma。这两大存储可以通过多虚拟存储集群的机制原生的接入 OushuDB ，实现 IO 资源的物理隔离。

------------------
Magma集群配置
------------------

用户通过配置 ``magma-topology.yaml`` 文件，定制 Magma 虚拟集群，但必须配置名为 ``vsc_catalog`` 的子集群作为 OushuDB 的元数据存储集群。

如下是一个配置了由单个节点组成的 ``vsc_catalog`` 的子集群和3个节点组成的 ``vsc_default`` 子集群。

.. code-block:: yaml

   nodes:
     - id: "cn1"
       addr: "192.168.1.100"
       label: { region: "region1", zone: "zone1"}
     - id: "dn[1-3]"
       addr: "192.168.1.[101-103]"
       label: { region: "region1", zone: "zone1"}
   vsc:
    - name: vsc_catalog
      nodes: cn1
      port: 6666
      num_ranges: 3
      num_replicas: 3
      data_dir: /data1/oushudb/magma_catalog
      log_dir:
      replica_locations: "region1.zone1:3"
      leader_preferences: "region1.zone1"
    - name: vsc_default
      nodes: dn1,dn2,dn3
      port: 6676
      num_ranges: 18
      num_replicas: 3
      data_dir: /data1/oushudb/magma_data
      log_dir:
      replica_locations: "region1.zone1:3"
      leader_preferences: "region1.zone1"


其中 ``nodes`` 下配置Magma集群的节点，并通过 ``addr`` 指定监听地址， ``label`` 指定机器所在的数据中心。 ``vsc`` 下配置Magma虚拟集群，通过 ``num_replicas`` 配置对应虚拟集群的副本数，通过 ``num_ranges`` 配置对应虚拟集群的数据分片数，通过 ``replica_locations`` 配置对应多个副本分别放置在哪些数据中心，通过 ``leader_preferences`` 配置对应虚拟集群的raft leader的位置。

用户还需要配置 ``magma-client.xml`` 为 Oushudb 提供 Magma 虚拟集群的 name service 以及连接 URL。

.. code-block:: html

   <?xml version="1.0" encoding="UTF-8"?>
   <configuration>
     <property>
       <name>nameservices</name>
       <value>magma_catalog</value>
     </property>
     <property>
       <name>magma_catalog</name>
       <value>magma_node1</value>
     </property>
     <property>
       <name>magma_catalog.magma_node1</name>
       <value>192.168.1.100:6666</value>
     </property>
   </configuration>


上述样例配置了一个名为 ``magma_catalog`` 的name service，并且该name service包含一个名为 ``magma_node1`` 的节点，该节点的URL为 ``192.168.1.100:6666`` 。 ``magma-client.xml`` 配置文件需要包含 ``vsc_catalog`` 中的所有节点，每一个节点的URL必须和 ``magma-topology.yaml`` 中配置的一致。

在数据库中，可以通过 ``TABLESPACE`` 来动态创建并使用Magma VSC：

::

   create tablespace magma_default location 'magma://magma_catalog/vsc_default' with (default_create_table_option='appendonly=true,orientation=magmaap', bucket_number=18)


该命令创建了一个名为 ``magma_default`` 的tablespace，对应的URL为 ``magma://magma_catalog/vsc_default`` ，默认的建表选项为 ``(appendonly=true,orientation=magmaap)`` ，桶数为 ``18`` 。Magma存储集群的桶数和 ``num_ranges`` 配置项一致。

为了在初始化阶段自动创建 ``TABLESPACE`` ，需要配置 ``oushudb-tablespace.yaml`` 文件。

.. code-block:: yaml

   - name: magma_default
     url: [magma://magma_catalog/vsc_default]
     default_create_table_option: appendonly=true,orientation=magmaap
     bucket_number: 18
     default: true


其中的参数配置和 ``CREATE TABLESPACE`` 的 ``WITH`` 选项保持一致。 ``default: true`` 指明 ``magma_default`` 这个tablespace是 ``postgres`` 数据库的默认建表tablespace。

Oushudb 集群通过 ``catalog_url`` 这个GUC来访问Magma元数据集群 ``vsc_catalog``。需要在 ``oushudb-site.xml`` 中配置：

.. code-block:: html

   <property>
     <name>catalog_url</name>
     <value>magma_catalog/vsc_catalog</value>
     <description>urls for accessing magma.</description>
   </property>


其中 ``magma_catalog/vsc_catalog`` 指明了 ``catalog_url`` 使用的name service为 ``magma_catalog`` ，VSC的名称为 ``vsc_catalog`` 。name service的名称必须和 ``magma-client.xml`` 中配置的一致，VSC的名称只能为 ``vsc_catalog`` ，且和 ``magma-topology.yaml`` 中保持一致。