goccy's BigQuery emulator covers GoogleSQL with a SQLite backend and a per-feature support matrix

The goal is client perspective equivalence, not a SQL playground

The project describes itself as the only open source emulator for Google BigQuery, and the stated goal is to build a server that behaves exactly like BigQuery from the BigQuery client's perspective. That framing sets the bar.

The difference from a local SQL engine is that the emulator has to answer the API calls, not just the queries. The goal section names the Model API, the Connection API and INFORMATION SCHEMA as things that need supporting in addition to evaluating GoogleSQL, because those are the calls a client library makes before it runs a query.

The quick start shows the intended workflow.

$ docker run -it -p 9050:9050 -p 9060:9060 ghcr.io/goccy/bigquery-emulator:latest --project=test
$ bq --api http://0.0.0.0:9050 query --project_id=test "SELECT 1"

Two ports are exposed because there are two APIs. The HTTP port, 9050 by default, serves the BigQuery API. The gRPC port, 9060 by default, serves the BigQuery Storage API, which is the read and write interface the newer client libraries use.

The `bq` command in that example is Google's own command line tool pointed at the emulator through the `--api` flag, which is the cleanest possible demonstration that the emulator is a drop-in rather than a lookalike. A client library that works against the emulator works against the real service with the same code, which is the entire value proposition.

The feature matrix is the honest part of the README

Rather than scattering caveats through the documentation, the project tracks coverage in a single MECE matrix, mutually exclusive and collectively exhaustive, at docs/feature-support.md.

At a glance the README says the emulator supports dataset, table and job management, tabledata management, GoogleSQL query execution, batch load and extract jobs including loads from Google Cloud Storage, streaming inserts, the gRPC BigQuery Storage read and write APIs, and logical and materialized views.

The list of what is not implemented is just as specific: IAM policy management, row access policies, copy jobs, external tables, table snapshots and BigQuery ML.

That second list is the one to read carefully, because each of those omissions breaks a plausible use case. A test that asserts on IAM policy behaviour cannot run here. A pipeline that loads from Cloud Storage via a copy job needs a different path. Anything using BigQuery ML is out of scope entirely. The matrix exists so that a reader can check before committing rather than discovering the gap in CI.

The project also states its maturity plainly, describing itself as still in beta while noting that a large part of BigQuery already works from the official client libraries. The evidence offered for that claim is the multi-client conformance suite in test/e2e, which exercises the official Python, Ruby, PHP, Node.js and Java client libraries plus the bq CLI against the emulator over a shared query corpus, and currently passes for every client.

A shared query corpus run through five client libraries is a stronger conformance argument than a single implementation tested against itself, and the Makefile has a dedicated target for it that requires a running Docker daemon and skips automatically when none is found.

googlesqlite is a pure Go GoogleSQL engine, and the numbers are published

Query execution is powered by googlesqlite, a separate project by the same author that implements almost all of GoogleSQL, and the README reports its support matrix precisely.

As of googlesqlite v0.1.0, the spec driven support matrix reports 523 of 529 GoogleSQL functions and 55 of 59 BigQuery specific functions implemented, roughly 570 built-in functions, along with 16 of 18 data types. Beyond functions it also supports wildcard tables, templated-argument functions and JavaScript UDFs.

Publishing per-function and per-type coverage is the right approach for a compatibility layer, and the missing functions and two missing data types are a usable number for a test environment. JavaScript UDFs matter more than their count suggests, because a lot of real BigQuery SQL uses them to work around dialect gaps, and a test environment that cannot run them will fail on queries that work in production.

The go.mod shows the current pin is googlesqlite v0.3.1, and the authoritative matrix lives in the googlesqlite repository rather than here. Other dependencies reveal how the emulator is built: cloud.google.com/go/bigquery and the official storage client, the Apache Arrow Go library and parquet-go for columnar data, the real Google protobuf and gRPC libraries, gorilla/mux for HTTP routing, zap for logging, and fsouza/fake-gcs-server.

