singlestore-sql-validator 0.0.3

SQL grammar validator for SingleStore queries

singlestore-sql-validator

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.3 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.