Chapter 0.SymmetricDS快速入门指南( Quick Start Guide)
本文档是SymmetricDS3.6.14文档的第一章节Quick Start Guide文档的翻译，的目的是帮助读者快速搭建一个SymmetricDS集群并普及一些基本概念术语。
本文档描述了如何在两个SymmetricDS节点之间同步两个相同schema的数据库。下面的例子构建了一个分销业务模型，有一个中央数据库（我们叫它root或者corp节点）和多个零售商店的数据库（我们叫它client或者store节点）。对于本教程，我们将只有一个store（商店）节点，如下图。如果你愿意，可以再教程的结束后，自己扩展这个例子，配置第二个商店。
在这个例子中，我们将安装两个独立的SymmetricDS代表两个不同的服务器。一个代表store服务器，一个代表corp服务器。每一个SymmetricDS安装副本将负责一个数据库，也就是一个SymmetricDS就是一个SymmetricDS术语中的节点。一个SymmetricDS安装副本负责一个数据库，代表一个节点，这种配置是最常用的（我们可以选择配置一个安装副本负责两个节点，这叫做multi-homing，将会在教程的最后讨论）。你很可能在一个机器上运行两个SymmetricDS副本，我们将运行两个SymmetricDS安装副本在两个不同的端口。我们将使用8080运行corp服务器，9090运行store服务器，如下图。
Corp SymmetricDS安装副本将负责捕获store端的item（item表和item_selling_price表）的数据变化，像itemnumber，描述和商店的价格。Store端的SymmetricDS捕获销售交易（sale_transaction表和sale_return_line_item表）数据的变化，比如销售的时间和商品。价格信息只发送给与价格相关的特定的商店，从而减少发送到每个商店的定价信息数据的数量。举个例子，换句话说，商店001的商品的定价信息只会发送给商店001的数据库，不会发送给商店002的数据库。
这个简单的配置总是使客户端发起与root节点的通信，这是一种相当常见的配置。在这个配置中，client将定期的从数据库服务器中拉数据附加到root节点上，client也会将捕获到的变化推送到root节点。
概述已经足够多了，下面我们开始，我们将按照下面的步骤行动：
1. 安装和配置两个SymmetricDS应用程序
2. 创建SymmetricDS配置文件和用来存储corp数据和store数据的数据库表。
3. 在corp数据库中创建零售数据
4. 启动SymmetricDS服务器，然后注册store节点到corp节点
5. 发送数据的初始负载到store节点
6. 执行一个数据推送和数据拉取操作
7. 验证发送和接收到的batch的信息
Installing SymmetricDS
首先，我们将安装两个SymmetricDS的副本，然后分别配置其与数据库的连接信息：
1. 下载SymmetricDS安装文件
2. 创建两个文件夹代表两个机器。一个存放Corp节点的安装副本，另一个存放store节点的安装副本。例如，你可以将这两个文件夹命名为sym-corp和sym-store001，下面将假设你是这样命名的。解压上面下载的文件到两个文件夹中。
3. 属性文件用来存放启动SymmetricDS需要的最小的配置信息。复制corp样例属性文件到corp engine文件夹，然后复制store属性文件到store的engine文件夹。如果你使用的是上面建议的文件夹命名，你将做下面的复制动：
- samples/corp-000.properties to sym-corp/symmetric-ds-3.x.x/engines/
samples/corp-000.properties to sym-corp/symmetric-ds-3.x.x/engines/
和
- samples/store-001.properties to sym-store001/symmetric-ds-3.x.x/engines/
samples/store-001.properties to sym-store001/symmetric-ds-3.x.x/engines/
4. 浏览两个属性文件，查看不同的配置。例如，root节点给定一个值为corp的组ID，store节点给定一个值为store的组ID；root节点给定了一个值为000的外部ID，store节点给定了一个值为001的外部节点。
下面是两个节点中engine目录下的两个配置文件都有的配置属性，指定了如何连接特定的数据库服务器（下面的值只是例子）：
- # The class name for the JDBC Driver
- db.driver=com.mysql.jdbc.Driver
- # The JDBC URL used toconnect to the database
- db.url=jdbc:mysql://localhost/sample
- # The user to login as whocan create and update tables
- db.user=symmetric
- # The password for the userto login as
- db.password=secret
# The class name for the JDBC Driver
db.driver=com.mysql.jdbc.Driver
# The JDBC URL used toconnect to the database
db.url=jdbc:mysql://localhost/sample
# The user to login as whocan create and update tables
db.user=symmetric
# The password for the userto login as
db.password=secret
5. 下一步，在store-001.properties文件中设置下面的属性，指定root节点所在的位置：
- # The HTTP URL of the root node to contact for registration
- registration.url=http://localhost:8080/sync/corp-000
# The HTTP URL of the root node to contact for registration
registration.url=http://localhost:8080/sync/corp-000
6. Tip，一个engine的URL是下面这种通用的格式：
- http://{hostname}:{port}/sync/{engine.name}
http://{hostname}:{port}/sync/{engine.name}
URL中的engine.name部分来自节点的配置文件。
1.2. Creating and Populating Your Databases
Important
你必须先为你的root节点和client节点创建数据库。创建的数据库的名字和上边配置文件中配置必须一致。
首先，通过下面的步骤，在root节点的数据库中创建例子的数据库表，加载样例数据，加载样例配置：
1. 打开一个命令行提示符，然后进入到corp安装副本的samples文件夹下
2. 在root节点中通过执行下面的命令为item，price和sale创建样例表：
- ../bin/dbimport --engine corp-000 --format XMLcreate_sample.xml
../bin/dbimport --engine corp-000 --format XMLcreate_sample.xml
来自命令行的警告信息是安全的可以忽略。
另一个关于属性文件的简要描述。在启动阶段，SymmetricDS寻找engines文件夹中的一个或多个属性文件。因为我们已经在命令行中指定了一个—engine参数，所以SymmetricDS将会寻找特定命名的文件，corp-000.properties。在这个例子中，因为在engines文件夹中只有一个属性文件，所以SymmetricDS将会默认加载这个属性文件中的配置。因此，在这个例子中，不指定—engine参数也是可以的。加上这个参数，运行这个例子是，可以减少因为启动错了安装副本而导致的错误。SymmetricDS将会抱怨丢失了你指定的属性配置文件。
3. 下一步，在corp节点的数据库中创建SymmetricDS特定的数据库表。这些表将包含同步操作的配置信息。下面的命令使用自动创建的特性创建所有必要的SymmetricDS系统表：
- ../bin/symadmin --engine corp-000create-sym-tables
../bin/symadmin --engine corp-000create-sym-tables
4. 最后一步，执行下面的操作，加载样例商品与交易数据和SymmetricDS配置信息到root节点的数据库：
- ../bin/dbimport --engine corp-000insert_sample.sql
../bin/dbimport --engine corp-000insert_sample.sql
Important
上面的操作，针对MySQL，需要执行insert_sample_mysql.sql文件。针对大小写敏感的表和列的命名，MySQL用反引号代替双引号。
我们现在已经穿件了corp数据库表，然后填充了我们的SymmetricDS配置信息和样例数据。下一步，我们将在store节点的数据库中创建样例数据库表，准备接收数据。
5. 打开一个命令提示符，进入store节点的SymmetricDS安装副本的samples文件夹。
6. 执行下面的命令，造store节点的数据库中创建空的样例表：
- ../bin/dbimport --engine store-001 --format XMLcreate_sample.xml
../bin/dbimport --engine store-001 --format XMLcreate_sample.xml
来自命令行的警告信息是安全的可以忽略。你可以查看create_sample.xml文件来看看它都有什么。
登陆数据库，核实两个数据库中的表：
1. 找到需要从corp节点到store节点同步的item表：item和item_selling_price。
2. 找到需要从store节点到corp节点的sale表：sale_transaction和sale_return_line_item。
3. 找到SymmetricDS的系统表，这些表都以sym_作为前缀，像sym_channel,sym_trigger,sym_router和sym_trigger_router.
4. 验证corp节点的item表是否有样例数据
1.3. Starting SymmetricDS
本教程中的数据库建立和配置现在已经完成了。是时候开始使用SymmetricDS了。现在我们启动两个SymmetricDS节点，然后观察它们的日志输出。
1. 打开两个命令行提示符，分别进入到两个安装副本的根目录下的samples目录下。
2. 在corp的samples目录下，执行下面的命令启动corp SymmetricDS：
- ../bin/sym --engine corp-000 --port 8080
../bin/sym --engine corp-000 --port 8080
在首次启动时，corp节点将会创建样例配置文件中所有的trigger。然后在8080端口为corp-000 engine监听同步和注册请求。
3. 在store001节点的samples目录，执行下面的命令，启动SymmetricDS：
- ../bin/sym --engine store-001 --port 9090
../bin/sym --engine store-001 --port 9090
这个命令第一次启动store节点的服务器时，将会使用自动创建特性创建SymmetricDS的系统表。然后不断的尝试注册到corp节点（通过前面配置的registration URL，可以知道corp节点的地址）。因为注册还没有打开，store节点将会收到认证失败（403 HTTP响应）。我们在下面的注册部分讨论。
1.4. Registering a Node
当一个未注册的节点启动时，它将尝试注册到registration URL指定的节点（在几乎所有的情况下，就是root节点）。通过允许注册和为已经注册的节点返回配置信息，Registration 节点集中的管理网络上的其他节点。在本教程中，Registration节点就是root节点，corp节点，这个节点同时参与与其他节点的同步操作。
因此，下一步，我们需要为store节点打开注册，以使store节点可以接收到初始负载的数据，然后就可以接收来自corp的数据，也可以向corp节点发送数据。有几种方式可以完成这个任务。我们将使用SymmetricDS的管理功能，在corp节点上执行一个命令（因为这个节点负责注册管理）。
1. 前面已经启动了corp节点和store节点的SymmetricDS应用程序，下面打开一个新的命令行提示符，进入到corp节点的安装副本的根目录下的samples目录。
通过执行下面的命令打开store节点的注册功能：
- ../bin/symadmin--engine corp-000 open-registration store 001
../bin/symadmin--engine corp-000 open-registration store 001
现在corp的注册功能已经为group为store，external id为001的节点打开了。Group和external id信息与store节点中的store-001.properties配置文件中的配置对应。在SymmetricDS中，每一个节点都被分配到一个节点组（Node Group），然后给一个external ID代表这个应用程序。在本教程中，我们命名代表商店的group为store，然后我们使用以001开始的数字标示符作为external ID（000代表corp节点）。关于节点组的更多的信息将在下一章节中介绍。
2. 查看store节点的日志输出，看是否成功注册到corp节点。Store被配置为以随机的时间间隔尝试注册一次，最多1分钟。一旦注册成功，corp和store节点将开始同步。
1.5. Sending an Initial Load
下一步，我们将发送一个数据的初始负载给store节点，再一次在corp节点上使用节点管理功能。
1. 打开一个命令行提示符，进入到corp安装副本的根目录的samples文件夹下。（注意，通常大多数系统命令在corp服务器端直接发出。例如，所有的配置文件，在corp输入，然后同步到任意的client节点。）
2. 执行下面的命令，发送一个数据的初始负载到store节点：
- ../bin/symadmin --engine corp-000 reload-node 001
../bin/symadmin --engine corp-000 reload-node 001
使用这个命令之后，corp节点排队各个store节点拉数据请求。数据的初始负载包括=被配置了同步的每一表中的数据。
3. 观察两个节点的日志输出，查看数据传输。Store被配置为每分钟从corp节点拉一次数据。
1.6 Pulling Data
下一步，我们将对中央数据库的item数据做一些修改（我们将增加一个新的商品），然后观察数据被拉到store节点。
1. 打开一个与Corp数据库的交互式sql Session
2. 在store001和store002（本例中只有store001），增加一个新的商品：
- insert into "item"("item_id", "name") values (110000055, 'Soft Drink');
- insert into "item_selling_price"("item_id", "store_id", "price") values(110000055, '001', 0.65); insert into "item_selling_price" ("item_id","store_id", "price") values (110000055, '002', 1.00);
insert into "item"("item_id", "name") values (110000055, 'Soft Drink');
insert into "item_selling_price"("item_id", "store_id", "price") values(110000055, '001', 0.65); insert into "item_selling_price" ("item_id","store_id", "price") values (110000055, '002', 1.00);
一旦statement被提交，数据变化将被SymmetricDS捕获，然后排队等store节点拉数据。
4. 观察两个节点的日志输出，查看数据传输情况。Store被配置为每分钟从corp节点拉一次数据。
5. 在本教程中，item_selling_price被配置为列匹配的Router，特定的定价数据的变化将仅发送给store_id和external ID匹配的节点。在store节点的数据库执行SQL语句，验证是否有新的数据到达。在本例中，第一条记录将仅仅被发送到store 001。
1.7. Pushing Data
现在，我们将假冒一条交易，然后观察SymmetricDS是怎么把交易信息推送到中央节点的。（在这我们可以发现，数据的拉取和推送都是各个从节点的事，中央节点只负责管理）
1. 对store节点的数据库打开一个SQL会话
2. 增加一个新的交易信息到store节点的数据库。
- insert into "sale_transaction"("tran_id", "store_id", "workstation","day", "seq") values (1000, '001', '3', '2007-11-01', 100);
- insert into "sale_return_line_item"("tran_id", "item_id", "price","quantity") values (1000, 110000055, 0.65, 1);
insert into "sale_transaction"("tran_id", "store_id", "workstation","day", "seq") values (1000, '001', '3', '2007-11-01', 100);
insert into "sale_return_line_item"("tran_id", "item_id", "price","quantity") values (1000, 110000055, 0.65, 1);
一旦statement被提交，数据修改将被捕获，然后排队等候store节点推送到中央节点。
3. 观察两个节点的日志输出，查看数据传输情况。Store节点被配置为每分钟推送一次数据到corp节点。
1.8 Verifying Outgoing Batches
前面我们演示了已经推送和拉取了数据，下面我们将描述你如何获取数据的batch和发送的相关的信息。一个batch被用来追踪和发送一个或者多个数据变化到给定的节点。数据所在的节点创建一个batch，接收数据的节点接收到数据然后做出回应。
除此之外，在SymmetricDS中，表被分组到不同的数据通道，为了允许不同的数据类型在部分数据类型有错误的情况下也可以同步。例如，如果将要发向给定的channel的batch发生了错误，这个batch将会在这个channel的每一次同步操作中进行尝试，直到这个batch不在发生错误。只有在这个batch不在发生错误之后，发向这个channel的其余的batch才会被发送。使用这种方式，在数据源发生的数据变化的顺序能保证以同样的顺序被发送到目的地，并且在目的地以同样的顺序应用这些变化。但是，一个channel上没有错误的batch不会被另一个有错误的batch的channel阻塞。使用这种方式，一个channel上的数据变化不会被另一个channel上的错误阻塞。
可以通过下面的步骤查看发出的batch信息：
1. 打开一个与corp或者store节点的数据库服务器连接的会话
2. 确认已经捕获到的数据变化：
- select * from sym_data order by data_id desc;
select * from sym_data order by data_id desc;
这个表中的每一行数据代表一行变化的数据。Data_id是顺序增长的，所以最近的一个data id应该与你的数据插入SQL相关联。Event_type是I代表insert，U代表update，D代表delete。对于插入和更新，捕获到的数据在row_data列中，对于更新和删除，主键的值在pk_data列中。
3. 使用上一步得到的data_id，确认数据变化在某个batch中：
- select * from sym_data_event where data_id = ?;
select * from sym_data_event where data_id = ?;
batch是基于必要的目的节点信息被创建的，称之为Route Job。作为Route Job的一部分，数据变化使用使用batch_id被分配到一个batch，batch_id在追踪和同步数据的时候会用到。Batch和数据之间的连接信息通过sym_data_event表被连接。
4. 使用上一步得到的batch_id，去人数据变化被batch，发送到目的地并得到响应：
- select * from sym_outgoing_batch where batch_id =?;
select * from sym_outgoing_batch where batch_id =?;
初始的Batch，在刚创建和还没有发送到一个节点的时候，有一个NE（new）的状态。一旦收到节点的响应，成功发送时，batch状态将会变为OK，发送失败，将会变为ER。如果这个batch失败，这个batch的error_flag将会被设置为1，已经失败的batch可能在它在重新尝试时成功，这时，这个状态需要被改变。
理解这三个表，还有我们在下个部分讨论到的第四个表，是诊断可能遇到的同步问题的关键。在你使用SymmetricDS的时候，不管是在实验环境还是生产环境，花些时间监控这些表可以更好的理解SymmetricDS是如何工作的。
1.9. Verifying Incoming Batches
接收数据的节点会保持本节点响应的batch信息和加载的数据相关的统计信息。重复的batch默认是忽略的，但是可以通过修改incoming.batches.skip.duplicates 改变这个行为。
通过下面的步骤观察接收到的batch信息：
1. 打开一个与corp或者store节点的数据库交互的SQL会话
2. 使用上个部分获得的batch_id，确认接收和响应的batch信息：
- select * from sym_incoming_batch where batch_id =?;
select * from sym_incoming_batch where batch_id =?;
一个batch代表节点加载的数据变化的集合。表中记录了创建和发送这个batch的节点，batch的状态成功时是OK，失败时是ER。
1.10. Multi-Homing
我们的快速入门指南到这就结束了。我们已经成功的创建了两个同步节点，然后在两个数据库中执行了同步操作。现在我们退回去，讨论一下在指南的第一步讨论的一个问题。也就是，在指南中，让你安装两个SymmetricDS副本的那一步。
在上边的例子中，我们在每一个SymmetricDS安装副本的engines目录中替换了一个属性文件。当SymmetricDS被启动的时候，SymmetricDS被初始化，然后根据提供的配置文件创建一个SymmetricDS engine（再说一次，一个engine就是一个SymmetricDS节点，负责一个特定的数据库）。
事实上，一个SymmetricDS应用程序可以同时启动多个engine。当SymmetricDS启动时，它在engines目录中寻找一‘.properties’结尾的文件。它将为找到的每一个配置文件启动一个SymmetricDS engine。命令行提示符中的—engine参数会覆盖上边的操作，将会使SymmetricDS只启动命令行中指定的一个engine。在一个SymmetricDS安装副本启动多个engine的这种情况，叫做‘multi-homing’。
对于上边的例子，如果我们想改成multi-homing的架构，只要要做下面的步骤：
1. 安装一个SymmetricDS副本代替上边的两个安装副本。不在需要一个目录代表两个机器。
2. 从安装副本的samples目录拷贝两个配置文件到engines目录。
3. 上边所有运行过的命令在此安装副本的samples目录下在运行一遍
4. 启动SymmetricDS时，不在需要指定特定的engine，这样将启动两个engine。这个命令还是从sampls目录运行，如下：
- ../bin/sym --port 8080
../bin/sym --port 8080
注意使用上边的命令，我们不在使用9090端口。SymmetricDS现在在8080端口监听corp和store engine之间的数据交换。
5. 除了启动服务器的命令，所有其他的命令的执行还是需要使用—engine参数指定engine。因为要给特定的节点（engine）来处理命令，像打开注册，发起从corp到store的初始负载等等。