Migrating from pg_query to GoSQLX

Last Updated: 2025-11-05

This guide helps you migrate from pg_query (PostgreSQL’s official parser wrapper) to GoSQLX, covering multi-dialect support, performance improvements, and practical migration strategies.

Table of Contents

• Overview Comparison
• Why Migrate to GoSQLX?
• Feature Mapping
• Side-by-Side Code Examples
• Common Patterns Translation
• Performance Comparison
• Migration Checklist
• Real Migration Case Study
• Known Limitations
• Getting Help

Overview Comparison

pg_query

pg_query wraps PostgreSQL’s official SQL parser (libpg_query) via FFI, providing bindings for multiple languages.

Key Strengths:

• 100% PostgreSQL compliance (uses official parser)
• Latest PostgreSQL features immediately available
• Trusted by production systems (sqlc, GitLab, DuckDB)
• Available for Ruby, Go, Python, Node.js, Rust
• Parses PL/pgSQL correctly

Key Weaknesses:

• PostgreSQL-only (no MySQL, SQL Server, Oracle, SQLite)
• C dependency (libpg_query) - complex builds
• FFI overhead for cross-language calls
• Larger binary size (includes PostgreSQL parser)
• Limited by FFI for concurrency scaling

GoSQLX

GoSQLX is a production-ready, race-free, high-performance SQL parsing SDK written entirely in Go.

Key Strengths:

• Multi-dialect support (PostgreSQL, MySQL, SQL Server, Oracle, SQLite)
• Pure Go (zero C dependencies, easier deployment)
• Blazing fast (1.38M+ ops/sec - 14x faster!)
• Native Go concurrency (linear scaling)
• Smaller binary size (no embedded parser)
• Easier to extend and customize

Key Trade-offs:

• ~80-85% PostgreSQL coverage (vs 100% from official parser)
• Slightly behind latest PostgreSQL features
• Different AST structure (simpler but non-standard)
• Less battle-tested than official PostgreSQL parser

Why Migrate to GoSQLX?

You Should Migrate If:

✅ You need multi-dialect support

• Supporting PostgreSQL + MySQL/SQL Server/Oracle/SQLite
• Database migration tools
• Cross-database SQL analysis
• Multi-tenant systems with different databases

✅ You want pure Go

• No C dependencies (easier builds)
• Cross-compilation friendly
• Simpler deployment (single binary)
• Better integration with Go ecosystem

✅ Performance is critical

• Need to parse millions of queries per second
• Real-time SQL validation
• High-concurrency workloads
• Memory-constrained environments

✅ You want simpler AST

• PostgreSQL’s AST is complex and verbose
• GoSQLX provides cleaner, easier-to-use structures
• Faster to implement custom logic

You Should Stay with pg_query If:

❌ You need 100% PostgreSQL compliance (official parser guarantee) ❌ You need latest PostgreSQL features immediately on release ❌ You heavily use PL/pgSQL (stored procedures, triggers) ❌ You trust only official parsers (regulatory/compliance)

Feature Mapping

Side-by-Side Code Examples

Example 1: Basic Parsing

pg_query (Go)

// go get github.com/pganalyze/pg_query_go/v4
package main

import (
    "fmt"
    "github.com/pganalyze/pg_query_go/v4"
)

func main() {
    sql := "SELECT * FROM users WHERE active = true"

    // Parse SQL (calls C library via FFI)
    result, err := pg_query.Parse(sql)
    if err != nil {
        panic(err)
    }

    // Access PostgreSQL AST (complex structure)
    fmt.Printf("Parsed %d statements\n", len(result.Stmts))

    // Get normalized query
    normalized, err := pg_query.Normalize(sql)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Normalized: %s\n", normalized)
}

GoSQLX (Go)

// go get github.com/ajitpratap0/GoSQLX
package main

import (
    "fmt"
    "github.com/ajitpratap0/GoSQLX/pkg/sql/tokenizer"
    "github.com/ajitpratap0/GoSQLX/pkg/sql/parser"
)

