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.
- package/README.md +110 -260
- package/dist/api/schemas/index.d.ts +20 -20
- package/dist/app.d.ts.map +1 -1
- package/dist/app.js +12 -0
- package/dist/app.js.map +1 -1
- package/dist/bin/clawsql.js +0 -0
- package/dist/cli/commands/clusters.d.ts +1 -1
- package/dist/cli/commands/clusters.d.ts.map +1 -1
- package/dist/cli/commands/clusters.js +291 -56
- package/dist/cli/commands/clusters.js.map +1 -1
- package/dist/cli/commands/templates.d.ts +11 -0
- package/dist/cli/commands/templates.d.ts.map +1 -0
- package/dist/cli/commands/templates.js +206 -0
- package/dist/cli/commands/templates.js.map +1 -0
- package/dist/cli/formatter.d.ts +24 -0
- package/dist/cli/formatter.d.ts.map +1 -1
- package/dist/cli/formatter.js +22 -0
- package/dist/cli/formatter.js.map +1 -1
- package/dist/cli/index.d.ts.map +1 -1
- package/dist/cli/index.js +2 -0
- package/dist/cli/index.js.map +1 -1
- package/dist/cli/raw-input.d.ts +9 -1
- package/dist/cli/raw-input.d.ts.map +1 -1
- package/dist/cli/raw-input.js +146 -10
- package/dist/cli/raw-input.js.map +1 -1
- package/dist/cli/repl.d.ts.map +1 -1
- package/dist/cli/repl.js +94 -29
- package/dist/cli/repl.js.map +1 -1
- package/dist/cli/ui/components.d.ts.map +1 -1
- package/dist/cli/ui/components.js +21 -5
- package/dist/cli/ui/components.js.map +1 -1
- package/dist/cli/utils/args.d.ts +25 -0
- package/dist/cli/utils/args.d.ts.map +1 -0
- package/dist/cli/utils/args.js +51 -0
- package/dist/cli/utils/args.js.map +1 -0
- package/dist/config/settings.d.ts +38 -6
- package/dist/config/settings.d.ts.map +1 -1
- package/dist/config/settings.js +8 -0
- package/dist/config/settings.js.map +1 -1
- package/dist/core/provisioning/cluster-provisioner.d.ts +99 -0
- package/dist/core/provisioning/cluster-provisioner.d.ts.map +1 -0
- package/dist/core/provisioning/cluster-provisioner.js +415 -0
- package/dist/core/provisioning/cluster-provisioner.js.map +1 -0
- package/dist/core/provisioning/index.d.ts +12 -0
- package/dist/core/provisioning/index.d.ts.map +1 -0
- package/dist/core/provisioning/index.js +21 -0
- package/dist/core/provisioning/index.js.map +1 -0
- package/dist/core/provisioning/predefined-templates.d.ts +43 -0
- package/dist/core/provisioning/predefined-templates.d.ts.map +1 -0
- package/dist/core/provisioning/predefined-templates.js +117 -0
- package/dist/core/provisioning/predefined-templates.js.map +1 -0
- package/dist/core/provisioning/template-manager.d.ts +113 -0
- package/dist/core/provisioning/template-manager.d.ts.map +1 -0
- package/dist/core/provisioning/template-manager.js +274 -0
- package/dist/core/provisioning/template-manager.js.map +1 -0
- package/dist/core/routing/proxysql-manager.d.ts +17 -0
- package/dist/core/routing/proxysql-manager.d.ts.map +1 -1
- package/dist/core/routing/proxysql-manager.js +77 -0
- package/dist/core/routing/proxysql-manager.js.map +1 -1
- package/dist/types/index.d.ts +52 -0
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/index.js +45 -1
- package/dist/types/index.js.map +1 -1
- package/dist/utils/database.d.ts.map +1 -1
- package/dist/utils/database.js +40 -0
- package/dist/utils/database.js.map +1 -1
- package/docker/Dockerfile.allinone +1 -1
- package/docker/Dockerfile.node +1 -1
- 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
|
-
|
|
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
|
|
50
|
-
clawsql install
|
|
35
|
+
# Pull Docker images (one-time setup)
|
|
36
|
+
clawsql install
|
|
51
37
|
|
|
52
|
-
# Start
|
|
38
|
+
# Start platform services
|
|
53
39
|
clawsql
|
|
54
|
-
> /start
|
|
40
|
+
> /start
|
|
55
41
|
```
|
|
56
42
|
|
|
57
|
-
|
|
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
|
-
|
|
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
|
-
|
|
74
|
-
|
|
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
|
-
###
|
|
53
|
+
### 3. Provision a Cluster
|
|
78
54
|
|
|
79
|
-
|
|
55
|
+
Choose a template and provision your cluster:
|
|
80
56
|
|
|
81
57
|
```bash
|
|
82
|
-
#
|
|
83
|
-
|
|
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
|
-
#
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
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
|
-
|
|
104
|
-
|
|
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
|
-
|
|
107
|
-
> /clusters sync
|
|
71
|
+
### Connect to Your Cluster
|
|
108
72
|
|
|
109
|
-
|
|
110
|
-
|
|
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
|
-
##
|
|
78
|
+
## Predefined Templates
|
|
114
79
|
|
|
115
|
-
|
|
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
|
-
|
|
118
|
-
|
|
119
|
-
|
|
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
|
-
|
|
94
|
+
Test ClawSQL with a pre-configured demo cluster:
|
|
129
95
|
|
|
130
|
-
|
|
96
|
+
```bash
|
|
97
|
+
# Pull demo images
|
|
98
|
+
clawsql install --demo
|
|
131
99
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
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
|
-
|
|
139
|
-
>
|
|
140
|
-
|
|
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
|
|
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
|
-
###
|
|
121
|
+
### Cluster Provisioning (Primary Method)
|
|
165
122
|
|
|
166
123
|
```bash
|
|
167
|
-
|
|
168
|
-
/
|
|
169
|
-
|
|
170
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
/
|
|
188
|
-
/
|
|
189
|
-
|
|
190
|
-
|
|
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
|
-
###
|
|
155
|
+
### Instance Management
|
|
207
156
|
|
|
208
157
|
```bash
|
|
209
|
-
/
|
|
210
|
-
/
|
|
211
|
-
/
|
|
212
|
-
/
|
|
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
|
|
226
|
-
/failover failover <cluster> [target] # Emergency failover
|
|
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
|
-
|
|
233
|
-
|
|
234
|
-
### Additional Commands
|
|
173
|
+
### Template Management
|
|
235
174
|
|
|
236
175
|
```bash
|
|
237
|
-
/
|
|
238
|
-
/
|
|
239
|
-
/
|
|
240
|
-
/
|
|
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
|
-
│
|
|
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 │
|
|
326
|
-
│ │
|
|
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
|
|
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
|
|
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" | "
|
|
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" | "
|
|
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"]>;
|