README
¶
Cloud SQL datasource
cloudsql is a GoFr SQL datasource for Google Cloud SQL (Postgres and MySQL).
It is built on top of GoFr's standard SQL datasource — it does not reimplement any
SQL behavior — and adds IAM database authentication via the
Cloud SQL Go Connector.
It supports, with a single DB_IAM_AUTH switch and no code change:
- IAM database authentication on the cloud (no static password, no Cloud SQL Auth Proxy sidecar) — credentials resolve via Application Default Credentials, which works with Workload Identity Federation.
- Username/password for local development — when IAM auth is off the datasource is GoFr's standard SQL connection.
It is published as a separate module so the GCP SDK dependencies are only pulled in by applications that actually use Cloud SQL — the GoFr core stays lean.
Install
go get gofr.dev/pkg/gofr/datasource/cloudsql
Usage
The same one line works locally and on GCP — only configuration changes:
package main
import (
"gofr.dev/pkg/gofr"
"gofr.dev/pkg/gofr/datasource/cloudsql"
)
func main() {
app := gofr.New()
app.AddSQLDB(cloudsql.New(app.Config))
app.Run()
}
Once added, app.SQL() / ctx.SQL behave like any other GoFr SQL connection,
including query logging, metrics and health checks.
Configuration
| Env var | Description |
|---|---|
DB_HOST |
Instance connection name project:region:instance (IAM), or host (standard) |
DB_DIALECT |
postgres or mysql |
DB_NAME |
Database name |
DB_USER |
IAM principal (SA email without .gserviceaccount.com), or DB user |
DB_IAM_AUTH |
true enables IAM auth; otherwise standard username/password is used |
DB_PASSWORD |
Only used when DB_IAM_AUTH is not true |
DB_CLOUDSQL_IP_TYPE |
PUBLIC (default), PRIVATE or PSC |
DB_MAX_IDLE_CONNECTION / DB_MAX_OPEN_CONNECTION |
Pool sizing; zero uses GoFr defaults |
How it works
New returns a *Connector that GoFr drives via AddSQLDB, which calls its
Connect method. When DB_IAM_AUTH is not true, Connect returns a nil
connector, so AddSQLDB keeps GoFr's standard env-configured SQL datasource
(username/password) untouched. When IAM auth is requested, Connect builds a
database/sql driver.Connector that dials through the Cloud SQL connector
(Postgres via pgx, MySQL via go-sql-driver) plus a cleanup that tears down the
dialer's background credential refresh.
GoFr core does the wrapping: AddSQLDB opens the connector through GoFr's standard
SQL datasource (sql.NewSQLFromConnector), so logging, metrics, health checks and
transactions behave identically and no SQL behavior is duplicated. Crucially this
module imports only database/sql/driver and the GCP SDK — never gofr.dev — so
the cloud SDK stays out of apps that don't use it.
Extending to other cloud providers
This module is the reference implementation of a GoFr "managed SQL" provider. AWS
RDS/Aurora and Azure Database can be added as their own leaf modules without any
change to GoFr core, following the same contract. See the developer guide in
doc.go for the AWS/Azure token-refresh pattern.
See the runnable example.
Documentation
¶
Overview ¶
Package cloudsql provides a Google Cloud SQL (Postgres and MySQL) connector for GoFr that authenticates with IAM database authentication via the Cloud SQL Go Connector. It builds only a database/sql driver.Connector and hands it to GoFr — it does not import GoFr core, so the GCP SDK stays out of any app that does not use it. GoFr's App.AddSQLDB opens the connector through GoFr's standard SQL datasource, so logging, metrics, health checks and transactions behave exactly as for any other GoFr SQL connection.
A single configuration switch, DB_IAM_AUTH, selects the connection mode:
- DB_IAM_AUTH=true → connect through the Cloud SQL connector using IAM auth. Credentials resolve via Application Default Credentials (which supports Workload Identity Federation), so no static password and no Cloud SQL Auth Proxy sidecar are required.
- otherwise → Connect returns a nil connector, so App.AddSQLDB keeps GoFr's standard env-configured SQL datasource (host:port with username/password), exactly as gofr.New() would on its own.
Because the mode is chosen from configuration, application code is identical in both environments — there is no conditional to write:
app := gofr.New() app.AddSQLDB(cloudsql.New(app.Config)) app.Run()
Set username/password locally and DB_IAM_AUTH=true on GCP; the code does not change. In both cases app.SQL()/ctx.SQL and all of GoFr's SQL logging, metrics, health checks and transactions behave identically, because GoFr always wraps the connection in its standard SQL datasource.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
Config is the read-only configuration accessor cloudsql needs. It is defined locally — rather than importing GoFr's config package — so this module never depends on GoFr core. GoFr's app.Config satisfies it, so the one-liner app.AddSQLDB(cloudsql.New(app.Config)) compiles unchanged.
type Connector ¶
type Connector struct {
// contains filtered or unexported fields
}
Connector builds a database/sql driver.Connector for a Cloud SQL instance from configuration. It is handed to GoFr's App.AddSQLDB, which calls Connect and wraps the result in GoFr's standard SQL datasource. Keeping this module's output a plain driver.Connector is what keeps GoFr core (and every other app) free of the GCP SDK.
func New ¶
New returns a Cloud SQL Connector that reads its configuration (the DB_* keys) from conf. No connection is established here; App.AddSQLDB calls Connect:
app.AddSQLDB(cloudsql.New(app.Config))
func (*Connector) Connect ¶
Connect builds the driver.Connector for IAM auth and a cleanup that tears down the Cloud SQL dialer (stopping its background credential refresh). When IAM auth is not requested it returns a nil connector and nil cleanup, signaling App.AddSQLDB to keep GoFr's standard env-configured SQL connection — so the same code and the same AddSQLDB call work locally and on GCP, with only configuration changing.
Connect is one-shot per Connector. The MySQL path registers a process-global dial-context under a unique name (database/sql/go-sql-driver have no unregister), so a Connector should be connected once over its lifetime rather than reconnected in a loop; the Postgres path registers nothing global.
Source Files