func main() {
    sql := "SELECT * FROM users WHERE active = true"

    // Tokenize (pure Go, no FFI)
    tkz := tokenizer.GetTokenizer()
    defer tokenizer.PutTokenizer(tkz)

    tokens, err := tkz.Tokenize([]byte(sql))
    if err != nil {
        panic(err)
    }

    // Convert tokens for parser
    p := parser.NewParser()
    defer p.Release()
    if err != nil {
        panic(err)
    }

    // Parse to AST (simpler structure)
    p := parser.NewParser()
    defer p.Release()

    ast, err := p.ParseFromModelTokens(tokens)
    if err != nil {
        panic(err)
    }

    fmt.Printf("Parsed %d statements\n", len(ast.Statements))
}

Example 2: Query Normalization

pg_query (Go)

package main

import (
    "fmt"
    "github.com/pganalyze/pg_query_go/v4"
)

func main() {
    // Original queries with different values
    sql1 := "SELECT * FROM users WHERE id = 123"
    sql2 := "SELECT * FROM users WHERE id = 456"

    // Normalize (built-in feature)
    norm1, _ := pg_query.Normalize(sql1)
    norm2, _ := pg_query.Normalize(sql2)

    // Both normalize to same pattern
    fmt.Println(norm1) // SELECT * FROM users WHERE id = $1
    fmt.Println(norm2) // SELECT * FROM users WHERE id = $1
    fmt.Println(norm1 == norm2) // true

    // Get fingerprint for deduplication
    fp1, _ := pg_query.Fingerprint(sql1)
    fp2, _ := pg_query.Fingerprint(sql2)
    fmt.Println(fp1 == fp2) // true (same query pattern)
}

GoSQLX (Go)

package main

import (
    "fmt"
    "github.com/ajitpratap0/GoSQLX/pkg/sql/tokenizer"
    "github.com/ajitpratap0/GoSQLX/pkg/models"
)

func main() {
    sql1 := "SELECT * FROM users WHERE id = 123"
    sql2 := "SELECT * FROM users WHERE id = 456"

    // Normalize manually (no built-in feature yet)
    norm1 := normalizeQuery(sql1)
    norm2 := normalizeQuery(sql2)

    fmt.Println(norm1) // SELECT * FROM users WHERE id = ?
    fmt.Println(norm2) // SELECT * FROM users WHERE id = ?
    fmt.Println(norm1 == norm2) // true
}

func normalizeQuery(sql string) string {
    tkz := tokenizer.GetTokenizer()
    defer tokenizer.PutTokenizer(tkz)

    tokens, _ := tkz.Tokenize([]byte(sql))

    // Replace literals with placeholders
    var result string
    for _, tok := range tokens {
        switch tok.Token.Type {
        case models.TokenTypeNumber, models.TokenTypeString:
            result += "?"
        default:
            result += tok.Token.Value
        }
        result += " "
    }

    return result
}

// Note: Built-in normalization is planned for a future release

Example 3: Multi-Dialect Support

pg_query (Go) - PostgreSQL Only

package main

import (
    "fmt"
    "github.com/pganalyze/pg_query_go/v4"
)

func main() {
    // PostgreSQL syntax works
    pgSQL := "SELECT * FROM users WHERE data @> '{\"active\": true}'"
    _, err := pg_query.Parse(pgSQL)
    fmt.Println("PostgreSQL:", err == nil) // true

    // MySQL syntax fails (not supported)
    mySQL := "SELECT * FROM users WHERE id = 1 LIMIT 10, 20"
    _, err = pg_query.Parse(mySQL)
    fmt.Println("MySQL:", err == nil) // false

    // SQL Server syntax fails (not supported)
    tsql := "SELECT TOP 10 * FROM users"
    _, err = pg_query.Parse(tsql)
    fmt.Println("SQL Server:", err == nil) // false
}

GoSQLX (Go) - Multi-Dialect

package main

import (
    "fmt"
    "github.com/ajitpratap0/GoSQLX/pkg/sql/tokenizer"
)

