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

mysql_shell/__init__.py

@@ -0,0 +1,7 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from .builders import *
+from .clients import *
+from .executors import *
+from .models import *

mysql_shell/builders/__init__.py

@@ -0,0 +1,7 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from .authorization import *
+from .locking import *
+from .logging import *
+from .quoting import *

mysql_shell/builders/authorization/__init__.py

@@ -0,0 +1,5 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from .base import BaseAuthorizationQueryBuilder
+from .charm import CharmAuthorizationQueryBuilder

mysql_shell/builders/authorization/base.py

@@ -0,0 +1,23 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from abc import ABC, abstractmethod
+
+
+class BaseAuthorizationQueryBuilder(ABC):
+    """Base class for authorization query builders."""
+
+    @abstractmethod
+    def build_instance_auth_roles_query(self) -> str:
+        """Builds the instance roles creation query."""
+        raise NotImplementedError()
+
+    @abstractmethod
+    def build_instance_router_role_query(self, rolename: str) -> str:
+        """Builds the instance router role creation query."""
+        raise NotImplementedError()
+
+    @abstractmethod
+    def build_database_admin_role_query(self, rolename: str, database: str) -> str:
+        """Builds the database admin role creation query."""
+        raise NotImplementedError()

mysql_shell/builders/authorization/charm.py

