OpusSolution.Tasken.Sync.Core 1.0.0-development

OPUS.Tasken.Sync.Core

Phiên bản: Development 1.0.0

OPUS.Tasken.Sync.Core là thư viện .NET 8 dùng để đồng bộ dữ liệu từ database master SQL Server/Azure SQL sang một hoặc nhiều database đích. Package sử dụng SQL Change Tracking, checkpoint riêng theo từng bảng, metadata của bảng và generic SQL writer để xử lý đồng bộ incremental.

Package này chỉ chứa sync engine dùng lại được. Nó không tự chạy lịch. Host bên ngoài, ví dụ OPUS.Tasken.Functions.Sync, chịu trách nhiệm trigger theo lịch và gọi sync runner.

Chức năng chính

• Đồng bộ incremental dựa trên SQL Change Tracking.
• Hỗ trợ mô hình 1 database nguồn sang 1 hoặc nhiều database đích.
• Cấu hình whitelist bảng được phép sync.
• Checkpoint riêng theo JobName + TargetName + TableName.
• Source reader và target writer dạng generic dựa trên metadata.
• Xử lý insert, update và delete.
• Hỗ trợ bảng có identity column bằng SET IDENTITY_INSERT.
• Xử lý theo batch.
• Đăng ký DI qua AddTaskenSyncCore.
• Kèm database scripts để tạo bảng control và bật Change Tracking.

Trạng thái package

Cài đặt

Sau khi package được publish lên NuGet:

dotnet add package OpusSolution.Tasken.Sync.Core --version 1.0.0

Cách sử dụng cơ bản

Đăng ký Sync Core trong host .NET:

using OPUS.Tasken.Sync.Core.Extensions;

builder.Services.AddTaskenSyncCore(builder.Configuration);

Inject và chạy job:

using OPUS.Tasken.Sync.Core.Abstractions;

public sealed class SyncWorker
{
    private readonly ISyncJobRunner _runner;

    public SyncWorker(ISyncJobRunner runner)
    {
        _runner = runner;
    }

    public async Task RunAsync(CancellationToken cancellationToken)
    {
        await _runner.RunAsync("MasterToTasken", cancellationToken);
    }
}

Cấu hình

Ví dụ cấu hình:

{
  "ConnectionStrings": {
    "MasterDb": "<connection-string-database-nguon>",
    "TargetDb": "<connection-string-database-dich>"
  },
  "Sync": {
    "Jobs": [
      {
        "Name": "MasterToTasken",
        "SourceConnectionStringName": "MasterDb",
        "Tables": [
          "AspNetUsers",
          "Department",
          "Request",
          "YearlyTarget"
        ],
        "Targets": [
          {
            "Name": "TaskenTargetDb",
            "ConnectionStringName": "TargetDb",
            "IsEnabled": true,
            "BatchSize": 500
          }
        ]
      }
    ]
  }
}

Tables là danh sách whitelist. Sync Core không tự động đồng bộ toàn bộ database.

Chuẩn bị database

Chạy các script trong thư mục database-script trên database master:

Chỉ chạy script baseline checkpoint sau khi database đích đã có dữ liệu nền tương ứng. Nếu database đích đang trống, cần seed dữ liệu ban đầu trước.

Luồng xử lý

Sync job
  -> target đang enabled
    -> bảng trong cấu hình
      -> đọc checkpoint
      -> kiểm tra Change Tracking min valid version
      -> đọc changes từ source
      -> đọc source rows cho insert/update
      -> ghi transaction vào target
      -> update checkpoint sau khi thành công

Interface chính

Bảng control

Implementation hiện tại dùng checkpoint trong database master:

sync.SyncCheckpoints

Database script cũng tạo thêm các bảng control phục vụ mở rộng:

sync.SyncJobs
sync.SyncTargets
sync.SyncJobTargets
sync.SyncRuns

Lỗi thường gặp

Ghi chú vận hành

• SQL Change Tracking chỉ tracking thay đổi dữ liệu theo row, không tracking thay đổi schema.
• Schema target phải tương thích với source.
• Mỗi bảng cần primary key để generic sync hoạt động.
• Identity value được giữ nguyên từ source sang target.
• Không lưu secret trong repository. Nên dùng environment variables, Azure Function App Settings hoặc Azure Key Vault.

Tài liệu liên quan

• docs/sync-core/00-Index.md
• docs/database-master-sync/03-sync-core-and-function-usage-guide.md
• database-script/001-create-sync-control-tables.sql
• database-script/002-enable-change-tracking-for-sync-tables.sql
• database-script/003-initialize-sync-checkpoints.sql