func main() {
    tkz := tokenizer.GetTokenizer()
    defer tokenizer.PutTokenizer(tkz)

    // PostgreSQL syntax works
    pgSQL := "SELECT * FROM users WHERE data @> '{\"active\": true}'"
    _, err := tkz.Tokenize([]byte(pgSQL))
    fmt.Println("PostgreSQL:", err == nil) // true

    // MySQL syntax works
    mySQL := "SELECT * FROM users WHERE id = 1 LIMIT 10, 20"
    tkz.Reset()
    _, err = tkz.Tokenize([]byte(mySQL))
    fmt.Println("MySQL:", err == nil) // true

    // SQL Server syntax works
    tsql := "SELECT TOP 10 * FROM users"
    tkz.Reset()
    _, err = tkz.Tokenize([]byte(tsql))
    fmt.Println("SQL Server:", err == nil) // true

    // Oracle syntax works
    oracle := "SELECT * FROM users WHERE ROWNUM <= 10"
    tkz.Reset()
    _, err = tkz.Tokenize([]byte(oracle))
    fmt.Println("Oracle:", err == nil) // true

    // SQLite syntax works
    sqlite := "SELECT * FROM users LIMIT 10 OFFSET 20"
    tkz.Reset()
    _, err = tkz.Tokenize([]byte(sqlite))
    fmt.Println("SQLite:", err == nil) // true
}

Example 4: Concurrent Processing

pg_query (Go)

package main

import (
    "sync"
    "github.com/pganalyze/pg_query_go/v4"
)

func main() {
    queries := []string{
        "SELECT * FROM users",
        "SELECT * FROM orders",
        // ... 10,000 more queries
    }

    var wg sync.WaitGroup
    results := make([]bool, len(queries))

    for i, sql := range queries {
        wg.Add(1)
        go func(idx int, query string) {
            defer wg.Done()

            // FFI call to C library
            // Has some contention/overhead
            _, err := pg_query.Parse(query)
            results[idx] = (err == nil)
        }(i, sql)
    }

    wg.Wait()
    // Scaling limited by FFI overhead
    // Typically 4-10x speedup on 16 cores
}

GoSQLX (Go)

package main

import (
    "sync"
    "github.com/ajitpratap0/GoSQLX/pkg/sql/tokenizer"
)

func main() {
    queries := []string{
        "SELECT * FROM users",
        "SELECT * FROM orders",
        // ... 10,000 more queries
    }

    var wg sync.WaitGroup
    results := make([]bool, len(queries))

    for i, sql := range queries {
        wg.Add(1)
        go func(idx int, query string) {
            defer wg.Done()

            // Pure Go, no FFI
            // Perfect concurrency scaling
            tkz := tokenizer.GetTokenizer()
            defer tokenizer.PutTokenizer(tkz)

            _, err := tkz.Tokenize([]byte(query))
            results[idx] = (err == nil)
        }(i, sql)
    }

    wg.Wait()
    // Linear scaling on all cores
    // Full 16x speedup on 16 cores!
}

Example 5: Error Handling

pg_query (Go)

package main

import (
    "fmt"
    "github.com/pganalyze/pg_query_go/v4"
)

func main() {
    sql := "SELECT * FORM users" // Typo: FORM instead of FROM

    _, err := pg_query.Parse(sql)
    if err != nil {
        // PostgreSQL error messages (detailed)
        fmt.Printf("Error: %v\n", err)
        // Output: syntax error at or near "users"
    }
}

GoSQLX (Go)

package main

import (
    "fmt"
    "github.com/ajitpratap0/GoSQLX/pkg/sql/tokenizer"
)

func main() {
    sql := "SELECT * FORM users" // Typo: FORM instead of FROM

    tkz := tokenizer.GetTokenizer()
    defer tokenizer.PutTokenizer(tkz)

    _, err := tkz.Tokenize([]byte(sql))
    if err != nil {
        // GoSQLX error messages (with position)
        fmt.Printf("Error: %v\n", err)
        // Includes line and column information
    }
}

Example 6: AST Structure Comparison

pg_query (Go) - Complex PostgreSQL AST

package main

import (
    "fmt"
    "github.com/pganalyze/pg_query_go/v4"
)

func main() {
    sql := "SELECT name, email FROM users WHERE id = 1"

    result, _ := pg_query.Parse(sql)

    // PostgreSQL AST is deeply nested
    for _, stmt := range result.Stmts {
        if selectStmt := stmt.Stmt.GetSelectStmt(); selectStmt != nil {
            // Navigate complex structure
            for _, target := range selectStmt.TargetList {
                if resTarget := target.GetResTarget(); resTarget != nil {
                    if colRef := resTarget.Val.GetColumnRef(); colRef != nil {
                        for _, field := range colRef.Fields {
                            if str := field.GetString_(); str != nil {
                                fmt.Printf("Column: %s\n", str.Str)
                            }
                        }
                    }
                }
            }
        }
    }
}

