clawsql 0.2.4 → 0.2.7

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 (69) hide show
  1. package/README.md +110 -260
  2. package/dist/api/schemas/index.d.ts +20 -20
  3. package/dist/app.d.ts.map +1 -1
  4. package/dist/app.js +12 -0
  5. package/dist/app.js.map +1 -1
  6. package/dist/bin/clawsql.js +0 -0
  7. package/dist/cli/commands/clusters.d.ts +1 -1
  8. package/dist/cli/commands/clusters.d.ts.map +1 -1
  9. package/dist/cli/commands/clusters.js +291 -56
  10. package/dist/cli/commands/clusters.js.map +1 -1
  11. package/dist/cli/commands/templates.d.ts +11 -0
  12. package/dist/cli/commands/templates.d.ts.map +1 -0
  13. package/dist/cli/commands/templates.js +206 -0
  14. package/dist/cli/commands/templates.js.map +1 -0
  15. package/dist/cli/formatter.d.ts +24 -0
  16. package/dist/cli/formatter.d.ts.map +1 -1
  17. package/dist/cli/formatter.js +22 -0
  18. package/dist/cli/formatter.js.map +1 -1
  19. package/dist/cli/index.d.ts.map +1 -1
  20. package/dist/cli/index.js +2 -0
  21. package/dist/cli/index.js.map +1 -1
  22. package/dist/cli/raw-input.d.ts +9 -1
  23. package/dist/cli/raw-input.d.ts.map +1 -1
  24. package/dist/cli/raw-input.js +146 -10
  25. package/dist/cli/raw-input.js.map +1 -1
  26. package/dist/cli/repl.d.ts.map +1 -1
  27. package/dist/cli/repl.js +94 -29
  28. package/dist/cli/repl.js.map +1 -1
  29. package/dist/cli/ui/components.d.ts.map +1 -1
  30. package/dist/cli/ui/components.js +21 -5
  31. package/dist/cli/ui/components.js.map +1 -1
  32. package/dist/cli/utils/args.d.ts +25 -0
  33. package/dist/cli/utils/args.d.ts.map +1 -0
  34. package/dist/cli/utils/args.js +51 -0
  35. package/dist/cli/utils/args.js.map +1 -0
  36. package/dist/config/settings.d.ts +38 -6
  37. package/dist/config/settings.d.ts.map +1 -1
  38. package/dist/config/settings.js +8 -0
  39. package/dist/config/settings.js.map +1 -1
  40. package/dist/core/provisioning/cluster-provisioner.d.ts +99 -0
  41. package/dist/core/provisioning/cluster-provisioner.d.ts.map +1 -0
  42. package/dist/core/provisioning/cluster-provisioner.js +415 -0
  43. package/dist/core/provisioning/cluster-provisioner.js.map +1 -0
  44. package/dist/core/provisioning/index.d.ts +12 -0
  45. package/dist/core/provisioning/index.d.ts.map +1 -0
  46. package/dist/core/provisioning/index.js +21 -0
  47. package/dist/core/provisioning/index.js.map +1 -0
  48. package/dist/core/provisioning/predefined-templates.d.ts +43 -0
  49. package/dist/core/provisioning/predefined-templates.d.ts.map +1 -0
  50. package/dist/core/provisioning/predefined-templates.js +117 -0
  51. package/dist/core/provisioning/predefined-templates.js.map +1 -0
  52. package/dist/core/provisioning/template-manager.d.ts +113 -0
  53. package/dist/core/provisioning/template-manager.d.ts.map +1 -0
  54. package/dist/core/provisioning/template-manager.js +274 -0
  55. package/dist/core/provisioning/template-manager.js.map +1 -0
  56. package/dist/core/routing/proxysql-manager.d.ts +17 -0
  57. package/dist/core/routing/proxysql-manager.d.ts.map +1 -1
  58. package/dist/core/routing/proxysql-manager.js +77 -0
  59. package/dist/core/routing/proxysql-manager.js.map +1 -1
  60. package/dist/types/index.d.ts +52 -0
  61. package/dist/types/index.d.ts.map +1 -1
  62. package/dist/types/index.js +45 -1
  63. package/dist/types/index.js.map +1 -1
  64. package/dist/utils/database.d.ts.map +1 -1
  65. package/dist/utils/database.js +40 -0
  66. package/dist/utils/database.js.map +1 -1
  67. package/docker/Dockerfile.allinone +1 -1
  68. package/docker/Dockerfile.node +1 -1
  69. package/package.json +1 -1
