Metadata-Version: 2.4
Name: singlestore-sql-validator
Version: 0.1.0
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

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

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