GoSQLX (Go) - Simpler AST

package main

import (
    "fmt"
    "github.com/ajitpratap0/GoSQLX/pkg/sql/ast"
    "github.com/ajitpratap0/GoSQLX/pkg/sql/parser"
    "github.com/ajitpratap0/GoSQLX/pkg/sql/tokenizer"
)

func main() {
    sql := "SELECT name, email FROM users WHERE id = 1"

    // Parse to simpler AST
    astObj := parseSQL(sql)

    // Simpler traversal with visitor
    visitor := &ColumnVisitor{}
    ast.Walk(visitor, astObj)

    for _, col := range visitor.columns {
        fmt.Printf("Column: %s\n", col)
    }
}

type ColumnVisitor struct {
    columns []string
}

func (v *ColumnVisitor) Visit(node ast.Node) ast.Visitor {
    if ident, ok := node.(*ast.Identifier); ok {
        v.columns = append(v.columns, ident.Value)
    }
    return v
}

func parseSQL(sql string) *ast.AST {
    tkz := tokenizer.GetTokenizer()
    defer tokenizer.PutTokenizer(tkz)
    tokens, _ := tkz.Tokenize([]byte(sql))

    p := parser.NewParser()
        defer p.Release()

    p := parser.NewParser()
    defer p.Release()
    astObj, _ := p.ParseFromModelTokens(tokens)

    return astObj
}

Common Patterns Translation

Pattern 1: Query Deduplication

pg_query (Go)

package main

import (
    "github.com/pganalyze/pg_query_go/v4"
)

type QueryCache struct {
    fingerprints map[uint64]bool
}

func (qc *QueryCache) IsDuplicate(sql string) bool {
    // Built-in fingerprinting
    fp, err := pg_query.Fingerprint(sql)
    if err != nil {
        return false
    }

    if qc.fingerprints[fp] {
        return true // Duplicate
    }

    qc.fingerprints[fp] = true
    return false
}

func main() {
    cache := &QueryCache{fingerprints: make(map[uint64]bool)}

    // Same query pattern, different values
    cache.IsDuplicate("SELECT * FROM users WHERE id = 1") // false (new)
    cache.IsDuplicate("SELECT * FROM users WHERE id = 2") // true (duplicate pattern)
}

GoSQLX (Go)

package main

import (
    "crypto/sha256"
    "encoding/hex"
    "github.com/ajitpratap0/GoSQLX/pkg/sql/tokenizer"
    "github.com/ajitpratap0/GoSQLX/pkg/models"
)

type QueryCache struct {
    fingerprints map[string]bool
}

func (qc *QueryCache) IsDuplicate(sql string) bool {
    // Manual fingerprinting (normalize then hash)
    normalized := normalizeQuery(sql)

    hash := sha256.Sum256([]byte(normalized))
    fp := hex.EncodeToString(hash[:])

    if qc.fingerprints[fp] {
        return true // Duplicate
    }

    qc.fingerprints[fp] = true
    return false
}

func normalizeQuery(sql string) string {
    tkz := tokenizer.GetTokenizer()
    defer tokenizer.PutTokenizer(tkz)

    tokens, _ := tkz.Tokenize([]byte(sql))

    var normalized string
    for _, tok := range tokens {
        if tok.Token.Type == models.TokenTypeEOF {
            break
        }

        // Replace literals with placeholders
        switch tok.Token.Type {
        case models.TokenTypeNumber, models.TokenTypeString:
            normalized += "?"
        default:
            normalized += tok.Token.Value
        }
        normalized += " "
    }

    return normalized
}

func main() {
    cache := &QueryCache{fingerprints: make(map[string]bool)}

    cache.IsDuplicate("SELECT * FROM users WHERE id = 1") // false (new)
    cache.IsDuplicate("SELECT * FROM users WHERE id = 2") // true (duplicate pattern)
}