package/README.md CHANGED
@@ -4,6 +4,7 @@ MySQL High Availability Management Platform with automatic failover, read/write
4
4
 
5
5
  ## Features
6
6
 
7
+ - **Template-Based Provisioning**: Create clusters from predefined templates in one command
7
8
  - **Automatic Failover**: Detect primary failures and promote replicas automatically
8
9
  - **Read/Write Splitting**: ProxySQL integration for transparent traffic routing
9
10
  - **Topology Management**: Orchestrator-powered MySQL cluster management
@@ -19,128 +20,90 @@ MySQL High Availability Management Platform with automatic failover, read/write
19
20
 
20
21
  ## Installation
21
22
 
22
- ### Via npm (Recommended)
23
-
24
23
  ```bash
25
24
  npm install -g clawsql
26
25
  ```
27
26
 
28
- ### From Source
29
-
30
- ```bash
31
- git clone https://github.com/clawsql/clawsql.git
32
- cd clawsql
33
- npm install
34
- npm run build
35
- ```
36
-
37
27
  ## Quick Start
38
28
 
39
- **New to ClawSQL?** See the **[Getting Started Guide](docs/GET_STARTED.md)** for a step-by-step tutorial.
40
-
41
- ### Option 1: Demo Mode (Recommended for Testing)
42
-
43
- Start with a pre-configured demo MySQL cluster:
29
+ ### 1. Install and Start Platform
44
30
 
45
31
  ```bash
46
32
  # Install ClawSQL
47
33
  npm install -g clawsql
48
34
 
49
- # Pull required Docker images (do this once)
50
- clawsql install --demo
35
+ # Pull Docker images (one-time setup)
36
+ clawsql install
51
37
 
52
- # Start the platform
38
+ # Start platform services
53
39
  clawsql
54
- > /start --demo
40
+ > /start
55
41
  ```
56
42
 
57
- This starts:
58
- - ClawSQL platform (API, Orchestrator, ProxySQL, Prometheus, Grafana)
59
- - Demo MySQL cluster (1 primary + 2 replicas) using host networking
60
-
61
- After starting, register the instances using your host IP:
43
+ ### 2. Create MySQL Admin User
62
44
 
63
- ```bash
64
- # Replace <host-ip> with your actual host IP (shown in startup output)
65
- > /instances register <host-ip> 3306
66
- > /instances register <host-ip> 3307
67
- > /instances register <host-ip> 3308
68
-
69
- # Set up replication (creates repl user automatically)
70
- > /instances setup-replication --host <host-ip>:3307 --master <host-ip>:3306
71
- > /instances setup-replication --host <host-ip>:3308 --master <host-ip>:3306
45
+ On each MySQL instance, create the admin user:
72
46
 
73
- # Sync to ProxySQL
74
- > /clusters sync
47
+ ```sql
48
+ CREATE USER 'clawsql'@'%' IDENTIFIED WITH mysql_native_password BY 'clawsql_password';
49
+ GRANT ALL PRIVILEGES ON *.* TO 'clawsql'@'%' WITH GRANT OPTION;
50
+ FLUSH PRIVILEGES;
75
51
  ```
76
52
 
77
- ### Option 2: Production Mode (Bring Your Own MySQL)
53
+ ### 3. Provision a Cluster
78
54
 
79
- Start the platform and connect to your existing MySQL instances:
55
+ Choose a template and provision your cluster:
80
56
 
81
57
  ```bash
82
- # Install ClawSQL
83
- npm install -g clawsql
84
-
85
- # Pull required Docker images
86
- clawsql install
87
-
88
- # Start the interactive CLI
89
- clawsql
90
-
91
- # Start platform services
92
- > /start
58
+ # View available templates
59
+ > /clusters provision
93
60
 
