Skip to content

Commit a7a5be2

Browse files
Kinin-Code-OfficalKinin-Code-Offical
committed
feat: enhance CI/CD workflows with smoke tests, documentation checks, and gcloud installer integration; update changelog and README
1 parent e267475 commit a7a5be2

File tree

5 files changed

+233
-0
lines changed

5 files changed

+233
-0
lines changed

‎README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,16 @@
1717

1818
Download the latest installer (`cloudsqlctl-setup.exe`) from the [Releases](https://github.com/Kinin-Code-Offical/cloudsqlctl/releases) page.
1919

20+
## Documentation
21+
22+
Full documentation is available in the [docs](docs/) folder:
23+
24+
- [**Wiki Home**](docs/Home.md)
25+
- [Installation Guide](docs/Installation.md)
26+
- [Configuration & Setup](docs/Configuration.md)
27+
- [Command Reference](docs/commands.md)
28+
- [Troubleshooting](docs/Troubleshooting.md)
29+
2030
## Quick Start
2131

2232
Run the setup wizard to configure gcloud, authentication, and the proxy:

‎docs/Configuration.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Configuration & Setup
2+
3+
After installing `cloudsqlctl`, you need to configure it to work with your Google Cloud environment.
4+
5+
## The Setup Wizard
6+
7+
The easiest way to configure the tool is to run the interactive setup wizard:
8+
9+
```powershell
10+
cloudsqlctl setup
11+
```
12+
13+
This wizard will guide you through:
14+
15+
1. **Checking Prerequisites**: Verifies `gcloud` is installed.
16+
2. **Authentication**: Helps you login to Google Cloud (`gcloud auth login`) and set up Application Default Credentials (`gcloud auth application-default login`).
17+
3. **Project Selection**: Lets you select the active Google Cloud project.
18+
4. **Proxy Installation**: Downloads the Cloud SQL Auth Proxy binary if it's missing.
19+
20+
## Manual Configuration
21+
22+
If you prefer to configure things manually or need to change settings later:
23+
24+
### 1. Authentication
25+
26+
Manage your authentication state using the `auth` command:
27+
28+
```powershell
29+
# Check current auth status
30+
cloudsqlctl auth status
31+
32+
# Login to gcloud
33+
cloudsqlctl auth login
34+
35+
# Set up Application Default Credentials (ADC) - Required for the proxy
36+
cloudsqlctl auth adc
37+
```
38+
39+
### 2. Select an Instance
40+
41+
To tell the proxy which database to connect to:
42+
43+
```powershell
44+
# List available instances in your project
45+
cloudsqlctl list
46+
47+
# Interactively select an instance
48+
cloudsqlctl select
49+
```
50+
51+
### 3. Environment Variables
52+
53+
The tool manages several environment variables for you. You can view them with:
54+
55+
```powershell
56+
cloudsqlctl env
57+
```
58+
59+
Key variables:
60+
61+
- `CLOUDSQLCTL_HOME`: Configuration directory (default: `~/.cloudsqlctl`)
62+
- `CLOUDSQLCTL_LOGS`: Log directory
63+
- `CLOUDSQLCTL_PROXY_PATH`: Path to the `cloud-sql-proxy` executable
64+
65+
## Running as a Service
66+
67+
For production or long-running background tasks, you can install the proxy as a Windows Service.
68+
69+
**Note**: This requires an Administrator PowerShell terminal.
70+
71+
```powershell
72+
# Install the service
73+
cloudsqlctl service install
74+
75+
# Start the service
76+
cloudsqlctl service start
77+
78+
# Check status
79+
cloudsqlctl service status
80+
81+
# Remove the service
82+
cloudsqlctl service remove
83+
```

‎docs/Home.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Welcome to the CloudSQLCTL Wiki
2+
3+
**CloudSQLCTL** is a Windows-native command-line tool designed to simplify the management of the Google Cloud SQL Auth Proxy. It integrates seamlessly with the `gcloud` CLI to provide a robust, production-ready experience for developers working on Windows.
4+
5+
## Key Features
6+
7+
- **Setup Wizard**: Interactive `setup` command to get everything running in minutes.
8+
- **Authentication Management**: Built-in `auth` command for gcloud login, ADC setup, and Service Account management.
9+
- **Automated Installation**: Downloads and verifies the official Cloud SQL Proxy binary.
10+
- **Instance Management**: Lists and selects Cloud SQL instances using your active `gcloud` configuration.
11+
- **Process Management**: Starts, stops, and restarts the proxy as a background process or Windows Service.
12+
- **Structured Logging**: JSON logging with automatic masking of sensitive tokens.
13+
- **Diagnostics**: Built-in `doctor` command to check environment health (gcloud, ADC, network, service).
14+
- **Self-Update**: Easily update the proxy binary to the latest version.
15+
16+
## Navigation
17+
18+
- [Installation Guide](Installation.md)
19+
- [Configuration & Setup](Configuration.md)
20+
- [Command Reference](commands.md)
21+
- [Troubleshooting](Troubleshooting.md)
22+
- [Contributing](../CONTRIBUTING.md)

‎docs/Installation.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Installation Guide
2+
3+
## Prerequisites
4+
5+
- **Operating System**: Windows 10/11 or Windows Server 2016+ (x64)
6+
- **PowerShell**: Version 5.1 or later
7+
- **Google Cloud CLI**: The `gcloud` CLI must be installed and available in your PATH. (The tool can help you install this if missing).
8+
9+
## Installation Methods
10+
11+
### Option 1: Installer (Recommended)
12+
13+
1. Go to the [Releases](https://github.com/Kinin-Code-Offical/cloudsqlctl/releases) page.
14+
2. Download the latest `cloudsqlctl-setup.exe`.
15+
3. Run the installer and follow the on-screen instructions.
16+
4. The installer will automatically add `cloudsqlctl` to your system PATH.
17+
18+
### Option 2: Standalone Binary
19+
20+
1. Go to the [Releases](https://github.com/Kinin-Code-Offical/cloudsqlctl/releases) page.
21+
2. Download `cloudsqlctl.exe`.
22+
3. Place it in a folder of your choice (e.g., `C:\Tools\cloudsqlctl`).
23+
4. Add that folder to your system PATH environment variable.
24+
25+
## Verification
26+
27+
Open a new PowerShell terminal and run:
28+
29+
```powershell
30+
cloudsqlctl --version
31+
```
32+
33+
You should see the version number output.
34+
35+
## Next Steps
36+
37+
Once installed, proceed to the [Configuration & Setup](Configuration.md) guide to initialize the tool.

‎docs/Troubleshooting.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Troubleshooting
2+
3+
If you encounter issues with `cloudsqlctl`, follow these steps to diagnose and resolve them.
4+
5+
## The Doctor Command
6+
7+
The first step in troubleshooting is to run the built-in diagnostics tool:
8+
9+
```powershell
10+
cloudsqlctl doctor
11+
```
12+
13+
This command checks:
14+
15+
- **Network Connectivity**: Can you reach Google Cloud APIs?
16+
- **Gcloud CLI**: Is it installed and authenticated?
17+
- **Credentials**: Are Application Default Credentials (ADC) set up correctly?
18+
- **Proxy Binary**: Is the Cloud SQL Proxy binary present and executable?
19+
- **Service Status**: Is the Windows Service healthy (if installed)?
20+
21+
## Common Issues
22+
23+
### "Credential missing" or "Could not find default credentials"
24+
25+
**Cause**: The Cloud SQL Proxy requires Application Default Credentials (ADC) to authenticate with the Google Cloud API.
26+
27+
**Solution**:
28+
Run the following command to generate the ADC file:
29+
30+
```powershell
31+
cloudsqlctl auth adc
32+
```
33+
34+
Or manually: `gcloud auth application-default login`
35+
36+
### "Instance not found" or "403 Forbidden"
37+
38+
**Cause**: The active project selected in `gcloud` might be incorrect, or your account doesn't have permissions for the instance.
39+
40+
**Solution**:
41+
42+
1. Check your active project:
43+
```powershell
44+
gcloud config get-value project
45+
```
46+
2. Switch projects if necessary:
47+
```powershell
48+
cloudsqlctl setup
49+
# OR
50+
gcloud config set project <PROJECT_ID>
51+
```
52+
3. Ensure your user has the `Cloud SQL Client` role.
53+
54+
### Proxy fails to start
55+
56+
**Cause**: Port conflicts (default 5432 for Postgres, 3306 for MySQL) or invalid configuration.
57+
58+
**Solution**:
59+
60+
1. Check the logs for detailed error messages:
61+
```powershell
62+
cloudsqlctl logs
63+
```
64+
2. Try running the proxy in the foreground to see immediate output:
65+
```powershell
66+
cloudsqlctl start --foreground
67+
```
68+
69+
## Resetting Configuration
70+
71+
If your configuration is corrupted, you can reset the tool to its default state:
72+
73+
```powershell
74+
cloudsqlctl reset
75+
```
76+
77+
**Warning**: This will remove your local configuration files and the downloaded proxy binary. You will need to run `cloudsqlctl setup` again.
78+
79+
## Getting Help
80+
81+
If you still have issues, please open an issue on our [GitHub Repository](https://github.com/Kinin-Code-Offical/cloudsqlctl/issues) with the output of `cloudsqlctl doctor` and `cloudsqlctl logs`.

0 commit comments

Comments
 (0)