Configuration Guide

Version: v1.6.0 Last Updated: December 2025

GoSQLX provides a comprehensive configuration system through YAML configuration files.

Quick Start

# Create .gosqlx.yml in your project root
gosqlx config init

# Validate your configuration
gosqlx config validate

# View your current configuration
gosqlx config show

Example Configuration

format:
  indent: 2
  uppercase_keywords: true
  max_line_length: 80

validate:
  dialect: postgresql
  strict_mode: false

output:
  format: auto
  verbose: false

analyze:
  security: true
  performance: true
  complexity: true

Configuration Schema

Complete Structure

format:
  indent: <int>                 # Indentation size (0-8)
  uppercase_keywords: <bool>    # Convert keywords to uppercase
  max_line_length: <int>        # Maximum line length (0-500)
  compact: <bool>               # Use compact formatting

validate:
  dialect: <string>             # SQL dialect
  strict_mode: <bool>           # Enable strict validation
  recursive: <bool>             # Recursively process directories
  pattern: <string>             # File pattern for recursive processing
  security:
    max_file_size: <int>        # Maximum file size in bytes

output:
  format: <string>              # Output format
  verbose: <bool>               # Enable verbose output

analyze:
  security: <bool>              # Enable security analysis
  performance: <bool>           # Enable performance analysis
  complexity: <bool>            # Enable complexity analysis
  all: <bool>                   # Enable all analysis features

Configuration Locations & Precedence

GoSQLX searches for configuration files in this order:

1. CLI Flags (highest priority)
2. Current Directory: .gosqlx.yml
3. Home Directory: ~/.gosqlx.yml
4. System-wide: /etc/gosqlx.yml
5. Built-in Defaults (lowest priority)

Default Values

Format Configuration

Validation Configuration

Output Configuration

Analyze Configuration

Configuration Options

Format Options

format.indent

Number of spaces for indentation.

• Range: 0-8
• Default: 2

format:
  indent: 4  # Use 4 spaces

format.uppercase_keywords

Convert SQL keywords to uppercase.

format:
  uppercase_keywords: true  # SELECT, FROM, WHERE
  # or
  uppercase_keywords: false  # select, from, where

format.max_line_length

Maximum line length before wrapping.

• Range: 0-500 (0 = unlimited)
• Default: 80

format:
  max_line_length: 120

format.compact

Use compact formatting with minimal whitespace.

format:
  compact: true

Validation Options

validate.dialect

SQL dialect for validation.

Options: postgresql, mysql, sqlserver, oracle, sqlite, generic

validate:
  dialect: mysql

validate.strict_mode

Enable strict validation mode.

validate:
  strict_mode: true  # Fail on any non-standard SQL

validate.recursive

Recursively process directories.

validate:
  recursive: true
  pattern: "**/*.sql"  # All SQL files in all directories

validate.security.max_file_size

Maximum file size to process (bytes).

validate:
  security:
    max_file_size: 52428800  # 50 MB

Output Options

output.format

Output format for results.

Options: json, yaml, table, tree, auto

output:
  format: json  # For CI/CD pipelines

output.verbose

Enable verbose output.

output:
  verbose: true

Analyze Options

analyze:
  security: true     # SQL injection detection
  performance: true  # Optimization suggestions
  complexity: true   # Complexity metrics
  all: true          # Enable all (overrides above)

CLI Commands

Initialize Configuration

# Create .gosqlx.yml in current directory
gosqlx config init

# Create in specific location
gosqlx config init --path ~/.gosqlx.yml

Validate Configuration

# Validate from default locations
gosqlx config validate

# Validate specific file
gosqlx config validate --file .gosqlx.yml

Show Configuration

# Show current configuration (YAML)
gosqlx config show

# Show as JSON
gosqlx config show --format json

Usage Examples

Example 1: Minimal Development

format:
  indent: 2

validate:
  dialect: postgresql

Example 2: Team Configuration

format:
  indent: 2
  uppercase_keywords: true
  max_line_length: 100

validate:
  dialect: postgresql
  strict_mode: false

output:
  format: table

Example 3: CI/CD Pipeline

format:
  indent: 2
  uppercase_keywords: true

validate:
  dialect: postgresql
  strict_mode: true

output:
  format: json
  verbose: false

analyze:
  all: true

Example 4: Personal Preferences

Store in ~/.gosqlx.yml:

format:
  indent: 4
  uppercase_keywords: false
  compact: true

output:
  verbose: true

Example 5: Enterprise MySQL

format:
  indent: 4
  uppercase_keywords: true
  max_line_length: 120

validate:
  dialect: mysql
  strict_mode: true
  recursive: true
  pattern: "**/*.sql"
  security:
    max_file_size: 52428800

output:
  format: json

analyze:
  all: true

Validation Rules

Format Validation

Dialect Validation

Valid values: postgresql, mysql, sqlserver, oracle, sqlite, generic

Output Format Validation

Valid values: json, yaml, table, tree, auto

Troubleshooting

Configuration File Not Found

# Show which config is being used
gosqlx config show

# Validate your config file
gosqlx config validate --file .gosqlx.yml

YAML Syntax Error

Common mistakes:

# Wrong - missing quotes for glob patterns
validate:
  pattern: **/*.sql  # Error!

# Right - with quotes
validate:
  pattern: "**/*.sql"  # Correct

# Wrong - inconsistent indentation
format:
  indent: 2
 uppercase_keywords: true  # Error!

# Right - consistent indentation
format:
  indent: 2
  uppercase_keywords: true

CLI Flags Not Overriding

CLI flags should always take highest priority:

# Override config file settings
gosqlx format --indent=4 --uppercase=false query.sql

# Or specify explicit config file
gosqlx format --config ~/custom-config.yml query.sql

Best Practices

1. Project Configuration

Store .gosqlx.yml in project root and commit to git:

gosqlx config init
git add .gosqlx.yml
git commit -m "chore: add GoSQLX configuration"

2. Minimal Configuration

Only specify settings that differ from defaults:

# Good - minimal
format:
  indent: 4

validate:
  dialect: mysql

3. Comment Your Configuration

# Team uses 2-space indentation
format:
  indent: 2

# Target PostgreSQL for production
validate:
  dialect: postgresql
  strict_mode: true  # Enforce strict validation in CI/CD

4. Validate Before Committing

gosqlx config validate
gosqlx config show
git add .gosqlx.yml
git commit -m "config: update GoSQLX settings"

Related Documentation

• CLI Guide - Complete CLI reference
• Linting Rules - Linting rules reference
• API Reference - Full API documentation

MCP Server Environment Variables

The gosqlx-mcp server is configured exclusively via environment variables. No YAML config file is used or read. All variables are optional with safe defaults for local development.

Examples

# Local development (all defaults)
gosqlx-mcp

# Custom port
GOSQLX_MCP_PORT=9090 gosqlx-mcp

# Expose to network with auth
GOSQLX_MCP_HOST=0.0.0.0 GOSQLX_MCP_PORT=8080 GOSQLX_MCP_AUTH_TOKEN=my-secret gosqlx-mcp

Notes

• GOSQLX_MCP_AUTH_TOKEN enables bearer token authentication. When set, all requests must include Authorization: Bearer <token>.
• GOSQLX_MCP_PORT rejects out-of-range or non-integer values at startup with a descriptive error.
• MCP server configuration is independent of .gosqlx.yml — the YAML config file is not read by gosqlx-mcp.

See MCP Server Guide for the full startup and auth reference.

Last Updated: December 2025 Version: v1.6.0