94
- # Create the clawsql admin user on your MySQL instances (run on each MySQL server)
95
- # mysql -e "CREATE USER 'clawsql'@'%' IDENTIFIED WITH mysql_native_password BY 'clawsql_password'; GRANT ALL ON *.* TO 'clawsql'@'%' WITH GRANT OPTION;"
96
-
97
- # Discover MySQL instances on your network
98
- > /instances discover 172.18.0.0/24 --auto-register
99
-
100
- # Or register instances manually
101
- > /instances register mysql-primary 3306
61
+ # Quick provision a 3-node production cluster
62
+ > /clusters quick standard mycluster mysql1:3306,mysql2:3306,mysql3:3306
63
+ Cluster "mycluster" ready at port 6033
64
+ ```
102
65
 
103
- # Set up replication (if needed)
104
- > /instances setup-replication --host replica-host:3306 --master primary-host:3306
66
+ That's it! ClawSQL automatically:
67
+ - Sets up GTID-based replication (first host = primary, others = replicas)
68
+ - Configures ProxySQL with a dedicated port (6033, 6034, etc.)
69
+ - Registers instances with Orchestrator for topology management
105
70
 
106
- # Sync to ProxySQL
107
- > /clusters sync
71
+ ### Connect to Your Cluster
108
72
 
109
- # Verify health
110
- > /doctor
73
+ ```bash
74
+ # Connect through ProxySQL (read/write split is automatic)
75
+ mysql -h 127.0.0.1 -P 6033 -u clawsql -pclawsql_password
111
76
  ```
112
77
 
113
- ## Services
78
+ ## Predefined Templates
114
79
 
115
- After starting, access these services:
80
+ | Template | Nodes | Mode | Use Case |
81
+ |----------|-------|------|----------|
82
+ | `dev-single` | 1 | async | Development/testing, CI/CD |
83
+ | `dev-replica` | 2 | async | Development with backup |
84
+ | `standard` | 3 | async | General production workloads |
85
+ | `ha-semisync` | 3 | semi-sync | Critical production, zero data loss |
86
+ | `read-heavy` | 5 | async | Analytics, reporting, high read throughput |
87
+ | `production-ha` | 4 | semi-sync | Mission-critical, enterprise databases |
88
+ | `geo-distributed` | 6 | async | Multi-region, disaster recovery |
116
89
 
117
- | Service | URL | Description |
118
- |---------|-----|-------------|
119
- | ClawSQL API | http://localhost:8080 | REST API |
120
- | API Docs | http://localhost:8080/docs | OpenAPI documentation |
121
- | Orchestrator | http://localhost:3000 | MySQL topology manager |
122
- | Prometheus | http://localhost:9090 | Metrics collection |
123
- | Grafana | http://localhost:3001 | Dashboards (admin/admin) |
124
- | ProxySQL | localhost:6033 | MySQL traffic (read/write split) |
125
- | OpenClaw Gateway | ws://localhost:18789 | AI agent gateway |
126
- | OpenClaw UI | http://localhost:18790 | AI control panel |
90
+ Templates are auto-initialized on startup. No manual creation needed.
91
+
92
+ ## Demo Mode
127
93
 
128
- ### Demo MySQL Cluster
94
+ Test ClawSQL with a pre-configured demo cluster:
129
95
 
130
- When started with `--demo`, MySQL containers use host networking to simulate real multi-node deployments. Instances are accessible at your host IP:
96
+ ```bash
97
+ # Pull demo images
98
+ clawsql install --demo
131
99
 
132
- | Instance | Port | Credentials |
133
- |----------|------|-------------|
134
- | Primary | 3306 | clawsql/clawsql_password |
135
- | Replica 1 | 3307 | clawsql/clawsql_password |
136
- | Replica 2 | 3308 | clawsql/clawsql_password |
100
+ # Start with demo MySQL cluster
101
+ clawsql
102
+ > /start --demo
137
103
 
138
- > **Note:** After starting with `--demo`, register instances using your host IP:
139
- > ```bash
140
- > > /instances register <host-ip> 3306
141
- > > /instances register <host-ip> 3307
142
- > > /instances register <host-ip> 3308
143
- > ```
104
+ # Provision the demo instances into a cluster
105
+ > /clusters quick standard demo <host-ip>:3306,<host-ip>:3307,<host-ip>:3308
106
+ ```
144
107
 
145
108
  ## CLI Commands
146
109
 
@@ -148,73 +111,54 @@ When started with `--demo`, MySQL containers use host networking to simulate rea
148
111
 
149
112
  ```bash
150
113
  /install [--demo] # Pull Docker images (required before first start)
151
- # --demo: Include MySQL demo cluster images
152
- # --detail: Show verbose output
153
-
154
114
  /start [--demo] # Start ClawSQL platform
