mysql-shell-client 0.6.0__py3-none-any.whl

mysql_shell/clients/instance.py

@@ -0,0 +1,524 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+import json
+import logging
+from typing import Any, Mapping, Sequence
+
+from ..builders import StringQueryQuoter
+from ..executors import BaseExecutor
+from ..executors.errors import ExecutionError
+from ..models.account import Role, User
+from ..models.instance import InstanceRole, InstanceState
+from ..models.statement import VariableScope
+
+logger = logging.getLogger()
+
+_Attrs = Mapping[str, str] | None
+
+
+class MySQLInstanceClient:
+    """Class to encapsulate all instance operations using MySQL Shell."""
+
+    def __init__(self, executor: BaseExecutor, quoter: StringQueryQuoter):
+        """Initialize the class."""
+        self._executor = executor
+        self._quoter = quoter
+
+    def check_work_ongoing(self, name_pattern: str) -> bool:
+        """Checks whether an instance work is ongoing."""
+        query = (
+            "SELECT work_completed, work_estimated "
+            "FROM performance_schema.events_stages_current "
+            "WHERE event_name LIKE {name_pattern}"
+        )
+        query = query.format(
+            name_pattern=self._quoter.quote_value(name_pattern),
+        )
+
+        try:
+            rows = self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error(f"Failed to check work for events with {name_pattern=}")
+            raise
+        else:
+            return any(row["work_completed"] < row["work_estimated"] for row in rows)
+
+    def create_instance_role(self, role: Role, roles: list[str] = None) -> None:
+        """Creates a new instance role."""
+        if not roles:
+            granting_query = ""
+        else:
+            granting_query = "GRANT {roles} TO {rolename}@{hostname}"
+            granting_query = granting_query.format(
+                rolename=self._quoter.quote_value(role.rolename),
+                hostname=self._quoter.quote_value(role.hostname),
+                roles=", ".join(self._quoter.quote_value(r) for r in roles),
+            )
+
+        creation_query = "CREATE ROLE {rolename}@{hostname}"
+        creation_query = creation_query.format(
+            rolename=self._quoter.quote_value(role.rolename),
+            hostname=self._quoter.quote_value(role.hostname),
+        )
+
+        queries = ";".join((
+            creation_query,
+            granting_query,
+        ))
+
+        try:
+            self._executor.execute_sql(queries)
+        except ExecutionError:
+            logger.error(f"Failed to create instance role {role.rolename}.{role.hostname}")
+            raise
+
+    def create_instance_user(self, user: User, password: str, roles: list[str] = None) -> None:
+        """Creates an instance user with the provided attributes."""
+        if not roles:
+            granting_query = ""
+        else:
+            granting_query = "GRANT {roles} TO {username}@{hostname}"
+            granting_query = granting_query.format(
+                username=self._quoter.quote_value(user.username),
+                hostname=self._quoter.quote_value(user.hostname),
+                roles=", ".join(self._quoter.quote_value(r) for r in roles),
+            )
+
+        creation_query = (
+            "CREATE USER {username}@{hostname} IDENTIFIED BY {password} ATTRIBUTE {attrs}"
+        )
+        creation_query = creation_query.format(
+            username=self._quoter.quote_value(user.username),
+            hostname=self._quoter.quote_value(user.hostname),
+            password=self._quoter.quote_value(password),
+            attrs=self._quoter.quote_value(user.serialize_attrs()),
+        )
+
+        queries = ";".join((
+            creation_query,
+            granting_query,
+        ))
+
+        try:
+            self._executor.execute_sql(queries)
+        except ExecutionError:
+            logger.error(f"Failed to create instance user {user.username}.{user.hostname}")
+            raise
+
+    def delete_instance_user(self, user: User) -> None:
+        """Deletes an instance user if it exists."""
+        query = "DROP USER IF EXISTS {username}@{hostname}"
+        query = query.format(
+            username=self._quoter.quote_value(user.username),
+            hostname=self._quoter.quote_value(user.hostname),
+        )
+
+        try:
+            self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error(f"Failed to delete instance user {user.username}.{user.hostname}")
+            raise
+
+    def delete_instance_users(self, users: list[User]) -> None:
+        """Deletes the instance users provided."""
+        query = "DROP USER IF EXISTS {username}@{hostname}"
+        queries = []
+
+        for user in users:
+            queries.append(
+                query.format(
+                    username=self._quoter.quote_value(user.username),
+                    hostname=self._quoter.quote_value(user.hostname),
+                )
+            )
+
+        queries = ";".join(queries)
+
+        try:
+            self._executor.execute_sql(queries)
+        except ExecutionError:
+            logger.error("Failed to delete instance users")
+            raise
+
+    def update_instance_user(self, user: User, password: str = None, attrs: _Attrs = None) -> None:
+        """Updates an instance user with the provided password and / or attributes."""
+        if not password and not attrs:
+            raise ValueError("Either password or attrs must be provided")
+
+        query = "ALTER USER {username}@{hostname}"
+        query = query.format(
+            username=self._quoter.quote_value(user.username),
+            hostname=self._quoter.quote_value(user.hostname),
+        )
+
+        if password:
+            query += f" IDENTIFIED BY {self._quoter.quote_value(password)}"
+        if attrs:
+            query += f" ATTRIBUTE {self._quoter.quote_value(json.dumps(attrs))}"
+
+        try:
+            self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error(f"Failed to update instance user {user.username}.{user.hostname}")
+            raise
+
+    def get_cluster_instance_label(self) -> str | None:
+        """Gets the instance label within the cluster."""
+        query = (
+            "SELECT instance_name "
+            "FROM mysql_innodb_cluster_metadata.instances "
+            "WHERE mysql_server_uuid = @@server_uuid"
+        )
+
+        try:
+            rows = self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error("Failed to get cluster instance label")
+            raise
+
+        if not rows:
+            return None
+
+        return rows[0]["instance_name"]
+
+    def get_cluster_instance_labels(self, cluster_name: str) -> list[str]:
+        """Gets the instance labels within the cluster."""
+        query = (
+            "SELECT instance_name "
+            "FROM mysql_innodb_cluster_metadata.instances "
+            "WHERE cluster_id IN ( "
+            "   SELECT cluster_id "
+            "   FROM mysql_innodb_cluster_metadata.clusters "
+            "   WHERE cluster_name = {cluster_name} "
+            ")"
+        )
+        query = query.format(
+            cluster_name=self._quoter.quote_value(cluster_name),
+        )
+
+        try:
+            rows = self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error(f"Failed to get cluster instance labels with {cluster_name=}")
+            raise
+        else:
+            return [row["instance_name"] for row in rows]
+
+    def get_cluster_labels(self) -> list[str]:
+        """Gets the cluster labels."""
+        query = "SELECT cluster_name FROM mysql_innodb_cluster_metadata.clusters"
+
+        try:
+            rows = self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error("Failed to get cluster labels")
+            raise
+        else:
+            return [row["cluster_name"] for row in rows]
+
+    def get_instance_replication_state(self) -> InstanceState | None:
+        """Gets the instance replication state."""
+        query = (
+            "SELECT member_state "
+            "FROM performance_schema.replication_group_members "
+            "WHERE member_id = @@server_uuid"
+        )
+
+        try:
+            rows = self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error("Failed to get instance replication state")
+            raise
+
+        if not rows:
+            return None
+
+        state = rows[0]["member_state"]
+        state = InstanceState(state) if state else None
+        return state
+
+    def get_instance_replication_role(self) -> InstanceRole | None:
+        """Gets the instance replication role."""
+        query = (
+            "SELECT member_role "
+            "FROM performance_schema.replication_group_members "
+            "WHERE member_id = @@server_uuid"
+        )
+
+        try:
+            rows = self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error("Failed to get instance replication role")
+            raise
+
+        if not rows:
+            return None
+
+        role = rows[0]["member_role"]
+        role = InstanceRole(role) if role else None
+        return role
+
+    def get_instance_variable(self, scope: VariableScope, name: str) -> Any | None:
+        """Gets an instance variable by scope and name."""
+        if scope in (VariableScope.PERSIST, VariableScope.PERSIST_ONLY):
+            raise ValueError("Invalid scope")
+
+        quoted_name = self._quoter.quote_identifier(name)
+
+        query = "SELECT @@{scope}.{name} AS {alias}"
+        query = query.format(
+            scope=scope.value,
+            name=quoted_name,
+            alias=quoted_name,
+        )
+
+        try:
+            rows = self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error(f"Failed to get instance variable {scope}.{name}")
+            raise
+
+        if not rows:
+            return None
+
+        return rows[0][name]
+
+    def set_instance_variable(self, scope: VariableScope, name: str, value: Any) -> None:
+        """Sets an instance variable by scope and name."""
+        quoted_name = self._quoter.quote_identifier(name)
+        quoted_value = self._quoter.quote_value(value) if isinstance(value, str) else value
+
+        query = "SET @@{scope}.{name} = {value}"
+        query = query.format(
+            scope=scope.value,
+            name=quoted_name,
+            value=quoted_value,
+        )
+
+        try:
+            self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error(f"Failed to set instance variable {scope}.{name}")
+            raise
+
+    def get_instance_version(self) -> str | None:
+        """Gets the instance version value."""
+        version = self.get_instance_variable(VariableScope.GLOBAL, "version")
+        if not version:
+            return None
+
+        return version.split("-")[0]
+
+    def install_instance_plugin(self, name: str, path: str) -> None:
+        """Installs an instance plugin by name and path."""
+        query = "INSTALL PLUGIN {plugin_name} SONAME {plugin_path}"
+        query = query.format(
+            plugin_name=self._quoter.quote_identifier(name),
+            plugin_path=self._quoter.quote_value(path),
+        )
+
+        try:
+            self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error(f"Failed to install instance plugin with {name=} and {path=}")
+            raise
+
+    def uninstall_instance_plugin(self, name: str) -> None:
+        """Uninstalls an instance plugin by name."""
+        query = "UNINSTALL PLUGIN {plugin_name}"
+        query = query.format(
+            plugin_name=self._quoter.quote_identifier(name),
+        )
+
+        try:
+            self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error(f"Failed to uninstall instance plugin with {name=}")
+            raise
+
+    def reload_instance_certs(self) -> None:
+        """Reloads TLS certificates."""
+        query = "ALTER INSTANCE RELOAD TLS"
+
+        try:
+            self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error("Failed to reload instance TLS certificates")
+            raise
+
+    def search_instance_replication_members(
+        self,
+        roles: Sequence[InstanceRole] | None = None,
+        states: Sequence[InstanceState] | None = None,
+    ) -> list[str]:
+        """Searches the instance replication member IDs by role and/or state."""
+        if not roles:
+            roles = list(InstanceRole)
+        if not states:
+            states = list(InstanceState)
+
+        query = (
+            "SELECT member_id "
+            "FROM performance_schema.replication_group_members "
+            "WHERE member_role IN ({roles}) AND member_state IN ({states})"
+        )
+        query = query.format(
+            roles=", ".join([self._quoter.quote_value(role) for role in roles]),
+            states=", ".join([self._quoter.quote_value(state) for state in states]),
+        )
+
+        try:
+            rows = self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error("Failed to search instance replication members")
+            raise
+        else:
+            return [row["member_id"] for row in rows]
+
+    def search_instance_connection_processes(self, name_pattern: str) -> list[int]:
+        """Searches the instance connection process IDs by name pattern."""
+        query = (
+            "SELECT processlist_id "
+            "FROM performance_schema.threads "
+            "WHERE "
+            "   processlist_id != CONNECTION_ID() AND "
+            "   connection_type IS NOT NULL AND "
+            "   name LIKE {name_pattern}"
+        )
+        query = query.format(
+            name_pattern=self._quoter.quote_value(name_pattern),
+        )
+
+        try:
+            rows = self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error(f"Failed to search instance connections with {name_pattern=}")
+            raise
+        else:
+            return [row["processlist_id"] for row in rows]
+
+    def search_instance_databases(self, name_pattern: str) -> list[str]:
+        """Searches the instance databases by name pattern."""
+        query = (
+            "SELECT schema_name "
+            "FROM information_schema.schemata "
+            "WHERE schema_name LIKE {name_pattern}"
+        )
+        query = query.format(
+            name_pattern=self._quoter.quote_value(name_pattern),
+        )
+
+        try:
+            rows = self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error(f"Failed to search instance databases with {name_pattern=}")
+            raise
+        else:
+            return [row["SCHEMA_NAME"] for row in rows]
+
+    def search_instance_plugins(self, name_pattern: str) -> list[str]:
+        """Searches the instance plugins by name pattern."""
+        # fmt: off
+        query = (
+            "SELECT name "
+            "FROM mysql.plugin "
+            "WHERE name LIKE {name_pattern}"
+        )
+        # fmt: on
+
+        query = query.format(
+            name_pattern=self._quoter.quote_value(name_pattern),
+        )
+
+        try:
+            rows = self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error(f"Failed to search instance plugins with {name_pattern=}")
+            raise
+        else:
+            return [row["name"] for row in rows]
+
+    def search_instance_roles(self, name_pattern: str) -> list[Role]:
+        """Searches the instance roles by name pattern."""
+        query = (
+            "SELECT user, host "
+            "FROM mysql.user "
+            "WHERE user LIKE {name_pattern} AND authentication_string=''"
+        )
+        query = query.format(
+            name_pattern=self._quoter.quote_value(name_pattern),
+        )
+
+        try:
+            rows = self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error(f"Failed to search instance roles with {name_pattern=}")
+            raise
+        else:
+            return [Role.from_row(row["user"], row["host"]) for row in rows]
+
+    def search_instance_users(self, name_pattern: str, attrs: _Attrs = None) -> list[User]:
+        """Searches the instance users by name pattern and attributes."""
+        attr_filter = "attribute LIKE {string}"
+        attr_substr = '%"{key}": "{val}"%'
+
+        if not attrs:
+            strings = ["%"]
+            filters = [attr_filter.format(string=self._quoter.quote_value(s)) for s in strings]
+        else:
+            strings = [attr_substr.format(key=key, val=val) for key, val in attrs.items()]
+            filters = [attr_filter.format(string=self._quoter.quote_value(s)) for s in strings]
+
+        query = (
+            "SELECT user, host, attribute "
+            "FROM information_schema.user_attributes "
+            "WHERE user LIKE {name_pattern} AND {attr_filters}"
+        )
+        query = query.format(
+            name_pattern=self._quoter.quote_value(name_pattern),
+            attr_filters=" AND ".join(filters),
+        )
+
+        try:
+            rows = self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error(f"Failed to search instance users with {name_pattern=}")
+            raise
+        else:
+            return [User.from_row(row["USER"], row["HOST"], row["ATTRIBUTE"]) for row in rows]
+
+    def start_instance_replication(self) -> None:
+        """Starts instance group replication."""
+        query = "START GROUP_REPLICATION"
+
+        try:
+            self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error("Failed to start instance replication")
+            raise
+
+    def stop_instance_replication(self) -> None:
+        """Stops instance group replication."""
+        query = "STOP GROUP_REPLICATION"
+
+        try:
+            self._executor.execute_sql(query)
+        except ExecutionError:
+            logger.error("Failed to stop instance replication")
+            raise
+
+    def stop_instance_processes(self, process_ids: Sequence[int]) -> None:
+        """Kills the instances processes by ID."""
+        if not process_ids:
+            return
+
+        query = "KILL CONNECTION {id}"
+        queries = [query.format(id=self._quoter.quote_value(pid)) for pid in process_ids]
+        queries = ";".join(queries)
+
+        try:
+            self._executor.execute_sql(queries)
+        except ExecutionError:
+            logger.error("Failed to kill instance processes")
+            raise

