sqlcommon

package
v1.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Index

Constants

View Source
const (
	AzureAuthTypeClientSecret          = "client_secret"
	AzureAuthTypeClientCertificate     = "client_certificate"
	AzureAuthTypeWorkloadIdentity      = "workload_identity"
	AzureAuthTypeSystemManagedIdentity = "system_managed_identity"
	AzureAuthTypeUserManagedIdentity   = "user_managed_identity"
)

Microsoft Entra ID (Azure AD) authentication mechanisms supported by the azure_postgres and azure_mysql database types.

View Source
const (
	// MySQL database type
	MySQL = "mysql"
	// PostgreSQL database type
	PostgreSQL = "postgres"
	// SQLite database type
	SQLite = "sqlite3"
	// AWSMySQL is a MySQL database provided by an AWS service
	AWSMySQL = "aws_mysql"
	// AWSPostgreSQL is a PostgreSQL database provided by an AWS service
	AWSPostgreSQL = "aws_postgres"
	// AzurePostgreSQL is a PostgreSQL database provided by an Azure service,
	// authenticated using Microsoft Entra ID (Azure AD)
	AzurePostgreSQL = "azure_postgres"
	// AzureMySQL is a MySQL database provided by an Azure service,
	// authenticated using Microsoft Entra ID (Azure AD)
	AzureMySQL = "azure_mysql"
)
View Source
const (
	SQLiteVersionQuery   = "SELECT sqlite_version()"
	PostgresVersionQuery = "SHOW server_version"
	MySQLVersionQuery    = "SELECT VERSION()"
)
View Source
const TLSConfigName = "spireCustomTLS"

TLSConfigName is the key under which the custom MySQL TLS config is registered with the go-sql-driver/mysql driver.

Variables

This section is empty.

Functions

func BuildAWSMySQLDSN added in v1.16.0

func BuildAWSMySQLDSN(cfg *Configuration, mysqlConfig *mysql.Config) (string, error)

BuildAWSMySQLDSN builds the AWS RDS / IAM DSN for a MySQL connection. It rejects a connection string carrying a password, since IAM auth supplies a rotating token instead.

func BuildAWSPostgresDSN added in v1.16.0

func BuildAWSPostgresDSN(cfg *Configuration, isReadOnly bool) (string, error)

BuildAWSPostgresDSN builds the AWS RDS / IAM DSN for a postgres connection. It rejects a connection string carrying a password, since IAM auth supplies a rotating token instead.

func BuildAzureMySQLDSN added in v1.16.0

func BuildAzureMySQLDSN(cfg *Configuration, mysqlConfig *mysql.Config) (string, error)

BuildAzureMySQLDSN builds the Microsoft Entra ID DSN for an Azure MySQL connection. It rejects a connection string carrying a password, since Entra ID auth supplies a rotating access token instead.

func BuildAzurePostgresDSN added in v1.16.0

func BuildAzurePostgresDSN(cfg *Configuration, isReadOnly bool) (string, error)

BuildAzurePostgresDSN builds the Microsoft Entra ID DSN for an Azure PostgreSQL connection. It rejects a connection string carrying a password, since Entra ID auth supplies a rotating access token instead.

func ConfigValidate added in v1.16.0

func ConfigValidate(cfg *Configuration) error

ConfigValidate performs static validation of a decoded datastore config.

func ConfigureMySQLConnection added in v1.16.0

func ConfigureMySQLConnection(cfg *Configuration, isReadOnly bool) (*mysql.Config, error)

ConfigureMySQLConnection parses the connection string into a *mysql.Config and, when custom TLS material is configured (root_ca_path / client_cert_path / client_key_path), builds and registers a custom tls.Config with the go-sql-driver/mysql driver and points the returned config at it. The connection string must already have been validated by ValidateMySQLConfig.

func EmbellishSQLite3ConnString

func EmbellishSQLite3ConnString(connectionString string) (string, error)

EmbellishSQLite3ConnString adds query values supported by github.com/mattn/go-sqlite3 to enable journal mode and foreign key support. These query values MUST be part of the connection string in order to be enabled for *each* connection opened by db/sql. If the connection string is not already a file: URI, it is converted first.

func GetConnectionString

func GetConnectionString(cfg *Configuration, isReadOnly bool) string

