English | Chinese

OBShell-SDK-Python is an SDK provided by theOceanBase Community to facilitate developers with quick access to OBShell services, allowing them to conveniently call OBShell interfaces using this SDK.

Install

pip install obshell

Quick Start

Please ensure that OBShell is running when using it.

Create a Client

Create a specified version client. Optional argument protocol_options controls HTTP/HTTPS and TLS (defaults to plain HTTP via ProtocolOptions.http() if omitted).

from obshell import ClientV1
from obshell.auth import PasswordAuth

def main():
    client = ClientV1("11.11.11.1", 2886, PasswordAuth("****"))

Create ClientSet the same way (ClientSet forwards protocol_options to ClientV1).

from obshell import ClientSet
from obshell.auth import PasswordAuth

def main():
    client = ClientSet("11.11.11.1", 2886, PasswordAuth("****"))

HTTPS and TLS (protocol_options)

Import ProtocolOptions from obshell.request and pass it as protocol_options to ClientV1 or ClientSet:

• ProtocolOptions.http() — HTTP (default when you omit protocol_options).
• ProtocolOptions.https() — HTTPS with default server certificate verification (typical for production).
• ProtocolOptions.https_insecure() — HTTPS without verifying the server certificate. Use only in non-production (for example, self-signed certs in a lab); it weakens transport security.
• ProtocolOptions.https(verify_cert=..., client_cert=...) — same meaning as requests verify and cert: verify_cert can be True, False, or a path to a CA bundle; client_cert can be a single PEM path or (cert_pem, key_pem).

from obshell import ClientV1
from obshell.auth import PasswordAuth
from obshell.request import ProtocolOptions

client = ClientV1(
    "11.11.11.1",
    2886,
    PasswordAuth("****"),
    protocol_options=ProtocolOptions.https(),
)

from obshell import ClientSet
from obshell.auth import PasswordAuth
from obshell.request import ProtocolOptions

client = ClientSet(
    "11.11.11.1",
    2886,
    PasswordAuth("****"),
    protocol_options=ProtocolOptions.https(
        verify_cert="/path/to/ca.pem",
        client_cert=("/path/to/client.crt", "/path/to/client.key"),
    ),
)

A PEM-formatted certificate file may use either .pem or .crt as its filename suffix.

Deploy Cluster

OBShell-SDK-Python provides two types of methods to deploy an OBShell cluster: the first immediately returns after successfully making a request to the OBShell API, and the second waits for the OBShell task to complete after the API request is successful before returning. The former executes the task asynchronously, while the latter executes the task synchronously.

Deploy a 1-1-1 cluster:

• Asynchronous Task Execution

from obshell import ClientSet
from obshell.auth import PasswordAuth
def main():
    client = ClientSet("11.11.11.1", 2886, PasswordAuth("****"))

    # join master
    dag = client.v1.join("11.11.11.1", 2886, "zone1")
    client.v1.wait_dag_succeed(dag.generic_id)
    # join follower
    dag = client.v1.join("11.11.11.2", 2886, "zone2")
    client.v1.wait_dag_succeed(dag.generic_id)
    dag = client.v1.join("11.11.11.3", 2886, "zone3")
    client.v1.wait_dag_succeed(dag.generic_id)

    # configure observer
    configs = {
        "datafile_size": "24G", "log_disk_size": "24G", 
        "cpu_count": "16", "memory_limit": "16G", "system_memory": "8G", 
        "enable_syslog_recycle": "true", "enable_syslog_wf": "true"}
    dag = client.v1.config_observer(configs, "GLOBAL", [])
    client.v1.wait_dag_succeed(dag.generic_id)

    # configure obcluster
    dag = client.v1.config_obcluster_sync("test-sdk", 11, "****")
    client.v1.wait_dag_succeed(dag.generic_id)

    # initialize obcluster
    dag = client.v1.init_sync()
    client.v1.wait_dag_succeed(dag.generic_id)
    
    # get the status of the cluster
    status = client.v1.get_status()
    print(status)

• Synchronous Task Execution

from obshell import ClientSet
from obshell.auth import PasswordAuth

def main():
    client = ClientSet("11.11.11.1", 2886, PasswordAuth("****"))

    # join master
    client.v1.join_sync("11.11.11.1", 2886, "zone1")
    # join follower
    client.v1.join_sync("11.11.11.2", 2886, "zone2")
    client.v1.join_sync("11.11.11.3", 2886, "zone3")

    # configure observer
    configs = {
        "datafile_size": "24G", "log_disk_size": "24G", 
        "cpu_count": "16", "memory_limit": "16G", "system_memory": "8G", 
        "enable_syslog_recycle": "true", "enable_syslog_wf": "true"}
    client.v1.config_observer_sync(configs, "GLOBAL", [])

    # configure obcluster
    client.v1.config_obcluster_sync("test-sdk", 11, "****")

    # initialize obcluster
    client.v1.init_sync()
    
    # get the status of the cluster
    status = client.v1.get_status()
    print(status)

Scale out

Scale out the agent '11.11.11.4' into the cluster where the agent '11.11.11.1' is located.

from obshell import ClientSet
from obshell.auth import PasswordAuth

def main():
    client = ClientSet("111.11.11.1", 2886, PasswordAuth("****"))

    # scale out
    configs = {
        "datafile_size": "24G", "log_disk_size": "24G", 
        "cpu_count": "16", "memory_limit": "16G", "system_memory": "8G", 
        "enable_syslog_recycle": "true", "enable_syslog_wf": "true"}
    client.v1.scale_out_sync("11.11.11.4", 2886, "zone3", configs)