GoSQLX Language Server Protocol (LSP) Guide

Version: v1.6.0 Last Updated: December 2025

Table of Contents

1. Overview
2. Quick Start
3. Starting the LSP Server
4. Supported Features
5. IDE Integration
6. Error Codes
7. Configuration
8. Performance
9. Troubleshooting

Overview

The GoSQLX Language Server Protocol (LSP) implementation provides real-time SQL validation, formatting, code completion, hover documentation, and code intelligence features for IDEs and text editors.

Key Features

• Real-time Diagnostics: Syntax error detection with precise error positions
• Code Completion: 100+ SQL keywords, functions, and 23 snippet templates
• Hover Documentation: Inline help for 70+ SQL keywords
• Document Formatting: Intelligent SQL formatting with configurable options
• Document Symbols: Navigation through SQL statements
• Signature Help: Function parameter documentation for 15+ SQL functions
• Code Actions: Quick fixes for common SQL issues
• Rate Limiting: Protection against DoS (100 requests/sec)

Quick Start

Command Line

# Start LSP server on stdio
gosqlx lsp

# Start with debug logging
gosqlx lsp --log /tmp/gosqlx-lsp.log

# Verify installation
gosqlx lsp --help

Within Go Code

import "github.com/ajitpratap0/GoSQLX/pkg/lsp"

// Create stdio server
server := lsp.NewStdioServer(logger)
err := server.Run()

Starting the LSP Server

Standard Input/Output

The server communicates via LSP protocol on stdin/stdout:

# Start server
gosqlx lsp

# With logging for debugging
gosqlx lsp --log /tmp/gosqlx-lsp.log

Process Lifecycle

1. Client connects via stdin/stdout
2. Client sends 'initialize' request
3. Server responds with capabilities
4. Client sends 'initialized' notification
5. Client sends document notifications (didOpen, didChange, etc.)
6. Server sends diagnostics and responses
7. Client sends 'shutdown' request
8. Client sends 'exit' notification
9. Server exits gracefully

Supported Features

1. Text Document Synchronization

Sync Mode: Incremental (full and partial updates)

{
  "method": "textDocument/didOpen",
  "params": {
    "textDocument": {
      "uri": "file:///path/to/query.sql",
      "languageId": "sql",
      "version": 1,
      "text": "SELECT * FROM users WHERE id = 1"
    }
  }
}

2. Diagnostics

Severity Levels:

• 1 = Error
• 2 = Warning
• 3 = Information
• 4 = Hint

Document Limits:

• Maximum 5MB per document
• Maximum 10MB per message

3. Code Completion

Trigger Characters: (space), . (dot), ( (paren)

Completion Types:

• Keywords: SELECT, FROM, WHERE, JOIN, etc. (90+ keywords)
• Functions: Aggregate and window functions
• Snippets: 23 SQL pattern templates

Available Snippets:

4. Hover Documentation

Markdown documentation for 70+ SQL keywords including:

• Clauses: SELECT, FROM, WHERE, GROUP BY, ORDER BY, HAVING
• Joins: JOIN, LEFT, RIGHT, INNER, OUTER, CROSS
• Operators: AND, OR, NOT, IN, BETWEEN, LIKE
• DDL: CREATE, DROP, ALTER, TRUNCATE
• Window functions: ROW_NUMBER, RANK, DENSE_RANK, LAG, LEAD

5. Document Formatting

Options:

{
  "tabSize": 2,
  "insertSpaces": true,
  "insertFinalNewline": true,
  "trimTrailingWhitespace": true
}

6. Document Symbols

Lists all SQL statements with categorization:

• Method (DML: SELECT, INSERT, UPDATE, DELETE)
• Struct (DDL: CREATE, DROP, ALTER)

7. Signature Help

Trigger Characters: ( and ,

Function documentation for:

• Aggregates: COUNT, SUM, AVG, MIN, MAX
• String: COALESCE, NULLIF, CAST, SUBSTRING, TRIM
• Window: ROW_NUMBER, RANK, DENSE_RANK, LAG, LEAD, NTILE

8. Code Actions

Quick fixes for common issues:

• Add missing semicolon
• Keyword case conversion

IDE Integration

Visual Studio Code

Install the official GoSQLX VSCode extension from the marketplace, or configure manually:

{
  "gosqlx.lsp.enable": true,
  "gosqlx.lsp.path": "gosqlx",
  "[sql]": {
    "editor.defaultFormatter": "gosqlx.formatter",
    "editor.formatOnSave": true
  }
}

Neovim

Using nvim-lspconfig:

require('lspconfig.configs').gosqlx = {
  default_config = {
    cmd = { 'gosqlx', 'lsp' },
    filetypes = { 'sql' },
    root_dir = function() return vim.fn.getcwd() end,
  },
}

require('lspconfig').gosqlx.setup{
  on_attach = function(client, bufnr)
    vim.keymap.set('n', 'K', vim.lsp.buf.hover, { noremap = true })
    vim.keymap.set('n', '<leader>ca', vim.lsp.buf.code_action, { noremap = true })
  end
}

Emacs

Using lsp-mode:

(lsp-register-client
 (make-lsp-client
  :new-connection (lsp-stdio-connection '("gosqlx" "lsp"))
  :major-modes '(sql-mode)
  :server-id 'gosqlx))

(add-hook 'sql-mode-hook #'lsp)

Using eglot:

(add-to-list 'eglot-server-programs
             '(sql-mode . ("gosqlx" "lsp")))

(add-hook 'sql-mode-hook #'eglot-ensure)

Sublime Text

{
  "lsp_servers": {
    "gosqlx": {
      "command": ["gosqlx", "lsp"],
      "languages": [
        {
          "languageId": "sql",
          "scopes": ["source.sql"],
          "syntaxes": ["Packages/SQL/SQL.sublime-syntax"]
        }
      ]
    }
  }
}

Error Codes

Tokenizer Errors (E1xxx)

Parser Errors (E2xxx)

Semantic Errors (E3xxx)

Configuration

Server Capabilities

{
  "capabilities": {
    "textDocumentSyncOptions": {
      "openClose": true,
      "change": 2,
      "save": {"includeText": true}
    },
    "completionProvider": {
      "triggerCharacters": [" ", ".", "("]
    },
    "hoverProvider": true,
    "documentFormattingProvider": true,
    "documentSymbolProvider": true,
    "signatureHelpProvider": {
      "triggerCharacters": ["(", ","]
    },
    "codeActionProvider": {
      "codeActionKinds": ["quickfix"]
    }
  }
}

Server Limits

Performance

Throughput

• Message Processing: 100+ concurrent requests/sec
• Latency: <100ms for most operations
• Token Processing: 8M+ tokens/sec (underlying parser)

Memory Usage

• Per Document: ~10KB baseline + document size
• Per Connection: ~1MB for internal buffers
• Pool Efficiency: 95%+ hit rate

Troubleshooting

Server Won’t Start

# Check installation
which gosqlx

# Reinstall if needed
go install github.com/ajitpratap0/GoSQLX/cmd/gosqlx@latest

# Test with logging
gosqlx lsp --log /tmp/test.log
cat /tmp/test.log

IDE Can’t Connect

# Verify gosqlx command exists
command -v gosqlx

# Test LSP protocol
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | gosqlx lsp

No Diagnostics

1. Verify document is under 5MB
2. Check for syntax errors preventing parsing
3. Enable logging: gosqlx lsp --log /tmp/lsp.log
4. Check log for diagnostic messages

Debug Mode

# Enable detailed logging
gosqlx lsp --log /tmp/gosqlx-lsp.log

# Monitor real-time
tail -f /tmp/gosqlx-lsp.log | grep -E "Initialize|Document|Diagnostic"

Resources

• Repository: https://github.com/ajitpratap0/GoSQLX
• Issues: https://github.com/ajitpratap0/GoSQLX/issues
• Discussions: https://github.com/ajitpratap0/GoSQLX/discussions
• LSP Specification: https://microsoft.github.io/language-server-protocol/

Last Updated: December 2025 Version: v1.6.0