feat(transpiler): SQL dialect transpilation API (#449)

Add pkg/transpiler/ package implementing a parse-rewrite-format pipeline for
converting SQL between dialects. Rewrite rules mutate the AST in place and are
composable per dialect pair.

Supported pairs and rules:
- MySQL → PostgreSQL: AUTO_INCREMENT→SERIAL/BIGSERIAL, TINYINT(1)→BOOLEAN
- PostgreSQL → MySQL: SERIAL→INT AUTO_INCREMENT, ILIKE→LOWER() LIKE LOWER()
- PostgreSQL → SQLite: SERIAL/BIGSERIAL→INTEGER, []array types→TEXT

Also exposes gosqlx.Transpile() top-level wrapper and adds
`gosqlx transpile --from <dialect> --to <dialect>` CLI subcommand.

Co-authored-by: Ajit Pratap Singh <ajitpratapsingh@Ajits-Mac-mini-2655.local>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

CHANGELOG.md

@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **SQL Transpilation** (`pkg/transpiler`): New `Transpile(sql, from, to)` function converts SQL between dialects with a composable rewrite-rule pipeline
+  - MySQL → PostgreSQL: `AUTO_INCREMENT` → `SERIAL`/`BIGSERIAL`, `TINYINT(1)` → `BOOLEAN`
+  - PostgreSQL → MySQL: `SERIAL` → `INT AUTO_INCREMENT`, `ILIKE` → `LOWER() LIKE LOWER()`
+  - PostgreSQL → SQLite: `SERIAL`/`BIGSERIAL` → `INTEGER`, array types → `TEXT`
+  - `gosqlx.Transpile()` top-level convenience wrapper
+  - `gosqlx transpile --from <dialect> --to <dialect>` CLI subcommand
 - **MariaDB dialect** (`--dialect mariadb`): New SQL dialect extending MySQL with support for SEQUENCE DDL (`CREATE/DROP/ALTER SEQUENCE` with full option set), temporal tables (`FOR SYSTEM_TIME`, `WITH SYSTEM VERSIONING`, `PERIOD FOR`), and `CONNECT BY` hierarchical queries with `PRIOR`, `START WITH`, and `NOCYCLE`
 
 ## [1.13.0] - 2026-03-20

cmd/gosqlx/cmd/transpile.go

@@ -0,0 +1,113 @@
+// Copyright 2026 GoSQLX Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cmd
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
+	"github.com/ajitpratap0/GoSQLX/pkg/sql/keywords"
+)
+
+var transpileCmd = &cobra.Command{
+	Use:   "transpile [SQL]",
+	Short: "Convert SQL from one dialect to another",
+	Long: `Transpile SQL between dialects.
+
+Supported dialect pairs:
+  mysql     → postgres
+  postgres  → mysql
+  postgres  → sqlite
+
+SQL can be provided as a positional argument or piped via stdin.
+
+Examples:
+  gosqlx transpile --from mysql --to postgres "CREATE TABLE t (id INT AUTO_INCREMENT PRIMARY KEY)"
+  echo "SELECT * FROM users WHERE name ILIKE '%alice%'" | gosqlx transpile --from postgres --to mysql
+  gosqlx transpile --from postgres --to sqlite "CREATE TABLE t (id SERIAL PRIMARY KEY, tags TEXT)"`,
+	Args: cobra.MaximumNArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		fromStr, _ := cmd.Flags().GetString("from")
+		toStr, _ := cmd.Flags().GetString("to")
+
+		from, err := parseDialectFlag(fromStr)
+		if err != nil {
+			return fmt.Errorf("--from: %w", err)
+		}
+		to, err := parseDialectFlag(toStr)
+		if err != nil {
+			return fmt.Errorf("--to: %w", err)
+		}
+
+		var sql string
+		if len(args) > 0 {
+			sql = args[0]
+		} else {
+			// Read from stdin.
+			data, readErr := io.ReadAll(os.Stdin)
+			if readErr != nil {
+				return fmt.Errorf("reading stdin: %w", readErr)
+			}
+			sql = strings.TrimSpace(string(data))
+		}
+
+		if sql == "" {
+			return fmt.Errorf("no SQL provided: pass as argument or via stdin")
+		}
+
+		result, err := gosqlx.Transpile(sql, from, to)
+		if err != nil {
+			return fmt.Errorf("transpile: %w", err)
+		}
+		fmt.Println(result)
+		return nil
+	},
+}
+
+func init() {
+	transpileCmd.Flags().String("from", "mysql", "Source dialect (mysql, postgres, sqlite, sqlserver, oracle, snowflake, clickhouse, mariadb)")
+	transpileCmd.Flags().String("to", "postgres", "Target dialect (mysql, postgres, sqlite, sqlserver, oracle, snowflake, clickhouse, mariadb)")
+	rootCmd.AddCommand(transpileCmd)
+}
+
+// parseDialectFlag converts a dialect name string to a keywords.SQLDialect value.
+func parseDialectFlag(s string) (keywords.SQLDialect, error) {
+	switch strings.ToLower(s) {
+	case "mysql":
+		return keywords.DialectMySQL, nil
+	case "postgres", "postgresql":
+		return keywords.DialectPostgreSQL, nil
+	case "sqlite":
+		return keywords.DialectSQLite, nil
+	case "sqlserver", "mssql":
+		return keywords.DialectSQLServer, nil
+	case "oracle":
+		return keywords.DialectOracle, nil
+	case "snowflake":
+		return keywords.DialectSnowflake, nil
+	case "clickhouse":
+		return keywords.DialectClickHouse, nil
+	case "mariadb":
+		return keywords.DialectMariaDB, nil
+	default:
+		return keywords.DialectGeneric, fmt.Errorf(
+			"unknown dialect %q; valid: mysql, postgres, sqlite, sqlserver, oracle, snowflake, clickhouse, mariadb", s)
+	}
+}