mysql_shell/executors/__init__.py

@@ -0,0 +1,5 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from .base import BaseExecutor
+from .local import LocalExecutor

mysql_shell/executors/base.py

@@ -0,0 +1,36 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from abc import ABC, abstractmethod
+from typing import Sequence
+
+from ..models import ConnectionDetails
+
+
+class BaseExecutor(ABC):
+    """Base class for all MySQL Shell executors."""
+
+    def __init__(self, conn_details: ConnectionDetails, shell_path: str):
+        """Initialize the executor."""
+        self._conn_details = conn_details
+        self._shell_path = shell_path
+
+    @property
+    def connection_details(self) -> ConnectionDetails:
+        """Return the connection details."""
+        return self._conn_details
+
+    @abstractmethod
+    def check_connection(self) -> None:
+        """Check the connection."""
+        raise NotImplementedError()
+
+    @abstractmethod
+    def execute_py(self, script: str, *, timeout: int | None = None) -> str:
+        """Execute a Python script."""
+        raise NotImplementedError()
+
+    @abstractmethod
+    def execute_sql(self, script: str, *, timeout: int | None = None) -> Sequence[dict]:
+        """Execute a SQL script."""
+        raise NotImplementedError()

mysql_shell/executors/errors/__init__.py

@@ -0,0 +1,4 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from .runtime import ExecutionError

mysql_shell/executors/errors/runtime.py

@@ -0,0 +1,15 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from typing import Any
+
+
+class ExecutionError(RuntimeError):
+    """MySQL shell execution error."""
+
+    def __init__(self, message: Any | None = None):
+        """Initialize the error."""
+        if isinstance(message, dict):
+            message = message.get("message")
+
+        super().__init__(message)