hiramedbc 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. hiramedbc-0.1.1/.gitignore +13 -0
  2. hiramedbc-0.1.1/LICENSE +21 -0
  3. hiramedbc-0.1.1/PKG-INFO +182 -0
  4. hiramedbc-0.1.1/README.md +163 -0
  5. hiramedbc-0.1.1/config/config.example.json +31 -0
  6. hiramedbc-0.1.1/pyproject.toml +49 -0
  7. hiramedbc-0.1.1/src/hiramedbc/__init__.py +11 -0
  8. hiramedbc-0.1.1/src/hiramedbc/__main__.py +3 -0
  9. hiramedbc-0.1.1/src/hiramedbc/cli.py +149 -0
  10. hiramedbc-0.1.1/src/hiramedbc/commands/__init__.py +0 -0
  11. hiramedbc-0.1.1/src/hiramedbc/commands/add.py +334 -0
  12. hiramedbc-0.1.1/src/hiramedbc/commands/common.py +211 -0
  13. hiramedbc-0.1.1/src/hiramedbc/commands/config.py +36 -0
  14. hiramedbc-0.1.1/src/hiramedbc/commands/connect.py +41 -0
  15. hiramedbc-0.1.1/src/hiramedbc/commands/doctor.py +278 -0
  16. hiramedbc-0.1.1/src/hiramedbc/commands/dump.py +110 -0
  17. hiramedbc-0.1.1/src/hiramedbc/commands/edit.py +22 -0
  18. hiramedbc-0.1.1/src/hiramedbc/commands/init.py +86 -0
  19. hiramedbc-0.1.1/src/hiramedbc/commands/list.py +54 -0
  20. hiramedbc-0.1.1/src/hiramedbc/commands/remove.py +36 -0
  21. hiramedbc-0.1.1/src/hiramedbc/commands/version.py +6 -0
  22. hiramedbc-0.1.1/src/hiramedbc/config/__init__.py +0 -0
  23. hiramedbc-0.1.1/src/hiramedbc/config/manager.py +139 -0
  24. hiramedbc-0.1.1/src/hiramedbc/config/schema.py +209 -0
  25. hiramedbc-0.1.1/src/hiramedbc/config/validator.py +62 -0
  26. hiramedbc-0.1.1/src/hiramedbc/context.py +43 -0
  27. hiramedbc-0.1.1/src/hiramedbc/docker/__init__.py +0 -0
  28. hiramedbc-0.1.1/src/hiramedbc/docker/image.py +86 -0
  29. hiramedbc-0.1.1/src/hiramedbc/docker/option_file.py +79 -0
  30. hiramedbc-0.1.1/src/hiramedbc/docker/runner.py +358 -0
  31. hiramedbc-0.1.1/src/hiramedbc/prompts/__init__.py +0 -0
  32. hiramedbc-0.1.1/src/hiramedbc/prompts/auth.py +133 -0
  33. hiramedbc-0.1.1/src/hiramedbc/secrets/__init__.py +0 -0
  34. hiramedbc-0.1.1/src/hiramedbc/secrets/keychain.py +81 -0
  35. hiramedbc-0.1.1/src/hiramedbc/utils/__init__.py +0 -0
  36. hiramedbc-0.1.1/src/hiramedbc/utils/aliases.py +77 -0
  37. hiramedbc-0.1.1/src/hiramedbc/utils/console.py +30 -0
  38. hiramedbc-0.1.1/src/hiramedbc/utils/errors.py +41 -0
  39. hiramedbc-0.1.1/src/hiramedbc/utils/platform.py +84 -0
  40. hiramedbc-0.1.1/tests/__init__.py +0 -0
  41. hiramedbc-0.1.1/tests/cli_env.py +59 -0
  42. hiramedbc-0.1.1/tests/conftest.py +85 -0
  43. hiramedbc-0.1.1/tests/fake_docker.py +79 -0
  44. hiramedbc-0.1.1/tests/test_aliases.py +50 -0
  45. hiramedbc-0.1.1/tests/test_cli_args.py +69 -0
  46. hiramedbc-0.1.1/tests/test_cmd_connect.py +214 -0
  47. hiramedbc-0.1.1/tests/test_cmd_dump.py +158 -0
  48. hiramedbc-0.1.1/tests/test_cmd_manage.py +527 -0
  49. hiramedbc-0.1.1/tests/test_cmd_setup.py +264 -0
  50. hiramedbc-0.1.1/tests/test_config_manager.py +143 -0
  51. hiramedbc-0.1.1/tests/test_config_schema.py +178 -0
  52. hiramedbc-0.1.1/tests/test_docker_image.py +146 -0
  53. hiramedbc-0.1.1/tests/test_docker_runner.py +178 -0
  54. hiramedbc-0.1.1/tests/test_docker_runner_cleanup.py +140 -0
  55. hiramedbc-0.1.1/tests/test_docker_runner_rm.py +85 -0
  56. hiramedbc-0.1.1/tests/test_keychain.py +66 -0
  57. hiramedbc-0.1.1/tests/test_option_file.py +60 -0
  58. hiramedbc-0.1.1/tests/test_platform.py +52 -0
  59. hiramedbc-0.1.1/tests/test_prompts_auth.py +111 -0
