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

mysql_shell/executors/local.py

@@ -0,0 +1,188 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+import json
+import re
+import subprocess
+from typing import Generator
+
+from ..models import ConnectionDetails
+from .base import BaseExecutor
+from .errors import ExecutionError
+
+
+class LocalExecutor(BaseExecutor):
+    """Local executor for the MySQL Shell."""
+
+    def __init__(self, conn_details: ConnectionDetails, shell_path: str):
+        """Initialize the executor."""
+        super().__init__(conn_details, shell_path)
+
+    def _common_args(self) -> list[str]:
+        """Return the list of common arguments."""
+        return [
+            self._shell_path,
+            "--json=raw",
+            "--save-passwords=never",
+            "--passwords-from-stdin",
+        ]
+
+    def _connection_args(self) -> list[str]:
+        """Return the list of connection arguments."""
+        if self._conn_details.socket:
+            return [
+                f"--socket={self._conn_details.socket}",
+                f"--user={self._conn_details.username}",
+            ]
+        else:
+            return [
+                f"--host={self._conn_details.host}",
+                f"--port={self._conn_details.port}",
+                f"--user={self._conn_details.username}",
+            ]
+
+    def _parse_error(self, output: str) -> dict:
+        """Parse the execution error."""
+        error = next(self._iter_output(output, "error"), None)
+        if not error:
+            error = {}
+
+        return error
+
+    def _parse_output_py(self, output: str) -> str:
+        """Parse the Python execution output."""
+        result = next(self._iter_output(output, "info"), None)
+        if not result:
+            result = "{}"
+
+        return result
+
+    def _parse_output_sql(self, output: str) -> list:
+        """Parse the SQL execution output."""
+        result = next(self._iter_output(output, "rows"), None)
+        if not result:
+            result = []
+
+        return result
+
+    @staticmethod
+    def _iter_output(output: str, key: str) -> Generator:
+        """Iterates over the log lines in reversed order."""
+        logs = output.split("\n")
+
+        # MySQL Shell always prints prompts and warnings first
+        for log in reversed(logs):
+            if not log:
+                continue
+
+            log = json.loads(log)
+            val = log.get(key)
+            if not isinstance(val, str) or val.strip():
+                yield val
+
+    @staticmethod
+    def _strip_password(error: subprocess.SubprocessError):
+        """Strip passwords from SQL scripts."""
+        if not hasattr(error, "cmd"):
+            return error
+
+        password_pattern = re.compile("(?<=IDENTIFIED BY ')[^']+(?=')")
+        password_replace = "*****"
+
+        for index, value in enumerate(error.cmd):
+            if "IDENTIFIED BY" in value:
+                error.cmd[index] = re.sub(password_pattern, password_replace, value)
+
+        return error
+
+    def check_connection(self) -> None:
+        """Check the connection."""
+        command = [
+            *self._common_args(),
+            *self._connection_args(),
+        ]
+
+        try:
+            subprocess.check_output(
+                command,
+                input=self._conn_details.password,
+                text=True,
+            )
+        except subprocess.CalledProcessError as exc:
+            err = self._parse_error(exc.output)
+            raise ExecutionError(err)
+        except subprocess.TimeoutExpired:
+            raise ExecutionError()
+
+    def execute_py(self, script: str, *, timeout: int | None = None) -> str:
+        """Execute a Python script.
+
+        Arguments:
+            script: Python script to execute
+            timeout: Optional timeout seconds
+
+        Returns:
+            String with the output of the MySQL Shell command.
+            The output cannot be parsed to JSON, as the output depends on the script
+        """
+        # Prepend every Python command with useWizards=False, to disable interactive mode.
+        # Cannot be set on command line as it conflicts with --passwords-from-stdin.
+        script = "shell.options.set('useWizards', False)\n" + script
+
+        command = [
+            *self._common_args(),
+            *self._connection_args(),
+            "--py",
+            "--execute",
+            script,
+        ]
+
+        try:
+            output = subprocess.check_output(
+                command,
+                timeout=timeout,
+                input=self._conn_details.password,
+                text=True,
+            )
+        except subprocess.CalledProcessError as exc:
+            err = self._parse_error(exc.output)
+            raise ExecutionError(err)
+        except subprocess.TimeoutExpired:
+            raise ExecutionError()
+        else:
+            return self._parse_output_py(output)
+
+    def execute_sql(self, script: str, *, timeout: int | None = None) -> list[dict]:
+        """Execute a SQL script.
+
+        Arguments:
+            script: SQL script to execute
+            timeout: Optional timeout seconds
+
+        Returns:
+            List of dictionaries, one per returned row
+        """
+        command = [
+            *self._common_args(),
+            *self._connection_args(),
+            "--sql",
+            "--execute",
+            script,
+        ]
+
+        try:
+            output = subprocess.check_output(
+                command,
+                timeout=timeout,
+                input=self._conn_details.password,
+                text=True,
+            )
+        except subprocess.CalledProcessError as exc:
+            err = self._parse_error(exc.output)
+            exc = self._strip_password(exc)
+            raise ExecutionError(err) from exc
+        except subprocess.TimeoutExpired as exc:
+            exc = self._strip_password(exc)
+            raise ExecutionError() from exc
+        else:
+            return self._parse_output_sql(output)

