Instance management

Create a binlog instance

This command adds a new binlog instance for a tenant that already has binlog enabled. The new instance inherits parameter settings from existing binlog instances.

Syntax

CREATE BINLOG INSTANCE instance_name 
       FOR cluster.tenant [binlog_instance_option [, binlog_instance_option...]];

binlog_instance_option: 
    obcdc_option
  | binlog_option
  | slot_option

obcdc_option: 
    START_TIMESTAMP
  | ROOTSERVER_LIST
  | CLUSTER_URL
  | CLUSTER_USER
  | CLUSTER_PASSWORD
  | EXTRA_OBCDC_CFG

binlog_option:
    MASTER_SERVER_ID
  | MASTER_SERVER_UUID
  | SERVER_ID
  | SERVER_UUID
  | BINLOG_EXPIRE_LOGS_SECONDS
  | BINLOG_EXPIRE_LOGS_SIZE
  | MAX_BINLOG_SIZE
  | AUTO_START_OBCDC
  | FAILOVER
  | _INITIAL_OB_TXN_ID
  | _INITIAL_OB_TXN_GTID_SEQ
  | BINLOG_EXPIRE_LOGS_AUTO_SCALE
  | BINLOG_INSTANCE_SCOPE_CFG

slot_option: 
    IP
  | ZONE
  | REGION
  | GROUP

BINLOG_EXPIRE_LOGS_AUTO_SCALE: {
    "enable": value,
    "max_scale_up_capacity_gb": value,
    "min_scale_down_capacity_gb": value,
    "scale_down_threshold": "value",
    "scale_down_step": "value",
    "scale_up_threshold": "value", 
    "scale_up_step": "value",
    "computed_binlog_expire_logs_size": value
}

Parameters

obcdc_option

obbinlog exposes commonly used obcdc settings as same-name options. Other obcdc parameters are set via EXTRA_OBCDC_CFG as follows:

• START_TIMESTAMP: obcdc start position (tenant time when the task starts). Unit: seconds. Default is the current Unix timestamp.

• ROOTSERVER_LIST: Root Service location at startup, format server_ip:server_rpc_port:server_sql_port. For scenarios without OCP.

• CLUSTER_URL: OceanBase cluster config URL in quotes. Obtain with SHOW PARAMETERS LIKE 'obconfig_url'; (value field). obcdc uses this to discover Root Service hosts. For OCP-backed deployments; may be auto-generated when OBM has OCP metadata configured.

• CLUSTER_USER: Username in the cluster sys tenant; must have read access to all tables in the oceanbase system database.

• CLUSTER_PASSWORD: Password for CLUSTER_USER.

• EXTRA_OBCDC_CFG: Additional obcdc parameters as a whitespace-separated list of obcdc_cfg_key=value without spaces around =. Values are treated as strings and need not be quoted.

  The following keys are ignored if set here; fixed values are always used at obcdc startup:

  obcdc parameter	Fixed value
  enable_output_trans_order_by_sql_operation	1
  sort_trans_participants	1
  enable_output_hidden_primary_key	0
  enable_convert_timestamp_to_unix_timestamp	1
  enable_output_invisible_column	1

binlog_option

Important binlog_option settings:

• BINLOG_EXPIRE_LOGS_SECONDS: Binlog file expiration by time. Files whose last update time is earlier than current time minus this value, with their index entries, are purged. Default 259200 seconds. Range [0, 4294967295]. 0 disables time-based cleanup.

• BINLOG_EXPIRE_LOGS_SIZE: Binlog file expiration by size. During rotation, if (total size − first file size) > this threshold, the first file and its index entries are removed, repeating until within threshold or one file remains, then rotate. Default 53687091200 bytes. Range [0, 9223372036854775807]. 0 disables size-based cleanup.

• MAX_BINLOG_SIZE: Maximum single binlog file size in bytes. After a transaction’s events are appended, if the file exceeds this size, rotation occurs. Default 536870912. Range [4096, 1073741824].

• AUTO_START_OBCDC: Whether obcdc log pulling starts automatically after the binlog instance starts. Default 1 (auto start).

• FAILOVER: Whether this binlog instance is automatically recovered when it fails while the node is healthy. Default 1 (enabled).

• _INITIAL_OB_TXN_ID: OceanBase transaction ID to start binlog conversion from. Only applies to the first binlog instance for an OceanBase tenant; later instances ignore it and rely on internal GTID consistency.

• _INITIAL_OB_TXN_GTID_SEQ: Starting GTID sequence. Same applicability as _INITIAL_OB_TXN_ID.

• BINLOG_EXPIRE_LOGS_AUTO_SCALE: Auto scale-out/scale-in in JSON. See BINLOG_EXPIRE_LOGS_AUTO_SCALE below.

  Note

  This parameter is available from V4.3.0.

• BINLOG_INSTANCE_SCOPE_CFG: Tenant-level tuning options. See BINLOG_INSTANCE_SCOPE_CFG below.

  Note

  This parameter is available from V4.3.0.

slot_option