@@ -0,0 +1,13 @@
1
+ # Local config used during development via HIRAMEDBC_CONFIG
2
+ /config/config.json
3
+
4
+ .venv/
5
+ __pycache__/
6
+ .pytest_cache/
7
+ build/
8
+ dist/
9
+ *.egg-info/
10
+ .coverage
11
+
12
+ # Design notes for Claude (kept local only)
13
+ /docs/claude/**/*.md
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 LLC.imaima
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,182 @@
1
+ Metadata-Version: 2.5
2
+ Name: hiramedbc
3
+ Version: 0.1.1
4
+ Summary: A CLI for switching between MySQL client versions using the official MySQL Docker image
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Classifier: Environment :: Console
8
+ Classifier: Operating System :: MacOS
9
+ Classifier: Operating System :: Microsoft :: Windows
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Topic :: Database
12
+ Requires-Python: >=3.12
13
+ Requires-Dist: keyring>=25
14
+ Requires-Dist: pydantic<3,>=2.7
15
+ Requires-Dist: questionary<3,>=2.1
16
+ Requires-Dist: rich>=13
17
+ Requires-Dist: typer<1,>=0.29
18
+ Description-Content-Type: text/markdown
19
+
20
+ # HirameDBC
21
+
22
+ **English** | [日本語](README.ja.md)
23
+
24
+ A CLI that runs the official MySQL Docker image as disposable containers, so you can switch between multiple versions of the MySQL client tools (`mysql` / `mysqldump`). Works on macOS and Windows.
25
+
26
+ - No local MySQL client installation required.
27
+ - Mix and match connections and MySQL versions freely (`hirame c 5.7 legacy` / `hirame c 8.4 production`).
28
+ - Choose where each password lives: enter it every time you connect, save it in the OS keychain (macOS Keychain / Windows Credential Manager), or save it in plaintext in the config file.
29
+ - Credentials are never passed as command-line arguments or environment variables. They reach the container as a MySQL option file.
30
+
31
+ > Install, upgrade, and uninstall with the **package name `hiramedbc`**. For everyday use, run the **command `hirame`**.
32
+
33
+ ## Requirements
34
+
35
+ | Requirement | How to get it |
36
+ |---|---|
37
+ | [uv](https://docs.astral.sh/uv/) | macOS: `brew install uv` / Windows: `winget install astral-sh.uv` |
38
+ | A Docker-compatible runtime (the `docker` command must work) | macOS: Docker Desktop / OrbStack / Colima / Rancher Desktop<br>Windows: Docker Desktop / Rancher Desktop (requires WSL2) |
39
+ | Network access to your MySQL server | - |
40
+
41
+ You do not need to install Python or git separately (uv provides Python). Docker Desktop may require a paid subscription depending on your organization's size. Check the current terms before adopting it.
42
+
43
+ ## Installation
44
+
45
+ ```bash
46
+ uv tool install hiramedbc # Install
47
+ uv tool install hiramedbc==0.1.0 # Install a specific version
48
+ uv tool upgrade hiramedbc # Upgrade
49
+ uv tool uninstall hiramedbc # Uninstall
50
+ uvx --from hiramedbc hirame # Run once without installing
51
+ ```
52
+
53
+ If `hirame` is not found right after installation, run `uv tool update-shell` and then open a new terminal.
54
+
55
+ ## Getting started
56
+
57
+ ```bash
58
+ hirame init # Environment check → create config file → add connections → pull images
59
+ hirame c production # Connect
60
+ ```
61
+
62
+ `init` runs the following steps in order. If Docker is unavailable, it prints a warning and still continues through the configuration steps.
63
+
64
+ 1. Environment check (same as `hirame doctor`)
65
+ 2. Create the config file (you are asked for the default MySQL version)
66
+ 3. Add connections (you can add several in a row)
67
+ 4. Choose whether to pull the images for the added connections now
68
+
69
+ ## Commands
70
+
71
+ | Command | Alias | Description |
72
+ |---|---|---|
73
+ | `hirame init` | - | Initial setup |
74
+ | `hirame connect [VERSION] ALIAS [DATABASE]` | `c` | Connect to a database |
75
+ | `hirame add [ALIAS]` | `a` | Add a connection (interactive) |
76
+ | `hirame list` | `ls` | List saved connections |
77
+ | `hirame edit ALIAS` | `e` | Edit a connection (interactive; press Enter to keep the current value) |
78
+ | `hirame remove ALIAS [-y]` | `rm` | Remove a connection and its password from the keychain (`-y` skips confirmation) |
79
+ | `hirame dump [VERSION] ALIAS DATABASE OUTPUT [-f] [-- EXTRA_OPTIONS_AND_TABLES]` | `d` | Create a dump with `mysqldump` (`-f` skips the overwrite confirmation) |
80
+ | `hirame config path` | - | Show the path of the config file in use |
81
+ | `hirame config edit` | - | Open the config file in your editor |
82
+ | `hirame doctor [--pull [VERSION...]] [--clean]` | `dr` | Check the environment, pre-pull images, and remove stopped leftover containers |
83
+ | `hirame version` | `v` | Show the version |
84
+
85
+ `connect` is optional: `hirame production` / `hirame 8.4 production` are the same as `hirame connect ...`. Every command accepts `--config <PATH>`.
86
+
87
+ ### Examples
88
+
89
+ ```bash
90
+ hirame c production # Connect with the configured version
91
+ hirame c 8.4 production my_db # Specify the version and database
92
+ hirame c production < script.sql # Pipe in an SQL file (save the username in the connection first)
93
+
94
+ hirame d production my_db backup.sql # Dump
95
+ hirame d production my_db - > backup.sql # Dump to stdout
96
+ hirame d production my_db backup.sql -- --no-data users # Pass options and table names to mysqldump
97
+
98
+ hirame doctor --pull # Pull images for every version used in the config
99
+ hirame doctor --pull 5.7 8.4 # Pull specific versions
100
+ ```
101
+
102
+ ### How the version is chosen
103
+
104
+ 1. The `VERSION` command argument
105
+ 2. The connection's `version`
106
+ 3. `defaults.version` in the config file
107
+
108
+ When connecting, `hirame` shows which version it uses and where it came from (argument / connection / default). If the first argument is version-like (`8`, `8.4`, `8.0.36`, and so on), it is treated as a version; otherwise it is treated as a connection name. As a result, version-like names and command names (`list`, `ls`, and so on) cannot be used as connection names.
109
+
110
+ ## Credentials
111
+
112
+ The username is either "saved" or "ask every time". The password can be "ask every time", saved in the OS keychain, or saved in plaintext in the config file.
113
+
114
+ | Username | Password | Typical use | Prompted on connect |
115
+ |---|---|---|---|
116
+ | Saved | Saved (config file) | Local development where you edit the password often | Nothing |
117
+ | Saved | Saved (keychain) | Shared development account | Nothing |
118
+ | Saved | Ask every time | You prefer not to store the password, or it rotates regularly | Password only |
119
+ | Ask every time | Ask every time | Personal accounts, or issued temporary accounts | Both |
120
+
121
+ - For production connections, you can choose not to save the password and enter it every time instead. When adding a connection, saving the password defaults to no.
122
+ - To skip saved values for a single run, pass `--ask-user` (which also prompts for the password) or `--ask-password`.
123
+ - A password saved in the config file is stored in plaintext. Only use it on a machine where just you can read the file (on macOS the file is created with 0600 permissions; `hirame doctor` warns if others can read it).
124
+ - To change a password saved in the config file, edit it with `hirame config edit` (or re-run `hirame edit`).
125
+ - `list` never shows password values. It only shows where each password is stored (keychain / config file).
126
+ - On macOS, the first keychain access shows a permission dialog. Choose "Always Allow". The dialog may appear again after uv updates Python.
127
+
128
+ ## Config file
129
+
130
+ | Priority | Location |
131
+ |---|---|
132
+ | 1 | `--config <PATH>` |
133
+ | 2 | The `HIRAMEDBC_CONFIG` environment variable |
134
+ | 3 | `~/.hiramedbc/config.json` (Windows: `%USERPROFILE%\.hiramedbc\config.json`) |
135
+
136
+ ```json
137
+ {
138
+ "connections": {
139
+ "development": { "host": "dev-db.example.com", "port": 3306, "user": "app_user", "password": "keyring", "version": "8.0" },
140
+ "production": {
141
+ "host": "prod-db.example.com", "port": 3306, "user": "", "password": "", "version": "8.4",
142
+ "ssl": { "mode": "VERIFY_IDENTITY", "ca": "/path/to/ca.pem" }
143
+ }
144
+ },
145
+ "defaults": { "version": "8.4" }
146
+ }
147
+ ```
148
+
149
+ | Key | Description |
150
+ |---|---|
151
+ | `host` | Required. The MySQL server host |
152
+ | `port` | Defaults to `3306` |
153
+ | `user` | A value means saved. Empty means ask every time |
154
+ | `password` | Empty means ask every time. `"keyring"` reads the password from the keychain. Any other value is used as the password itself (plaintext). The literal password `keyring` therefore cannot be saved in the config file |
155
+ | `version` | The MySQL version (image tag) for this connection |
156
+ | `ssl` | Optional. `mode` (`DISABLED` / `PREFERRED` / `REQUIRED` / `VERIFY_CA` / `VERIFY_IDENTITY`) and `ca` / `cert` / `key` (paths on the host). Certificates are mounted into the container read-only |
157
+ | `defaults.version` | The default version shared by all connections |
158
+
159
+ You cannot combine an ask-every-time username with a saved password, because passwords are stored per connection. On macOS, the config file is created with owner-only read/write permissions (0600).
160
+
161
+ ## Notes
162
+
163
+ - **Connecting to MySQL on the host machine**: Inside a container, `localhost` / `127.0.0.1` refers to the container itself. Use `host.docker.internal` instead.
164
+ - **Apple Silicon**: Versions without an arm64 build of the official image (such as 5.7) run under amd64 emulation. They do not work if Rosetta / QEMU is disabled in your runtime (check with `hirame doctor`).
165
+ - **Container cleanup**: The container is removed when the session ends, on error, and on Ctrl+C. Containers left behind (for example, when a terminal is force-closed) are detected by `hirame doctor`. Stopped ones can be removed with `hirame doctor --clean`. Leftover containers that are still running might be in use from another terminal, so they are not removed automatically; their names are shown instead. If they are not in use, remove them with `docker rm -f <name>`.
166
+ - **Dump files**: Dumps are saved with owner-only read/write permissions. If a dump fails or is interrupted, any existing file is left unchanged. Arguments after `--` are passed as `mysqldump ... <database> <extra arguments>` (table names are allowed). Extra arguments without `--` cause an error.
167
+ - **Unsupported password characters**: Passwords that contain both double quotes (`"`) and single quotes (`'`), or that contain a NUL character, are not supported (they cannot be represented safely in a MySQL option file).
168
+
169
+ ## Development
170
+
171
+ ```bash
172
+ uv sync # Install dependencies
173
+ HIRAMEDBC_CONFIG=./config/config.json uv run hirame ls # Run with the in-repo config (config/config.json is gitignored)
174
+ uv run pytest # Run tests
175
+ uv run ruff check . && uv run ruff format --check .
176
+ ```
177
+
178
+ - Releases: Pushing a `v*` tag publishes to PyPI through GitHub Actions Trusted Publishing (no API token is stored in the repository).
179
+
180
+ ## License
181
+
182
+ [MIT](LICENSE)
@@ -0,0 +1,163 @@
1
+ # HirameDBC
2
+
3
+ **English** | [日本語](README.ja.md)
4
+
5
+ A CLI that runs the official MySQL Docker image as disposable containers, so you can switch between multiple versions of the MySQL client tools (`mysql` / `mysqldump`). Works on macOS and Windows.
6
+
7
+ - No local MySQL client installation required.
8
+ - Mix and match connections and MySQL versions freely (`hirame c 5.7 legacy` / `hirame c 8.4 production`).
9
+ - Choose where each password lives: enter it every time you connect, save it in the OS keychain (macOS Keychain / Windows Credential Manager), or save it in plaintext in the config file.
10
+ - Credentials are never passed as command-line arguments or environment variables. They reach the container as a MySQL option file.
11
+
12
+ > Install, upgrade, and uninstall with the **package name `hiramedbc`**. For everyday use, run the **command `hirame`**.
13
+
14
+ ## Requirements
15
+
16
+ | Requirement | How to get it |
17
+ |---|---|
18
+ | [uv](https://docs.astral.sh/uv/) | macOS: `brew install uv` / Windows: `winget install astral-sh.uv` |
19
+ | A Docker-compatible runtime (the `docker` command must work) | macOS: Docker Desktop / OrbStack / Colima / Rancher Desktop<br>Windows: Docker Desktop / Rancher Desktop (requires WSL2) |
20
+ | Network access to your MySQL server | - |
21
+
22
+ You do not need to install Python or git separately (uv provides Python). Docker Desktop may require a paid subscription depending on your organization's size. Check the current terms before adopting it.
23
+
24
+ ## Installation
25
+
26
+ ```bash
27
+ uv tool install hiramedbc # Install
28
+ uv tool install hiramedbc==0.1.0 # Install a specific version
29
+ uv tool upgrade hiramedbc # Upgrade
30
+ uv tool uninstall hiramedbc # Uninstall
31
+ uvx --from hiramedbc hirame # Run once without installing
32
+ ```
33
+
34
+ If `hirame` is not found right after installation, run `uv tool update-shell` and then open a new terminal.
35
+
36
+ ## Getting started
37
+
38
+ ```bash
39
+ hirame init # Environment check → create config file → add connections → pull images
40
+ hirame c production # Connect
41
+ ```
42
+
43
+ `init` runs the following steps in order. If Docker is unavailable, it prints a warning and still continues through the configuration steps.
44
+
45
+ 1. Environment check (same as `hirame doctor`)
46
+ 2. Create the config file (you are asked for the default MySQL version)
47
+ 3. Add connections (you can add several in a row)
48
+ 4. Choose whether to pull the images for the added connections now
49
+
50
+ ## Commands
51
+
52
+ | Command | Alias | Description |
53
+ |---|---|---|
54
+ | `hirame init` | - | Initial setup |
55
+ | `hirame connect [VERSION] ALIAS [DATABASE]` | `c` | Connect to a database |
56
+ | `hirame add [ALIAS]` | `a` | Add a connection (interactive) |
57
+ | `hirame list` | `ls` | List saved connections |
58
+ | `hirame edit ALIAS` | `e` | Edit a connection (interactive; press Enter to keep the current value) |
59
+ | `hirame remove ALIAS [-y]` | `rm` | Remove a connection and its password from the keychain (`-y` skips confirmation) |
60
+ | `hirame dump [VERSION] ALIAS DATABASE OUTPUT [-f] [-- EXTRA_OPTIONS_AND_TABLES]` | `d` | Create a dump with `mysqldump` (`-f` skips the overwrite confirmation) |
61
+ | `hirame config path` | - | Show the path of the config file in use |
62
+ | `hirame config edit` | - | Open the config file in your editor |
63
+ | `hirame doctor [--pull [VERSION...]] [--clean]` | `dr` | Check the environment, pre-pull images, and remove stopped leftover containers |
64
+ | `hirame version` | `v` | Show the version |
65
+
66
+ `connect` is optional: `hirame production` / `hirame 8.4 production` are the same as `hirame connect ...`. Every command accepts `--config <PATH>`.
67
+
68
+ ### Examples
69
+
70
+ ```bash
71
+ hirame c production # Connect with the configured version
72
+ hirame c 8.4 production my_db # Specify the version and database
73
+ hirame c production < script.sql # Pipe in an SQL file (save the username in the connection first)
74
+
75
+ hirame d production my_db backup.sql # Dump
76
+ hirame d production my_db - > backup.sql # Dump to stdout
77
+ hirame d production my_db backup.sql -- --no-data users # Pass options and table names to mysqldump
78
+
79
+ hirame doctor --pull # Pull images for every version used in the config
80
+ hirame doctor --pull 5.7 8.4 # Pull specific versions
81
+ ```
82
+
83
+ ### How the version is chosen
84
+
85
+ 1. The `VERSION` command argument
86
+ 2. The connection's `version`
87
+ 3. `defaults.version` in the config file
88
+
89
+ When connecting, `hirame` shows which version it uses and where it came from (argument / connection / default). If the first argument is version-like (`8`, `8.4`, `8.0.36`, and so on), it is treated as a version; otherwise it is treated as a connection name. As a result, version-like names and command names (`list`, `ls`, and so on) cannot be used as connection names.
90
+
91
+ ## Credentials
92
+
93
+ The username is either "saved" or "ask every time". The password can be "ask every time", saved in the OS keychain, or saved in plaintext in the config file.
94
+
95
+ | Username | Password | Typical use | Prompted on connect |
96
+ |---|---|---|---|
97
+ | Saved | Saved (config file) | Local development where you edit the password often | Nothing |
98
+ | Saved | Saved (keychain) | Shared development account | Nothing |
99
+ | Saved | Ask every time | You prefer not to store the password, or it rotates regularly | Password only |
100
+ | Ask every time | Ask every time | Personal accounts, or issued temporary accounts | Both |
101
+
102
+ - For production connections, you can choose not to save the password and enter it every time instead. When adding a connection, saving the password defaults to no.
103
+ - To skip saved values for a single run, pass `--ask-user` (which also prompts for the password) or `--ask-password`.
104
+ - A password saved in the config file is stored in plaintext. Only use it on a machine where just you can read the file (on macOS the file is created with 0600 permissions; `hirame doctor` warns if others can read it).
105
+ - To change a password saved in the config file, edit it with `hirame config edit` (or re-run `hirame edit`).
106
+ - `list` never shows password values. It only shows where each password is stored (keychain / config file).
107
+ - On macOS, the first keychain access shows a permission dialog. Choose "Always Allow". The dialog may appear again after uv updates Python.
108
+
109
+ ## Config file
110
+
111
+ | Priority | Location |
112
+ |---|---|
113
+ | 1 | `--config <PATH>` |
114
+ | 2 | The `HIRAMEDBC_CONFIG` environment variable |
115
+ | 3 | `~/.hiramedbc/config.json` (Windows: `%USERPROFILE%\.hiramedbc\config.json`) |
116
+
117
+ ```json
118
+ {
119
+ "connections": {
120
+ "development": { "host": "dev-db.example.com", "port": 3306, "user": "app_user", "password": "keyring", "version": "8.0" },
121
+ "production": {
122
+ "host": "prod-db.example.com", "port": 3306, "user": "", "password": "", "version": "8.4",
123
+ "ssl": { "mode": "VERIFY_IDENTITY", "ca": "/path/to/ca.pem" }
124
+ }
125
+ },
126
+ "defaults": { "version": "8.4" }
127
+ }
128
+ ```
129
+
130
+ | Key | Description |
131
+ |---|---|
132
+ | `host` | Required. The MySQL server host |
133
+ | `port` | Defaults to `3306` |
134
+ | `user` | A value means saved. Empty means ask every time |
135
+ | `password` | Empty means ask every time. `"keyring"` reads the password from the keychain. Any other value is used as the password itself (plaintext). The literal password `keyring` therefore cannot be saved in the config file |
136
+ | `version` | The MySQL version (image tag) for this connection |
137
+ | `ssl` | Optional. `mode` (`DISABLED` / `PREFERRED` / `REQUIRED` / `VERIFY_CA` / `VERIFY_IDENTITY`) and `ca` / `cert` / `key` (paths on the host). Certificates are mounted into the container read-only |
138
+ | `defaults.version` | The default version shared by all connections |
139
+
140
+ You cannot combine an ask-every-time username with a saved password, because passwords are stored per connection. On macOS, the config file is created with owner-only read/write permissions (0600).
141
+
142
+ ## Notes
143
+
144
+ - **Connecting to MySQL on the host machine**: Inside a container, `localhost` / `127.0.0.1` refers to the container itself. Use `host.docker.internal` instead.
145
+ - **Apple Silicon**: Versions without an arm64 build of the official image (such as 5.7) run under amd64 emulation. They do not work if Rosetta / QEMU is disabled in your runtime (check with `hirame doctor`).
146
+ - **Container cleanup**: The container is removed when the session ends, on error, and on Ctrl+C. Containers left behind (for example, when a terminal is force-closed) are detected by `hirame doctor`. Stopped ones can be removed with `hirame doctor --clean`. Leftover containers that are still running might be in use from another terminal, so they are not removed automatically; their names are shown instead. If they are not in use, remove them with `docker rm -f <name>`.
147
+ - **Dump files**: Dumps are saved with owner-only read/write permissions. If a dump fails or is interrupted, any existing file is left unchanged. Arguments after `--` are passed as `mysqldump ... <database> <extra arguments>` (table names are allowed). Extra arguments without `--` cause an error.
148
+ - **Unsupported password characters**: Passwords that contain both double quotes (`"`) and single quotes (`'`), or that contain a NUL character, are not supported (they cannot be represented safely in a MySQL option file).
149
+
150
+ ## Development
151
+
152
+ ```bash
153
+ uv sync # Install dependencies
154
+ HIRAMEDBC_CONFIG=./config/config.json uv run hirame ls # Run with the in-repo config (config/config.json is gitignored)
155
+ uv run pytest # Run tests
156
+ uv run ruff check . && uv run ruff format --check .
157
+ ```
158
+
159
+ - Releases: Pushing a `v*` tag publishes to PyPI through GitHub Actions Trusted Publishing (no API token is stored in the repository).
160
+
161
+ ## License
162
+
163
+ [MIT](LICENSE)
@@ -0,0 +1,31 @@
1
+ {
2
+ "connections": {
3
+ "development": {
4
+ "host": "dev-db.example.com",
5
+ "port": 3306,
6
+ "user": "app_user",
7
+ "password": "keyring",
8
+ "version": "8.0"
9
+ },
10
+ "staging": {
11
+ "host": "stg-db.example.com",
12
+ "port": 3306,
13
+ "user": "app_user",
14
+ "password": ""
15
+ },
16
+ "production": {
17
+ "host": "prod-db.example.com",
18
+ "port": 3306,
19
+ "user": "",
20
+ "password": "",
21
+ "version": "8.4",
22
+ "ssl": {
23
+ "mode": "VERIFY_IDENTITY",
24
+ "ca": "/path/to/ca.pem"
25
+ }
26
+ }
27
+ },
28
+ "defaults": {
29
+ "version": "8.4"
30
+ }
31
+ }
@@ -0,0 +1,49 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "hiramedbc"
7
+ version = "0.1.1"
8
+ description = "A CLI for switching between MySQL client versions using the official MySQL Docker image"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ requires-python = ">=3.12"
13
+ dependencies = [
14
+ "typer>=0.29,<1",
15
+ "rich>=13",
16
+ "pydantic>=2.7,<3",
17
+ "keyring>=25",
18
+ "questionary>=2.1,<3",
19
+ ]
20
+ classifiers = [
21
+ "Environment :: Console",
22
+ "Operating System :: MacOS",
23
+ "Operating System :: Microsoft :: Windows",
24
+ "Programming Language :: Python :: 3",
25
+ "Topic :: Database",
26
+ ]
27
+
28
+ [project.scripts]
29
+ hirame = "hiramedbc.cli:app"
30
+
31
+ [dependency-groups]
32
+ dev = ["pytest>=8", "ruff>=0.6"]
33
+
34
+ [tool.hatch.build.targets.sdist]
35
+ include = ["src/hiramedbc", "tests", "config/config.example.json", "README.md", "LICENSE", "pyproject.toml"]
36
+
37
+ [tool.hatch.build.targets.wheel]
38
+ packages = ["src/hiramedbc"]
39
+
40
+ [tool.pytest.ini_options]
41
+ testpaths = ["tests"]
42
+ addopts = "-ra"
43
+
44
+ [tool.ruff]
45
+ line-length = 120
46
+ target-version = "py312"
47
+
48
+ [tool.ruff.lint]
49
+ select = ["E", "F", "I", "B", "UP"]
@@ -0,0 +1,11 @@
1
+ """HirameDBC: a CLI for switching between MySQL client versions running on Docker."""
2
+
3
+ from importlib.metadata import PackageNotFoundError, version
4
+
5
+ try:
6
+ __version__ = version("hiramedbc")
7
+ except PackageNotFoundError: # pragma: no cover - when run directly from the source tree
8
+ __version__ = "0.0.0+unknown"
9
+
10
+ APP_NAME = "hiramedbc"
11
+ """Name used for the config directory, the keychain service name, and the container name prefix."""
@@ -0,0 +1,3 @@
1
+ from hiramedbc.cli import app
2
+
3
+ app(prog_name="hirame")
@@ -0,0 +1,149 @@
1
+ """CLI entry point.
2
+
3
+ - Command aliases (`c` -> `connect`, etc.) are resolved in one place: HirameGroup.get_command.
4
+ - If the first argument matches no command name or alias, `connect` is inserted (`hirame production`).
5
+ - The global `--config` option is accepted before or after the subcommand.
6
+ """
7
+
8
+ from typing import Annotated, Any
9
+
10
+ import typer
11
+ from typer.core import TyperGroup
12
+
13
+ from hiramedbc.context import RAW_ARGS_KEY, AppContext
14
+ from hiramedbc.utils import console as out
15
+ from hiramedbc.utils.aliases import alias_of, resolve_command_name
16
+ from hiramedbc.utils.errors import HirameError
17
+
18
+ CONFIG_OPTION = "--config"
19
+
20
+
21
+ def normalize_args(args: list[str]) -> list[str]:
22
+ """Move `--config` to the front, and insert `connect` if the command name is omitted.
23
+
24
+ Arguments after `--` are passed to the external command untouched.
25
+ """
26
+ if "--" in args:
27
+ split = args.index("--")
28
+ head, tail = args[:split], args[split:]
29
+ else:
30
+ head, tail = list(args), []
31
+
32
+ hoisted: list[str] = []
33
+ rest: list[str] = []
34
+ i = 0
35
+ while i < len(head):
36
+ token = head[i]
37
+ if token == CONFIG_OPTION and i + 1 < len(head):
38
+ hoisted += [token, head[i + 1]]
39
+ i += 2
40
+ continue
41
+ if token.startswith(CONFIG_OPTION + "="):
42
+ hoisted.append(token)
43
+ else:
44
+ rest.append(token)
45
+ i += 1
46
+
47
+ for token in rest:
48
+ if token.startswith("-"):
49
+ if token in ("--help", "-h"):
50
+ break
51
+ continue
52
+ if resolve_command_name(token) is None:
53
+ # Insert at the front so connect options placed first, as in `hirame --ask-user prod`, still parse
54
+ rest.insert(0, "connect")
55
+ break
56
+
57
+ return hoisted + rest + tail
58
+
59
+
60
+ class HirameGroup(TyperGroup):
61
+ def get_command(self, ctx: Any, cmd_name: str) -> Any:
62
+ return super().get_command(ctx, resolve_command_name(cmd_name) or cmd_name)
63
+
64
+ def parse_args(self, ctx: Any, args: list[str]) -> list[str]:
65
+ normalized = normalize_args(args)
66
+ # click strips `--`, so keep the original order for commands (dump) that need to tell arguments after `--` apart
67
+ ctx.meta[RAW_ARGS_KEY] = list(normalized)
68
+ return super().parse_args(ctx, normalized)
69
+
70
+ def invoke(self, ctx: Any) -> Any:
71
+ try:
72
+ return super().invoke(ctx)
73
+ except HirameError as e:
74
+ out.error(e.message, e.hint)
75
+ raise typer.Exit(e.exit_code) from None
76
+
77
+
78
+ app = typer.Typer(
79
+ cls=HirameGroup,
80
+ name="hirame",
81
+ help="HirameDBC: switch between MySQL client versions using the official MySQL Docker image",
82
+ invoke_without_command=True,
83
+ add_completion=False,
84
+ context_settings={"help_option_names": ["-h", "--help"]},
85
+ rich_markup_mode="rich",
86
+ # Do not show local variables (which may contain passwords) in tracebacks. Typer defaults to False, but be explicit
87
+ pretty_exceptions_show_locals=False,
88
+ )
89
+
90
+
91
+ @app.callback()
92
+ def main(
93
+ ctx: typer.Context,
94
+ config: Annotated[
95
+ str | None,
96
+ typer.Option(
97
+ CONFIG_OPTION,
98
+ metavar="PATH",
99
+ help="Path to the config file (takes precedence over the HIRAMEDBC_CONFIG environment variable)",
100
+ ),
101
+ ] = None,
102
+ ) -> None:
103
+ if isinstance(ctx.obj, AppContext): # An AppContext with replaced dependencies was passed in (e.g. by tests)
104
+ ctx.obj.config_option = config
105
+ else:
106
+ ctx.obj = AppContext(config_option=config)
107
+ if ctx.invoked_subcommand is not None:
108
+ return
109
+ help_text = ctx.get_help()
110
+ if help_text:
111
+ typer.echo(help_text)
112
+ if not ctx.obj.manager.exists():
113
+ out.info("\nNo config file yet. Run `hirame init` to start the initial setup.")
114
+ raise typer.Exit(0)
115
+
116
+
117
+ def command_help(name: str, text: str) -> str:
118
+ short = alias_of(name)
119
+ return f"{text} (alias: {short})" if short else text
120
+
121
+
122
+ def _register() -> None:
123
+ from hiramedbc.commands import add, connect, doctor, dump, edit, init, remove, version
124
+ from hiramedbc.commands import config as config_command
125
+ from hiramedbc.commands import list as list_command
126
+
127
+ commands = [
128
+ ("init", init.init, "Initial setup (environment check → create config file → add connections → pull images)"),
129
+ ("connect", connect.connect, "Connect to a database"),
130
+ ("add", add.add, "Add a connection"),
131
+ ("list", list_command.list_connections, "List saved connections"),
132
+ ("remove", remove.remove, "Remove a connection (also deletes its password from the keychain)"),
133
+ ("edit", edit.edit, "Edit a connection"),
134
+ ("dump", dump.dump, "Create a dump with mysqldump"),
135
+ ("version", version.version, "Show the app version"),
136
+ (
137
+ "doctor",
138
+ doctor.doctor,
139
+ "Check the environment (--pull to pre-pull images, --clean to remove leftover containers)",
140
+ ),
141
+ ]
142
+ for name, func, text in commands:
143
+ # Show the docstring below the help as a detailed description
144
+ epilog = (func.__doc__ or "").strip() or None
145
+ app.command(name, help=command_help(name, text), epilog=epilog)(func)
146
+ app.add_typer(config_command.config_app, name="config")
147
+
148
+
149
+ _register()
File without changes