singlestore-sql-validator

Attention: The code in this repository is intended for experimental use only and is not fully tested, documented, or supported by SingleStore. Visit the SingleStore Forums to ask questions about this repository.

singlestore-sql-validator is a Python library for validating SQL queries using the SingleStore Language Server (version 0.1.3 and later). It provides a convenient interface to check SQL syntax and semantics by communicating with a SingleStore language server instance over TCP or WebSocket (with optional TLS support).

Features

• Validate SQL queries for correctness using SingleStore's language server
• Supports TCP, WS, and WSS (WebSocket Secure) connections
• Flexible connection configuration (host/port or connection string)
• TLS/SSL support for secure connections
• Returns detailed validation results, including error tokens and suggestions

Installation

Install via pip (after cloning or packaging):

pip install singlestore-sql-validator

Or add to your pyproject.toml as a dependency.

Usage

from sql_validator import Validator, ConnectionMode

# Example: Connect using TCP
validator = Validator(
	connection_mode=ConnectionMode.TCP,
	server_host="localhost",
	server_port=9000
)

# Example: Connect using a connection string
# validator = Validator(connection_string="tcp://localhost:9000")

result = validator.validate("SELECT * FROM my_table;")
if result.is_valid:
	print("Query is valid!")
else:
	print(f"Error: {result.error_token} at {result.error_token_position}")
	if result.alternative_tokens:
		print("Suggestions:", result.alternative_tokens)

API

Validator

Initialization

You can initialize a Validator in two ways:

• By specifying connection_mode, server_host, and server_port:

  • connection_mode: ConnectionMode.TCP, ConnectionMode.WS, or ConnectionMode.WSS
  • server_host: Hostname of the language server
  • server_port: Port number
  • tls: Enable TLS (for WSS or secure TCP)
  • tls_ca_file: Path to CA certificate (optional)
  • tls_insecure_skip_verify: Skip TLS verification (optional)

• By providing a connection_string (e.g., tcp://localhost:9000, ws://host:port, wss://host:port)

Methods

• validate(query: str, version: str = "") -> ValidationResult
  • Validates the given SQL query.
  • version (optional): Database version string (format: major.minor.build, or empty/"default").
  • Returns a ValidationResult object.

Static Methods

• _validate_version(version: str) -> bool
  • Checks if the version string matches the required pattern (major.minor.build).

ValidationResult

• is_valid: bool — Whether the query is valid
• error_token: Optional[str] — The token that caused the error (if any)
• error_token_position: Optional[TokenPosition] — Position of the error token
• alternative_tokens: Optional[CompletionList] — Suggestions for fixing the error

Example

from sql_validator import Validator
validator = Validator(connection_string="tcp://localhost:9000")
result = validator.validate("SELECT foo FROM bar;")
if result.is_valid:
	print("Valid!")
else:
	print("Invalid SQL:", result.error_token)

Notes

• This library is intended to be used with a running SingleStore Language Server instance (version 0.1.13 or later).
• It does not start or manage the server process itself.
• Documentation for the SingleStore Language Server can be found at: https://github.com/singlestore-labs/language-server

License

This project is licensed under the terms of the Apache License, Version 2.0.