googlesqlite

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, and query execution runs on 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

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:

https://goccy.github.io/googlesqlite/

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.

Specs marked partial are documented gaps with a concrete infrastructure dependency; see each spec's frontmatter notes: field for what is missing.

Quick start

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) for seven years without taking any action. Unable to watch that any longer, in 2022 I built 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.

Documentation

Index

• func RegisterExportURIWriter(scheme string, w ExportURIWriter)
• func TimeFromTimestampValue(v string) (time.Time, error)
• type ChangedCatalog
  • func ChangedCatalogFromRows(rows *sql.Rows) (*ChangedCatalog, error)
• type ChangedFunction
• type ChangedTable
• type ColumnSpec
• type ColumnType
  • func UnmarshalDatabaseTypeName(typ string) (*ColumnType, error)
• type Conn
  • func (c *Conn) Begin() (t driver.Tx, e error)
  • func (c *Conn) BeginTx(ctx context.Context, opts driver.TxOptions) (t driver.Tx, e error)
  • func (s *Conn) CheckNamedValue(value *driver.NamedValue) error
  • func (c *Conn) Close() error
  • func (c *Conn) ExecContext(ctx context.Context, query string, args []driver.NamedValue) (r driver.Result, e error)
  • func (c *Conn) IsValid() bool
  • func (c *Conn) Prepare(query string) (driver.Stmt, error)
  • func (c *Conn) PrepareContext(ctx context.Context, query string) (s driver.Stmt, e error)
  • func (c *Conn) QueryContext(ctx context.Context, query string, args []driver.NamedValue) (r driver.Rows, e error)
  • func (c *Conn) SetMaxNamePath(num int)
  • func (c *Conn) SetNamePath(path []string) error
• type Driver
  • func (d *Driver) Open(name string) (driver.Conn, error)
  • func (d *Driver) OpenConnector(name string) (driver.Connector, error)
• type ExportURIWriter
• type ExportWriterOpts
• type FunctionSpec
• type NameWithType
• type TableSpec
• type Tx
  • func (tx *Tx) Commit() error
  • func (tx *Tx) Rollback() error
• type Type

Functions

func RegisterExportURIWriter

func RegisterExportURIWriter(scheme string, w ExportURIWriter)

RegisterExportURIWriter installs w as the writer for EXPORT DATA URIs whose scheme matches scheme (case-insensitive). The "gs" scheme is registered by default and writes to Google Cloud Storage (honoring STORAGE_EMULATOR_HOST so a fake-gcs-server instance is reachable without any extra wiring). Register additional schemes — typically "s3" or "azure" for BigQuery Omni destinations — when the application targets them; an EXPORT DATA against an unregistered scheme fails with a descriptive error rather than silently dropping the export.

Passing a nil writer unregisters the scheme. Registering an already-registered scheme replaces the previous writer; this is by design so an application can swap out the built-in.

func TimeFromTimestampValue

func TimeFromTimestampValue(v string) (time.Time, error)

TimeFromTimestampValue converts a googlesqlite TIMESTAMP cell value back to time.Time. The driver's canonical scan form for TIMESTAMP is "YYYY-MM-DD HH:MM:SS[.ffffff]+00" — those land in the canonical branch below. The function also accepts the predecessor's "<unix-secs>[.frac]" epoch-float spelling so callers carrying old testdata or external integrations relying on that shape keep working.

Types

type ChangedCatalog

type ChangedCatalog = internal.ChangedCatalog

func ChangedCatalogFromRows

func ChangedCatalogFromRows(rows *sql.Rows) (*ChangedCatalog, error)

ChangedCatalogFromRows retrieve modified catalog information from sql.Rows. NOTE: This API relies on the internal structure of sql.Rows, so not will work for all Go versions.

type ChangedFunction

type ChangedFunction = internal.ChangedFunction

type ChangedTable

type ChangedTable = internal.ChangedTable

type ColumnSpec

type ColumnSpec = internal.ColumnSpec

type ColumnType

type ColumnType = internal.Type

func UnmarshalDatabaseTypeName

func UnmarshalDatabaseTypeName(typ string) (*ColumnType, error)

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

func (*Conn) Begin

func (c *Conn) Begin() (t driver.Tx, e error)

func (*Conn) BeginTx

func (c *Conn) BeginTx(ctx context.Context, opts driver.TxOptions) (t driver.Tx, e error)

func (*Conn) CheckNamedValue

func (s *Conn) CheckNamedValue(value *driver.NamedValue) error

func (*Conn) Close

func (c *Conn) Close() error

func (*Conn) ExecContext

func (c *Conn) ExecContext(ctx context.Context, query string, args []driver.NamedValue) (r driver.Result, e error)

func (*Conn) IsValid

func (c *Conn) IsValid() bool

IsValid implements database/sql/driver.Validator. database/sql calls it on every pool fetch before handing the Conn to the next caller — returning false makes the pool discard us and pull a fresh one instead of letting us surface a confusing "sql: connection is already closed" error inside the next request. The flag is set by translateConnDone whenever an earlier operation observed the inner handle had been closed (typically by a request whose context was cancelled mid-statement; database/sql's tx watcher then ran Rollback(discardConn=true) on the inner connection).

func (*Conn) Prepare

func (c *Conn) Prepare(query string) (driver.Stmt, error)

func (*Conn) PrepareContext

func (c *Conn) PrepareContext(ctx context.Context, query string) (s driver.Stmt, e error)

func (*Conn) QueryContext

func (c *Conn) QueryContext(ctx context.Context, query string, args []driver.NamedValue) (r driver.Rows, e error)

func (*Conn) SetMaxNamePath

func (c *Conn) SetMaxNamePath(num int)

SetMaxNamePath specifies the maximum value of name path. If the name path in the query is the maximum value, the name path set as prefix is not used. Effective only when a value greater than zero is specified ( default zero ).

func (*Conn) SetNamePath

func (c *Conn) SetNamePath(path []string) error

SetNamePath set path to name path to be set as prefix. If max name path is specified, an error is returned if the number is exceeded.

type Driver

type Driver struct {
	ConnectHook func(*Conn) error
}

func (*Driver) Open

func (d *Driver) Open(name string) (driver.Conn, error)

func (*Driver) OpenConnector

func (d *Driver) OpenConnector(name string) (driver.Connector, error)

type ExportURIWriter

type ExportURIWriter = exportdata.URIWriter

ExportURIWriter opens an io.WriteCloser for an EXPORT DATA destination URI. The engine uses it to materialize the rows produced by an `EXPORT DATA OPTIONS(uri = '...', format = '...', ...) AS <query>` statement. See RegisterExportURIWriter.

type ExportWriterOpts

type ExportWriterOpts = exportdata.WriterOpts

ExportWriterOpts carries the EXPORT DATA OPTIONS that influence how the destination is opened. Implementations of ExportURIWriter should honor each field where it is meaningful to their scheme and ignore the rest.

type FunctionSpec

type FunctionSpec = internal.FunctionSpec

type NameWithType

type NameWithType = internal.NameWithType

type TableSpec

type TableSpec = internal.TableSpec

type Tx

type Tx struct {
	// contains filtered or unexported fields
}

func (*Tx) Commit

func (tx *Tx) Commit() error

func (*Tx) Rollback

func (tx *Tx) Rollback() error

type Type

type Type = internal.Type