From d4a4dc3aa17829adf9d66d53d7a534ea59ead6be Mon Sep 17 00:00:00 2001 From: Mike Fridman Date: Sat, 3 Feb 2024 07:03:21 -0500 Subject: [PATCH] docs: Improve OpenDBWithDriver comments --- db.go | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/db.go b/db.go index e43a6fe4f..10311236e 100644 --- a/db.go +++ b/db.go @@ -5,15 +5,23 @@ import ( "fmt" ) -// OpenDBWithDriver creates a connection to a database, and modifies goose -// internals to be compatible with the supplied driver by calling SetDialect. +// OpenDBWithDriver creates a connection to a database, and modifies goose internals to be +// compatible with the supplied driver by calling SetDialect. func OpenDBWithDriver(driver string, dbstring string) (*sql.DB, error) { if err := SetDialect(driver); err != nil { return nil, err } - // To avoid breaking existing consumers. An implementation detail - // that consumers should not care which underlying driver is used. + // The Go ecosystem has added more and more drivers over the years. As a result, there's no + // longer a one-to-one match between the driver name and the dialect name. For instance, there's + // no "redshift" driver, but that's the internal dialect name within goose. Hence, we need to + // convert the dialect name to a supported driver name. This conversion is a best-effort + // attempt, as we can't support both lib/pq and pgx, which some users might have. + // + // We recommend users to create a [NewProvider] with the desired dialect, open a connection + // using their preferred driver, and provide the *sql.DB to goose. This approach removes the + // need for mapping dialects to drivers, rendering this function unnecessary. + switch driver { case "mssql": driver = "sqlserver" @@ -22,7 +30,6 @@ func OpenDBWithDriver(driver string, dbstring string) (*sql.DB, error) { case "turso": driver = "libsql" case "sqlite3": - // Internally uses the CGo-free port of SQLite: modernc.org/sqlite driver = "sqlite" case "postgres", "redshift": driver = "pgx"