mysql_shell/models/__init__.py

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

mysql_shell/models/account.py

@@ -0,0 +1,49 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+import json
+from dataclasses import dataclass
+
+
+@dataclass
+class Role:
+    """MySQL role account."""
+
+    rolename: str
+    hostname: str = "%"
+
+    @classmethod
+    def from_row(cls, rolename: str, hostname: str):
+        """Create a role account from a MySQL row."""
+        return Role(
+            rolename=rolename,
+            hostname=hostname,
+        )
+
+
+@dataclass
+class User:
+    """MySQL user account."""
+
+    username: str
+    hostname: str = "%"
+    attributes: dict | None = None
+
+    @classmethod
+    def from_row(cls, username: str, hostname: str, attributes: str | None):
+        """Create a user account from a MySQL row."""
+        if not attributes:
+            attributes = "{}"
+
+        return User(
+            username=username,
+            hostname=hostname,
+            attributes=json.loads(attributes),
+        )
+
+    def serialize_attrs(self) -> str:
+        """Serialize the user attributes."""
+        if not self.attributes:
+            return "{}"
+
+        return json.dumps(self.attributes)

mysql_shell/models/cluster.py

@@ -0,0 +1,57 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from enum import Enum
+
+
+class ClusterSetStatus(str, Enum):
+    """MySQL cluster-set statuses.
+
+    https://dev.mysql.com/doc/mysql-shell/8.0/en/innodb-clusterset-status.html
+    """
+
+    HEALTHY = "HEALTHY"
+    AVAILABLE = "AVAILABLE"
+    UNAVAILABLE = "UNAVAILABLE"
+
+
+class ClusterGlobalStatus(str, Enum):
+    """MySQL cluster statuses within a cluster-set context.
+
+    https://dev.mysql.com/doc/mysql-shell/8.0/en/innodb-clusterset-status.html
+    """
+
+    OK = "OK"
+    OK_NOT_REPLICATING = "OK_NOT_REPLICATING"
+    OK_NOT_CONSISTENT = "OK_NOT_CONSISTENT"
+    OK_MISCONFIGURED = "OK_MISCONFIGURED"
+    NOT_OK = "NOT_OK"
+    UNKNOWN = "UNKNOWN"
+    INVALIDATED = "INVALIDATED"
+
+
+class ClusterRole(str, Enum):
+    """MySQL cluster roles."""
+
+    PRIMARY = "PRIMARY"
+    REPLICA = "REPLICA"
+
+
+class ClusterStatus(str, Enum):
+    """MySQL cluster statuses.
+
+    There is a slight discrepancy between the possible cluster statuses reported
+    on different MySQL documentation pages, this list contains the common ones across them.
+    - https://dev.mysql.com/doc/mysql-shell/8.0/en/innodb-clusterset-status.html
+    - https://dev.mysql.com/doc/mysql-shell/8.0/en/monitoring-innodb-cluster.html
+    """
+
+    OK = "OK"
+    OK_PARTIAL = "OK_PARTIAL"
+    OK_NO_TOLERANCE = "OK_NO_TOLERANCE"
+    OK_NO_TOLERANCE_PARTIAL = "OK_NO_TOLERANCE_PARTIAL"
+    NO_QUORUM = "NO_QUORUM"
+    OFFLINE = "OFFLINE"
+    ERROR = "ERROR"
+    UNREACHABLE = "UNREACHABLE"
+    UNKNOWN = "UNKNOWN"