155
- # --demo: Start with demo MySQL cluster
156
- # --pull: Force pull missing images
157
-
158
115
  /stop # Stop all services
159
- /status # Show platform status (images, containers, services)
116
+ /status # Show platform status
160
117
  /cleanup # Remove all containers and data
161
118
  /doctor # Run diagnostics and suggest fixes
162
119
  ```
163
120
 
164
- ### Configuration
121
+ ### Cluster Provisioning (Primary Method)
165
122
 
166
123
  ```bash
167
- /config show # Display current configuration
168
- /config init # Interactive configuration wizard
169
- /config set <key> <value> # Set configuration value
170
- /config get <key> # Get configuration value
124
+ # Interactive mode - shows template selection
125
+ /clusters provision
126
+
127
+ # Provision with template
128
+ /clusters provision --template <template> --cluster <name> --hosts <h:p,...>
129
+
130
+ # Quick provisioning (minimal arguments)
131
+ /clusters quick <template> <cluster> <h:p,...>
132
+
133
+ # Deprovision
134
+ /clusters deprovision <cluster> --force
171
135
  ```
172
136
 
173
- Available configuration keys:
174
- - `mysql.admin_user` - MySQL admin username
175
- - `mysql.admin_password` - MySQL admin password
176
- - `mysql.repl_user` - MySQL replication username
177
- - `mysql.repl_password` - MySQL replication password
178
- - `orchestrator.url` - Orchestrator URL
179
- - `proxysql.host` - ProxySQL hostname
180
- - `proxysql.admin_port` - ProxySQL admin port
181
- - `failover.auto_enabled` - Enable auto failover (true/false)
182
- - `log.level` - Log level (DEBUG/INFO/WARNING/ERROR/SILENT)
137
+ ### Cluster Management
183
138
 
184
- ### Instance Management
139
+ ```bash
140
+ /clusters list # List all clusters
141
+ /clusters topology [--name <name>] # Show topology
142
+ ```
143
+
144
+ ### Manual Operations (Advanced)
145
+
146
+ For existing topologies or special cases:
185
147
 
186
148
  ```bash
187
- /instances list # List discovered instances
188
- /instances discover <network> [options] # Scan network for MySQL
189
- --user <user> MySQL username for discovery
190
- --password <pass> MySQL password
191
- --port <port> Port range (default: 3306)
192
- --auto-register Auto-register discovered instances
193
-
194
- /instances register <host> [port] [options] # Register instance manually
195
- <host> MySQL hostname or IP (use host IP for demo)
196
- [port] MySQL port (default: 3306)
197
- --user <user> MySQL username (default: from config)
198
- --password <pass> MySQL password
199
-
200
- /instances remove <host> [port] # Remove instance
201
-
202
- /instances setup-replication --host <replica:port> --master <primary:port>
203
- # Configure replication (creates repl user automatically)
149
+ /clusters manual import --primary <h:p> # Import existing topology
150
+ /clusters manual create --name <n> --primary <h:p> [--replicas <h:p,...>]
151
+ /clusters manual sync [--name <cluster>] # Sync to ProxySQL
152
+ /clusters manual promote --name <n> --host <h:p>
204
153
  ```
205
154
 
206
- ### Cluster Management
155
+ ### Instance Management
207
156
 
208
157
  ```bash
209
- /clusters list # List all clusters
210
- /clusters topology [--name <cluster>] # Show topology
211
- /clusters import --primary <host:port> # Import existing topology
212
- /clusters create --name <name> --primary <h:p> # Create new cluster
213
- --replicas <h:p,...> Replica instances (optional)
214
-
215
- /clusters sync [--name <cluster>] # Sync to ProxySQL
216
- /clusters add-replica --name <cluster> --host <h:p> # Add replica
217
- /clusters remove-replica --name <cluster> --host <h:p> # Remove replica
158
+ /instances list # List discovered instances
159
+ /instances discover <network> --auto-register # Scan network for MySQL
160
+ /instances register <host> [port] # Register instance manually
161
+ /instances remove <host> [port] # Remove instance
218
162
  ```
219
163
 
220
164
  ### Failover Operations
@@ -222,52 +166,44 @@ Available configuration keys:
222
166
  ```bash
223
167
  /failover status # Show failover configuration
224
168
  /failover history # Show operation history