pkg/gosqlx/gosqlx.go

@@ -26,6 +26,7 @@ import (
 	"github.com/ajitpratap0/GoSQLX/pkg/sql/keywords"
 	"github.com/ajitpratap0/GoSQLX/pkg/sql/parser"
 	"github.com/ajitpratap0/GoSQLX/pkg/sql/tokenizer"
+	"github.com/ajitpratap0/GoSQLX/pkg/transpiler"
 )
 
 // Version is the current GoSQLX library version.
@@ -657,3 +658,25 @@ func Normalize(sql string) (string, error) {
 func Fingerprint(sql string) (string, error) {
 	return fingerprint.Fingerprint(sql)
 }
+
+// Transpile converts SQL from one dialect to another.
+//
+// Supported dialect pairs:
+//   - MySQL → PostgreSQL  (AUTO_INCREMENT→SERIAL, TINYINT(1)→BOOLEAN)
+//   - PostgreSQL → MySQL  (SERIAL→AUTO_INCREMENT, ILIKE→LOWER() LIKE LOWER())
+//   - PostgreSQL → SQLite (SERIAL→INTEGER, array types→TEXT)
+//
+// For unsupported dialect pairs the SQL is parsed and reformatted without any
+// dialect-specific rewrites (passthrough with normalisation).
+//
+// Example:
+//
+//	result, err := gosqlx.Transpile(
+//	    "CREATE TABLE t (id INT AUTO_INCREMENT PRIMARY KEY)",
+//	    keywords.DialectMySQL,
+//	    keywords.DialectPostgreSQL,
+//	)
+//	// result: "CREATE TABLE t (id SERIAL PRIMARY KEY)"
+func Transpile(sql string, from, to keywords.SQLDialect) (string, error) {
+	return transpiler.Transpile(sql, from, to)
+}

pkg/gosqlx/transpile_test.go

@@ -0,0 +1,55 @@
+// Copyright 2026 GoSQLX Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package gosqlx_test
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
+	"github.com/ajitpratap0/GoSQLX/pkg/sql/keywords"
+)
+
+func TestGoSQLX_Transpile_BasicSelect(t *testing.T) {
+	sql := "SELECT id, name FROM users WHERE id = 1"
+	result, err := gosqlx.Transpile(sql, keywords.DialectMySQL, keywords.DialectPostgreSQL)
+	if err != nil {
+		t.Fatalf("Transpile: %v", err)
+	}
+	if result == "" {
+		t.Error("expected non-empty result")
+	}
+	if !strings.Contains(strings.ToUpper(result), "SELECT") {
+		t.Errorf("result should contain SELECT, got: %s", result)
+	}
+}
+
+func TestGoSQLX_Transpile_InvalidSQL(t *testing.T) {
+	_, err := gosqlx.Transpile("NOT VALID", keywords.DialectMySQL, keywords.DialectPostgreSQL)
+	if err == nil {
+		t.Fatal("expected error for invalid SQL")
+	}
+}
+
+func TestGoSQLX_Transpile_AutoIncrementToSerial(t *testing.T) {
+	sql := "CREATE TABLE users (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255))"
+	result, err := gosqlx.Transpile(sql, keywords.DialectMySQL, keywords.DialectPostgreSQL)
+	if err != nil {
+		t.Fatalf("Transpile: %v", err)
+	}
+	if !strings.Contains(strings.ToUpper(result), "SERIAL") {
+		t.Errorf("expected SERIAL in output, got: %s", result)
+	}
+}