mysql_shell/models/connection.py

@@ -0,0 +1,22 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ConnectionDetails:
+    """MySQL connection details."""
+
+    username: str
+    password: str
+    host: str = ""
+    port: str = ""
+    socket: str = ""
+
+    def __post_init__(self) -> None:
+        """Validates that the connection details are correct."""
+        if (not self.host or not self.port) and not self.socket:
+            raise ValueError("Connection details must not be empty")
+        if (self.host or self.port) and self.socket:
+            raise ValueError("Connection details must not be state both TCP and socket values")

mysql_shell/models/instance.py

@@ -0,0 +1,27 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from enum import Enum
+
+
+class InstanceRole(str, Enum):
+    """MySQL instance roles."""
+
+    PRIMARY = "PRIMARY"
+    SECONDARY = "SECONDARY"
+
+
+class InstanceState(str, Enum):
+    """MySQL instance states.
+
+    There is a slight discrepancy between the possible instance states reported
+    by different MySQL mechanisms, this list contains the common ones across them.
+    - https://dev.mysql.com/doc/refman/8.0/en/group-replication-server-states.html
+    - https://dev.mysql.com/doc/mysql-shell/8.0/en/monitoring-innodb-cluster.html
+    """
+
+    ONLINE = "ONLINE"
+    RECOVERING = "RECOVERING"
+    OFFLINE = "OFFLINE"
+    ERROR = "ERROR"
+    UNREACHABLE = "UNREACHABLE"

mysql_shell/models/statement.py

@@ -0,0 +1,30 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+from enum import Enum
+
+
+class LogType(str, Enum):
+    """MySQL log types.
+
+    https://dev.mysql.com/doc/refman/8.0/en/flush.html#flush-logs
+    """
+
+    BINARY = "BINARY"
+    ENGINE = "ENGINE"
+    ERROR = "ERROR"
+    GENERAL = "GENERAL"
+    RELAY = "RELAY"
+    SLOW = "SLOW"
+
+
+class VariableScope(str, Enum):
+    """MySQL variable scopes.
+
+    https://dev.mysql.com/doc/refman/8.0/en/set-variable.html
+    """
+
+    GLOBAL = "GLOBAL"
+    SESSION = "SESSION"
+    PERSIST = "PERSIST"
+    PERSIST_ONLY = "PERSIST_ONLY"