@@ -0,0 +1,213 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from ..quoting import StringQueryQuoter
+from .base import BaseAuthorizationQueryBuilder
+
+
+class CharmAuthorizationQueryBuilder(BaseAuthorizationQueryBuilder):
+    """Charm authorization query builder."""
+
+    ROLE_CREATION_QUERY = "CREATE ROLE {rolename}"
+    ROLE_GRANTING_QUERY = "GRANT {parents} TO {rolename}"
+    PRIV_GRANTING_QUERY = "GRANT {privileges} ON {database}.* TO {rolename}"
+
+    _DATA_PRIVILEGES = [
+        "SELECT",
+        "INSERT",
+        "DELETE",
+        "UPDATE",
+        "EXECUTE",
+    ]
+
+    _SCHEMA_PRIVILEGES = [
+        "ALTER",
+        "ALTER ROUTINE",
+        "CREATE",
+        "CREATE ROUTINE",
+        "CREATE VIEW",
+        "DROP",
+        "INDEX",
+        "LOCK TABLES",
+        "REFERENCES",
+        "TRIGGER",
+    ]
+
+    def __init__(
+        self,
+        role_admin: str,
+        role_backup: str,
+        role_ddl: str,
+        role_stats: str,
+        role_reader: str,
+        role_writer: str,
+    ):
+        """Initialize the query builder."""
+        self._quoter = StringQueryQuoter()
+        self._role_admin = self._quoter.quote_value(role_admin)
+        self._role_backup = self._quoter.quote_value(role_backup)
+        self._role_ddl = self._quoter.quote_value(role_ddl)
+        self._role_stats = self._quoter.quote_value(role_stats)
+        self._role_reader = self._quoter.quote_value(role_reader)
+        self._role_writer = self._quoter.quote_value(role_writer)
+
+    def _build_instance_admin_role_queries(self) -> list[str]:
+        """Builds the instance admin role creation queries."""
+        return [
+            self.ROLE_CREATION_QUERY.format(
+                rolename=self._role_admin,
+            ),
+            self.ROLE_GRANTING_QUERY.format(
+                parents=", ".join([
+                    self._role_backup,
+                    self._role_ddl,
+                    self._role_stats,
+                    self._role_writer,
+                ]),
+                rolename=self._role_admin,
+            ),
+            self.PRIV_GRANTING_QUERY.format(
+                privileges=", ".join([
+                    *self._DATA_PRIVILEGES,
+                    "EVENT",
+                    "SHUTDOWN",
+                    "AUDIT_ADMIN",
+                    "CONNECTION_ADMIN",
+                    "SYSTEM_VARIABLES_ADMIN",
+                ]),
+                rolename=self._role_admin,
+                database="*",
+            ),
+        ]
+
+    def _build_instance_backup_role_queries(self) -> list[str]:
+        """Builds the instance backups role creation queries."""
+        return [
+            self.ROLE_CREATION_QUERY.format(
+                rolename=self._role_backup,
+            ),
+            self.ROLE_GRANTING_QUERY.format(
+                parents=", ".join([self._role_stats]),
+                rolename=self._role_backup,
+            ),
+            self.PRIV_GRANTING_QUERY.format(
+                privileges=", ".join([
+                    "EXECUTE",
+                    "LOCK TABLES",
+                    "PROCESS",
+                    "RELOAD",
+                    "BACKUP_ADMIN",
+                    "CONNECTION_ADMIN",
+                ]),
+                rolename=self._role_backup,
+                database="*",
+            ),
+        ]
+
+    def _build_instance_ddl_role_queries(self) -> list[str]:
+        """Builds the instance backups role creation queries."""
+        return [
+            self.ROLE_CREATION_QUERY.format(
+                rolename=self._role_ddl,
+            ),
+            self.ROLE_GRANTING_QUERY.format(
+                parents=", ".join([self._role_writer]),
+                rolename=self._role_ddl,
+            ),
+            self.PRIV_GRANTING_QUERY.format(
+                privileges=", ".join([*self._SCHEMA_PRIVILEGES, "SHOW_ROUTINE", "SHOW VIEW"]),
+                rolename=self._role_ddl,
+                database="*",
+            ),
+        ]
+
+    def _build_instance_stats_role_queries(self) -> list[str]:
+        """Builds the instance stats role creation queries."""
+        return [
+            self.ROLE_CREATION_QUERY.format(
+                rolename=self._role_stats,
+            ),
+            self.PRIV_GRANTING_QUERY.format(
+                privileges=", ".join(["SELECT"]),
+                rolename=self._role_stats,
+                database="performance_schema",
+            ),
+            self.PRIV_GRANTING_QUERY.format(
+                privileges=", ".join(["PROCESS", "RELOAD", "REPLICATION CLIENT"]),
+                rolename=self._role_stats,
+                database="*",
+            ),
+        ]
+
+    def _build_instance_reader_role_queries(self) -> list[str]:
+        """Builds the instance reader role creation queries."""
+        return [
+            self.ROLE_CREATION_QUERY.format(
+                rolename=self._role_reader,
+            ),
+        ]
+
+    def _build_instance_writer_role_queries(self) -> list[str]:
+        """Builds the instance writer role creation queries."""
+        return [
+            self.ROLE_CREATION_QUERY.format(
+                rolename=self._role_writer,
+            ),
+        ]
+
+    def build_instance_auth_roles_query(self) -> str:
+        """Builds the instance roles creation query."""
+        return ";".join([
+            *self._build_instance_reader_role_queries(),
+            *self._build_instance_writer_role_queries(),
+            *self._build_instance_stats_role_queries(),
+            *self._build_instance_ddl_role_queries(),
+            *self._build_instance_backup_role_queries(),
+            *self._build_instance_admin_role_queries(),
+        ])
+
+    def build_instance_router_role_query(self, rolename: str) -> str:
+        """Builds the instance router role creation query."""
+        rolename = self._quoter.quote_value(rolename)
+
+        return ";".join([
+            self.ROLE_CREATION_QUERY.format(
+                rolename=rolename,
+            ),
+            (self.PRIV_GRANTING_QUERY + " WITH GRANT OPTION").format(
+                privileges=", ".join(["CREATE USER"]),
+                rolename=rolename,
+                database="*",
+            ),
+            self.PRIV_GRANTING_QUERY.format(
+                privileges=", ".join([*self._DATA_PRIVILEGES]),
+                rolename=rolename,
+                database="mysql_innodb_cluster_metadata",
+            ),
+            self.PRIV_GRANTING_QUERY.format(
+                privileges=", ".join(["SELECT"]),
+                rolename=rolename,
+                database="mysql",
+            ),
+            self.PRIV_GRANTING_QUERY.format(
+                privileges=", ".join(["SELECT"]),
+                rolename=rolename,
+                database="performance_schema",
+            ),
+        ])
+
+    def build_database_admin_role_query(self, rolename: str, database: str) -> str:
+        """Builds the database admin role creation query."""
+        database = self._quoter.quote_identifier(database)
+        rolename = self._quoter.quote_value(rolename)
+
+        return ";".join([
+            self.ROLE_CREATION_QUERY.format(
+                rolename=rolename,
+            ),
+            self.PRIV_GRANTING_QUERY.format(
+                privileges=", ".join([*self._DATA_PRIVILEGES, *self._SCHEMA_PRIVILEGES]),
+                rolename=rolename,
+                database=database,
+            ),
+        ])