pkg/transpiler/dialect_rules.go

@@ -0,0 +1,64 @@
+// Copyright 2026 GoSQLX Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package transpiler
+
+import (
+	"github.com/ajitpratap0/GoSQLX/pkg/sql/keywords"
+	"github.com/ajitpratap0/GoSQLX/pkg/transpiler/rules"
+)
+
+type dialectPair struct {
+	from, to keywords.SQLDialect
+}
+
+var ruleRegistry = map[dialectPair][]RewriteRule{}
+
+func init() {
+	register(keywords.DialectMySQL, keywords.DialectPostgreSQL,
+		rules.MySQLAutoIncrementToSerial,
+		rules.MySQLBacktickToDoubleQuote,
+		rules.MySQLLimitCommaToOffset,
+		rules.MySQLBooleanToPgBool,
+	)
+	register(keywords.DialectPostgreSQL, keywords.DialectMySQL,
+		rules.PgSerialToAutoIncrement,
+		rules.PgDoubleQuoteToBacktick,
+		rules.PgILikeToLower,
+	)
+	register(keywords.DialectPostgreSQL, keywords.DialectSQLite,
+		rules.PgSerialToIntegerPK,
+		rules.PgArrayToJSON,
+	)
+}
+
+func register(from, to keywords.SQLDialect, rs ...RewriteRule) {
+	key := dialectPair{from, to}
+	ruleRegistry[key] = append(ruleRegistry[key], rs...)
+}
+
+// RulesFor returns the registered rewrite rules for a dialect pair.
+// Returns nil (empty) for unregistered or same-dialect pairs.
+// Exported for testing.
+func RulesFor(from, to keywords.SQLDialect) []RewriteRule {
+	if from == to {
+		return nil
+	}
+	return ruleRegistry[dialectPair{from, to}]
+}
+
+// rulesFor is the internal version used by Transpile.
+func rulesFor(from, to keywords.SQLDialect) []RewriteRule {
+	return RulesFor(from, to)
+}

pkg/transpiler/dialect_rules_test.go

@@ -0,0 +1,42 @@
+// Copyright 2026 GoSQLX Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package transpiler_test
+
+import (
+	"testing"
+
+	"github.com/ajitpratap0/GoSQLX/pkg/sql/keywords"
+	"github.com/ajitpratap0/GoSQLX/pkg/transpiler"
+)
+
+func TestRulesFor_MySQLToPostgres_NonEmpty(t *testing.T) {
+	rules := transpiler.RulesFor(keywords.DialectMySQL, keywords.DialectPostgreSQL)
+	if len(rules) == 0 {
+		t.Error("expected at least one rule for MySQL→PostgreSQL")
+	}
+}
+
+func TestRulesFor_SameDialect_Empty(t *testing.T) {
+	rules := transpiler.RulesFor(keywords.DialectPostgreSQL, keywords.DialectPostgreSQL)
+	if len(rules) != 0 {
+		t.Errorf("expected no rules for same dialect, got %d", len(rules))
+	}
+}
+
+func TestRulesFor_UnregisteredPair_Empty(t *testing.T) {
+	rules := transpiler.RulesFor(keywords.DialectOracle, keywords.DialectClickHouse)
+	// Unknown pair → no rules (passthrough).
+	_ = rules // should be 0 length, no panic
+}