mysql_shell_client-0.6.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: mysql-shell-client
+Version: 0.6.0
+Summary: Python client for MySQL Shell
+License-Expression: Apache-2.0
+License-File: LICENSE
+Author: Sinclert Perez
+Author-email: sinclert.perez@canonical.com
+Maintainer: Canonical Data Platform
+Maintainer-email: data-platform@lists.launchpad.net
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: format
+Provides-Extra: lint
+Provides-Extra: test
+Requires-Dist: codespell (>=2.3,<3.0) ; extra == "lint"
+Requires-Dist: coverage (>=7.6,<8.0) ; extra == "test"
+Requires-Dist: pytest (>=8.3,<9.0) ; extra == "test"
+Requires-Dist: ruff (>=0.9,<1.0) ; extra == "format"
+Requires-Dist: ruff (>=0.9,<1.0) ; extra == "lint"
+Project-URL: Changelog, https://github.com/canonical/mysql-shell-client/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/canonical/mysql-shell-client
+Project-URL: Issues, https://github.com/canonical/mysql-shell-client/issues
+Description-Content-Type: text/markdown
+
+# MySQL Shell Python client
+
+[![CI/CD Status][ci-status-badge]][ci-status-link]
+[![Coverage Status][cov-status-badge]][cov-status-link]
+[![Apache license][apache-license-badge]][apache-license-link]
+
+MySQL Shell is an advanced client for MySQL Server that allow system administrator to perform both
+cluster and instance level operations, using a single binary.
+
+This project provides a Python client to perform the most common set of operations,
+in addition to a set of predefined queries to cover most of the common use-cases.
+
+## 🧑‍💻 Usage
+
+1. Install the package from PyPi:
+   ```shell
+   pip install mysql-shell-client
+   ```
+
+2. Import and build the executors:
+   ```python
+   from mysql_shell.executors import LocalExecutor
+   from mysql_shell.models import ConnectionDetails
+
+   cluster_conn = ConnectionDetails(
+       username="...",
+       password="...",
+       host="...",
+       port="...",
+   )
+   instance_conn = ConnectionDetails(
+       username="...",
+       password="...",
+       host="...",
+       port="...",
+   )
+   
+   cluster_executor = LocalExecutor(cluster_conn, "mysqlsh")
+   instance_executor = LocalExecutor(instance_conn, "mysqlsh")
+   ```
+
+3. Import and build the query builders **[optional]**:
+   ```python
+   from mysql_shell.builders import CharmLockingQueryBuilder
+
+   # This is just an example
+   builder = CharmLockingQueryBuilder("mysql", "locking")
+   query = builder.build_table_creation_query()
+   rows = instance_executor.execute_sql(query)
+   ```
+
+4. Import and build the clients:
+   ```python
+   from mysql_shell.clients import MySQLClusterClient, MySQLInstanceClient
+   
+   cluster_client = MySQLClusterClient(cluster_executor)
+   instance_client = MySQLInstanceClient(instance_executor)
+   ```
+
+
+## 🔧 Development
+
+### Dependencies
+In order to install all the development packages:
+
+```shell
+poetry install --all-extras
+```
+
+### Linting
+All Python files are linted using [Ruff][docs-ruff], to run it:
+
+```shell
+tox -e lint
+```
+
+### Testing
+Project testing is performed using [Pytest][docs-pytest], to run them:
+
+```shell
+tox -e unit
+```
+
+```shell
+export MYSQL_DATABASE="test"
+export MYSQL_USERNAME="root"
+export MYSQL_PASSWORD="root_pass"
+export MYSQL_SHELL_PATH="mysqlsh"
+
+podman-compose -f compose/mysql-8.0.yaml up --detach && tox -e integration
+podman-compose -f compose/mysql-8.0.yaml down
+```
+
+### Release
+Commits can be tagged to create releases of the package, in order to do so:
+
+1. Bump up the version within the `pyproject.toml` file.
+2. Add a new section to the `CHANGELOG.md`.
+3. Commit + push the changes.
+4. Trigger the [release workflow][github-workflows].
+
+
+[apache-license-badge]: https://img.shields.io/badge/License-Apache%202.0-blue.svg
+[apache-license-link]: https://github.com/canonical/mysql-shell-client/blob/main/LICENSE
+[ci-status-badge]: https://github.com/canonical/mysql-shell-client/actions/workflows/ci.yaml/badge.svg?branch=main
+[ci-status-link]: https://github.com/canonical/mysql-shell-client/actions/workflows/ci.yaml?query=branch%3Amain
+[cov-status-badge]: https://codecov.io/gh/canonical/mysql-shell-client/branch/main/graph/badge.svg
+[cov-status-link]: https://codecov.io/gh/canonical/mysql-shell-client
+
+[docs-pytest]: https://docs.pytest.org/en/latest/#
+[docs-ruff]: https://docs.astral.sh/ruff/
+[github-workflows]: https://github.com/canonical/mysql-shell-client/actions/workflows/release.yaml
+