225
- /failover switchover <cluster> [target] # Planned primary change (primary healthy)
226
- /failover failover <cluster> [target] # Emergency failover (primary down)
227
- /failover recover list # List instances pending recovery
228
- /failover recover <instance> # Recover specific instance
229
- /failover recover --all # Recover all pending instances
169
+ /failover switchover <cluster> [target] # Planned primary change
170
+ /failover failover <cluster> [target] # Emergency failover
230
171
  ```
231
172
 
232
- > **Note:** For promoting replicas, use `/failover switchover` instead of `/clusters promote`.
233
-
234
- ### Additional Commands
173
+ ### Template Management
235
174
 
236
175
  ```bash
237
- /topology [--name <cluster>] # Quick topology view
238
- /sql <host:port> "<query>" # Execute SQL query on instance
239
- /cron list # List scheduled tasks
240
- /cron create "<cron>" "<command>" # Schedule a recurring task
241
- /cron remove <task-id> # Remove scheduled task
242
- /notify send --message "<msg>" # Send notification
176
+ /templates list # List available templates
177
+ /templates show <name> # Show template details
178
+ /templates create --name <name> [--replicas <n>] [--mode <async|semi-sync>]
179
+ /templates delete <name> --force # Delete custom template
243
180
  ```
244
181
 
182
+ ## Services
183
+
184
+ | Service | URL | Description |
185
+ |---------|-----|-------------|
186
+ | ClawSQL API | http://localhost:8080 | REST API |
187
+ | API Docs | http://localhost:8080/docs | OpenAPI documentation |
188
+ | Orchestrator | http://localhost:3000 | MySQL topology manager |
189
+ | Prometheus | http://localhost:9090 | Metrics collection |
190
+ | Grafana | http://localhost:3001 | Dashboards (admin/admin) |
191
+ | ProxySQL | localhost:6033+ | MySQL traffic (per-cluster ports) |
192
+ | OpenClaw Gateway | ws://localhost:18789 | AI agent gateway |
193
+ | OpenClaw UI | http://localhost:18790 | AI control panel |
194
+
245
195
  ## MySQL Configuration Requirements
246
196
 
247
197
  ### Admin User (Required)
248
198
 
249
- Create the `clawsql` admin user on your MySQL instances. This user is used by ClawSQL for topology discovery, monitoring, and management:
250
-
251
199
  ```sql
252
200
  CREATE USER 'clawsql'@'%' IDENTIFIED WITH mysql_native_password BY 'clawsql_password';
253
201
  GRANT ALL PRIVILEGES ON *.* TO 'clawsql'@'%' WITH GRANT OPTION;
254
202
  FLUSH PRIVILEGES;
255
203
  ```
256
204
 
257
- ### Replication User (Created Automatically)
258
-
259
- The replication user is created automatically by ClawSQL when you run `/instances setup-replication`. If you want to set up replication manually:
260
-
261
- ```sql
262
- CREATE USER 'repl'@'%' IDENTIFIED WITH mysql_native_password BY 'repl_password';
263
- GRANT REPLICATION SLAVE ON *.* TO 'repl'@'%';
264
- FLUSH PRIVILEGES;
265
- ```
266
-
267
205
  ### MySQL Server Configuration
268
206
 
269
- For replication, your MySQL instances should have:
270
-
271
207
  ```ini
272
208
  [mysqld]
273
209
  server-id = 1 # Unique for each server
@@ -278,25 +214,6 @@ enforce-gtid-consistency = ON
278
214
  log-slave-updates = ON
279
215
  ```
280
216
 
281
- ## Configuration
282
-
283
- Configuration is managed via environment variables. Copy `.env.example` to `.env`:
284
-
285
- ```bash
286
- cp .env.example .env
287
- ```
288
-
289
- Key settings:
290
-
291
- | Variable | Default | Description |
292
- |----------|---------|-------------|
293
- | `API_PORT` | 8080 | API server port |
294
- | `API_TOKEN_SECRET` | change-me | JWT secret (change in production!) |
295
- | `MYSQL_ADMIN_USER` | clawsql | MySQL admin username |
296
- | `MYSQL_ADMIN_PASSWORD` | clawsql_password | MySQL admin password |
297
- | `AUTO_FAILOVER_ENABLED` | true | Enable automatic failover |
298
- | `LOG_LEVEL` | INFO | Logging level |
299
-
300
217
  ## Architecture
301
218
 
302
219
  ```
