google/googlesql: the SQL analyzer you embed, not the database you query

What google/googlesql actually is, and who needs it

The README is blunt about scope: GoogleSQL defines a SQL language (grammar, types, data model, semantics and function library) and implements parsing and analysis as a reusable component. It is not itself a database or query engine. That single sentence decides who the project is for. If you want to run queries against stored data, you want BigQuery, Spanner, PostgreSQL or something else. If you are writing a query engine, a SQL front end, a migration tool or a linter, and you want your users' SELECT statements to resolve names, check types and insert implicit casts the way Google's products do, this is the component you embed.

The language is used across BigQuery, Spanner, F1, BigTable, Dremel and Procella, according to the README. Those are engines with different storage and execution models sharing one front end. That is the design bet: language behavior belongs in a library, so a fleet of engines agrees on what a query means before any of them executes it. The compliance test suite exists to check that an engine implementation is correct and consistent with that shared meaning.

The repository also states plainly that it provides no guarantees of API stability and cannot accept contributions. Treat that as a hard constraint on how you depend on it, not a formality.

Parsing, analysis and the Resolved AST

The pipeline visible in the repository layout has three stages. The grammar and parser live in googlesql/parser, described as semi-public because parse trees are not a stable API. The analyzer in googlesql/analyzer does the work engines care about: name resolution, type checking and implicit casting. Its output is the Resolved AST, defined in googlesql/resolved_ast and documented in docs/resolved_ast.md, which the README calls the intermediate representation produced by the GoogleSQL analyzer.

The Resolved AST is the integration point. An engine consumes it instead of re-implementing semantics, and googlesql/public holds most of the public APIs. Function implementations that engines can reuse live in googlesql/public/functions. Below that sits googlesql/reference_impl, the reference implementation for executing queries, which is what the execute_query tool drives.

Two consequences follow. First, engines may implement a subset of features and return errors for the rest, so a query that analyzes cleanly here can still fail in a given engine. Second, because parse trees are explicitly not a stable API, tooling that reaches below the analyzer into the parser is building on sand. The supported surface is the public API and the Resolved AST, and the repository does not promise stability even there.

Installing execute_query and running a first query

For a first look you do not need to build anything. The README points to prebuilt binaries for execute_query for Linux and MacOS on the Releases page. Download one, make it executable and start the web interface:

chmod +x execute_query_linux
./execute_query_linux --web

The prebuilt binaries require GCC 9 or newer and tzdata. On macOS the README notes you may hit a developer verification error; right-click the execute_query_macos file, choose open, and it should run afterwards.

If the binary will not run on your platform, the Docker route avoids the dependency question. Download googlesql_docker.tar.gz from the Releases page and load it:

sudo docker load -i /path/to/the/downloaded/googlesql_docker.tar.gz
sudo docker run --init -it -h=$(hostname) -p 8080:8080 googlesql execute_query --web

The image name is googlesql. The README explains each flag: --init lets execute_query handle signals, -it runs interactively, -h=$(hostname) matches the container hostname to the host, and -p 8080:8080 forwards the port so the web server is reachable. On an Apple M-series machine, add --platform linux/amd64 to the docker run command.

Building from source uses Bazel, with the version pinned in .bazelversion, plus tzdata (installable with apt-get install tzdata on Linux). The README gives this as the build and run command:

bazel run googlesql/tools/execute_query:execute_query -- --web

Runnable examples ship in the repository, including googlesql/examples/tpch and googlesql/examples/pipe_queries, so you have something to paste into the tool before writing your own SQL.

Pipe syntax is the feature most worth evaluating first

GoogleSQL's pipe query syntax is the part of the language that differs most visibly from ordinary SQL, and the README gives it unusual prominence: reference documentation in docs/pipe-syntax.md, a research paper (VLDB 2024, "SQL Has Problems. We Can Fix Them: Pipe Syntax in SQL"), example scripts under googlesql/examples/pipe_queries and TPC-H queries under googlesql/examples/tpch. If you are evaluating the project, run one of those TPC-H queries through execute_query before anything else. It exercises the parser, the analyzer and the reference implementation in one pass, and it shows whether your engine's existing SQL dialect and this one can coexist.

