SQL Language Server

Common errors

• Error: Column 'column_name' not found in table 'table_name'

  cause The language server's internal schema cache is outdated or incorrect for the current database connection or SQL dialect being used.
  fix Ensure the `sql-language-server` is correctly configured with the database connection details (e.g., PostgreSQL, SQLite). Manually trigger a schema refresh or restart the language server if the database schema has recently changed.

• Failed to resolve root path config

  cause The language server could not correctly determine its root directory or configuration files, often due to an incorrect working directory or misconfigured client-side settings.
  fix Ensure the language server is launched from the correct working directory that contains your SQL project. Verify client-side LSP configurations that specify the `rootPath` or `workspaceFolders` are pointing to valid directories.

• Syntax error near 'IS NOT NULL' operation.

  cause Older versions of the parser had a bug in correctly handling the right-hand side of `IS NOT NULL` operations.
  fix Upgrade to `sql-language-server` version 1.6.0 or newer, which contains a fix for this specific parsing error. If upgrading isn't an option, rephrase the SQL query to avoid the problematic `IS NOT NULL` pattern if possible.

Warnings

• breaking Upgrading `vscode-languageserver` to version `8.0.0-next.8` in v1.2.1 may introduce breaking changes or require compatibility adjustments for host environments or custom LSP clients relying on older `vscode-languageserver` API contracts.
  Fix: Review the `vscode-languageserver` changelog for `8.0.0-next.8` and update any custom client or host code that directly interacts with the LSP client/server libraries to ensure compatibility with the new API.
• gotcha Prior to v1.3.0, the server could be inadvertently booted twice in certain integration scenarios, leading to unexpected behavior or resource consumption issues.
  Fix: Upgrade to v1.3.0 or newer to benefit from the fix addressing the double-boot issue. Ensure proper lifecycle management of the server process within your LSP host environment.
• gotcha Older versions (pre-1.2.1) had issues correctly parsing SQL identifiers enclosed in double quotes, leading to incorrect linting or autocompletion.
  Fix: Upgrade to v1.2.1 or newer to resolve issues with double-quoted identifiers. Ensure your SQL parser configuration is up-to-date with the latest version's parsing capabilities.
• gotcha Version 1.3.3 introduced a change to 'not throw an error when it's failed to parse'. While this improves resilience, it might mask underlying syntax issues if clients rely on explicit parse errors for strict validation.
  Fix: Implement robust client-side validation or interpret diagnostics provided by the language server. Do not assume the absence of an error throw implies completely successful parsing in all contexts; instead, rely on the diagnostic messages provided by the LSP.

Install

• npm install sql-language-server npm
• yarn add sql-language-server yarn
• pnpm add sql-language-server pnpm

Imports

• Config

  import type { Config } from 'sql-language-server'

  Primarily an executable server. This type defines configuration options sent from the client to the server and is used for type checking client-side configurations. Direct programmatic import of server logic is not the primary use case.
• SQLOption

  import type { SQLOption } from 'sql-language-server'

  Primarily an executable server. This type defines specific SQL-related options within the server configuration. Used for type checking client-side configurations rather than direct library usage.
• LSP_SERVER_NAME

  import { LSP_SERVER_NAME } from 'sql-language-server'

  Primarily an executable server. This constant provides the name identifier for the language server. While exported, the main interaction is running the server, not importing this constant into an application.

Quickstart

Demonstrates how to install the SQL Language Server globally and run it via standard I/O. Includes a commented example of how an LSP client in a VS Code extension might programmatically start and connect to the server process.

npm install -g sql-language-server

# To run the language server, typically it's invoked by an LSP-enabled editor
# or manually via standard I/O (stdio) for debugging/testing:
sql-language-server --stdio

# Example of how an LSP client (e.g., in a VS Code extension) might start it:
// In a client-side extension's activate() function:
// import * as path from 'path';
// import { LanguageClient, LanguageClientOptions, ServerOptions, TransportKind } from 'vscode-languageclient/node';

// let serverModule = context.asAbsolutePath(path.join('node_modules', 'sql-language-server', 'lib', 'main.js'));
// let debugOptions = { execArgv: ['--nolazy', '--inspect=6009'] };

// let serverOptions: ServerOptions = {
// 	run: { module: serverModule, transport: TransportKind.stdio },
// 	debug: { module: serverModule, transport: TransportKind.stdio, options: debugOptions }
// };

// let clientOptions: LanguageClientOptions = {
// 	documentSelector: [{ scheme: 'file', language: 'sql' }],
// 	synchronize: { fileEvents: workspace.createFileSystemWatcher('**/.sql') }
// };

// let client = new LanguageClient('sqlLanguageServer', 'SQL Language Server', serverOptions, clientOptions);
// client.start();