(SymmetricDS快速入門手冊)Chapter 1. Quick Start Guide，symmetricdschapter

(SymmetricDS快速入門手冊)Chapter 1. Quick Start Guide，symmetricdschapter

本文檔是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/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

5.      下一步，在store-001.properties檔案中設定下面的屬性，指定root節點所在的位置：

# 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}

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

來自命令列的警告資訊是安全的可以忽略。

另一個關於屬性檔案的簡要描述。在啟動階段，SymmetricDS尋找engines檔案夾中的一個或多個屬性檔案。因為我們已經在命令列中指定了一個—engine參數，所以SymmetricDS將會尋找特定命名的檔案，corp-000.properties。在這個例子中，因為在engines檔案夾中只有一個屬性檔案，所以SymmetricDS將會預設載入這個屬性檔案中的配置。因此，在這個例子中，不指定—engine參數也是可以的。加上這個參數，運行這個例子是，可以減少因為啟動錯了安裝副本而導致的錯誤。SymmetricDS將會抱怨丟失了你指定的屬性設定檔。

3.      下一步，在corp節點的資料庫中建立SymmetricDS特定的資料庫表。這些表將包含同步操作的配置資訊。下面的命令使用自動建立的特性建立所有必要的SymmetricDS系統資料表：

../bin/symadmin --engine corp-000create-sym-tables

4.      最後一步，執行下面的操作，載入範例商品與交易資料和SymmetricDS配置資訊到root節點的資料庫：

../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

來自命令列的警告資訊是安全的可以忽略。你可以查看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

在初次開機時，corp節點將會建立範例設定檔中所有的trigger。然後在8080連接埠為corp-000 engine監聽同步和註冊請求。

3.      在store001節點的samples目錄，執行下面的命令，啟動SymmetricDS：

../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

現在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

使用這個命令之後，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);

一旦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);

一旦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;

這個表中的每一行資料代表一行變化的資料。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 = ?;

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 =?;

初始的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 =?;

一個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

注意使用上邊的命令，我們不在使用9090連接埠。SymmetricDS現在在8080連接埠監聽corp和store engine之間的資料交換。

5.      除了啟動伺服器的命令，所有其他的命令的執行還是需要使用—engine參數指定engine。因為要給特定的節點（engine）來處理命令，像開啟註冊，發起從corp到store的初始負載等等。