sqldb

Documentation

Overview

Package sqldb is a package that puts a *sql.DB into the context of every request and retrieves it for you. It also initializes and deinitializes the database connection.

This package is an outgrowth of the fleet console service https://pkg.go.dev/go.chromium.org/infra/fleetconsole, which takes inspiration (nearly verbatim inspiration) from device manager https://pkg.go.dev/go.chromium.org/infra/device_manager.

Its goal is to make it easier to connect to a SQL database from a LUCI server application without a lot of boilerplate code, and to correctly handle getting the database credential from secret manager (accessed via the LUCI secrets library).

https://pkg.go.dev/go.chromium.org/luci/server/secrets

It understands the following flags:

-sqldb-password-secret
-sqldb-connection-url

Note that the driver is implied by the scheme of the URL. This is to allow you to talk to "postgres://username@localhost:5000/dbname" using "pgx://username@localhost:5000/dbname".

Also, note that the exact details of how the driver and the connection URL interact is easily the most contentious part of the design of this library. Another way of thinking about it is that this is where we have chosen to spend our complexity budget. The rest of the module is pretty straightforward.

This package also does not support multiple, simultaneous DB connections. We thought about it, and we decided not to do it. There is a path forward, though, if we need to add this in the future without breaking backwards compatibility. That is to have the concept of a "main" database, specified in some way which will use the current API, but also some additional functions for accessing a DB connection by a string name.

Index

• Variables
• func GetDB(ctx context.Context) (*sql.DB, error)
• func MustGetDB(ctx context.Context) *sql.DB
• func NewModule(opts *ModuleOptions) module.Module
• func NewModuleFromFlags() module.Module
• func UseDB(ctx context.Context, db *sql.DB) context.Context
• type ModuleOptions
  • func (o *ModuleOptions) Register(f *flag.FlagSet)

Variables

var ModuleName = module.RegisterName("go.chromium.org/luci/server/sqldb")

ModuleName can be used to refer to this module when declaring dependencies.

Functions

func GetDB

func GetDB(ctx context.Context) (*sql.DB, error)

GetDB retrieves the current database connection from the context.

func MustGetDB

func MustGetDB(ctx context.Context) *sql.DB

MustGetDB gets a sql.DB from the context and panics if it isn't available.

func NewModule

func NewModule(opts *ModuleOptions) module.Module

NewModule makes a new module.

func NewModuleFromFlags

func NewModuleFromFlags() module.Module

NewModuleFromFlags is a variant of NewModule that initializes options through command line flags.

Calling this function registers flags in flag.CommandLine. They are usually parsed in server.Main(...).

func UseDB

func UseDB(ctx context.Context, db *sql.DB) context.Context

UseDB puts a SQL database connection into the current context, giving us back a new context.

Types

type ModuleOptions

type ModuleOptions struct {
	// DBPasswordSecret is a secret-manager managed secret if using the sm:// protocol
	// For local stuff use devsecret://<base64> or devsecret-text://<normal text>
	DBPasswordSecret string
	// DBConnectionURL is the connection string for the DB.
	DBConnectionURL *url.URL
}

ModuleOptions are the options for SQLDB.

func (*ModuleOptions) Register

func (o *ModuleOptions) Register(f *flag.FlagSet)

Register registers some flags.