The honest trade-off: pipe syntax is a language extension, not a neutral parser swap. An engine that adopts GoogleSQL to get consistent semantics also inherits a syntax its users may not know. The repository does not document a compatibility mode for stripping pipe syntax, so if your users write standard SQL and you only want name resolution and type checking, you are adopting more language than you asked for.

No API stability, no contributions, and no production executor

The limitations are stated by the project itself, which is rare and useful. There are no guarantees of API stability, and contributions are not accepted. That means a dependency on google/googlesql is a fork-and-maintain relationship, not a normal upstream one. You can read the code, you can vendor it, but you cannot send a patch and expect it to land. Plan for that before you build a product on it.

The reference implementation is a second boundary. It exists to execute queries for debugging, and the README describes execute_query as a tool to parse, analyze and run SQL using the reference implementation. Nothing in the repository presents it as a production query engine. Do not benchmark it as one and do not ship it as one.

Platform support is the third constraint. Linux is the reference platform, with Ubuntu 22.04 named specifically and other distributions possibly working. macOS is marked experimental. There is no Windows target in the stated multiplatform plan.

Finally, the rename. GoogleSQL was previously ZetaSQL, and there is a migration guide in zetasql_to_googlesql_migration.md. Older documentation, package names and blog posts use the old name, so expect to translate when reading anything not in this repository.

GoogleSQL vs PostgreSQL: different jobs, not competing ones

The comparison people reach for is GoogleSQL against PostgreSQL, and the useful answer is that they are not the same kind of thing. PostgreSQL is a database: it stores data, plans and executes queries, and manages transactions. google/googlesql is an analyzer library with a reference executor for debugging. You cannot connect to it and persist a table.

The real alternative depends on what you are building. If you need a SQL front end you can embed in a C++ engine, the closest approach in spirit is to write your own parser and analyzer, or to use a parser generator and hand-roll semantics. That gives you control over the dialect and no dependency risk, at the cost of reimplementing name resolution, type checking and implicit casting, which is precisely the work this project has already done and tests with a compliance suite.

If you are working in the BigQuery ecosystem rather than building an engine, the README points to the GoogleSQL Toolkit, a separate project that uses GoogleSQL to analyze and understand queries against BigQuery and other GoogleSQL engines. That is a higher-level tool for a different job: understanding existing queries rather than implementing a language. Choose based on whether you are writing an engine or inspecting one.

Maintenance, releases and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-16. Releases are frequent and versioned by date: 2026.9.2 on 2026-09-16, 2026.9.1 on 2026-09-03, and 2026.7.2 on 2026-07-14. That cadence matters less than it looks, because the project disclaims API stability. Upgrading is not a matter of reading a changelog and bumping a number; it is a matter of recompiling against the new revision and seeing what the analyzer now rejects or resolves differently. Budget for that on every release you take.

The licence is Apache-2.0, which is permissive and includes an explicit patent grant. The practical implication for a team embedding this in a product is that you can ship it inside a proprietary engine, provided you keep the licence notice and are aware of the patent termination clause. That is a statement about what the licence text is, not legal advice; your counsel should review it alongside your distribution model.

One dependency note from the repository files: go.mod pins the Go module path github.com/google/googlesql and requires the textmapper generator, used for grammar work. The Java APIs under googlesql/java/com/google/googlesql are implemented by calling a local RPC server, so a JVM integration is not a simple jar drop; it carries a process boundary.

Editorial conclusion

Adopt google/googlesql if you are building or validating a query engine and want GoogleSQL name resolution, type checking and implicit casting to behave the same way they do in BigQuery or Spanner, and if you can live with the repository's statement that it offers no API stability guarantees and cannot accept contributions. Do not adopt it as a database: it stores nothing, and the reference implementation exists for debugging rather than production workloads. Before committing, verify that your target platform is Linux (Ubuntu 22.04 is the stated reference platform, with macOS experimental), that you can supply tzdata and GCC 9 or newer for the prebuilt binary, and that you have read the migration guide from the ZetaSQL naming.

Frequently asked questions

Official sources

1. google/googlesql on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases