SQLx MCP Server

# Deployment and Release Guide ## 🚀 Automated Release Process This project uses GitHub Actions for automated building, testing, and publishing to both GitHub Releases and NPM. ### Release Triggers #### 1. Tag-based Release (Recommended) ```bash # Create and push a new version tag git tag v1.0.1 git push origin v1.0.1 ``` #### 2. Manual Release - Go to GitHub Actions - Select "Release and Publish" workflow - Click "Run workflow" - Enter version number (e.g., `1.0.1`) ### Release Process Overview 1. **Build Binaries** - Cross-compiles for all supported platforms: - Windows x64 (`x86_64-pc-windows-msvc`) - Linux x64 (`x86_64-unknown-linux-gnu`) - macOS x64 (`x86_64-apple-darwin`) - macOS ARM64 (`aarch64-apple-darwin`) 2. **Create NPM Packages**: - Platform-specific packages: `@sqlx-mcp/windows-x64`, `@sqlx-mcp/linux-x64`, etc. - Main package: `@sqlx-mcp/sqlx-mcp` (depends on platform packages) 3. **Publish to NPM**: - Publishes platform packages first - Waits for availability - Publishes main package 4. **Create GitHub Release**: - Creates release with binaries - Includes installation instructions - Provides download links ## 🛠️ Local Development and Testing ### Prerequisites - Rust 1.70+ - Node.js 14+ - Git ### Build Locally #### Current Platform Only ```bash # Using PowerShell script (Windows) .\build.ps1 # Using Node.js script (Cross-platform) node scripts/build.js --current ``` #### All Platforms ```bash # Using PowerShell script .\build.ps1 -All # Using Node.js script node scripts/build.js --all ``` #### Specific Platform ```bash # Using PowerShell script .\build.ps1 -Target "windows-x64" # Using Node.js script node scripts/build.js --target=linux-x64 ``` ### Testing #### Run Tests ```bash cargo test ``` #### Check Formatting ```bash cargo fmt --all -- --check ``` #### Run Clippy ```bash cargo clippy --all-targets --all-features -- -D warnings ``` #### Integration Testing ```bash # Build and test the binary cargo build --release ./target/release/sqlx-mcp --help # Test with a database (requires DATABASE_URL) export DATABASE_URL="sqlite::memory:" ./target/release/sqlx-mcp ``` ## 🔧 Configuration ### GitHub Secrets Required secrets for automated releases: - `NPM_TOKEN`: NPM access token with publish permissions - Create at: https://www.npmjs.com/settings/tokens - Scope: Automation token (recommended) ### NPM Setup #### 1. Create NPM Organization ```bash # Create organization (one-time setup) npm owner add your-username @sqlx-mcp ``` #### 2. Verify Access ```bash # Check organization access npm access list packages @sqlx-mcp # Test package creation (dry run) npm publish --dry-run --access public ``` ## 📦 Package Structure ### Platform Packages Each platform has its own NPM package: ``` @sqlx-mcp/windows-x64/ ├── package.json ├── index.js # Wrapper script └── sqlx-mcp.exe # Binary @sqlx-mcp/linux-x64/ ├── package.json ├── index.js # Wrapper script └── sqlx-mcp # Binary ``` ### Main Package The main package depends on platform packages: ``` @sqlx-mcp/sqlx-mcp/ ├── package.json # Main package config ├── index.js # Platform detection and binary execution ├── scripts/ │ └── postinstall.js # Post-installation setup └── README.md ``` ## 🔄 Version Management ### Semantic Versioning This project follows [Semantic Versioning](https://semver.org/): - **MAJOR** (X.0.0): Breaking changes - **MINOR** (0.X.0): New features, backwards compatible - **PATCH** (0.0.X): Bug fixes, backwards compatible ### Version Synchronization All packages (main and platform) use the same version number: - `@sqlx-mcp/sqlx-mcp@1.0.1` - `@sqlx-mcp/windows-x64@1.0.1` - `@sqlx-mcp/linux-x64@1.0.1` - etc. ## 🚨 Troubleshooting ### Common Issues #### 1. Cross-compilation Failures ```bash # Install target if missing rustup target add x86_64-pc-windows-msvc # Update Rust toolchain rustup update stable ``` #### 2. NPM Publishing Failures ```bash # Check NPM authentication npm whoami # Verify package access npm access list packages @sqlx-mcp # Test with dry run npm publish --dry-run --access public ``` #### 3. GitHub Actions Failures - Check secret configuration in repository settings - Verify NPM token has correct permissions - Review build logs for specific error messages ### Debug Commands #### Check Build Environment ```bash # Rust environment rustc --version cargo --version rustup show # Node.js environment node --version npm --version # Git environment git --version gh --version # GitHub CLI ``` #### Test Binary Execution ```bash # Test all built binaries for dir in packages/*/; do echo "Testing $dir" if [[ -f "$dir/sqlx-mcp.exe" ]]; then "$dir/sqlx-mcp.exe" --help elif [[ -f "$dir/sqlx-mcp" ]]; then "$dir/sqlx-mcp" --help fi done ``` ## 📋 Release Checklist ### Pre-release - [ ] Update version in `Cargo.toml` - [ ] Update `CHANGELOG.md` (if exists) - [ ] Run tests locally: `cargo test` - [ ] Test build: `.\build.ps1 -All` - [ ] Verify binary functionality - [ ] Update documentation if needed ### Release - [ ] Create and push version tag: `git tag v1.0.1 && git push origin v1.0.1` - [ ] Monitor GitHub Actions workflow - [ ] Verify NPM packages published successfully - [ ] Test NPM installation: `npm install -g @sqlx-mcp/sqlx-mcp` - [ ] Verify GitHub release created ### Post-release - [ ] Test installation on different platforms - [ ] Update documentation with new version - [ ] Announce release (if applicable) - [ ] Monitor for issues and feedback ## 🔗 Useful Links - [GitHub Actions Workflow](.github/workflows/release.yml) - [NPM Organization](https://www.npmjs.com/org/sqlx-mcp) - [GitHub Releases](https://github.com/lihongjie0209/sqlx-mcp/releases) - [Build Scripts](scripts/) - [Rust Cross-compilation Guide](https://rust-lang.github.io/rustup/cross-compilation.html)