// Note: Built-in fingerprinting is planned for a future release

Pattern 2: Database Migration Tool

pg_query (Ruby) - PostgreSQL Only

# gem install pg_query
require 'pg_query'

class MigrationValidator
  def validate(sql)
    begin
      # Parse with PostgreSQL parser
      PgQuery.parse(sql)
      { valid: true }
    rescue PgQuery::ParseError => e
      { valid: false, error: e.message }
    end
  end

  def validate_migrations(directory)
    Dir.glob("#{directory}/*.sql").each do |file|
      sql = File.read(file)
      result = validate(sql)

      puts "#{file}: #{result[:valid] ? '✓' : '✗'}"
      puts "  Error: #{result[:error]}" unless result[:valid]
    end
  end
end

# Only works for PostgreSQL migrations
validator = MigrationValidator.new
validator.validate_migrations('./migrations/postgres')

GoSQLX (Go) - Multi-Database

package main

import (
    "fmt"
    "os"
    "path/filepath"
    "github.com/ajitpratap0/GoSQLX/pkg/sql/tokenizer"
)

type MigrationValidator struct {
    dialect string
}

func (mv *MigrationValidator) Validate(sql string) map[string]interface{} {
    tkz := tokenizer.GetTokenizer()
    defer tokenizer.PutTokenizer(tkz)

    _, err := tkz.Tokenize([]byte(sql))

    if err != nil {
        return map[string]interface{}{
            "valid": false,
            "error": err.Error(),
        }
    }

    return map[string]interface{}{"valid": true}
}

func (mv *MigrationValidator) ValidateMigrations(directory string) {
    files, _ := filepath.Glob(filepath.Join(directory, "*.sql"))

    for _, file := range files {
        sql, _ := os.ReadFile(file)
        result := mv.Validate(string(sql))

        status := "✗"
        if result["valid"].(bool) {
            status = "✓"
        }

        fmt.Printf("%s: %s\n", file, status)
        if !result["valid"].(bool) {
            fmt.Printf("  Error: %v\n", result["error"])
        }
    }
}

func main() {
    // Works for all supported databases!
    validators := map[string]*MigrationValidator{
        "postgres":  {dialect: "postgres"},
        "mysql":     {dialect: "mysql"},
        "sqlserver": {dialect: "sqlserver"},
        "oracle":    {dialect: "oracle"},
        "sqlite":    {dialect: "sqlite"},
    }

    for db, validator := range validators {
        fmt.Printf("\nValidating %s migrations:\n", db)
        validator.ValidateMigrations(fmt.Sprintf("./migrations/%s", db))
    }
}

Performance Comparison

Benchmark: Parsing 10,000 PostgreSQL Queries

Test Query:

SELECT u.id, u.name, u.email, COUNT(o.id) as order_count
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
WHERE u.active = true
GROUP BY u.id, u.name, u.email
HAVING COUNT(o.id) > 5
ORDER BY order_count DESC

Results:

Real-World Scenario: Query Analysis Service

Scenario: Microservice analyzing SQL queries for a multi-tenant SaaS

pg_query (Ruby/Go):

- Dialect Support: PostgreSQL only
- Throughput: 100,000 queries/sec
- Memory: 2GB for 100K queries
- Deployment: Complex (C library dependencies)
- Use Case: PostgreSQL-exclusive systems

GoSQLX (Go):

- Dialect Support: PostgreSQL + MySQL + SQL Server + Oracle + SQLite
- Throughput: 1,388,889 queries/sec
- Memory: 720MB for 100K queries
- Deployment: Simple (single binary)
- Use Case: Multi-database systems

Advantages:

• 14x faster parsing
• 5 database dialects vs 1
• 2.7x less memory usage
• Simpler deployment (no C dependencies)

Migration Checklist

Phase 1: Assessment (Week 1)

• Identify all uses of pg_query in your codebase
• List which databases you support (if PostgreSQL-only, consider staying)
• Check if you use PostgreSQL-specific features (PL/pgSQL, etc.)
• Review normalization/fingerprinting usage
• Document build complexity issues (if any)

Phase 2: Proof of Concept (Week 1-2)