Controls resource slot assignment for binlog instances. Each machine can host multiple instances (possibly for different tenants). Creating an instance allocates a slot (resources on an IP). Each node has physical attributes (IP, ZONE, REGION) and logical GROUP; slots are chosen by intersecting constraints. If no slot matches, an ERROR packet is returned.

• Physical: IP, ZONE, REGION describe location. Containment: IP ⊂ ZONE ⊂ REGION.

• Logical: GROUP assigns the machine to a logical group.

BINLOG_EXPIRE_LOGS_AUTO_SCALE

JSON configuration for auto scale-out/scale-in. Example:

CREATE BINLOG INSTANCE binlog1 FOR obdemo.test1 
    CLUSTER_URL = 'http://10.10.10.1:8080/services?Action=ObRootServiceInfo&ObCluster=obdemo', 
    BINLOG_EXPIRE_LOGS_AUTO_SCALE='{
      "enable":0,
      "scale_up_threshold":"20%",
      "scale_up_step":"20%",
      "max_scale_up_capacity_gb":5000,
      "scale_down_threshold":"50%",
      "scale_down_step":"20%",
      "min_scale_down_capacity_gb":10,
      "computed_binlog_expire_logs_size":10737418240
      }';

Fields in BINLOG_EXPIRE_LOGS_AUTO_SCALE:

BINLOG_INSTANCE_SCOPE_CFG

Tenant-level tuning string: whitespace-separated obcdc_cfg_key=value without spaces around =.

Examples

• Create instance binlog1 for tenant test1 in cluster obdemo.

  CREATE BINLOG INSTANCE binlog1 FOR obdemo.test1 CLUSTER_URL='http://10.10.10.1:8080/services?Action=ObRootServiceInfo&ObCluster=obdemo';
  

• Create instance binlog2 for the same tenant with obcdc settings.

  CREATE BINLOG INSTANCE binlog2 FOR obdemo.test1 CLUSTER_URL='http://10.10.10.1:8080/services?Action=ObRootServiceInfo&ObCluster=obdemo',EXTRA_OBCDC_CFG = 'memory_limit=6G progress_limit_sec_for_dml=30';
  

• Create instance binlog3 with auto scale-out/scale-in and high-performance-related settings.

  Note

  Auto scale-out/scale-in is generally not recommended. This example sets enable to 0 to disable it.

  CREATE BINLOG INSTANCE binlog3 FOR obdemo.test1 
      CLUSTER_URL = 'http://10.10.10.1:8080/services?Action=ObRootServiceInfo&ObCluster=obdemo', 
      BINLOG_INSTANCE_SCOPE_CFG='record_queue_size=150000 read_wait_num=1500 storage_wait_num=1500 binlog_serialize_thread_size=8 throttle_convert_rps=99 throttle_convert_iops=2097152 throttle_dump_rps=111 throttle_dump_iops=2097152 throttle_dump_conn=333',
      BINLOG_EXPIRE_LOGS_AUTO_SCALE='{
        "enable":0,
        "scale_up_threshold":"33%",
        "scale_up_step":"33%",
        "max_scale_up_capacity_gb":4000,
        "scale_down_threshold":"53%",
        "scale_down_step":"12%",
        "min_scale_down_capacity_gb":33,
        "computed_binlog_expire_logs_size":10737418243
        }';
  

Query binlog instances

Returns one or more rows if matching binlog instances exist; otherwise an empty set.

Syntax

SHOW BINLOG INSTANCES {
      FOR cluster.tenant 
    | [instance_name [, instance_name...]]
};

Parameters

Examples

• Query all instances for tenant test1 in cluster obdemo.

  SHOW BINLOG INSTANCES FOR obdemo.test1;
  

• Query specific instances.

  SHOW BINLOG INSTANCES `eo46r4f2e8`,`gldwt7bnco`;
  

Sample output:

+------------+------------+-----------+---------------+------+------+--------+-------+---------+---------+---------------+-------------+--------------+-----------------+---------------+-------------+-------------+--------------+-----------------------------+-------------------------------+---------+-----------------------------+-------------------------------------------------+----------+
| name       | ob_cluster | ob_tenant | ip            | port | zone | region | group | running | state   | obcdc_running | obcdc_state | service_mode | convert_running | convert_delay | convert_rps | convert_eps | convert_iops | convert_checkpoint_current  |  convert_checkpoint_earliest  | dumpers | last_dumper_disconnect_time |  version                                        | odp_addr |
+------------+------------+-----------+---------------+------+------+--------+-------+---------+---------+---------------+-------------+--------------+-----------------+---------------+-------------+-------------+--------------+-----------------------------+-------------------------------+---------+-----------------------------+-------------------------------------------------+----------+
| eo46r4f2e8 | obdemo     | test1     | 10.10.10.1    | 8104 |      |        |       | Yes     | Running | Yes           | Running     | enabled      | Yes             |           578 |           1 |           0 |            0 |         1757944196          |                1757684969     |      0  |   1757944160                | 4.0.1-92748c6c59534426d187977b13b61b7cdf4fa200  | NULL     |
| gldwt7bnco | obdemo     | test1     | 10.10.10.1    | 8103 |      |        |       | Yes     | Running | Yes           | Running     | enabled      | Yes             |           478 |           1 |           0 |            0 |         1757944196          |                1757684969     |      0  |   1757944160                | 4.0.1-92748c6c59534426d187977b13b61b7cdf4fa200  | NULL     |
+------------+------------+-----------+---------------+------+------+--------+-------+---------+---------+---------------+-------------+--------------+-----------------+---------------+-------------+-------------+--------------+-----------------------------+-------------------------------+---------+-----------------------------+-------------------------------------------------+----------+

