# NPM Package Usage Guide
## 📦 Installation
### Global Installation (Recommended)
```bash
npm install -g @sqlx-mcp/sqlx-mcp
```
### Local Installation
```bash
npm install @sqlx-mcp/sqlx-mcp
```
## 🚀 Usage
### Command Line Usage
After global installation, you can use `sqlx-mcp` directly:
```bash
# With environment variable
export DATABASE_URL="postgresql://user:pass@localhost/mydb"
sqlx-mcp
# With command line argument
sqlx-mcp --database-url "postgresql://user:pass@localhost/mydb"
# SQLite example
sqlx-mcp --database-url "sqlite:./database.db"
# MySQL example
sqlx-mcp --database-url "mysql://user:pass@localhost/mydb"
```
### Programmatic Usage
```javascript
const { spawn } = require('child_process');
// Start SQLx MCP Server
const mcpServer = spawn('sqlx-mcp', [
'--database-url', 'postgresql://user:pass@localhost/mydb'
], {
stdio: ['pipe', 'pipe', 'inherit']
});
// Handle MCP communication
mcpServer.stdout.on('data', (data) => {
// Process MCP messages
console.log('MCP Output:', data.toString());
});
mcpServer.stdin.write(JSON.stringify({
jsonrpc: "2.0",
id: 1,
method: "initialize",
params: {
protocolVersion: "2024-11-05",
capabilities: {},
clientInfo: {
name: "test-client",
version: "1.0.0"
}
}
}) + '\n');
```
## 🔧 Claude Desktop Integration
### Configuration
Add to your Claude Desktop configuration file:
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"sqlx-mcp": {
"command": "sqlx-mcp",
"args": [
"--database-url",
"postgresql://user:password@localhost:5432/database"
]
}
}
}
```
### Environment Variables
You can also use environment variables:
```json
{
"mcpServers": {
"sqlx-mcp": {
"command": "sqlx-mcp",
"env": {
"DATABASE_URL": "postgresql://user:password@localhost:5432/database"
}
}
}
}
```
## 🗄️ Database Connection Examples
### PostgreSQL
```bash
# Standard connection
sqlx-mcp --database-url "postgresql://username:password@localhost:5432/database_name"
# With SSL
sqlx-mcp --database-url "postgresql://username:password@localhost:5432/database_name?sslmode=require"
# Connection pool options
sqlx-mcp --database-url "postgresql://username:password@localhost:5432/database_name?max_connections=10"
```
### MySQL
```bash
# Standard connection
sqlx-mcp --database-url "mysql://username:password@localhost:3306/database_name"
# With SSL
sqlx-mcp --database-url "mysql://username:password@localhost:3306/database_name?ssl-mode=REQUIRED"
```
### SQLite
```bash
# File database
sqlx-mcp --database-url "sqlite:./database.db"
# In-memory database
sqlx-mcp --database-url "sqlite::memory:"
# With connection options
sqlx-mcp --database-url "sqlite:./database.db?mode=rwc"
```
## 🛠️ Available Tools
The SQLx MCP Server provides 6 powerful tools:
1. **get_database_info** - Get database information and statistics
2. **list_tables** - List all tables with metadata
3. **get_table_structure** - Get detailed table structure
4. **get_table_ddl** - Export table DDL (CREATE statements)
5. **execute_readonly_query** - Execute safe read-only queries
6. **execute_write_query** - Execute write operations
### Tool Usage Examples
#### Get Database Information
```json
{
"name": "get_database_info",
"arguments": {
"database_url": "postgresql://user:pass@localhost/mydb"
}
}
```
#### List Tables
```json
{
"name": "list_tables",
"arguments": {
"database_url": "postgresql://user:pass@localhost/mydb"
}
}
```
#### Execute Read-Only Query
```json
{
"name": "execute_readonly_query",
"arguments": {
"database_url": "postgresql://user:pass@localhost/mydb",
"query": "SELECT COUNT(*) FROM users WHERE created_at > '2024-01-01'"
}
}
```
## 🔒 Security Features
- **Query Validation**: Strict enforcement of read-only queries
- **SQL Injection Protection**: Parameterized queries where possible
- **Connection Security**: SSL/TLS support for all databases
- **Access Control**: Respects database user permissions
## 🚨 Troubleshooting
### Binary Not Found
If you get "Binary not found" errors:
```bash
# Force reinstall to ensure platform packages are installed
npm install --force @sqlx-mcp/sqlx-mcp
# Or install specific platform package manually
npm install @sqlx-mcp/windows-x64 # Windows
npm install @sqlx-mcp/linux-x64 # Linux
npm install @sqlx-mcp/macos-x64 # macOS Intel
npm install @sqlx-mcp/macos-arm64 # macOS Apple Silicon
```
### Permission Issues
On Unix-like systems, ensure the binary has execute permissions:
```bash
# Find the binary location
npm list -g @sqlx-mcp/sqlx-mcp
# Make executable
chmod +x /path/to/global/node_modules/@sqlx-mcp/sqlx-mcp/node_modules/@sqlx-mcp/*/sqlx-mcp
```
### Connection Issues
- Verify database URL format and credentials
- Check if database server is running and accessible
- For SSL connections, ensure certificates are properly configured
- Check firewall settings and network connectivity
## 📚 Additional Resources
- [GitHub Repository](https://github.com/lihongjie0209/sqlx-mcp)
- [Detailed Usage Guide](https://github.com/lihongjie0209/sqlx-mcp/blob/master/README_USAGE.md)
- [Installation & Configuration](https://github.com/lihongjie0209/sqlx-mcp/blob/master/README.md)
- [Issue Tracker](https://github.com/lihongjie0209/sqlx-mcp/issues)
## 🔄 Updates
To update to the latest version:
```bash
# Global installation
npm update -g @sqlx-mcp/sqlx-mcp
# Local installation
npm update @sqlx-mcp/sqlx-mcp
```
Check for available versions:
```bash
npm view @sqlx-mcp/sqlx-mcp versions --json
```