• Install Go 1.21+ if not already present
• Install GoSQLX: go get github.com/ajitpratap0/GoSQLX
• Test parsing your PostgreSQL queries
• Implement custom normalization if needed
• Benchmark performance improvement
• Test concurrent processing

Phase 3: Implementation (Week 2-4)

• Replace pg_query parsing with GoSQLX
• Implement normalization/fingerprinting manually
• Add multi-dialect support if needed
• Update error handling
• Write comprehensive tests
• Update build scripts (remove C dependencies!)

Phase 4: Testing (Week 4-5)

• Unit test with real SQL queries
• Load test for performance validation
• Test concurrent processing
• Verify error messages are helpful
• Test with PostgreSQL-specific syntax you use

Phase 5: Deployment (Week 5-6)

• Deploy alongside pg_query initially
• Monitor performance metrics
• Gradually shift traffic to GoSQLX
• Remove pg_query dependency
• Celebrate simpler builds! 🎉

Phase 6: Optimization (Week 6+)

• Add multi-dialect support for new customers
• Implement custom features on simpler AST
• Optimize for your specific use case
• Share migration experience with community

Real Migration Case Study

Company: Database Tools Startup (Fictional Example)

Industry: Database DevOps Tools Product: SQL query analyzer for multi-database environments Previous Setup: pg_query for PostgreSQL customers only

Problem

• Could only support PostgreSQL customers
• Lost deals due to lack of MySQL/SQL Server support
• Complex builds with C dependencies
• Slow iteration on new features (complex AST)

Migration Process

Week 1-2: Evaluation

Requirements:

1. Support PostgreSQL + MySQL + SQL Server
2. Maintain or improve performance
3. Simplify deployment
4. Easier feature development

Decision: Migrate to GoSQLX for multi-dialect support

Week 3-4: Implementation

Before (pg_query):

// parser.go
import "github.com/pganalyze/pg_query_go/v4"

func ParseQuery(sql string) (*QueryInfo, error) {
    result, err := pg_query.Parse(sql)
    if err != nil {
        return nil, err
    }

    // Complex AST navigation
    info := &QueryInfo{
        Tables:  extractTables(result),
        Columns: extractColumns(result),
    }

    return info, nil
}

// Only works for PostgreSQL!

After (GoSQLX):

// parser.go
import (
    "github.com/ajitpratap0/GoSQLX/pkg/sql/tokenizer"
    "github.com/ajitpratap0/GoSQLX/pkg/sql/parser"
)

func ParseQuery(sql string, dialect string) (*QueryInfo, error) {
    tkz := tokenizer.GetTokenizer()
    defer tokenizer.PutTokenizer(tkz)

    tokens, err := tkz.Tokenize([]byte(sql))
    if err != nil {
        return nil, err
    }

    // Simpler extraction
    info := &QueryInfo{
        Tables:  extractTablesFromTokens(tokens),
        Columns: extractColumnsFromTokens(tokens),
        Dialect: dialect,
    }

    return info, nil
}

// Works for PostgreSQL, MySQL, SQL Server, Oracle, SQLite!

Week 5-6: Results

Business Impact:

Customer Base:
  Before: 100 PostgreSQL-only customers
  After:  250 customers (150 non-PostgreSQL)
  Growth: 150% increase in 3 months

Revenue:
  Before: $50K MRR (monthly recurring revenue)
  After:  $125K MRR
  Growth: 150% increase

Technical Impact:

Performance:
  Before: 100K queries/sec (PostgreSQL)
  After:  1.38M queries/sec (all dialects)
  Improvement: 13.8x faster

Build Time:
  Before: 5 minutes (CGO + C deps)
  After:  30 seconds (pure Go)
  Improvement: 10x faster

Binary Size:
  Before: 45MB (with libpg_query)
  After:  15MB (pure Go)
  Improvement: 3x smaller

Deployment:
  Before: Complex (C library, different for each OS)
  After:  Simple (single binary, easy cross-compile)
  Improvement: Much simpler DevOps

Developer Productivity:

Feature Velocity:
  Before: 2 weeks per feature (complex AST navigation)
  After:  3 days per feature (simpler AST)
  Improvement: 4.7x faster iteration

Bug Fixes:
  Before: 1 week average (C/Go debugging difficult)
  After:  1 day average (pure Go debugging easy)
  Improvement: 5x faster resolution