Result columns:

Modify a binlog instance

Modifies parameters of the specified binlog instance.

Syntax

ALTER BINLOG INSTANCE instance_name
    SET binlog_instance_option [, binlog_instance_option...];

Parameters

Examples

• Set binlog file validity on instance binlog1 to 6 days (518400 seconds).

  ALTER BINLOG INSTANCE binlog1 SET BINLOG_EXPIRE_LOGS_SECONDS = 518400;
  

• Update auto scale-out/scale-in and high-performance settings on instance binlog2.

  Note

  Auto scale-out/scale-in is generally not recommended. This example sets enable to 0 to disable it.

  ALTER BINLOG INSTANCE binlog2 SET 
      BINLOG_INSTANCE_SCOPE_CFG='record_queue_size=100000 read_wait_num=2000 storage_wait_num=2000 binlog_serialize_thread_size=7',
      BINLOG_EXPIRE_LOGS_AUTO_SCALE='{
        "enable":1,
        "scale_up_threshold":"44%",
        "scale_up_step":"44%",
        "max_scale_up_capacity_gb":5000,
        "scale_down_threshold":"54%",
        "scale_down_step":"14%",
        "min_scale_down_capacity_gb":44,
        "computed_binlog_expire_logs_size":10737418244
        }';
  

Stop a binlog instance

Stops the specified binlog instance.

Syntax

STOP BINLOG INSTANCE instance_name;

instance_name is the instance to stop.

Example

Stop instance eo46r4f2e8:

STOP BINLOG INSTANCE eo46r4f2e8;

After stopping, run SHOW BINLOG INSTANCES eo46r4f2e8;. The state column becomes Stop:

+------------+------------+-----------+---------------+------+------+--------+-------+---------+---------+---------------+-------------+--------------+-----------------+---------------+-------------+-------------+--------------+---------+------------------------------------------------+----------+
| name       | ob_cluster | ob_tenant | ip            | port | zone | region | group | running | state   | obcdc_running | obcdc_state | service_mode | convert_running | convert_delay | convert_rps | convert_eps | convert_iops | dumpers | version                                        | odp_addr |
+------------+------------+-----------+---------------+------+------+--------+-------+---------+---------+---------------+-------------+--------------+-----------------+---------------+-------------+-------------+--------------+---------+------------------------------------------------+----------+
| eo46r4f2e8 | obdemo     | test1     | 10.10.10.1    | 8106 |      |        |       | No      | Stop    | No            | Stop        | disabled     | No              |          NULL |        NULL |        NULL |         NULL |    NULL | 4.0.1-92748c6c59534426d187977b13b61b7cdf4fa200 | NULL     |
+------------+------------+-----------+---------------+------+------+--------+-------+---------+---------+---------------+-------------+--------------+-----------------+---------------+-------------+-------------+--------------+---------+------------------------------------------------+----------+

Start a binlog instance

Starts the specified binlog instance.

Syntax

START BINLOG INSTANCE instance_name;

instance_name is the instance to start.

Example

Start instance eo46r4f2e8:

START BINLOG INSTANCE eo46r4f2e8;

Switch the primary binlog instance

Manually switches the primary binlog instance for a tenant.

Syntax

SWITCH MASTER INSTANCE TO instance_name FOR TENANT cluster.tenant [FULL]

Parameters

Examples

For tenant test1 in cluster obdemo:

1. Find the node hosting the primary instance.

   SHOW BINLOG SERVER FOR TENANT obdemo.test1;
   

   Sample output — primary is on 10.10.10.1:8103:

   +---------+--------+------------+------+--------+-------+
   | cluster | tenant | ip         | port | status | cause |
   +---------+--------+------------+------+--------+-------+
   | obdemo  | test1  | 10.10.10.1 | 8103 | OK     |  NULL |
   +---------+--------+------------+------+--------+-------+
   

2. Switch primary.

   SWITCH MASTER INSTANCE TO eo46r4f2e8 FOR TENANT obdemo.test1;
   

3. Verify the new primary.

   SHOW BINLOG SERVER FOR TENANT obdemo.test1;
   

   Sample output — primary is now on 10.10.10.1:8106:

   +---------+--------+------------+------+--------+-------+
   | cluster | tenant | ip         | port | status | cause |
   +---------+--------+------------+------+--------+-------+
   | obdemo  | test1  | 10.10.10.1 | 8106 | OK     |  NULL |
   +---------+--------+------------+------+--------+-------+
   

Release a binlog instance

Deletes the specified binlog instance and its binlog files.

Syntax

DROP BINLOG INSTANCE instance_name [FORCE]

Parameters

Example

Force-drop instance binlog2:

DROP BINLOG INSTANCE binlog2 FORCE;