GetConnectionString returns the connection string corresponding to the database connection.

func HasTLSConfig added in v1.16.0

func HasTLSConfig(cfg *Configuration) bool

HasTLSConfig reports whether the configuration requests custom TLS material (a custom Root CA and/or a client certificate/key pair).

func IsMySQLConstraintViolation

func IsMySQLConstraintViolation(err error) bool

func IsMySQLDbType added in v1.16.0

func IsMySQLDbType(dbType string) bool

IsMySQLDbType reports whether dbType is a MySQL-family database type.

func IsPostgresConstraintViolation

func IsPostgresConstraintViolation(err error) bool

IsPostgresConstraintViolation reports whether err is a PostgreSQL constraint violation (SQLSTATE class 23). It matches errors from both lib/pq and pgx, since connections may be opened through either driver.

func IsPostgresDbType added in v1.16.0

func IsPostgresDbType(dbType string) bool

IsPostgresDbType reports whether dbType is a PostgreSQL-family database type.

func IsSQLiteConstraintViolation

func IsSQLiteConstraintViolation(err error) bool

func IsSQLiteDbType added in v1.16.0

func IsSQLiteDbType(dbType string) bool

IsSQLiteDbType reports whether dbType is the SQLite database type.

func NewSQLError

func NewSQLError(fmtMsg string, args ...any) error

func NewValidationError

func NewValidationError(fmtMsg string, args ...any) error

func NewWrappedSQLError

func NewWrappedSQLError(err error) error

func NewWrappedValidationError

func NewWrappedValidationError(err error) error

func ValidateMySQLConfig added in v1.16.0

func ValidateMySQLConfig(cfg *Configuration, isReadOnly bool) error

ValidateMySQLConfig ensures the MySQL connection string requests parseTime.

Types

type AWSConfig

type AWSConfig struct {
	Region          string `hcl:"region"`
	AccessKeyID     string `hcl:"access_key_id"`
	SecretAccessKey string `hcl:"secret_access_key"`
}

func (*AWSConfig) Validate

func (a *AWSConfig) Validate() error

type AzureConfig added in v1.16.0

type AzureConfig struct {
	// AuthType is one of "client_secret", "client_certificate",
	// "workload_identity", "system_managed_identity", or
	// "user_managed_identity".
	AuthType string `hcl:"auth_type" json:"auth_type"`

	// TenantID is required for auth_type "client_secret",
	// "client_certificate", and "workload_identity". Falls back to
	// AZURE_TENANT_ID.
	TenantID string `hcl:"tenant_id" json:"tenant_id"`

	// ClientID is required for auth_type "client_secret",
	// "client_certificate", and "workload_identity", and for
	// "user_managed_identity" when managed_identity_resource_id is not set.
	// Falls back to AZURE_CLIENT_ID.
	ClientID string `hcl:"client_id" json:"client_id"`

	// ClientSecret is required for auth_type "client_secret". Falls back to
	// AZURE_CLIENT_SECRET.
	ClientSecret string `hcl:"client_secret" json:"client_secret"`

	// ClientCertificatePath is required for auth_type "client_certificate".
	// It must point to a PEM or PKCS#12 file containing the client
	// certificate and private key. Falls back to
	// AZURE_CLIENT_CERTIFICATE_PATH.
	ClientCertificatePath string `hcl:"client_certificate_path" json:"client_certificate_path"`

	// ClientCertificatePassword decrypts ClientCertificatePath, if needed.
	// Falls back to AZURE_CLIENT_CERTIFICATE_PASSWORD.
	ClientCertificatePassword string `hcl:"client_certificate_password" json:"client_certificate_password"`

	// SendCertificateChain is optional and only applies to auth_type
	// "client_certificate". When true, the certificate chain from
	// ClientCertificatePath is sent with each token request, as required for
	// Subject Name/Issuer (SNI) authentication. Defaults to false. Falls back
	// to AZURE_CLIENT_SEND_CERTIFICATE_CHAIN ("1" or "true", case-insensitive)
	// when not set to true here.
	SendCertificateChain bool `hcl:"send_certificate_chain" json:"send_certificate_chain"`

	// FederatedTokenFile is required for auth_type "workload_identity". It is
	// the path to the Kubernetes service account token mounted by the AKS
	// workload identity webhook. Falls back to AZURE_FEDERATED_TOKEN_FILE.
	FederatedTokenFile string `hcl:"federated_token_file" json:"federated_token_file"`

	// ManagedIdentityResourceID is an alternative to ClientID for selecting
	// which user-assigned managed identity to use when auth_type is
	// "user_managed_identity".
	ManagedIdentityResourceID string `hcl:"managed_identity_resource_id" json:"managed_identity_resource_id"`
}