@@ -308,13 +225,12 @@ Key settings:
308
225
  ┌─────────────────────────────────────────────────────────────────┐
309
226
  │ ProxySQL │
310
227
  │ (Read/Write Splitting) │
311
- Port 6033 - MySQL Traffic | Port 6032 - Admin
228
+ Per-Cluster Ports: 6033 (cluster1), 6034 (cluster2), ...
312
229
  └───────────────┬─────────────────────────────┬───────────────────┘
313
230
  │ │
314
231
  ┌───────▼───────┐ ┌───────▼───────┐
315
232
  │ Primary │ │ Replica │
316
233
  │ (Writer) │────────────▶│ (Reader) │
317
- │ Port 3306 │ Repl │ Port 3306 │
318
234
  └───────────────┘ └───────────────┘
319
235
  │ │
320
236
  └──────────────┬──────────────┘
@@ -322,19 +238,16 @@ Key settings:
322
238
  ┌──────────────────────────────▼──────────────────────────────────┐
323
239
  │ ClawSQL │
324
240
  │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
325
- │ │ Orchestrator│ │ Failover │ │ Monitoring │
326
- │ │ Client │ │ Engine │ │ Service │ │
327
- └─────────────┘ └─────────────┘ └─────────────┘ │
328
- ┌─────────────────────────────────────────────────┐
329
- │ │ OpenClaw AI Gateway │ │
330
- │ │ Port 18789 - Gateway | Port 18790 - UI │ │
331
- │ └─────────────────────────────────────────────────┘ │
241
+ │ │ Provisioning│ │ Orchestrator│ │ Failover │ │
242
+ │ │ Engine │ │ Client │ │ Engine │ │
243
+ │ (Templates) │ └─────────────┘ └─────────────┘ │
244
+ └─────────────┘
332
245
  └─────────────────────────────────────────────────────────────────┘
333
246
  ```
334
247
 
335
248
  ## AI Agent Integration
336
249
 
337
- ClawSQL integrates with [OpenClaw](https://github.com/openclaw/openclaw) for AI-powered database operations. OpenClaw starts automatically with the platform.
250
+ ClawSQL integrates with [OpenClaw](https://github.com/openclaw/openclaw) for AI-powered database operations:
338
251
 
339
252
  ```
340
253
  clawsql> show me the cluster topology
@@ -342,77 +255,15 @@ clawsql> what's the replication lag?
342
255
  clawsql> help me troubleshoot replication issues
343
256
  ```
344
257
 
345
- See **[AI Integration Documentation](docs/AI.md)** for details on setup, configuration, and usage.
258
+ See **[AI Integration Documentation](docs/AI.md)** for details.
346
259
 
347
260
  ## Development
348
261
 
349
262
  ```bash
350
- # Install dependencies
351
263
  npm install
352
-
353
- # Build TypeScript
354
264
  npm run build
355
-
356
- # Run CLI locally
357
- node dist/bin/clawsql.js
358
-
359
- # Run tests
360
265
  npm test