Onboarding:
  Before: 2 weeks (learn PostgreSQL AST, CGO, C deps)
  After:  2 days (simpler Go codebase)
  Improvement: 5x faster

Lessons Learned

1. Multi-dialect = More Customers: Unlocked 60% more market
2. Pure Go = Better DX: Developers much happier without CGO
3. Simpler AST = Faster Development: 4-5x faster feature development
4. Performance Bonus: Unexpected 14x performance improvement
5. Trade-off Acceptable: ~80-85% PostgreSQL coverage was sufficient

Known Limitations

Features Not Available in GoSQLX

1. 100% PostgreSQL Compliance

pg_query Has:

• Official PostgreSQL parser (guaranteed compliance)
• All latest PostgreSQL features immediately

GoSQLX Status:

• ~80-85% PostgreSQL coverage
• Slightly behind latest features

Workaround: For PostgreSQL-only projects needing 100% compliance, keep pg_query.

2. Built-in Normalization

pg_query Has:

• pg_query.Normalize() built-in
• pg_query.Fingerprint() built-in

GoSQLX Status:

• ⚠️ Not yet available (planned for future release)
• Implement normalization manually for now

Workaround: Implement normalization manually (see examples above).

3. Full PL/pgSQL Support

pg_query Has:

• Complete stored procedure parsing
• Trigger function parsing

GoSQLX Status:

• ⚠️ Basic support only
• Sufficient for most use cases

Workaround: For heavy PL/pgSQL use, keep pg_query or contribute PL/pgSQL support to GoSQLX.

4. PostgreSQL-Specific Operators

pg_query Has:

• Full support for all PostgreSQL operators
• JSON/JSONB operators (@>, ->, etc.)
• Array operators (&&, @>, etc.)

GoSQLX Status:

• ✅ JSON/JSONB operators supported in v1.6.0 (->, ->>, #>, #>>, @>, <@, ?, ?|, ?&, #-)
• ⚠️ Array operators have partial support

Getting Help

Documentation

• GoSQLX Documentation - Complete documentation
• Getting Started Guide - Quick start in 5 minutes
• Usage Guide - Comprehensive patterns
• API Reference - Complete API documentation

Community Support

• GitHub Issues - Report bugs or request features
• GitHub Discussions - Ask questions
• Examples Directory - Real-world code examples

Migration Support

• Comparison Guide - Detailed feature comparison
• Production Guide - Production best practices
• Troubleshooting - Common issues and solutions

Next Steps

After Migration

1. Add Multi-Dialect Support

   • Expand to MySQL, SQL Server, Oracle, SQLite customers
   • Test dialect-specific features
   • Document dialect differences

2. Simplify Deployment

   • Remove C dependencies from build
   • Use single binary deployment
   • Simplify CI/CD pipelines

3. Optimize Performance

   • Leverage 14x faster parsing
   • Improve concurrency scaling
   • Reduce infrastructure costs

4. Contribute Back

   • Share PostgreSQL coverage feedback
   • Contribute missing PostgreSQL features
   • Help improve multi-dialect support

FAQ

Q: Will I lose PostgreSQL compliance?

A: You’ll go from 100% to ~80-85% coverage. For most applications, this is sufficient. Test your queries!

Q: What about normalization/fingerprinting?

A: Implement manually using the examples provided above. Built-in support is planned for a future release.

Q: Can I support multiple databases?

A: Yes! That’s GoSQLX’s main advantage. Support PostgreSQL + MySQL + SQL Server + Oracle + SQLite.

Q: How difficult is the migration?

A: Moderate. Main work is implementing normalization if you use it. Otherwise, straightforward.

Q: What about build complexity?

A: Much simpler! No more C dependencies, CGO, or cross-compilation issues.

Q: Should I migrate if I’m PostgreSQL-only?

A: Maybe not, unless you need the performance or simpler builds. pg_query has 100% PostgreSQL compliance.

Migration Time Estimate: 4-6 weeks for typical project Performance Improvement: 14x faster parsing Deployment: 10x simpler (no C dependencies)

Ready to migrate? Start with our Getting Started Guide!

Last Updated: 2025-11-05 Maintained by: GoSQLX Community