Metadata-Version: 2.4
Name: singlestore-sql-validator
Version: 0.0.3
Summary: SQL grammar validator for SingleStore queries
License: Apache License (2.0)
License-File: LICENSE
Author: Volodymyr Tkachuk
Author-email: vtkachuk-ua@singlestore.com
Requires-Python: >=3.10,<4.0
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: websockets (>=16.0,<17.0)
Project-URL: Homepage, https://github.com/singlestore-labs/sql-validator-python
Project-URL: Issues, https://github.com/singlestore-labs/sql-validator-python/issues
Description-Content-Type: text/markdown

# 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):

```bash
pip install singlestore-sql-validator
```

Or add to your `pyproject.toml` as a dependency.

## Usage

```python
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

```python
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](https://github.com/singlestore-labs/language-server)

## License

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

