sqlc-gen-typescript (PagerGuild Fork)

Note

This is PagerGuild's fork of sqlc-gen-typescript with additional features cherry-picked from upstream PRs.

Upstream Repository: https://github.com/sqlc-dev/sqlc-gen-typescript

Caution

Here be dragons! This plugin is still in early access. Expect breaking changes, missing functionality, and sub-optimal output. Please report all issues and errors. Good luck!

Fork-Specific Changes

This fork includes the following changes not yet merged upstream:

PR	Description	Status Upstream
#58	Native Bun SQL and SQLite drivers	Open

Complete Docker Example

We provide a complete, self-contained example that demonstrates native Bun SQL with PostgreSQL using Docker.

Location: examples/bun-sql-docker/

Quick Start

cd examples/bun-sql-docker
./run-test.sh

This script will:

Start a PostgreSQL container (postgres:alpine)
Create the database schema
Run a comprehensive test program exercising all CRUD operations
Clean up the container automatically

What It Demonstrates

Zero npm dependencies for PostgreSQL - uses Bun's built-in SQL support
Type-safe database queries generated by sqlc
Full CRUD operations: Create, Read, Update, Delete
Docker-based testing for reproducible environments

Requirements

Bun v1.2 or later (for native SQL support)
Docker
sqlc

Syncing with Upstream

Prerequisites

Ensure you have the upstream remote configured:

git remote add upstream https://github.com/sqlc-dev/sqlc-gen-typescript.git
git fetch upstream

When Upstream Merges Our Applied PRs

When upstream merges a PR that we've already applied (e.g., PR #58), follow these steps to rebase:

Fetch the latest upstream changes:
```
git fetch upstream
```

Create a backup branch:

git checkout main
git checkout -b main-backup-$(date +%Y%m%d)

Rebase onto upstream, dropping our cherry-picked commits:
```
git checkout main
git rebase -i upstream/main
```
In the interactive rebase, look for commits with messages like:
- Apply upstream PR #58: ...
These can be dropped (delete the line or change pick to drop) since upstream now has the equivalent changes.
Push the rebased main:
```
git push origin main --force-with-lease
```

Update the submodule in guilde repo:

cd /path/to/guilde
git submodule update --remote submodules/sqlc-gen-typescript
git add submodules/sqlc-gen-typescript
git commit -m "Update sqlc-gen-typescript submodule to latest"

Applying New Upstream PRs

To apply a new upstream PR that hasn't been merged:

Create a feature branch:

git checkout main
git checkout -b upstream-pr-XX

Fetch and apply the PR:

gh pr diff XX --repo sqlc-dev/sqlc-gen-typescript > /tmp/prXX.patch
git apply /tmp/prXX.patch

Commit with upstream reference:

git add -A
git commit -m "Apply upstream PR #XX: <title>

Upstream PR: https://github.com/sqlc-dev/sqlc-gen-typescript/pull/XX
Author: <author>"

Create PR and merge:

git push origin upstream-pr-XX
gh pr create --base main --head upstream-pr-XX \
  --title "Apply upstream PR #XX: <title>" \
  --body "Upstream PR: https://github.com/sqlc-dev/sqlc-gen-typescript/pull/XX"

Checking Upstream Status

To see what upstream has that we don't:

git fetch upstream
git log main..upstream/main --oneline

To see what we have that upstream doesn't:

git log upstream/main..main --oneline

Usage

version: '2'
plugins:
- name: ts
  wasm:
    url: https://downloads.sqlc.dev/plugin/sqlc-gen-typescript_0.1.3.wasm
    sha256: 287df8f6cc06377d67ad5ba02c9e0f00c585509881434d15ea8bd9fc751a9368
sql:
- schema: "schema.sql"
  queries: "query.sql"
  engine: postgresql
  codegen:
  - out: src/authors
    plugin: ts
    options:
      runtime: node
      driver: postgres

Supported engines and drivers

PostgreSQL via pg, postgres or Bun SQL.
MySQL via mysql2.
SQLite via sqlite3.

Getting started

This tutorial assumes that the latest version of sqlc is installed and ready to use.

We'll generate TypeScript here, but other language plugins are available. You'll need Bun (or Node.js) installed if you want to build and run a program with the code sqlc generates, but sqlc itself has no dependencies.

We'll also rely on sqlc's managed databases, which require a sqlc Cloud project and auth token. You can get those from the sqlc Cloud dashboard. Managed databases are an optional feature that improves sqlc's query analysis in many cases, but you can turn it off simply by removing the cloud and database sections of your configuration.

Setting up

Create a new directory called sqlc-tutorial and open it up.

Initialize a new package.

$ bun init

sqlc looks for either a sqlc.(yaml|yml) or sqlc.json file in the current directory. In our new directory, create a file named sqlc.yaml with the following contents:

version: "2"
cloud:
  # Replace <PROJECT_ID> with your project ID from the sqlc Cloud dashboard
  project: "<PROJECT_ID>"
plugins:
- name: ts
  wasm:
    url: https://downloads.sqlc.dev/plugin/sqlc-gen-typescript_0.1.3.wasm
    sha256: 287df8f6cc06377d67ad5ba02c9e0f00c585509881434d15ea8bd9fc751a9368
sql:
  - engine: "postgresql"
    queries: "query.sql"
    schema: "schema.sql"
    database:
      managed: true
    codegen:
    - out: db
      plugin: ts
      options:
        runtime: node
        driver: pg

Replace <PROJECT_ID> with your project ID from the sqlc Cloud dashboard. It will look something like 01HA8SZH31HKYE9RR3N3N3TSJM.

And finally, set the SQLC_AUTH_TOKEN environment variable:

export SQLC_AUTH_TOKEN="<your sqlc auth token>"

Schema and queries

sqlc needs to know your database schema and queries in order to generate code. In the same directory, create a file named schema.sql with the following content:

CREATE TABLE authors (
  id   BIGSERIAL PRIMARY KEY,
  name text      NOT NULL,
  bio  text
);

Next, create a query.sql file with the following five queries:

-- name: GetAuthor :one
SELECT * FROM authors
WHERE id = $1 LIMIT 1;

-- name: ListAuthors :many
SELECT * FROM authors
ORDER BY name;

-- name: CreateAuthor :one
INSERT INTO authors (
  name, bio
) VALUES (
  $1, $2
)
RETURNING *;

-- name: UpdateAuthor :exec
UPDATE authors
  set name = $2,
  bio = $3
WHERE id = $1;

-- name: DeleteAuthor :exec
DELETE FROM authors
WHERE id = $1;

If you prefer, you can alter the UpdateAuthor query to return the updated record:

-- name: UpdateAuthor :one
UPDATE authors
  set name = $2,
  bio = $3
WHERE id = $1
RETURNING *;

Generating code

You are now ready to generate code. You shouldn't see any output when you run the generate subcommand, unless something goes wrong:

$ sqlc generate

You should now have a tutorial subdirectory with three files containing Go source code. These files comprise a Go package named tutorial:

├── package.json
├── query.sql
├── schema.sql
├── sqlc.yaml
└── db
    ├── query_sql.ts

Using generated code

You can use your newly-generated code package from any TypeScript program. Create a file named index.ts and add the following contents:

import { Pool } from "pg";

import {
  createAuthor,
  deleteAuthor,
  getAuthor,
  listAuthors,
} from "./db/query_sql";

async function main() {
  const client = new Pool({ connectionString: process.env["DATABASE_URL"] });
  await client.connect();

  // list all authors
  const authors = await listAuthors(client);
  console.log(authors);

  // create an author
  const author = await createAuthor(client, {
    name: "Anders Hejlsberg",
	bio: "Original author of Turbo Pascal and co-creator of TypeScript",
  });
  if (author === null) {
    throw new Error("author not created");
  }
  console.log(author);

  // get the author we just created
  const anders = await getAuthor(client, { id: author.id });
  if (anders === null) {
    throw new Error("anders not found");
  }
  console.log(anders);

  // delete the author
  await deleteAuthor(client, { id: anders.id });
}

(async () => {
  await main();
  process.exit()
})();

Before this code will run you'll need to install the pg package:

$ bun install pg

The program should compile without errors. To make that possible, sqlc generates readable, idiomatic TypeScript code that you otherwise would've had to write yourself. Take a look in db/query_sql.ts.

Of course for this program to run successfully you'll need to run after setting the DATABASE_URL environment variable. And your database must have the authors table as defined in schema.sql.

$ DATABASE_URL="$(sqlc createdb)" bun run index.ts

$ bun run index.ts

You should now have a working program using sqlc's generated TypeScript source code, and hopefully can see how you'd use sqlc in your own real-world applications.

Configuration

PostgreSQL and node-postgres

version: '2'
plugins:
- name: ts
  wasm:
    url: https://downloads.sqlc.dev/plugin/sqlc-gen-typescript_0.1.3.wasm
    sha256: 287df8f6cc06377d67ad5ba02c9e0f00c585509881434d15ea8bd9fc751a9368
sql:
- schema: "schema.sql"
  queries: "query.sql"
  engine: postgresql
  codegen:
  - out: db
    plugin: ts
    options:
      runtime: node
      driver: pg # npm package name

PostgreSQL and postgres.js

version: '2'
plugins:
- name: ts
  wasm:
    url: https://downloads.sqlc.dev/plugin/sqlc-gen-typescript_0.1.3.wasm
    sha256: 287df8f6cc06377d67ad5ba02c9e0f00c585509881434d15ea8bd9fc751a9368
sql:
- schema: "schema.sql"
  queries: "query.sql"
  engine: postgresql
  codegen:
  - out: db
    plugin: ts
    options:
      runtime: node
      driver: postgres # npm package name

PostgreSQL and Bun SQL

version: '2'
plugins:
- name: ts
  wasm:
    url: https://downloads.sqlc.dev/plugin/sqlc-gen-typescript_0.1.4.wasm
    sha256: 9b2f4eca095a3ba1f0f5e971e371ae52f991396efdb63728fc3e8df92c31ff5f
sql:
- schema: "schema.sql"
  queries: "query.sql"
  engine: postgresql
  codegen:
  - out: db
    plugin: ts
    options:
      runtime: bun
      driver: bun-sql # to use native SQL library of Bun 1.2

MySQL and mysql2

version: '2'
plugins:
- name: ts
  wasm:
    url: https://downloads.sqlc.dev/plugin/sqlc-gen-typescript_0.1.3.wasm
    sha256: 287df8f6cc06377d67ad5ba02c9e0f00c585509881434d15ea8bd9fc751a9368
sql:
- schema: "schema.sql"
  queries: "query.sql"
  engine: "mysql"
  codegen:
  - out: db
    plugin: ts
    options:
      runtime: node
      driver: mysql2 # npm package name

SQLite and better-sqlite3 (Beta)

version: '2'
plugins:
- name: ts
  wasm:
    url: https://downloads.sqlc.dev/plugin/sqlc-gen-typescript_0.1.3.wasm
    sha256: 287df8f6cc06377d67ad5ba02c9e0f00c585509881434d15ea8bd9fc751a9368
sql:
- schema: "schema.sql"
  queries: "query.sql"
  engine: sqlite
  codegen:
  - out: db
    plugin: ts
    options:
      runtime: node
      driver: better-sqlite3 # npm package name

SQLite and Bun SQLite

version: '2'
plugins:
- name: ts
  wasm:
    url: https://downloads.sqlc.dev/plugin/sqlc-gen-typescript_0.1.4.wasm
    sha256: 9b2f4eca095a3ba1f0f5e971e371ae52f991396efdb63728fc3e8df92c31ff5f
sql:
- schema: "schema.sql"
  queries: "query.sql"
  engine: sqlite
  codegen:
  - out: db
    plugin: ts
    options:
      runtime: bun
      driver: bun-sqlite # to use native SQLite library of Bun

Development

If you want to build and test sqlc-gen-typescript locally, follow these steps:

Clone the repository and install dependencies:

git clone https://github.com/sqlc-dev/sqlc-gen-typescript.git
cd sqlc-gen-typescript
npm install

Make your desired changes to the codebase. The main source files are located in the src directory.
If you've made changes that require updating dependencies, run:
```
npm install
```

Build the WASM plugin:
Check the Makefile for details.

make out.js

# Ensure you have Javy installed and available in your PATH
make examples/plugin.wasm

To test your local build, create a test project with a sqlc.yaml file containing:

version: '2'
plugins:
- name: ts
  wasm:
    url: file://{path_to_your_local_wasm_file}
    sha256: {sha256_of_your_wasm_file}
sql:
- schema: "schema.sql"
  queries: "query.sql"
  engine: {your_database_engine}
  codegen:
  - out: db
    plugin: ts
    options:
      runtime: node
      driver: {your_database_driver}

Replace the placeholders with appropriate values for your setup.

Run sqlc in your test project to generate TypeScript code using your local plugin build:
```
sqlc generate
```

For more details on sqlc development, refer to the sqlc core development guide. This guide provides additional information on setting up and working with sqlc in general, which may be useful for contributors to this project.
https://docs.sqlc.dev/en/latest/guides/development.html

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
.github/workflows		.github/workflows
examples		examples
src		src
.gitignore		.gitignore
.oxfmtrc.json		.oxfmtrc.json
.oxlintrc.json		.oxlintrc.json
Justfile		Justfile
README.md		README.md
buf.gen.yaml		buf.gen.yaml
bun.lock		bun.lock
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

sqlc-gen-typescript (PagerGuild Fork)

Fork-Specific Changes

Complete Docker Example

Quick Start

What It Demonstrates

Requirements

Syncing with Upstream

Prerequisites

When Upstream Merges Our Applied PRs

Applying New Upstream PRs

Checking Upstream Status

Usage

Supported engines and drivers

Getting started

Setting up

Schema and queries

Generating code

Using generated code

Configuration

PostgreSQL and node-postgres

PostgreSQL and postgres.js

PostgreSQL and Bun SQL

MySQL and mysql2

SQLite and better-sqlite3 (Beta)

SQLite and Bun SQLite

Development

About

Uh oh!

Releases 6

Packages

Languages

pagerguild/sqlc-gen-typescript

Folders and files

Latest commit

History

Repository files navigation

sqlc-gen-typescript (PagerGuild Fork)

Fork-Specific Changes

Complete Docker Example

Quick Start

What It Demonstrates

Requirements

Syncing with Upstream

Prerequisites

When Upstream Merges Our Applied PRs

Applying New Upstream PRs

Checking Upstream Status

Usage

Supported engines and drivers

Getting started

Setting up

Schema and queries

Generating code

Using generated code

Configuration

PostgreSQL and node-postgres

PostgreSQL and postgres.js

PostgreSQL and Bun SQL

MySQL and mysql2

SQLite and better-sqlite3 (Beta)

SQLite and Bun SQLite

Development

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Languages

Packages