polyglot_sql_ffi

Ruby wrapper for polyglot — a SQL parser, transpiler, optimizer, and lineage engine written in Rust. Mirrors the polyglot-sql Python package's module-level API via FFI.

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.

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:

PolyglotSql.configure { |c| c.default_dialect = :sqlite }

Errors raise subclasses of PolyglotSql::Error (ParseError, TranspileError, ColumnResolutionError, ...).

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.

bundle install
rake native:fetch
bundle exec rspec

Tag vX.Y.Z and push. The release workflow packages platform gems plus the source gem and publishes to RubyGems via trusted publishing.

MIT