https://github.com/goccy/googlesqlite
Run GoogleSQL using SQLite3 as the backend
https://github.com/goccy/googlesqlite
golang golang-library googlesql sqlite webassembly
Last synced: 25 days ago
JSON representation
Run GoogleSQL using SQLite3 as the backend
- Host: GitHub
- URL: https://github.com/goccy/googlesqlite
- Owner: goccy
- License: mit
- Created: 2026-04-19T03:52:44.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-25T03:02:21.000Z (27 days ago)
- Last Synced: 2026-05-26T21:34:46.584Z (25 days ago)
- Topics: golang, golang-library, googlesql, sqlite, webassembly
- Language: Go
- Homepage: https://goccy.github.io/googlesqlite/
- Size: 2.4 MB
- Stars: 10
- Watchers: 0
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Notice: NOTICE
Awesome Lists containing this project
README
# GoogleSQLite
GoogleSQLite is a Go project that runs GoogleSQL — the SQL dialect
used by BigQuery and Cloud Spanner — on top of a SQLite backend. It is
exposed as a `database/sql` driver, so any `database/sql` consumer gets
a local GoogleSQL execution engine with no external services to run.
GoogleSQL parsing and analysis is provided by
[`goccy/go-googlesql`](https://github.com/goccy/go-googlesql), and query
execution runs on
[`ncruces/go-sqlite3`](https://github.com/ncruces/go-sqlite3). Both are
implemented in pure Go, so GoogleSQLite is pure Go as well — no cgo is
required.
Because GoogleSQL is the dialect behind BigQuery and Cloud Spanner,
this project gives strong support to use cases such as locally
emulating those services.
## Usage
```go
import (
"database/sql"
_ "github.com/goccy/googlesqlite"
)
db, err := sql.Open("googlesqlite", ":memory:")
if err != nil {
log.Fatal(err)
}
defer db.Close()
rows, err := db.Query(`SELECT FORMAT('%t', DATE '2026-05-14') AS today`)
// ...
```
The driver registers under `googlesqlite`. DSN is the underlying
SQLite path (`:memory:`, a file path, or
`file:foo.db?cache=shared`).
## Playground
Try GoogleSQLite in your browser, with nothing to install:
****
The Playground is the whole engine — GoogleSQL parsing, analysis, and
the SQLite backend — compiled to WebAssembly and run entirely
client-side. Highlights:
- **No server, no install.** Every query is parsed, analyzed, and
executed inside the browser tab; nothing is sent anywhere.
- **Responsive UI.** The engine runs in a Web Worker, so editing and
running queries never blocks the page.
- **Persistent database.** The SQLite database lives in the Origin
Private File System (OPFS), so your tables and data survive page
reloads with no explicit save step.
- **A real SQL editor**, with query history and result export.
It is the quickest way to explore the supported GoogleSQL syntax and
functions without setting up a Go environment.
## Status
Every function and type is backed by a declarative spec under
`docs/specs/` and at least one upstream-sourced test case under
`testdata/specs/`. The full support matrix — per-function and
per-type status with a link to each spec — is generated from spec
frontmatter into [`docs/specs/INDEX.md`](docs/specs/INDEX.md).
Specs marked `partial` are documented gaps with a concrete
infrastructure dependency; see each spec's frontmatter `notes:`
field for what is missing.
## Quick start
```sh
make build # build the bin/googlesqlite CLI
make test # run unit and spec tests
make lint # golangci-lint via tools/go.mod
make spec/upstream-sync # refresh docs/third_party/googlesql-docs from upstream
```
## Layout
- `docs/specs/` — canonical, normalized spec markdown (one file per
function/type).
- `testdata/specs/` — declarative YAML test cases referenced by spec
frontmatter. The repo-root `TestSpec` runner executes each case
against the driver as a Go subtest.
- `docs/third_party/googlesql-docs/` — Apache-2.0 snapshot of upstream
`google/googlesql` `docs/`. Refreshed by
`make spec/upstream-sync`.
- `cmd/specctl/` — operational CLI (normalize, upstream-sync,
check, ...).
- `tools/go.mod` — pinned developer tools (golangci-lint).
## Sponsorship
This is a personal project. It is developed by referencing the
open-source GoogleSQL repository, but it receives no support of any kind
from Google — no sponsorship, no contributions, no promotion.
For example, Google has had a request for a BigQuery emulator open on
its Issue Tracker
([issue 129248927](https://issuetracker.google.com/issues/129248927))
for seven years without taking any action. Unable to watch that any
longer, in 2022 I built
[`goccy/bigquery-emulator`](https://github.com/goccy/bigquery-emulator)
— the only BigQuery emulator in the world — and have maintained it ever
since.
This project is used by that `bigquery-emulator`. I do not use BigQuery
in my own job, however. I simply happen to have the skills to build
this, noticed how many people are struggling without it, and so I spend
my personal time and money on it.
Because of that, keeping this project alive needs your help. Emulating
BigQuery locally brings many benefits to development and can
significantly cut development costs. Could you return a small part of
those savings to me? I believe doing so leads to a better future for
both me and your company.
See `CLAUDE.md` for the project's working rules.