SQLite storage, in memory or on disk, with YAML seeds

The storage layer is SQLite, which is an interesting choice and explains a lot about the behaviour. You can select either memory or a file as the data storage destination at startup, and if you set it to file the data can be persisted.

SQLite gives you a real SQL engine underneath, transactional semantics and a file format you can inspect with standard tools, which is far better for a test environment than an in-memory map. It also bounds what the emulator can do, since anything SQLite cannot express has to be emulated in Go, and it is the reason the SQL dialect work happens in googlesqlite rather than in the emulator itself.

Seeds are loaded from a YAML file at startup, so a test can start the emulator with a known dataset without running setup queries first. That is the feature that turns the emulator from a curiosity into a usable fixture for a test suite.

The Go feature list also includes the option to launch the emulator inside the test process using httptest, for the case where your test client is written in Go. For everything else, the emulator builds as a static single binary and runs as a standalone process, so you point any client at the address and it works, including the bq command line tool and clients written in other languages.

The standalone server takes a set of flags that are worth knowing before you script it: `--project` for the project name, `--dataset` for the dataset name, `--port` for the HTTP port used by the BigQuery API, `--grpc-port` for the gRPC port used by the BigQuery Storage API, and `--log-level`.

The port defaults matter for CI, since 9050 and 9060 are the values the Docker example and the Makefile assume.

A one person project with an explicit feature matrix and signed artefacts

The sponsorship section is unusually candid and is the clearest signal about what to expect from this repository.

The project is a personal project with no support from Google of any kind, no sponsorship, no contributions and no promotion. The author notes that Google has had a request for a BigQuery emulator open on its issue tracker for seven years without taking action, and that in 2022 he built the emulator and has maintained it since. He states that he does not use BigQuery in his own job, develops the project on days off and after work while working full time and maintaining other open source projects, and that the available time is therefore limited.

That is a fair and useful warning. A single maintainer with limited hours is a real risk for a dependency, and the honest framing lets you weigh it. The counterweight is the feature matrix, the multi-client conformance suite, the signed build provenance, and a release history that shows v0.8.1 and v0.8.0 both on 2026-06-13 with v0.7.2 on 2026-05-19. The last push was on 2026-07-24 and the repository is not archived.

The release engineering is better than the version number suggests. Both the release archives and the container image ship a signed GitHub build-provenance attestation, verifiable with the GitHub CLI.

# release archive
$ gh attestation verify bigquery-emulator_v0.0.0_linux_amd64.tar.gz --repo goccy/bigquery-emulator

# container image
$ gh attestation verify oci://ghcr.io/goccy/bigquery-emulator:latest --repo goccy/bigquery-emulator

The build is deliberately cgo free, which is what makes a fully static binary and a multi-architecture image possible without emulation. The Dockerfile cross-compiles on the native build platform using the buildx platform arguments, so multi-arch builds need no QEMU, and the Makefile has a target that builds the multi-arch image exactly as CI does.

The licence is MIT, the module requires Go 1.25.0, and installation is an ordinary `go install` with no native build step, or a Docker pull, or prebuilt binaries and deb, rpm and apk packages from the releases page.

Editorial conclusion

Adopt the BigQuery emulator if your test suite talks to BigQuery and you want to run it locally without credentials, a cloud project or the cost of real queries. Do not adopt it if you need the features listed as unimplemented, since IAM policy management, row access policies, copy jobs, external tables, table snapshots and BigQuery ML are all absent, and do not treat it as a substitute for a final integration test against the real service. Verify first that the feature support matrix covers the specific BigQuery calls your code makes, that the conformance suite in test/e2e passes for the client library your language uses, and that the storage backend choice, memory or file, matches what your test needs.

Frequently asked questions

Official sources

1. goccy/bigquery-emulator on GitHub
2. Issues
3. License: MIT
4. README
5. Releases