361
-
362
- # Run with file watcher
363
- npm run dev
364
- ```
365
-
366
- ### Project Structure
367
-
368
- ```
369
- clawsql/
370
- ├── src/
371
- │ ├── index.ts # Entry point
372
- │ ├── app.ts # Fastify application setup
373
- │ ├── config/ # Configuration management
374
- │ ├── types/ # TypeScript types and interfaces
375
- │ ├── core/ # Core business logic
376
- │ │ ├── discovery/ # Instance discovery and topology
377
- │ │ ├── monitoring/ # Metrics and health checks
378
- │ │ ├── failover/ # Failover operations
379
- │ │ └── routing/ # ProxySQL integration
380
- │ ├── api/ # REST API routes
381
- │ ├── cli/ # CLI commands
382
- │ ├── utils/ # Utilities
383
- │ └── __tests__/ # Test files
384
- ├── docker/ # Docker configurations
385
- ├── scripts/ # Utility scripts
386
- ├── package.json # Node.js dependencies
387
- └── tsconfig.json # TypeScript configuration
388
- ```
389
-
390
- ## Troubleshooting
391
-
392
- ### Check Platform Health
393
-
394
- ```bash
395
- clawsql -c "/doctor"
396
- ```
397
-
398
- ### View Logs
399
-
400
- ```bash
401
- docker compose logs -f clawsql
402
- docker compose logs -f orchestrator
403
- docker compose logs -f proxysql
404
- ```
405
-
406
- ### Check MySQL Replication
407
-
408
- ```bash
409
- docker exec mysql-replica-1 mysql -uroot -prootpassword -e "SHOW REPLICA STATUS\G"
410
- ```
411
-
412
- ### Reset ProxySQL
413
-
414
- ```bash
415
- docker exec proxysql mysql -h127.0.0.1 -P6032 -uadmin -padmin -e "DELETE FROM mysql_servers; LOAD MYSQL SERVERS TO RUNTIME;"
266
+ node dist/bin/clawsql.js
416
267
  ```
417
268
 
418
269
  ## Documentation
@@ -422,7 +273,6 @@ docker exec proxysql mysql -h127.0.0.1 -P6032 -uadmin -padmin -e "DELETE FROM my
422
273
  - [API Documentation](docs/API.md) - REST API reference
423
274
  - [Demo Guide](docs/DEMO.md) - Testing with demo cluster
424
275
  - [Failover Documentation](docs/failover.md) - Failover architecture and operations
425
- - [System Architecture](docs/architecture/system_design.md) - Technical details
426
276
 
427
277
  ## License
428
278
 
@@ -137,6 +137,7 @@ export declare const InstanceListResponse: z.ZodObject<{
137
137
  page: z.ZodNumber;
138
138
  page_size: z.ZodNumber;
139
139
  }, "strip", z.ZodTypeAny, {
140
+ total: number;
140
141
  page: number;
141
142
  page_size: number;
142
143
  items: {
@@ -153,8 +154,8 @@ export declare const InstanceListResponse: z.ZodObject<{
153
154
  last_seen: Date;
154
155
  created_at: Date;
155
156
  }[];
156
- total: number;
157
157
  }, {
158
+ total: number;
158
159
  page: number;
159
160
  page_size: number;
160
161
  items: {
@@ -171,7 +172,6 @@ export declare const InstanceListResponse: z.ZodObject<{
171
172
  last_seen: Date;
172
173
  created_at: Date;
173
174
  }[];
174
- total: number;
175
175
  }>;
176
176
  export declare const InstanceMetricsResponse: z.ZodObject<{
177
177
  instance_id: z.ZodString;
@@ -294,7 +294,7 @@ export declare const DiscoveryResponse: z.ZodObject<{
294
294
  started_at: z.ZodOptional<z.ZodDate>;
295
295
  completed_at: z.ZodOptional<z.ZodDate>;
296
296
  }, "strip", z.ZodTypeAny, {
297
- status: "failed" | "completed" | "running" | "pending";
297
+ status: "failed" | "completed" | "pending" | "running";
298
298
  network_segments: string[];
299
299
  task_id: string;
300
300
  instances_found: number;
@@ -316,7 +316,7 @@ export declare const DiscoveryResponse: z.ZodObject<{
316
316
  started_at?: Date | undefined;
317
317
  completed_at?: Date | undefined;
318
318
  }, {
319
- status: "failed" | "completed" | "running" | "pending";
319
+ status: "failed" | "completed" | "pending" | "running";
320
320
  network_segments: string[];
321
321
  task_id: string;
322
322
  instances_found: number;
@@ -675,6 +675,7 @@ export declare const ClusterListResponse: z.ZodObject<{
675
675
  page: z.ZodNumber;
676
676
  page_size: z.ZodNumber;
677
677
  }, "strip", z.ZodTypeAny, {
678
+ total: number;
678
679
  page: number;
679
680
  page_size: number;
680
681
  items: {
@@ -714,8 +715,8 @@ export declare const ClusterListResponse: z.ZodObject<{
714
715
  health_status: "unknown" | "healthy" | "degraded" | "unhealthy";
715
716
  updated_at: Date;
716
717
  }[];
717
- total: number;
718
718
  }, {
719
+ total: number;
719
720
  page: number;
720
721
  page_size: number;
721
722
  items: {
@@ -755,7 +756,6 @@ export declare const ClusterListResponse: z.ZodObject<{
755
756
  health_status: "unknown" | "healthy" | "degraded" | "unhealthy";
756
757
  updated_at: Date;
757
758
  }[];
758
- total: number;
759
759
  }>;
760
760
  export declare const FailoverStateSchema: z.ZodEnum<["idle", "detecting", "candidate_selection", "promoting", "reconfiguring", "completed", "failed"]>;
761
761
  export declare const FailoverRequest: z.ZodObject<{
@@ -785,10 +785,10 @@ export declare const FailoverOperationResponse: z.ZodObject<{
785
785
  }, "strip", z.ZodTypeAny, {
786
786
  error: string | null;
787
787
  state: "failed" | "idle" | "detecting" | "candidate_selection" | "promoting" | "reconfiguring" | "completed";
788
- reason: string | null;
789
- cluster_id: string;
790
788
  steps: string[];
791
789
  manual: boolean;
790
+ reason: string | null;
791
+ cluster_id: string;
792
792
  operation_id: string;
793
793
  started_at: string | null;
794
794
  completed_at: string | null;
@@ -799,10 +799,10 @@ export declare const FailoverOperationResponse: z.ZodObject<{
799
799
  }, {
800
800
  error: string | null;
801
801
  state: "failed" | "idle" | "detecting" | "candidate_selection" | "promoting" | "reconfiguring" | "completed";
802
- reason: string | null;
803
- cluster_id: string;
804
802
  steps: string[];
805
803
  manual: boolean;
804
+ reason: string | null;
805
+ cluster_id: string;
806
806
  operation_id: string;
807
807
  started_at: string | null;
808
808
  completed_at: string | null;
@@ -829,10 +829,10 @@ export declare const FailoverListResponse: z.ZodObject<{
829
829
  }, "strip", z.ZodTypeAny, {
830
830
  error: string | null;
831
831
  state: "failed" | "idle" | "detecting" | "candidate_selection" | "promoting" | "reconfiguring" | "completed";
832
- reason: string | null;
833
- cluster_id: string;
834
832
  steps: string[];
835
833
  manual: boolean;
834
+ reason: string | null;
835
+ cluster_id: string;
836
836
  operation_id: string;
837
837
  started_at: string | null;
838
838
  completed_at: string | null;
@@ -843,10 +843,10 @@ export declare const FailoverListResponse: z.ZodObject<{
843
843
  }, {
844
844
  error: string | null;
845
845
  state: "failed" | "idle" | "detecting" | "candidate_selection" | "promoting" | "reconfiguring" | "completed";
846
- reason: string | null;
847
- cluster_id: string;
848
846
  steps: string[];
849
847
  manual: boolean;
848
+ reason: string | null;
849
+ cluster_id: string;
850
850
  operation_id: string;
851
851
  started_at: string | null;
852
852
  completed_at: string | null;
@@ -857,13 +857,14 @@ export declare const FailoverListResponse: z.ZodObject<{
857
857
  }>, "many">;
858
858
  total: z.ZodNumber;
859
859
  }, "strip", z.ZodTypeAny, {
860
+ total: number;
860
861
  items: {
861
862
  error: string | null;
862
863
  state: "failed" | "idle" | "detecting" | "candidate_selection" | "promoting" | "reconfiguring" | "completed";
863
- reason: string | null;
864
- cluster_id: string;
865
864
  steps: string[];
866
865
  manual: boolean;
866
+ reason: string | null;
867
+ cluster_id: string;
867
868
  operation_id: string;
868
869
  started_at: string | null;
869
870
  completed_at: string | null;
@@ -872,15 +873,15 @@ export declare const FailoverListResponse: z.ZodObject<{
872
873
  duration_seconds: number | null;
873
874
  triggered_by: string | null;
874
875
  }[];
875
- total: number;
876
876
  }, {
877
+ total: number;
877
878
  items: {
878
879
  error: string | null;
879
880
  state: "failed" | "idle" | "detecting" | "candidate_selection" | "promoting" | "reconfiguring" | "completed";
880
- reason: string | null;
881
- cluster_id: string;
882
881
  steps: string[];
883
882
  manual: boolean;
883
+ reason: string | null;
884
+ cluster_id: string;
884
885
  operation_id: string;
885
886
  started_at: string | null;
886
887
  completed_at: string | null;
@@ -889,7 +890,6 @@ export declare const FailoverListResponse: z.ZodObject<{
889
890
  duration_seconds: number | null;
890
891
  triggered_by: string | null;
891
892
  }[];
892
- total: number;
893
893
  }>;
894
894
  export declare const HealthStatusResponse: z.ZodObject<{
895
895
  status: z.ZodEnum<["healthy", "unhealthy"]>;