mysql_shell_client-0.6.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+mysql_shell/__init__.py,sha256=MfYnXwgdAN0FdILtYZBo-gR6xpsDs9nBBVUI120R4co,169
+mysql_shell/builders/__init__.py,sha256=hw7c-Z3DGnL_DnjU3zzj1wnQ73KmRWCYTQgu090GllU,173
+mysql_shell/builders/authorization/__init__.py,sha256=mKu4sNa1L65d1gpzokxdHmGVGJOlUA8FufTOAus90-w,173
+mysql_shell/builders/authorization/base.py,sha256=ueo_Wo6JsL9UW1JEUit5tJabLxKZok_Jgxdm3sElNEs,768
+mysql_shell/builders/authorization/charm.py,sha256=PRglXU2UKhzo3tWdPLVJbTCBeJaEc8aVNRNndrrgFdU,7336
+mysql_shell/builders/locking/__init__.py,sha256=Qy1Q_YDEDGAs7q9pmCWtZpcIi9P_C_3OIqUyNaroITM,161
+mysql_shell/builders/locking/base.py,sha256=bZj943m_uvmHTtlBS4-q1mDN9u9b0vNXXSV6eYhMsKw,880
+mysql_shell/builders/locking/charm.py,sha256=JaAae3CTxzgnZMbBx2l5BmA_4mxy8HHBggjnlIxTQ2U,3267
+mysql_shell/builders/logging/__init__.py,sha256=zM_LjTJlOTNlgfli1CJFvKiuo0OqSgtUcyEUITgyXJg,161
+mysql_shell/builders/logging/base.py,sha256=mFjOHl3iMah11Pddk95ap7QrozpKLRgEbV3qcUJy0ns,413
+mysql_shell/builders/logging/charm.py,sha256=A6PelFVHxiTDOUnQ-vjlPwCGIlvokKN-3YcD_iAhOWY,1132
+mysql_shell/builders/quoting.py,sha256=mhVo2md38m3ok9kn12lSDjl2-V_SKp-LWyvr3uSOSPo,1934
+mysql_shell/clients/__init__.py,sha256=D4y63dGJUsq7Pklqo_vaijhVqdp640X-6H9eZDS8KCc,122
+mysql_shell/clients/cluster.py,sha256=IIkumRhAyMhxjH7vT5cNHLLQi8djxVz8sxyzrPSQT5w,15024
+mysql_shell/clients/instance.py,sha256=Vy_yhwxJ6T4ChiC4IiP9TVer8mCzC5A7O6ENyzHJuv8,18419
+mysql_shell/executors/__init__.py,sha256=mplYyzgA-22b7GNjVUEmEiI4lN0tgIl9qlgNHe3tRPI,139
+mysql_shell/executors/base.py,sha256=rsvOLSWvlxtYcVDq_FeNoEBphixv-iW0Fa1OdWqgG6M,1089
+mysql_shell/executors/errors/__init__.py,sha256=zAJdgtRRGGcdMJg-5nNy3iS7FcGKyCstbQko0QT4n5k,111
+mysql_shell/executors/errors/runtime.py,sha256=er7m8HECfeAkMgT7UI0TvWK9hh56MxL0meO291GqM0c,382
+mysql_shell/executors/local.py,sha256=9wrL7o_vopZYtTEgwSCaeL949qJSFpo-u6oOUvOuDqU,5858
+mysql_shell/models/__init__.py,sha256=erB_kCQjGfKik32UTcm_GUndZVCefPepKe60SkE99cU,196
+mysql_shell/models/account.py,sha256=u8DGcq2SgxYxZKqmykQaSmcxTiO1yQt9yWMg1f_TtDw,1101
+mysql_shell/models/cluster.py,sha256=rA1V7lohODVaJvvSEQKr325tz_eiafN5LsPO-ZH6ChQ,1546
+mysql_shell/models/connection.py,sha256=YTxJP_49TWxQR6QZjP_u8OxHfPOubCEIHkckU38Fbt4,665
+mysql_shell/models/instance.py,sha256=br2mvraBrMqigsUGb794n5XUybDD5e9eOVJEujyHd2k,745
+mysql_shell/models/statement.py,sha256=rm9nf-qKlRc2snVyw2KgISdFuhdH7Kvext-7KQbhRZI,591
+mysql_shell_client-0.6.0.dist-info/METADATA,sha256=8lUDCYLBPpRIyL1hufg2-vQsfNabBpcciemzo87UvHY,4645
+mysql_shell_client-0.6.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+mysql_shell_client-0.6.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+mysql_shell_client-0.6.0.dist-info/RECORD,,

mysql_shell_client-0.6.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.1
+Root-Is-Purelib: true
+Tag: py3-none-any