mysql_shell/builders/locking/__init__.py

@@ -0,0 +1,5 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from .base import BaseLockingQueryBuilder
+from .charm import CharmLockingQueryBuilder

mysql_shell/builders/locking/base.py

@@ -0,0 +1,28 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from abc import ABC, abstractmethod
+
+
+class BaseLockingQueryBuilder(ABC):
+    """Base class for all the locking query builders."""
+
+    @abstractmethod
+    def build_table_creation_query(self) -> str:
+        """Builds the locking table creation query."""
+        raise NotImplementedError()
+
+    @abstractmethod
+    def build_fetch_acquired_query(self, task: str) -> str:
+        """Builds the acquired lock check query."""
+        raise NotImplementedError()
+
+    @abstractmethod
+    def build_acquire_query(self, task: str, instance: str) -> str:
+        """Builds the lock acquiring query."""
+        raise NotImplementedError()
+
+    @abstractmethod
+    def build_release_query(self, task: str, instance: str) -> str:
+        """Builds the lock releasing query."""
+        raise NotImplementedError()

mysql_shell/builders/locking/charm.py

@@ -0,0 +1,97 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from ..quoting import StringQueryQuoter
+from .base import BaseLockingQueryBuilder
+
+
+class CharmLockingQueryBuilder(BaseLockingQueryBuilder):
+    """Charm locking query builder."""
+
+    INSTANCE_ADDITION_TASK = "unit-add"
+    INSTANCE_REMOVAL_TASK = "unit-teardown"
+
+    TASKS = [
+        INSTANCE_ADDITION_TASK,
+        INSTANCE_REMOVAL_TASK,
+    ]
+
+    def __init__(self, table_schema: str, table_name: str):
+        """Initialize the query builder."""
+        self._quoter = StringQueryQuoter()
+        self._table = "{table_schema}.{table_name}".format(
+            table_schema=self._quoter.quote_identifier(table_schema),
+            table_name=self._quoter.quote_identifier(table_name),
+        )
+
+    def build_table_creation_query(self) -> str:
+        """Builds the locking table creation query."""
+        create_query = (
+            "CREATE TABLE IF NOT EXISTS {table} ( "
+            "    task VARCHAR(20), "
+            "    executor VARCHAR(20), "
+            "    status VARCHAR(20), "
+            "    PRIMARY KEY(task) "
+            ")"
+        )
+        insert_query = (
+            "INSERT INTO {table} (task, executor, status) "
+            "VALUES ('{task}', '', 'not-started') "
+            "ON DUPLICATE KEY UPDATE "
+            "    executor = '', "
+            "    status = 'not-started'"
+        )
+
+        create_queries = [create_query.format(table=self._table)]
+        insert_queries = [insert_query.format(table=self._table, task=task) for task in self.TASKS]
+
+        return ";".join((
+            *create_queries,
+            *insert_queries,
+        ))
+
+    def build_fetch_acquired_query(self, task: str) -> str:
+        """Builds the acquired lock fetch query."""
+        query = "SELECT executor FROM {table} WHERE task = {task} AND status = {status}"
+
+        return query.format(
+            table=self._table,
+            task=self._quoter.quote_value(task),
+            status=self._quoter.quote_value("in-progress"),
+        )
+
+    def build_acquire_query(self, task: str, instance: str) -> str:
+        """Builds the lock acquiring query."""
+        if task not in self.TASKS:
+            raise ValueError("Task not supported")
+
+        query = (
+            "UPDATE {table} "
+            "SET status = {status}, executor = {instance} "
+            "WHERE task = {task} AND executor = ''"
+        )
+
+        return query.format(
+            table=self._table,
+            task=self._quoter.quote_value(task),
+            instance=self._quoter.quote_value(instance),
+            status=self._quoter.quote_value("in-progress"),
+        )
+
+    def build_release_query(self, task: str, instance: str) -> str:
+        """Builds the lock releasing query."""
+        if task not in self.TASKS:
+            raise ValueError(f"Task not supported")
+
+        query = (
+            "UPDATE {table} "
+            "SET status = {status}, executor = '' "
+            "WHERE task = {task} AND executor = {instance}"
+        )
+
+        return query.format(
+            table=self._table,
+            task=self._quoter.quote_value(task),
+            instance=self._quoter.quote_value(instance),
+            status=self._quoter.quote_value("not-started"),
+        )

