https://github.com/h22rana/jsonlogic2sql
JSON Logic to SQL Transpiler
https://github.com/h22rana/jsonlogic2sql
go golang jsonlogic sql transpilation transpiler
Last synced: about 19 hours ago
JSON representation
JSON Logic to SQL Transpiler
- Host: GitHub
- URL: https://github.com/h22rana/jsonlogic2sql
- Owner: h22rana
- License: mit
- Created: 2025-10-15T03:58:07.000Z (6 months ago)
- Default Branch: master
- Last Pushed: 2026-03-27T06:43:16.000Z (6 days ago)
- Last Synced: 2026-03-27T07:53:06.333Z (6 days ago)
- Topics: go, golang, jsonlogic, sql, transpilation, transpiler
- Language: Go
- Homepage:
- Size: 77 MB
- Stars: 6
- Watchers: 0
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# JSON Logic to SQL Transpiler
A Go library that converts JSON Logic expressions into SQL. This library provides a clean, type-safe API for transforming JSON Logic rules into SQL WHERE clauses or standalone conditions, with support for multiple SQL dialects.
## Features
- **Complete JSON Logic Support**: Implements all core JSON Logic operators
- **SQL Dialect Support**: Target BigQuery, Spanner, PostgreSQL, DuckDB, or ClickHouse
- **Parameterized Queries**: Generate SQL with bind placeholders (`@p1`, `$1`) and separate parameter values for safe execution
- **Custom Operators**: Extensible registry pattern for custom SQL functions
- **Schema Validation**: Optional field schema for strict column validation
- **Structured Errors**: Error codes and JSONPath locations for debugging
- **Library & CLI**: Both programmatic API and interactive REPL
## Quick Start
```bash
go get github.com/h22rana/jsonlogic2sql@latest
```
### Inline SQL
```go
package main
import (
"fmt"
"github.com/h22rana/jsonlogic2sql"
)
func main() {
sql, err := jsonlogic2sql.Transpile(
jsonlogic2sql.DialectBigQuery,
`{">": [{"var": "amount"}, 1000]}`,
)
if err != nil {
panic(err)
}
fmt.Println(sql) // Output: WHERE amount > 1000
}
```
### Parameterized Queries
```go
package main
import (
"fmt"
"github.com/h22rana/jsonlogic2sql"
)
func main() {
sql, params, err := jsonlogic2sql.TranspileParameterized(
jsonlogic2sql.DialectBigQuery,
`{"and": [{"==": [{"var": "status"}, "active"]}, {">": [{"var": "amount"}, 1000]}]}`,
)
if err != nil {
panic(err)
}
fmt.Println(sql) // Output: WHERE (status = @p1 AND amount > @p2)
fmt.Println(params) // Output: [{p1 active} {p2 1000}]
}
```
## Supported Operators
| Category | Operators |
|----------|-----------|
| **Data Access** | `var`, `missing`, `missing_some` |
| **Comparison** | `==`, `===`, `!=`, `!==`, `>`, `>=`, `<`, `<=` |
| **Logical** | `and`, `or`, `!`, `!!`, `if` |
| **Numeric** | `+`, `-`, `*`, `/`, `%`, `max`, `min` |
| **Array** | `in`, `map`, `filter`, `reduce`, `all`, `some`, `none`, `merge` |
| **String** | `in`, `cat`, `substr` |
## Supported Dialects
| Dialect | Constant |
|---------|----------|
| Google BigQuery | `DialectBigQuery` |
| Google Cloud Spanner | `DialectSpanner` |
| PostgreSQL | `DialectPostgreSQL` |
| DuckDB | `DialectDuckDB` |
| ClickHouse | `DialectClickHouse` |
## Documentation
- [Getting Started](docs/getting-started.md) - Installation and basic usage
- [Parameterized Queries](docs/parameterized-queries.md) - Bind-parameter output for safe SQL execution
- [Operators](docs/operators.md) - All supported operators with examples
- [SQL Dialects](docs/dialects.md) - Dialect-specific SQL generation
- [Custom Operators](docs/custom-operators.md) - Extend with your own operators
- [Schema Validation](docs/schema-validation.md) - Field validation and type checking
- [Examples](docs/examples.md) - Comprehensive examples
- [API Reference](docs/api-reference.md) - Full API documentation
- [Error Handling](docs/error-handling.md) - Error codes and programmatic handling
- [Development](docs/development.md) - Contributing and development guide
- [REPL](docs/repl.md) - Interactive testing tool
- [WASM Playground](docs/wasm-playground.md) - Browser-based demo via WebAssembly
## Important Notes
> **Semantic Correctness Assumption:** This library assumes that the input JSONLogic is semantically correct. The transpiler generates SQL that directly corresponds to the JSONLogic structure without validating the logical correctness of the expressions.
> **SQL Injection:** This library includes hardening measures against SQL injection - identifier names are validated against a whitelist pattern, string literals are escaped, and numeric string operands are safely coerced. For maximum safety, use the [parameterized query API](docs/parameterized-queries.md) which generates SQL with bind placeholders instead of inlined literals.
## Interactive REPL
```bash
make run
```
```
[BigQuery] jsonlogic> {">": [{"var": "amount"}, 1000]}
SQL: WHERE amount > 1000
[BigQuery] jsonlogic> :params
Parameterized mode: ON (output uses bind placeholders)
[BigQuery] jsonlogic> {"==": [{"var": "status"}, "active"]}
SQL: WHERE status = @p1
Params: [{p1: "active"}]
[BigQuery] jsonlogic> :dialect
Select dialect: PostgreSQL
[PostgreSQL] jsonlogic> {"merge": [{"var": "a"}, {"var": "b"}]}
SQL: WHERE (a || b)
```
## Development
```bash
make test # Run all tests (3,000+ test cases)
make bench # Run benchmarks
make build # Build REPL binary
make build/wasm # Build WASM binary for browser playground
make lint # Run linter
make run # Run REPL
```
## License
This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.