AzureConfig holds the settings needed to authenticate to an Azure database using a Microsoft Entra ID (Azure AD) access token instead of a password. AuthType selects which of the settings below are required; each one may be provided either directly in this configuration or through its corresponding environment variable.

func (*AzureConfig) Resolve added in v1.16.0

func (a *AzureConfig) Resolve() (*ResolvedAzureAuth, error)

Resolve validates AuthType and the settings it requires, resolving each against its corresponding environment variable when not set directly in the configuration. It returns an error naming the missing configuration option and environment variable when a required setting is absent.

func (*AzureConfig) Validate added in v1.16.0

func (a *AzureConfig) Validate() error

type Configuration

type Configuration struct {
	DatabaseTypeNode   ast.Node `hcl:"database_type" json:"database_type"`
	ConnectionString   string   `hcl:"connection_string" json:"connection_string"`
	RoConnectionString string   `hcl:"ro_connection_string" json:"ro_connection_string"`
	RootCAPath         string   `hcl:"root_ca_path" json:"root_ca_path"`
	ClientCertPath     string   `hcl:"client_cert_path" json:"client_cert_path"`
	ClientKeyPath      string   `hcl:"client_key_path" json:"client_key_path"`
	ConnMaxLifetime    *string  `hcl:"conn_max_lifetime" json:"conn_max_lifetime"`
	MaxOpenConns       *int     `hcl:"max_open_conns" json:"max_open_conns"`
	MaxIdleConns       *int     `hcl:"max_idle_conns" json:"max_idle_conns"`
	DisableMigration   bool     `hcl:"disable_migration" json:"disable_migration"`

	DBTypeConfig *DBTypeConfig
	// Undocumented flags
	LogSQL bool `hcl:"log_sql" json:"log_sql"`
}

Configuration for the sql datastore implementation. Pointer values are used to distinguish between "unset" and "zero" values.

func BuildConfig added in v1.16.0

func BuildConfig(hclConfiguration string) (*Configuration, error)

BuildConfig decodes the HCL datastore configuration and resolves the database_type node into a DBTypeConfig.

type DBTypeConfig

type DBTypeConfig struct {
	AWSMySQL      *AWSConfig   `hcl:"aws_mysql" json:"aws_mysql"`
	AWSPostgres   *AWSConfig   `hcl:"aws_postgres" json:"aws_postgres"`
	AzureMySQL    *AzureConfig `hcl:"azure_mysql" json:"azure_mysql"`
	AzurePostgres *AzureConfig `hcl:"azure_postgres" json:"azure_postgres"`
	DatabaseType  string
}

func ParseDatabaseTypeASTNode added in v1.16.0

func ParseDatabaseTypeASTNode(node ast.Node) (*DBTypeConfig, error)

ParseDatabaseTypeASTNode resolves the database_type HCL node, which may be either a bare string ("sqlite3") or an object block (aws_mysql, aws_postgres, azure_mysql, azure_postgres).

type ResolvedAzureAuth added in v1.16.0

type ResolvedAzureAuth struct {
	AuthType                  string
	TenantID                  string
	ClientID                  string
	ClientSecret              string
	ClientCertificatePath     string
	ClientCertificatePassword string
	SendCertificateChain      bool
	FederatedTokenFile        string
	ManagedIdentityResourceID string
}

ResolvedAzureAuth holds the concrete Microsoft Entra ID authentication settings to use, after resolving AzureConfig values against their corresponding environment variables.

type SQLError

type SQLError struct {
	// contains filtered or unexported fields
}

func (*SQLError) Error

func (s *SQLError) Error() string

func (*SQLError) Unwrap

func (s *SQLError) Unwrap() error

type ValidationError

type ValidationError struct {
	// contains filtered or unexported fields
}

func (*ValidationError) Error

func (v *ValidationError) Error() string

func (*ValidationError) Unwrap

func (v *ValidationError) Unwrap() error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL