Documentation
¶
Overview ¶
Copyright 2025 Google LLC
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Index ¶
- Constants
- func GetCloudSQLOpts(ipType, userAgent string, useIAM bool) ([]cloudsqlconn.Option, error)
- func GetIAMAccessToken(ctx context.Context) (string, error)
- func GetIAMPrincipalEmailFromADC(ctx context.Context, dbType string) (string, error)
- func InitConnectionSpan(ctx context.Context, tracer trace.Tracer, sourceType, sourceName string) (context.Context, trace.Span)
- func NormalizeValue(val any, oid uint32) any
- func Register(sourceType string, factory SourceConfigFactory) bool
- type Cache
- type ConnectOnce
- type Dialect
- type IPType
- type Item
- type OnEvictFunc
- type Option
- type Source
- type SourceConfig
- type SourceConfigFactory
Constants ¶
const CloudPlatformScope = "https://www.googleapis.com/auth/cloud-platform"
CloudPlatformScope is the OAuth2 scope for Google Cloud Platform services.
const ConnectTimeout = 60 * time.Second
ConnectTimeout is the default ceiling on a connection attempt. It is sized for a cold cloud connector path rather than for a healthy connection.
Variables ¶
This section is empty.
Functions ¶
func GetCloudSQLOpts ¶
func GetCloudSQLOpts(ipType, userAgent string, useIAM bool) ([]cloudsqlconn.Option, error)
GetCloudSQLDialOpts retrieve dial options with the right ip type and user agent for cloud sql databases.
func GetIAMPrincipalEmailFromADC ¶
GetIAMPrincipalEmailFromADC finds the email associated with ADC
func InitConnectionSpan ¶
func InitConnectionSpan(ctx context.Context, tracer trace.Tracer, sourceType, sourceName string) (context.Context, trace.Span)
InitConnectionSpan adds a span for database pool connection initialization
func NormalizeValue ¶ added in v1.10.0
NormalizeValue converts specific database types to friendly representations (e.g. UUID to string).
func Register ¶
func Register(sourceType string, factory SourceConfigFactory) bool
Register registers a new source type with its factory. It returns false if the type is already registered.
Types ¶
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache is a thread-safe, expiring key-value store
func NewCache ¶
func NewCache(onEvict OnEvictFunc) *Cache
NewCache creates a new cache and cleans up every 55 min
func (*Cache) DeleteExpired ¶
func (c *Cache) DeleteExpired()
DeleteExpired removes all expired items
type ConnectOnce ¶ added in v1.11.0
type ConnectOnce[T any] struct { // contains filtered or unexported fields }
ConnectOnce holds a connection a source builds on first use. A source keeps one of these instead of a bare handle and resolves it through Do.
func NewConnectOnce ¶ added in v1.11.0
func NewConnectOnce[T any](ctx context.Context, name, sourceType string, tracer trace.Tracer, opts ...Option) *ConnectOnce[T]
NewConnectOnce returns a holder for a connection that has not been made yet. ctx must be the context Initialize was called with: every later connect runs under it, so the source reports the startup user agent and cannot pick up request-scoped values from whichever caller happens to trigger it.
func (*ConnectOnce[T]) Close ¶ added in v1.11.0
func (c *ConnectOnce[T]) Close(ctx context.Context) error
Close releases the connection, if one was ever made, and stops another from being made. It is safe on a source that never connected and safe to call twice.
Close does not wait for an attempt that is already in flight. That attempt releases its own result rather than caching it into a closed holder, so shutdown never blocks on a connect that may be hung for the full timeout.
func (*ConnectOnce[T]) Do ¶ added in v1.11.0
func (c *ConnectOnce[T]) Do(ctx context.Context, connect func(context.Context) (T, error)) (T, error)
Do returns the connection, making it on the first call. Concurrent callers share one attempt, and a failed attempt is not remembered.
Because a failure is retried by the next caller rather than cached, connect must release whatever it had already built before it returns an error. A pool that fails its ping and is returned unclosed leaks once per tool call, not once per process.
func (*ConnectOnce[T]) Get ¶ added in v1.11.0
func (c *ConnectOnce[T]) Get() (T, bool)
Get returns the connection if one has already been made. It never blocks and never fails, so a source's context-free accessors — the ones tools type assert on — can report a handle without being able to build one.
func (*ConnectOnce[T]) OnClose ¶ added in v1.11.0
func (c *ConnectOnce[T]) OnClose(fn func(context.Context, T) error) *ConnectOnce[T]
OnClose registers how to release the connection. A source that holds a handle with no teardown can leave it unset. It is meant to be chained onto NewConnectOnce, before the holder is reachable by another goroutine.
type OnEvictFunc ¶
OnEvictFunc is the signature for the callback
type Option ¶ added in v1.11.0
type Option func(*options)
Option configures a ConnectOnce.
func WithMinConnectTimeout ¶ added in v1.11.0
WithMinConnectTimeout raises the ceiling for a source whose own configuration allows a longer connect. A shorter value is ignored: the source's own bound still applies inside the ceiling, and lowering the ceiling would not make it any tighter.
type Source ¶
type Source interface {
SourceType() string
ToConfig() SourceConfig
IsReadOnly() bool
}
Source is the interface for the source itself.
type SourceConfig ¶
type SourceConfig interface {
SourceConfigType() string
Initialize(ctx context.Context, tracer trace.Tracer) (Source, error)
}
SourceConfig is the interface for configuring a source.
func DecodeConfig ¶
func DecodeConfig(ctx context.Context, sourceType string, name string, decoder *yaml.Decoder) (SourceConfig, error)
DecodeConfig decodes a source configuration using the registered factory for the given type.
type SourceConfigFactory ¶
type SourceConfigFactory func(ctx context.Context, name string, decoder *yaml.Decoder) (SourceConfig, error)
SourceConfigFactory defines the function signature for creating a SourceConfig.
Source Files
Directories