mysql_shell/builders/logging/__init__.py

@@ -0,0 +1,5 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from .base import BaseLoggingQueryBuilder
+from .charm import CharmLoggingQueryBuilder

mysql_shell/builders/logging/base.py

@@ -0,0 +1,14 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from abc import ABC, abstractmethod
+from typing import Sequence
+
+
+class BaseLoggingQueryBuilder(ABC):
+    """Base class for all the logging query builders."""
+
+    @abstractmethod
+    def build_logs_flushing_query(self, logs: Sequence[str] | None) -> str:
+        """Builds the logs flushing query."""
+        raise NotImplementedError()

mysql_shell/builders/logging/charm.py

@@ -0,0 +1,36 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from typing import Sequence
+
+from ...models import LogType
+from ..quoting import StringQueryQuoter
+from .base import BaseLoggingQueryBuilder
+
+
+class CharmLoggingQueryBuilder(BaseLoggingQueryBuilder):
+    """Charm logging query builder."""
+
+    def __init__(self):
+        """Initialize the query builder."""
+        self._quoter = StringQueryQuoter()
+
+    def build_logs_flushing_query(self, logs: Sequence[LogType] | None = None) -> str:
+        """Builds the logs flushing query.
+
+        Arguments:
+            logs: a sequence of LogTypes to flush. If None, flush all
+        """
+        binlog_query = "SET @@SESSION.sql_log_bin = {value}"
+
+        if not logs:
+            flush_query = "FLUSH LOGS"
+        else:
+            flush_query = "FLUSH {log} LOGS"
+            flush_query = ";".join(flush_query.format(log=log.value) for log in logs)
+
+        return ";".join((
+            binlog_query.format(value=self._quoter.quote_value("OFF")),
+            flush_query,
+            binlog_query.format(value=self._quoter.quote_value("ON")),
+        ))

mysql_shell/builders/quoting.py

@@ -0,0 +1,46 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from typing import Any
+
+
+class StringQueryQuoter:
+    """Class to escape and quote MySQL query input parameters."""
+
+    @staticmethod
+    def escape(value: Any) -> Any:
+        """Escapes a string that can be used in a SQL statement.
+
+        This function will only be used in the context of MySQL Shell,
+        as the recommended way to deal with SQL injection attacks
+        (using parametrized queries) is not available.
+
+        The code has been copied from the mysql-connector Python package.
+        https://github.com/mysql/mysql-connector-python/blob/8.0.33/lib/mysql/connector/conversion.py#L174-L201
+        """
+        if isinstance(value, (bytes, bytearray)):
+            value = value.replace(b"\\", b"\\\\")
+            value = value.replace(b"\n", b"\\n")
+            value = value.replace(b"\r", b"\\r")
+            value = value.replace(b"\140", b"\134\140")  # tick quote
+            value = value.replace(b"\047", b"\134\047")  # single quotes
+            value = value.replace(b"\042", b"\134\042")  # double quotes
+            value = value.replace(b"\032", b"\134\032")  # for Win32
+        elif isinstance(value, str):
+            value = value.replace("\\", "\\\\")
+            value = value.replace("\n", "\\n")
+            value = value.replace("\r", "\\r")
+            value = value.replace("\140", "\134\140")  # tick quote
+            value = value.replace("\047", "\134\047")  # single quotes
+            value = value.replace("\042", "\134\042")  # double quotes
+            value = value.replace("\032", "\134\032")  # for Win32
+
+        return value
+
+    def quote_value(self, value: Any) -> str:
+        """Quotes the provided value."""
+        return f"'{self.escape(value)}'"
+
+    def quote_identifier(self, name: str) -> str:
+        """Quotes the provided identifier name."""
+        return f"`{self.escape(name)}`"

mysql_shell/clients/__init__.py

@@ -0,0 +1,5 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from .cluster import *
+from .instance import *