polyglot_sql_ffi 0.1.0-aarch64-linux-gnu

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 61e5ac76e197d3843bb8e8d44e6d588ca33b31e83b878dd3cd1a6f1ddd8b45a7
+  data.tar.gz: 4ebff0650298fd2f8d2c8cd2b73d94e1f1a2c426a6e3c73d3826421994c3ba95
+SHA512:
+  metadata.gz: 55a9e3864f3cbaa59ed35ad9d0bb11c0db6749c5c811f5cb60e22d7cd2a8d7a44978c62617053cad1870ffd895dfd1844239c9c7de7e1d3a9a35efa00f742e48
+  data.tar.gz: a169c32f8af62575b3499bec91ec2d626c3d2cda55a792d64d1b5f9ad0342c87232e8ae03f952bd299a47d2a53a624774da6219ca3b11ffda0717e259f1d6185

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem "rspec", "~> 3.12"
+  gem "rake", "~> 13.0"
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TobiLG <github@tobilg.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,81 @@
+# polyglot_sql_ffi
+
+Ruby wrapper for [polyglot](https://github.com/tobilg/polyglot) — a SQL parser, transpiler,
+optimizer, and lineage engine written in Rust. Mirrors the polyglot-sql Python package's
+module-level API via FFI.
+
+## Installation
+
+```ruby
+gem "polyglot_sql_ffi"
+```
+
+The library itself is namespaced `PolyglotSql` and required as `polyglot_sql` (both happen
+automatically under bundler).
+
+Platform gems bundle the native library (linux/macos, x86_64/arm64). Installs that bypass platform
+gems — JRuby, bundler's `force_ruby_platform`, a lockfile missing your platform — get the source gem
+instead, which downloads the same official binary at install time. Platforms polyglot publishes no
+binary for (e.g. Alpine/musl) must build `libpolyglot_sql_ffi` themselves and point
+`POLYGLOT_SQL_FFI_PATH` at it.
+
+## Usage
+
+```ruby
+require "polyglot_sql"
+
+# Transpile between dialects
+PolyglotSql.transpile("SELECT IFNULL(a, b) FROM t", read: :mysql, write: :postgres)
+# => "SELECT COALESCE(a, b) FROM t"
+
+# Parse to a Hash AST and generate back
+ast = PolyglotSql.parse_one("SELECT 1 + 2", dialect: :sqlite)
+PolyglotSql.generate(ast, dialect: :sqlite)
+
+# Pretty-format
+PolyglotSql.format("SELECT a,b FROM t WHERE x=1", dialect: :sqlite)
+
+# Validate
+PolyglotSql.validate("SELECT a FROM t", dialect: :sqlite).valid?
+
+# Canonicalize / optimize
+PolyglotSql.optimize("WITH cte AS (SELECT a FROM t) SELECT a FROM cte", dialect: :sqlite)
+# => "SELECT a FROM t"
+
+# Lineage
+PolyglotSql.lineage("total", sql, dialect: :sqlite)      # by column name
+PolyglotSql.lineage_at(0, sql, dialect: :sqlite)         # by output ordinal
+PolyglotSql.output_columns(sql, dialect: :sqlite)        # ordered output shape
+PolyglotSql.source_tables("total", sql, dialect: :sqlite)
+```
+
+Set a default dialect once instead of passing it everywhere:
+
+```ruby
+PolyglotSql.configure { |c| c.default_dialect = :sqlite }
+```
+
+Errors raise subclasses of `PolyglotSql::Error` (`ParseError`, `TranspileError`,
+`ColumnResolutionError`, ...).
+
+## Native library
+
+The gem loads `libpolyglot_sql_ffi` from `lib/polyglot_sql/`; set `POLYGLOT_SQL_FFI_PATH` to
+override with your own build. The bundled version is pinned by `PolyglotSql::POLYGLOT_VERSION`.
+
+## Development
+
+```sh
+bundle install
+rake native:fetch
+bundle exec rspec
+```
+
+## Releasing
+
+Tag `vX.Y.Z` and push. The release workflow packages platform gems plus the source gem and publishes
+to RubyGems via trusted publishing.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+namespace :native do
+  desc "Fetch the prebuilt polyglot-sql-ffi library for this platform"
+  task :fetch do
+    ruby "scripts/fetch_native.rb"
+  end
+end
+
+task default: :spec

data/ext/polyglot_sql_ffi/extconf.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# extconf.rb — invoked by `gem install` / `bundle install` to provide the
+# polyglot-sql-ffi shared library, downloaded from the official polyglot
+# GitHub release and checksum-verified.
+
+require "fileutils"
+require "open-uri"
+require "digest"
+
+RUST_REPO = "https://github.com/tobilg/polyglot"
+VERSION   = File.read(File.expand_path("../../lib/polyglot_sql/version.rb", __dir__))[/POLYGLOT_VERSION = "(.+?)"/, 1]
+RUST_TAG  = "v#{VERSION}"
+EXT_DIR   = __dir__
+LIB_DIR   = File.expand_path("../../lib/polyglot_sql", EXT_DIR)
+
+# Release artifact name for this platform, nil if none is published.
+def release_artifact
+  cpu = RbConfig::CONFIG["host_cpu"]
+  arch = { "x86_64" => "x86_64", "arm64" => "aarch64", "aarch64" => "aarch64" }[cpu]
+  return nil unless arch
+
+  case RbConfig::CONFIG["host_os"]
+  when /linux/ then "polyglot-sql-ffi-linux-#{arch}.tar.gz"
+  when /darwin/ then "polyglot-sql-ffi-macos-#{arch}.tar.gz"
+  end
+end
+
+def install_prebuilt
+  artifact = release_artifact
+  unless artifact
+    abort <<~MSG
+      ERROR: no prebuilt polyglot-sql-ffi binary for this platform
+      (#{RbConfig::CONFIG["host_os"]} / #{RbConfig::CONFIG["host_cpu"]}).
+
+      Build libpolyglot_sql_ffi from #{RUST_REPO} (tag #{RUST_TAG}) with
+      `cargo build -p polyglot-sql-ffi --profile ffi_release`, then set
+      POLYGLOT_SQL_FFI_PATH to the resulting library and reinstall.
+    MSG
+  end
+
+  base = "#{RUST_REPO}/releases/download/#{RUST_TAG}"
+  puts "Downloading #{base}/#{artifact}..."
+  tarball = URI.open("#{base}/#{artifact}").read
+  checksums = URI.open("#{base}/checksums.sha256").read
+
+  expected = checksums[/^(\h{64})\s+.*#{Regexp.escape(artifact)}$/, 1]
+  abort "ERROR: checksum mismatch for #{artifact}" unless Digest::SHA256.hexdigest(tarball) == expected
+
+  dir = File.join(EXT_DIR, "prebuilt")
+  FileUtils.mkdir_p(dir)
+  File.binwrite(File.join(dir, artifact), tarball)
+  system("tar", "xzf", artifact, chdir: dir) or abort "ERROR: tar extraction failed"
+
+  so_file = Dir[File.join(dir, "**", "libpolyglot_sql_ffi.{so,dylib}")].first
+  abort "ERROR: shared library not found in #{artifact}" unless so_file
+
+  FileUtils.mkdir_p(LIB_DIR)
+  FileUtils.cp(so_file, LIB_DIR, verbose: true)
+end
+
+if Dir[File.join(LIB_DIR, "libpolyglot_sql_ffi.{so,dylib}")].any?
+  puts "libpolyglot_sql_ffi already present in #{LIB_DIR}, skipping."
+else
+  install_prebuilt
+end
+
+# Dummy Makefile — required by the rubygems extension protocol.
+File.write(File.join(EXT_DIR, "Makefile"), "all:\ninstall:\nclean:\n")

data/lib/polyglot_sql/dialect.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PolyglotSql
+  # Normalizes dialect arguments (Symbol or String) into the string names the
+  # native library understands. The authoritative list comes from
+  # {PolyglotSql.dialects}; unknown names are rejected by the native layer.
+  module Dialect
+    DEFAULT = "generic"
+
+    # Convenience aliases accepted in addition to the canonical names.
+    ALIASES = {
+      "postgresql" => "postgres",
+      "pg" => "postgres",
+      "mssql" => "tsql",
+      "sqlserver" => "tsql",
+      "mariadb" => "mysql",
+    }.freeze
+
+    # @param name [Symbol, String, nil]
+    # @return [String] canonical dialect name (default: "generic")
+    def self.resolve(name)
+      return DEFAULT if name.nil?
+
+      key = name.to_s.strip.downcase
+      return DEFAULT if key.empty?
+
+      ALIASES.fetch(key, key)
+    end
+  end
+end

data/lib/polyglot_sql/error.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module PolyglotSql
+  # Base class for every error raised by this gem. Mirrors the Python
+  # package's `PolyglotError` hierarchy.
+  class Error < StandardError; end
+
+  # Raised when the SQL cannot be tokenized or parsed.
+  class ParseError < Error; end
+
+  # Raised when SQL cannot be generated from an AST.
+  class GenerateError < Error; end
+
+  # Raised when transpilation between dialects fails.
+  class TranspileError < Error; end
+
+  # Raised when a lineage column cannot be resolved (not found,
+  # indeterminate, or ambiguous).
+  class ColumnResolutionError < TranspileError; end
+
+  # Raised when semantic/syntactic validation fails at the boundary
+  # (not the per-statement diagnostics returned by {PolyglotSql.validate}).
+  class ValidationError < Error; end
+
+  # Raised for invalid arguments: NULL/blank input, unknown dialect, bad UTF-8.
+  class ArgumentError < Error; end
+
+  # Raised when the native library cannot be found or loaded.
+  class LibraryNotFoundError < Error; end
+
+  # Status codes returned across the FFI boundary (see polyglot-sql-ffi types.rs).
+  module Status
+    SUCCESS = 0
+    PARSE_ERROR = 1
+    GENERATE_ERROR = 2
+    TRANSPILE_ERROR = 3
+    VALIDATION_ERROR = 4
+    INVALID_ARGUMENT = 5
+    SERIALIZATION_ERROR = 6
+    COLUMN_NOT_FOUND = 7
+    COLUMN_INDETERMINATE = 8
+    COLUMN_AMBIGUOUS = 9
+    INTERNAL_ERROR = 99
+
+    CLASS_FOR = {
+      PARSE_ERROR => ParseError,
+      GENERATE_ERROR => GenerateError,
+      TRANSPILE_ERROR => TranspileError,
+      VALIDATION_ERROR => ValidationError,
+      INVALID_ARGUMENT => ArgumentError,
+      SERIALIZATION_ERROR => Error,
+      COLUMN_NOT_FOUND => ColumnResolutionError,
+      COLUMN_INDETERMINATE => ColumnResolutionError,
+      COLUMN_AMBIGUOUS => ColumnResolutionError,
+      INTERNAL_ERROR => Error,
+    }.freeze
+
+    def self.error_class(status)
+      CLASS_FOR.fetch(status, Error)
+    end
+  end
+end

data/lib/polyglot_sql/native.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "ffi"
+require "json"
+
+module PolyglotSql
+  # Low-level FFI bindings to libpolyglot_sql_ffi.
+  #
+  # Not intended for direct use -- see the public API on {PolyglotSql}.
+  # Every FFI function returns a +PolyglotResult+ (or +PolyglotValidationResult+)
+  # struct by value; the safe wrappers here read the payload, free the struct's
+  # owned strings, and raise on a non-zero status so callers never touch raw
+  # pointers or manage memory.
+  #
+  # @api private
+  module Native
+    extend FFI::Library
+
+    LIB_NAME = "polyglot_sql_ffi"
+    SOEXT = FFI::Platform::LIBSUFFIX # "so" on Linux, "dylib" on macOS
+
+    # Search order:
+    #   1. POLYGLOT_SQL_FFI_PATH (explicit override, matches the Go SDK)
+    #   2. lib/polyglot_sql/ inside the gem (where extconf.rb / fetch_native.rb put it)
+    #   3. system library path
+    def self.find_library
+      if (env_path = ENV["POLYGLOT_SQL_FFI_PATH"])
+        return env_path if File.exist?(env_path)
+      end
+
+      bundled = File.expand_path("lib#{LIB_NAME}.#{SOEXT}", __dir__)
+      return bundled if File.exist?(bundled)
+
+      LIB_NAME
+    end
+
+    begin
+      ffi_lib find_library
+    rescue LoadError => e
+      raise PolyglotSql::LibraryNotFoundError,
+            "Could not load libpolyglot_sql_ffi. #{e.message}\n\n" \
+            "Fetch the native library with:\n" \
+            "  rake native:fetch\n\n" \
+            "Or set POLYGLOT_SQL_FFI_PATH to the full path of the .so/.dylib file."
+    end
+
+    # ── Result structs (returned by value; see polyglot-sql-ffi types.rs) ──
+
+    class Result < FFI::Struct
+      layout :data, :pointer, :error, :pointer, :status, :int32
+    end
+
+    class ValidationResult < FFI::Struct
+      layout :valid, :int32,
+             :errors_json, :pointer,
+             :error, :pointer,
+             :status, :int32
+    end
+
+    # ── C function declarations ────────────────────────────────────────
+
+    attach_function :polyglot_transpile, %i[string string string], Result.by_value
+    attach_function :polyglot_transpile_with_options, %i[string string string string], Result.by_value
+    attach_function :polyglot_parse, %i[string string], Result.by_value
+    attach_function :polyglot_parse_one, %i[string string], Result.by_value
+    attach_function :polyglot_parse_data_type, %i[string string], Result.by_value
+    attach_function :polyglot_tokenize, %i[string string], Result.by_value
+    attach_function :polyglot_generate, %i[string string], Result.by_value
+    attach_function :polyglot_generate_data_type, %i[string string], Result.by_value
+    attach_function :polyglot_format, %i[string string], Result.by_value
+    attach_function :polyglot_format_with_options, %i[string string string], Result.by_value
+    attach_function :polyglot_optimize, %i[string string], Result.by_value
+    attach_function :polyglot_lineage, %i[string string string], Result.by_value
+    attach_function :polyglot_lineage_with_schema, %i[string string string string], Result.by_value
+    attach_function :polyglot_lineage_at, %i[size_t string string], Result.by_value
+    attach_function :polyglot_lineage_at_with_schema, %i[size_t string string string], Result.by_value
+    attach_function :polyglot_output_columns, %i[string string], Result.by_value
+    attach_function :polyglot_output_columns_with_schema, %i[string string string], Result.by_value
+    attach_function :polyglot_source_tables, %i[string string string], Result.by_value
+    attach_function :polyglot_analyze_query, %i[string string], Result.by_value
+    attach_function :polyglot_openlineage_column_lineage, %i[string string], Result.by_value
+    attach_function :polyglot_openlineage_job_event, %i[string string], Result.by_value
+    attach_function :polyglot_openlineage_run_event, %i[string string], Result.by_value
+    attach_function :polyglot_diff, %i[string string string], Result.by_value
+    attach_function :polyglot_qualify_tables, %i[string string], Result.by_value
+    attach_function :polyglot_set_limit, %i[string uint64], Result.by_value
+    attach_function :polyglot_set_offset, %i[string uint64], Result.by_value
+    attach_function :polyglot_set_order_by, %i[string string], Result.by_value
+    attach_function :polyglot_rename_tables_with_options, %i[string string string], Result.by_value
+    attach_function :polyglot_annotate_types, %i[string string string], Result.by_value
+
+    attach_function :polyglot_validate, %i[string string], ValidationResult.by_value
+    attach_function :polyglot_validate_with_options, %i[string string string], ValidationResult.by_value
+
+    attach_function :polyglot_dialect_list, [], :pointer
+    attach_function :polyglot_dialect_count, [], :int32
+    # Returns a static pointer -- :string lets FFI read it without freeing.
+    attach_function :polyglot_version, [], :string
+
+    attach_function :polyglot_free_string, [:pointer], :void
+    attach_function :polyglot_free_result, [Result.by_value], :void
+    attach_function :polyglot_free_validation_result, [ValidationResult.by_value], :void
+
+    # ── Safe wrappers ──────────────────────────────────────────────────
+
+    # Read the payload from a Result struct, free its owned strings, and return
+    # the data. Raises the mapped error class on a non-zero status.
+    #
+    # @param result [Result]
+    # @return [String] the +data+ payload
+    def self.unwrap(result)
+      status = result[:status]
+      data = pointer_to_string(result[:data])
+      error = pointer_to_string(result[:error])
+
+      return data if status == Status::SUCCESS
+
+      raise Status.error_class(status),
+            error || "polyglot-sql failed with status #{status}"
+    ensure
+      polyglot_free_result(result)
+    end
+
+    # Read a ValidationResult into a plain Hash and free its owned strings.
+    #
+    # @param result [ValidationResult]
+    # @return [Hash] { valid: Boolean, errors: Array<Hash> }
+    def self.unwrap_validation(result)
+      status = result[:status]
+      error = pointer_to_string(result[:error])
+
+      # status 4 (VALIDATION_ERROR) is not a failure here: it means the SQL is
+      # invalid, and errors_json carries the diagnostics.
+      if status != Status::SUCCESS && status != Status::VALIDATION_ERROR
+        raise Status.error_class(status),
+              error || "polyglot-sql validation failed with status #{status}"
+      end
+
+      errors_json = pointer_to_string(result[:errors_json])
+      {
+        valid: result[:valid] == 1,
+        errors: errors_json ? JSON.parse(errors_json, max_nesting: false) : [],
+      }
+    ensure
+      polyglot_free_validation_result(result)
+    end
+
+    # Read, then free, a bare +char*+ returned by e.g. polyglot_dialect_list.
+    #
+    # @param ptr [FFI::Pointer]
+    # @return [String, nil]
+    def self.take_string(ptr)
+      return nil if ptr.null?
+
+      ptr.read_string.force_encoding("UTF-8")
+    ensure
+      polyglot_free_string(ptr) unless ptr.null?
+    end
+
+    def self.pointer_to_string(ptr)
+      return nil if ptr.null?
+
+      ptr.read_string.force_encoding("UTF-8")
+    end
+    private_class_method :pointer_to_string
+  end
+end

data/lib/polyglot_sql/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module PolyglotSql
+  # Wires a `config.polyglot_sql.default_dialect` setting into Rails so the
+  # dialect can be omitted from calls.
+  class Railtie < Rails::Railtie
+    config.polyglot_sql = ActiveSupport::OrderedOptions.new
+
+    initializer "polyglot_sql.configure" do |app|
+      PolyglotSql.configure do |c|
+        c.default_dialect = app.config.polyglot_sql.default_dialect
+      end
+    end
+  end
+end

data/lib/polyglot_sql/validation_result.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module PolyglotSql
+  # Result of {PolyglotSql.validate}. Mirrors the Python package's
+  # +ValidationResult+: a validity flag plus a list of diagnostic Hashes
+  # (each with +message+, +line+, +col+/+column+, +code+, +severity+).
+  class ValidationResult
+    # @return [Array<Hash>]
+    attr_reader :errors
+
+    def initialize(valid, errors)
+      @valid = valid
+      @errors = errors
+    end
+
+    # @return [Boolean]
+    def valid?
+      @valid
+    end
+
+    def to_h
+      { valid: @valid, errors: @errors }
+    end
+
+    def inspect
+      "#<PolyglotSql::ValidationResult valid=#{@valid} errors=#{@errors.size}>"
+    end
+  end
+end

data/lib/polyglot_sql/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module PolyglotSql
+  VERSION = "0.1.0"
+
+  # Upstream polyglot-sql-ffi crate version this gem is built against.
+  POLYGLOT_VERSION = "0.8.1"
+end

data/lib/polyglot_sql.rb

@@ -0,0 +1,386 @@
+# frozen_string_literal: true
+
+require_relative "polyglot_sql/version"
+require_relative "polyglot_sql/error"
+require_relative "polyglot_sql/dialect"
+require_relative "polyglot_sql/validation_result"
+require_relative "polyglot_sql/native"
+
+require_relative "polyglot_sql/railtie" if defined?(Rails::Railtie)
+
+# PolyglotSql wraps the polyglot-sql-ffi native library, mirroring the
+# polyglot-sql Python package: parse, transpile across 30+ dialects, generate,
+# pretty-format, validate, optimize, lineage, and query analysis.
+#
+# The parsed AST is a plain Ruby Hash/Array (deserialized from the engine's
+# JSON), and can be round-tripped back through {.generate}.
+#
+# @example Transpile between dialects
+#   PolyglotSql.transpile("SELECT `a` FROM `t`", read: :mysql, write: :sqlite)
+#   # => "SELECT \"a\" FROM \"t\""
+#
+# @example Pretty-format SQLite
+#   PolyglotSql.format("SELECT a,b FROM t WHERE x=1", dialect: :sqlite)
+module PolyglotSql
+  class Configuration
+    # Default dialect used when none is specified.
+    # @return [Symbol, String, nil]
+    attr_accessor :default_dialect
+
+    def initialize
+      @default_dialect = nil
+    end
+  end
+
+  class << self
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    # ── Transpile ──────────────────────────────────────────────────────
+
+    # Transpile SQL from one dialect to another.
+    #
+    # @param sql [String]
+    # @param read [Symbol, String, nil] source dialect (alias: +from+)
+    # @param write [Symbol, String, nil] target dialect (alias: +to+)
+    # @param pretty [Boolean] format the output with indentation and newlines
+    # @param from [Symbol, String, nil] alias for +read+
+    # @param to [Symbol, String, nil] alias for +write+
+    # @return [String, Array<String>] one String, or an Array for multi-statement input
+    def transpile(sql, read: nil, write: nil, pretty: false, from: nil, to: nil)
+      read_str = resolve_dialect(read || from)
+      write_str = resolve_dialect(write || to)
+
+      json =
+        if pretty
+          Native.unwrap(Native.polyglot_transpile_with_options(
+                          sql, read_str, write_str, encode(pretty: true)
+                        ))
+        else
+          Native.unwrap(Native.polyglot_transpile(sql, read_str, write_str))
+        end
+
+      unwrap_list(decode(json))
+    end
+
+    # ── Parse / tokenize ───────────────────────────────────────────────
+
+    # Parse SQL into an Array of AST statements (each a Hash).
+    #
+    # @return [Array<Hash>]
+    def parse(sql, dialect: nil)
+      decode(Native.unwrap(Native.polyglot_parse(sql, resolve_dialect(dialect))))
+    end
+
+    # Parse SQL expected to contain exactly one statement.
+    #
+    # @return [Hash]
+    def parse_one(sql, dialect: nil)
+      decode(Native.unwrap(Native.polyglot_parse_one(sql, resolve_dialect(dialect))))
+    end
+
+    # Parse a SQL type expression (e.g. "DECIMAL(10, 2)") into a DataType AST.
+    #
+    # @return [Hash]
+    def parse_data_type(sql, dialect: nil)
+      decode(Native.unwrap(Native.polyglot_parse_data_type(sql, resolve_dialect(dialect))))
+    end
+
+    # Tokenize SQL into an Array of tokens.
+    #
+    # @return [Array<Hash>]
+    def tokenize(sql, dialect: nil)
+      decode(Native.unwrap(Native.polyglot_tokenize(sql, resolve_dialect(dialect))))
+    end
+
+    # ── Generate ───────────────────────────────────────────────────────
+
+    # Generate SQL from an AST (a Hash from {.parse_one} or an Array from {.parse}).
+    #
+    # @param ast [Hash, Array<Hash>]
+    # @param pretty [Boolean] format the output with indentation and newlines
+    # @return [String, Array<String>] one String, or an Array for multi-statement AST
+    def generate(ast, dialect: nil, pretty: false)
+      dialect_str = resolve_dialect(dialect)
+      ast_json = encode(statements(ast))
+      sql = unwrap_list(decode(Native.unwrap(Native.polyglot_generate(ast_json, dialect_str))))
+      return sql unless pretty
+
+      # The FFI has no pretty-generate; re-format the generated SQL instead.
+      pretty_each(sql, dialect_str)
+    end
+
+    # Generate a SQL type string from a DataType AST.
+    #
+    # @return [String]
+    def generate_data_type(data_type, dialect: nil)
+      Native.unwrap(Native.polyglot_generate_data_type(encode(data_type), resolve_dialect(dialect)))
+    end
+
+    # ── Format (pretty-print) ──────────────────────────────────────────
+
+    # Pretty-format SQL, honoring the target dialect's quoting rules.
+    #
+    # @param max_input_bytes [Integer, nil] guard override
+    # @param max_tokens [Integer, nil] guard override
+    # @param max_ast_nodes [Integer, nil] guard override
+    # @param max_set_op_chain [Integer, nil] guard override
+    # @return [String, Array<String>]
+    def format(sql, dialect: nil, max_input_bytes: nil, max_tokens: nil,
+               max_ast_nodes: nil, max_set_op_chain: nil)
+      dialect_str = resolve_dialect(dialect)
+      options = compact(
+        maxInputBytes: max_input_bytes,
+        maxTokens: max_tokens,
+        maxAstNodes: max_ast_nodes,
+        maxSetOpChain: max_set_op_chain,
+      )
+
+      json =
+        if options.empty?
+          Native.unwrap(Native.polyglot_format(sql, dialect_str))
+        else
+          Native.unwrap(Native.polyglot_format_with_options(sql, dialect_str, encode(options)))
+        end
+
+      unwrap_list(decode(json))
+    end
+    alias_method :format_sql, :format
+
+    # ── Validate ───────────────────────────────────────────────────────
+
+    # Validate SQL syntactically and (optionally) semantically.
+    #
+    # @param strict_syntax [Boolean] reject compatibility forms (trailing commas, ...)
+    # @param semantic [Boolean] add W001-W004 semantic warnings
+    # @return [ValidationResult]
+    def validate(sql, dialect: nil, strict_syntax: false, semantic: false)
+      dialect_str = resolve_dialect(dialect)
+
+      result =
+        if strict_syntax || semantic
+          Native.unwrap_validation(Native.polyglot_validate_with_options(
+                                     sql, dialect_str,
+                                     encode(strictSyntax: strict_syntax, semantic: semantic)
+                                   ))
+        else
+          Native.unwrap_validation(Native.polyglot_validate(sql, dialect_str))
+        end
+
+      ValidationResult.new(result[:valid], result[:errors])
+    end
+
+    # ── Optimize ───────────────────────────────────────────────────────
+
+    # Run the full optimizer pipeline over the SQL.
+    #
+    # @return [String, Array<String>]
+    def optimize(sql, dialect: nil)
+      unwrap_list(decode(Native.unwrap(Native.polyglot_optimize(sql, resolve_dialect(dialect)))))
+    end
+
+    # ── Lineage / analysis ─────────────────────────────────────────────
+
+    # Column-level lineage for +column+ within +sql+.
+    #
+    # @param schema [Hash, nil] optional ValidationSchema for schema-aware lineage
+    # @return [Hash] a LineageNode
+    def lineage(column, sql, dialect: nil, schema: nil)
+      dialect_str = resolve_dialect(dialect)
+      json =
+        if schema
+          Native.unwrap(Native.polyglot_lineage_with_schema(column, sql, encode(schema), dialect_str))
+        else
+          Native.unwrap(Native.polyglot_lineage(column, sql, dialect_str))
+        end
+
+      decode(json)
+    end
+
+    # Column-level lineage for the zero-based output +ordinal+ within +sql+.
+    # Use instead of {lineage} when output names are duplicated or ambiguous.
+    #
+    # @param schema [Hash, nil] optional ValidationSchema for schema-aware lineage
+    # @return [Hash] a LineageNode
+    def lineage_at(ordinal, sql, dialect: nil, schema: nil)
+      dialect_str = resolve_dialect(dialect)
+      json =
+        if schema
+          Native.unwrap(Native.polyglot_lineage_at_with_schema(ordinal, sql, encode(schema), dialect_str))
+        else
+          Native.unwrap(Native.polyglot_lineage_at(ordinal, sql, dialect_str))
+        end
+
+      decode(json)
+    end
+
+    # Physical source tables feeding +column+.
+    #
+    # @return [Array<String>]
+    def source_tables(column, sql, dialect: nil)
+      decode(Native.unwrap(Native.polyglot_source_tables(column, sql, resolve_dialect(dialect))))
+    end
+
+    # Ordered output columns of +sql+. With +schema+, wildcards are expanded
+    # into concrete columns.
+    #
+    # @param schema [Hash, nil] optional ValidationSchema
+    # @return [Hash] columns with name/ordinal plus an +ordinalComplete+ flag
+    def output_columns(sql, dialect: nil, schema: nil)
+      dialect_str = resolve_dialect(dialect)
+      json =
+        if schema
+          Native.unwrap(Native.polyglot_output_columns_with_schema(sql, encode(schema), dialect_str))
+        else
+          Native.unwrap(Native.polyglot_output_columns(sql, dialect_str))
+        end
+
+      decode(json)
+    end
+
+    # Structural analysis of a query (relations, base tables, projections, CTEs).
+    #
+    # @param options [Hash, nil] AnalyzeQueryOptions (may include +dialect+ and +schema+)
+    # @return [Hash] a QueryAnalysis
+    def analyze_query(sql, options: nil, dialect: nil)
+      opts = options ? options.dup : {}
+      opts[:dialect] ||= resolve_dialect(dialect) if dialect
+      decode(Native.unwrap(Native.polyglot_analyze_query(sql, encode(opts))))
+    end
+
+    # ── OpenLineage ────────────────────────────────────────────────────
+
+    # @return [Hash] OpenLineageColumnLineageResult
+    def openlineage_column_lineage(sql, options)
+      decode(Native.unwrap(Native.polyglot_openlineage_column_lineage(sql, encode(options))))
+    end
+
+    # @return [Hash] OpenLineageEventResult
+    def openlineage_job_event(sql, options)
+      decode(Native.unwrap(Native.polyglot_openlineage_job_event(sql, encode(options))))
+    end
+
+    # @return [Hash] OpenLineageEventResult
+    def openlineage_run_event(sql, options)
+      decode(Native.unwrap(Native.polyglot_openlineage_run_event(sql, encode(options))))
+    end
+
+    # ── Diff ───────────────────────────────────────────────────────────
+
+    # Structural diff between two SQL statements.
+    #
+    # @return [Array<Hash>] diff edits
+    def diff(sql1, sql2, dialect: nil)
+      decode(Native.unwrap(Native.polyglot_diff(sql1, sql2, resolve_dialect(dialect))))
+    end
+
+    # ── AST mutators ───────────────────────────────────────────────────
+
+    # @return [Array<Hash>] the modified AST
+    def set_limit(ast, limit)
+      decode(Native.unwrap(Native.polyglot_set_limit(encode(statements(ast)), limit)))
+    end
+
+    # @return [Array<Hash>] the modified AST
+    def set_offset(ast, offset)
+      decode(Native.unwrap(Native.polyglot_set_offset(encode(statements(ast)), offset)))
+    end
+
+    # @param order_by [Hash, Array<Hash>] ORDER BY expression AST
+    # @return [Array<Hash>] the modified AST
+    def set_order_by(ast, order_by)
+      decode(Native.unwrap(Native.polyglot_set_order_by(encode(statements(ast)), encode(statements(order_by)))))
+    end
+
+    # @param options [Hash] qualify options (e.g. catalog/schema defaults)
+    # @return [Array<Hash>] the modified AST
+    def qualify_tables(ast, options: {})
+      decode(Native.unwrap(Native.polyglot_qualify_tables(encode(statements(ast)), encode(options))))
+    end
+
+    # @param mapping [Hash] old-name => new-name
+    # @param options [Hash] rename options
+    # @return [Array<Hash>] the modified AST
+    def rename_tables(ast, mapping, options: {})
+      decode(Native.unwrap(Native.polyglot_rename_tables_with_options(
+                                 encode(statements(ast)), encode(mapping), encode(options)
+                               )))
+    end
+
+    # Annotate an AST with inferred column types.
+    #
+    # @param schema [Hash, nil] optional ValidationSchema
+    # @return [Hash]
+    def annotate_types(sql, dialect: nil, schema: nil)
+      schema_json = schema ? encode(schema) : nil
+      decode(Native.unwrap(Native.polyglot_annotate_types(sql, resolve_dialect(dialect), schema_json)))
+    end
+
+    # ── Introspection ──────────────────────────────────────────────────
+
+    # @return [Array<String>] the dialect names the engine supports
+    def dialects
+      decode(Native.take_string(Native.polyglot_dialect_list))
+    end
+
+    # @return [Integer]
+    def dialect_count
+      Native.polyglot_dialect_count
+    end
+
+    # @return [String] the underlying polyglot-sql engine version, e.g. "0.8.1"
+    def version
+      Native.polyglot_version
+    end
+
+    private
+
+    def resolve_dialect(name)
+      name = configuration.default_dialect if name.nil?
+      Dialect.resolve(name)
+    end
+
+    # The FFI expects a Vec<Expression> JSON array. A single statement from
+    # {.parse_one} is a Hash and must be wrapped without Array()'s Hash-to-pairs
+    # coercion; an Array from {.parse} passes through unchanged.
+    def statements(ast)
+      ast.is_a?(Array) ? ast : [ast]
+    end
+
+    # A JSON array of strings collapses to a bare String for single-statement
+    # results (smart unwrap); multi-statement results stay an Array.
+    def unwrap_list(list)
+      return list unless list.is_a?(Array)
+
+      list.length == 1 ? list.first : list
+    end
+
+    def pretty_each(sql, dialect_str)
+      if sql.is_a?(Array)
+        sql.map { |s| unwrap_list(decode(Native.unwrap(Native.polyglot_format(s, dialect_str)))) }
+      else
+        unwrap_list(decode(Native.unwrap(Native.polyglot_format(sql, dialect_str))))
+      end
+    end
+
+    def compact(hash)
+      hash.reject { |_, v| v.nil? }
+    end
+
+    # Real-world ASTs nest far deeper than Ruby's default max_nesting of 100,
+    # so both directions disable the limit.
+    def decode(json)
+      JSON.parse(json, max_nesting: false)
+    end
+
+    def encode(obj)
+      JSON.generate(obj, max_nesting: false)
+    end
+  end
+end

data/lib/polyglot_sql_ffi.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Entry point matching the gem name; the library lives under PolyglotSql.
+require "polyglot_sql"

data/polyglot_sql_ffi.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "lib/polyglot_sql/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "polyglot_sql_ffi"
+  spec.version = PolyglotSql::VERSION
+  spec.authors = ["Accountaim"]
+  spec.summary = "Ruby wrapper for polyglot-sql: a SQL parser, optimizer, and transpiler"
+  spec.description = <<~DESC
+    A Ruby gem that wraps the polyglot-sql-ffi native library, mirroring the
+    polyglot-sql Python package: SQL parsing, transpilation across 30+ dialects,
+    pretty-formatting, validation, optimization, lineage, and query analysis.
+  DESC
+  spec.homepage = "https://github.com/AccountAim/polyglot-sql-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir["{lib,ext}/**/*", "Gemfile", "Rakefile", "polyglot_sql_ffi.gemspec", "README.md", "LICENSE"].reject do |file|
+      file.match?(%r{\Alib/polyglot_sql/libpolyglot_sql_ffi\.(so|dylib)\z})
+    end
+  end
+
+  spec.require_paths = ["lib"]
+  spec.extensions = ["ext/polyglot_sql_ffi/extconf.rb"]
+
+  spec.add_dependency "ffi", "~> 1.15"
+
+  spec.metadata = {
+    "source_code_uri" => "https://github.com/AccountAim/polyglot-sql-ruby",
+    "rubygems_mfa_required" => "true",
+  }
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: polyglot_sql_ffi
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: aarch64-linux-gnu
+authors:
+- Accountaim
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+description: |
+  A Ruby gem that wraps the polyglot-sql-ffi native library, mirroring the
+  polyglot-sql Python package: SQL parsing, transpilation across 30+ dialects,
+  pretty-formatting, validation, optimization, lineage, and query analysis.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- ext/polyglot_sql_ffi/extconf.rb
+- lib/polyglot_sql.rb
+- lib/polyglot_sql/dialect.rb
+- lib/polyglot_sql/error.rb
+- lib/polyglot_sql/libpolyglot_sql_ffi.so
+- lib/polyglot_sql/native.rb
+- lib/polyglot_sql/railtie.rb
+- lib/polyglot_sql/validation_result.rb
+- lib/polyglot_sql/version.rb
+- lib/polyglot_sql_ffi.rb
+- polyglot_sql_ffi.gemspec
+homepage: https://github.com/AccountAim/polyglot-sql-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/AccountAim/polyglot-sql-ruby
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: 'Ruby wrapper for polyglot-sql: a SQL parser, optimizer, and transpiler'
+test_files: []