From 79023854de24a58a22efedc42b161c89043ce205 Mon Sep 17 00:00:00 2001 From: Marin Nozhchev Date: Tue, 13 Jan 2026 09:01:44 +0200 Subject: [PATCH 1/6] Add more examples for compatible drivers --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e66f416..de730b2 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,7 @@ `usqlgen` creates custom distributions of [github.com/xo/usql](https://github.com/xo/usql) — a universal single-binary SQL CLI, built by the [github.com/xo](https://github.com/xo) team, and inspired by [psql](https://www.postgresql.org/docs/current/app-psql.html). - -`usql` is great because it is a multi-platform, multi-database SQL client in a single binary. -Learn more about it from its [README](https://github.com/xo/usql#readme). +With `usqlgen`, you can turn any Go `database/sql` driver into a CLI with a single command. `usqlgen` builds on usql's extensibility to allow including arbitrary drivers and other customizations, without needing to fork. @@ -107,7 +105,10 @@ You can try the same with databases or data engines like: - various SQLite derivatives - [rqlite](https://github.com/rqlite/gorqlite?tab=readme-ov-file#driver-for-databasesql), [libsql / turso](https://github.com/tursodatabase/go-libsql) -- [Dremio or Apache Drill](https://github.com/factset/go-drill), +- [Dremio or Apache Drill](https://github.com/factset/go-drill), +- [Cloudflare D1](https://github.com/SyneHQ/d1_go_sql), +- [TDEngine](https://github.com/taosdata/driver-go) - [a time-series database](https://tdengine.com/tsdb/), +- - etc. `usqlgen` also allows you to import alternative drivers of supported databases. Examples include: @@ -121,6 +122,7 @@ You can try the same with databases or data engines like: [its ADBC API](https://duckdb.org/docs/clients/adbc) - [github.com/ncruces/go-sqlite3/driver](https://github.com/ncruces/go-sqlite3) - another pure Go SQLite, based on [wazero](https://github.com/wazero/wazero), as opposed to ccgo. +- [github.com/mattn/go-oci8](https://github.com/mattn/go-oci8) - alternative Oracle driver, wrapping the official Oracle client For more options, see `usqlgen --help` or review the examples below. From 720879ae13fbe948ad31bc8996130cdc67f96f4e Mon Sep 17 00:00:00 2001 From: Marin Nozhchev Date: Tue, 13 Jan 2026 21:58:50 +0200 Subject: [PATCH 2/6] Update README with IBM DB2 and ImmuDB details Added information about IBM DB2 and ImmuDB drivers. --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index de730b2..6544335 100644 --- a/README.md +++ b/README.md @@ -108,7 +108,9 @@ You can try the same with databases or data engines like: - [Dremio or Apache Drill](https://github.com/factset/go-drill), - [Cloudflare D1](https://github.com/SyneHQ/d1_go_sql), - [TDEngine](https://github.com/taosdata/driver-go) - [a time-series database](https://tdengine.com/tsdb/), -- +- [IBM DB2](https://github.com/ibmdb/go_ibm_db) - vanilla usql makes you use ODBC to access DB2. ODBC might not be available on your system or container. +- [ImmuDB](https://immudb.io/) - driver package is [github.com/codenotary/immudb/v2/pkg/stdlib](https://docs.immudb.io/master/connecting/sdks) + - ImmuDB is an example of a driver whose license allows you to use it locally with `usqlgen` but likely prevents adding it to upstream `usql`. - etc. `usqlgen` also allows you to import alternative drivers of supported databases. Examples include: From 059bdd542ac857f7b05c65c80ba1ff11b2430fa6 Mon Sep 17 00:00:00 2001 From: Marin Nozhchev Date: Wed, 14 Jan 2026 09:27:49 +0200 Subject: [PATCH 3/6] Complete README --- README.md | 72 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 40 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 6544335..988191b 100644 --- a/README.md +++ b/README.md @@ -66,9 +66,12 @@ chmod +x ./usql `usqlgen` isn't distributed as prebuilt binaries because running it requires Go installation anyway (locally or within a container). +For brevity, the examples below assume `usqlgen` is installed on the PATH, but, in practice, +it is more convinient use `go run` without installing. + ## Quickstart -To install `usql` with support for an additional driver, first review your driver documentation +To build `usql` with support for an additional driver, first review your driver documentation to find the Go driver name, DSN ([Data Source Name](https://pkg.go.dev/database/sql#Open)) format, and package that needs to be imported. Let's take for example, [MonetDB](https://github.com/MonetDB/MonetDB-Go#readme), which is not in `usql` yet. The docs @@ -101,44 +104,20 @@ So to connect to MonetDB with the binary we just built, run: Above `monetdb` is repeated in the beginning of the DB URL because it is both the Go driver name, and the admin username in the beginning of the DSN. -You can try the same with databases or data engines like: - -- various SQLite derivatives - [rqlite](https://github.com/rqlite/gorqlite?tab=readme-ov-file#driver-for-databasesql), - [libsql / turso](https://github.com/tursodatabase/go-libsql) -- [Dremio or Apache Drill](https://github.com/factset/go-drill), -- [Cloudflare D1](https://github.com/SyneHQ/d1_go_sql), -- [TDEngine](https://github.com/taosdata/driver-go) - [a time-series database](https://tdengine.com/tsdb/), -- [IBM DB2](https://github.com/ibmdb/go_ibm_db) - vanilla usql makes you use ODBC to access DB2. ODBC might not be available on your system or container. -- [ImmuDB](https://immudb.io/) - driver package is [github.com/codenotary/immudb/v2/pkg/stdlib](https://docs.immudb.io/master/connecting/sdks) - - ImmuDB is an example of a driver whose license allows you to use it locally with `usqlgen` but likely prevents adding it to upstream `usql`. -- etc. - -`usqlgen` also allows you to import alternative drivers of supported databases. Examples include: - -- [github.com/microsoft/gocosmos](https://github.com/microsoft/gocosmos) - an official(-ish) mirror of the unofficial - driver included in `usql` -- [github.com/yugabyte/pgx/stdlib](https://github.com/yugabyte/pgx) - Standalone fork of the Postgres pgx driver with - cluster-aware load balancing by [Yugabyte](https://www.yugabyte.com/) -- [github.com/mailru/go-clickhouse/v2](https://github.com/mailru/go-clickhouse) - HTTP-only alternative of the built-in Clickhouse driver -- [github.com/sclgo/adbcduck-go](https://github.com/sclgo/adbcduck-go) - alternative driver for DuckDB on top of - [its ADBC API](https://duckdb.org/docs/clients/adbc) -- [github.com/ncruces/go-sqlite3/driver](https://github.com/ncruces/go-sqlite3) - another pure Go SQLite, based on - [wazero](https://github.com/wazero/wazero), as opposed to ccgo. -- [github.com/mattn/go-oci8](https://github.com/mattn/go-oci8) - alternative Oracle driver, wrapping the official Oracle client - -For more options, see `usqlgen --help` or review the examples below. +For more options, see `usqlgen --help` or review the [examples](#examples) below. ## Limitations Most `usql` [backslash (meta) commands](https://github.com/xo/usql?tab=readme-ov-file#backslash-commands) work with new drivers added with `--import`, including [cross-database `\copy`](https://github.com/xo/usql?tab=readme-ov-file#copying-between-databases). -Informational commands will work though if the database provides ANSI-compatible `information_schema`. +However, informational commands eg. `\dt` work only if the database provides ANSI-compatible +[information_schema](https://en.wikipedia.org/wiki/Information_schema). `usql` requires that connection strings are valid URIs or URLs, at least according to the Go `net/url` parsing algorithm. If you get an error that parameter in the form `driverName:DSN` can't be parsed as a URL, start `usql` without a connection string - in interactive mode or with the `-f` parameter. `usql` will start not connected to a DB. -Then use the `\connect` command with two arguments driverName and DSN. In the `monetdb` example above, that would be: +Then use the `\connect` command with two arguments driverName and DSN. In the `monetdb` quickstart example above, that would be: `\connect monetdb monetdb:password@localhost:50000/monetdb`. ## CGO usage @@ -146,8 +125,8 @@ Then use the `\connect` command with two arguments driverName and DSN. In the `m With `usqlgen`, [CGO support](https://pkg.go.dev/cmd/cgo) on the system is not needed in most cases. In contrast, compiling `usql` the regular way does require CGO. With `usqlgen`, you only need CGO if you: -- import drivers that use CGO e.g. `--import github.com/sclgo/adbcduck-go`. The driver documentation should mention such - usage. +- import drivers that use CGO e.g. `--import github.com/sclgo/adbcduck-go`. The driver documentation should mention + if the drivers uses CGO. - add drivers that use CGO with tags e.g. `-- -tags duckdb` . When CGO is not available, `usqlgen build/install` commands modify the default "base" driver set, @@ -168,6 +147,35 @@ All in all, `usqlgen`, and the `usql` binaries it produces, are very portable, e ## Examples +### Tested drivers + +You can try `usqlgen` with databases or data engines like: + +- various SQLite derivatives - [rqlite](https://github.com/rqlite/gorqlite?tab=readme-ov-file#driver-for-databasesql), + [libsql / turso](https://github.com/tursodatabase/go-libsql) +- [Dremio or Apache Drill](https://github.com/factset/go-drill), +- [Cloudflare D1](https://github.com/SyneHQ/d1_go_sql), +- [TDEngine](https://github.com/taosdata/driver-go) - [a time-series database](https://tdengine.com/tsdb/) . This driver compiles only if TDEngine + libraries are already installed on the system and, as a result, can't be added to upstream `usql`. +- [ImmuDB](https://immudb.io/) - driver package is [github.com/codenotary/immudb/v2/pkg/stdlib](https://docs.immudb.io/master/connecting/sdks) . + This is an example of a driver whose license allows you to use it locally with `usqlgen` but likely prevents adding it to upstream `usql`. +- etc. + +`usqlgen` also allows you to import alternative drivers of supported databases. Examples include: + +- [github.com/microsoft/gocosmos](https://github.com/microsoft/gocosmos) - an official(-ish) mirror of the unofficial + driver included in `usql` +- [github.com/yugabyte/pgx/stdlib](https://github.com/yugabyte/pgx) - Standalone fork of the Postgres pgx driver with + cluster-aware load balancing by [Yugabyte](https://www.yugabyte.com/) +- [github.com/mailru/go-clickhouse/v2](https://github.com/mailru/go-clickhouse) - HTTP-only alternative of the built-in Clickhouse driver +- [github.com/sclgo/adbcduck-go](https://github.com/sclgo/adbcduck-go) - alternative driver for DuckDB on top of + [its ADBC API](https://duckdb.org/docs/clients/adbc) +- [github.com/ncruces/go-sqlite3/driver](https://github.com/ncruces/go-sqlite3) - another pure Go SQLite, based on + [wazero](https://github.com/wazero/wazero), as opposed to ccgo. +- [github.com/mattn/go-oci8](https://github.com/mattn/go-oci8) - alternative Oracle driver, wrapping the official Oracle client +- [github.com/ibmdb/go_ibm_db](https://github.com/ibmdb/go_ibm_db) - upstream `usql` makes you use ODBC to access IBM DB2. If ODBC is not an option + for you, this driver might help even though [its installation](https://github.com/ibmdb/go_ibm_db/blob/master/INSTALL.md) is quite convoluted. + ### Installing the customized `usql` Use `usqlgen install ...` to install the customized `usql` to `GOPATH/bin` which is @@ -184,7 +192,7 @@ usql -c '\drivers' | grep monetdb `usqlgen build` and `usqlgen install` call `go build` and `go install` respectively. You can pass options directly to the `go` commands after the `--` parameter. -For example, the following command supplies go build tag no_base which removes +For example, the following command supplies go build tag `no_base` which removes all built-in `usql` drivers so only the custom one we add remains: ```shell From 26b9bdd1fd282d40dca351d96196f4741b5da62e Mon Sep 17 00:00:00 2001 From: Marin Nozhchev Date: Wed, 14 Jan 2026 09:31:46 +0200 Subject: [PATCH 4/6] Improve documentation on compilation errors Clarify potential causes of compilation errors and provide additional troubleshooting steps. --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 988191b..39c7654 100644 --- a/README.md +++ b/README.md @@ -307,12 +307,15 @@ stop the program. ### Compilation errors -Any compilation errors during `build` or `install` commands are likely caused by +Compilation errors during `build` or `install` commands may be caused by incompatibility between the newly imported drivers and the existing ones. Trying adding `-- -tags no_base` to the command. If that resolves the compilation issue, but removes an existing driver that you need, try adding it specifically using the respective tag, documented in . +Compilation errors may also be caused by unsatisfied requirements of the driver. Some Go drivers wrap +native drivers and need the drivers to be manually installed beforehand. + ## Support If you encounter problems, please review [open issues](https://github.com/sclgo/usqlgen/issues) and create one if From 8904260b0a10336d1cf16d181efb25fe87c43a91 Mon Sep 17 00:00:00 2001 From: Marin Nozhchev Date: Wed, 14 Jan 2026 09:35:09 +0200 Subject: [PATCH 5/6] Update README.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 39c7654..4218b82 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ chmod +x ./usql (locally or within a container). For brevity, the examples below assume `usqlgen` is installed on the PATH, but, in practice, -it is more convinient use `go run` without installing. +it is more convenient use `go run` without installing. ## Quickstart From 1175b18873f91322d4164c63dc0065af54f5bc8a Mon Sep 17 00:00:00 2001 From: Marin Nozhchev Date: Wed, 14 Jan 2026 09:35:19 +0200 Subject: [PATCH 6/6] Update README.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4218b82..94e1a08 100644 --- a/README.md +++ b/README.md @@ -126,7 +126,7 @@ With `usqlgen`, [CGO support](https://pkg.go.dev/cmd/cgo) on the system is not n In contrast, compiling `usql` the regular way does require CGO. With `usqlgen`, you only need CGO if you: - import drivers that use CGO e.g. `--import github.com/sclgo/adbcduck-go`. The driver documentation should mention - if the drivers uses CGO. + if the driver uses CGO. - add drivers that use CGO with tags e.g. `-- -tags duckdb` . When CGO is not available, `usqlgen build/install` commands modify the default "base" driver set,