connectionstate

package
v1.18.1 Latest Latest
Warning

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

 Go to latest Published: Sep 24, 2025 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// ContextStartup is used for ConnectionProperty instances that may only be set at startup and may not be changed
	// during the lifetime of a connection.
	ContextStartup = iota
	// ContextUser is used for ConnectionProperty instances that may be set both at startup and during the lifetime of
	// a connection.
	ContextUser
)

Variables

This section is empty.

Functions

func ConvertBool 

func ConvertBool(value string) (bool, error)

func ConvertDuration 

func ConvertDuration(value string) (time.Duration, error)

func ConvertInt 

func ConvertInt(value string) (int, error)

func ConvertInt64 

func ConvertInt64(value string) (int64, error)

func ConvertReadOnlyStaleness 

func ConvertReadOnlyStaleness(value string) (spanner.TimestampBound, error)

func ConvertString 

func ConvertString(value string) (string, error)

func ConvertUint64 

func ConvertUint64(value string) (uint64, error)

func CreateReadOnlyConverter 

func CreateReadOnlyConverter[T any](property string) func(value string) (T, error)

func ExtractValues 

func ExtractValues(properties map[string]ConnectionProperty, values map[string]string) (map[string]ConnectionPropertyValue, error)

ExtractValues extracts a map of ConnectionPropertyValue from a map of strings. The converter function that is registered for the corresponding ConnectionProperty is used to convert the string value to the actual value.

Types

type ConnectionProperty 

type ConnectionProperty interface {
	// Key returns the unique key of the ConnectionProperty. This is equal to the name of the property for properties
	// without an extension, and equal to `extension.name` for properties with an extension.
	Key() string
	// Context returns the Context where the property is allowed to be updated (e.g. only at startup or during the
	// lifetime of a connection).
	Context() Context
	// CreateDefaultValue creates an initial value of the property with the default value of the property as the current
	// and reset value.
	CreateDefaultValue() ConnectionPropertyValue
	// CreateInitialValue creates an initial value of the property with the given value as the default and reset value.
	CreateInitialValue(value any) (ConnectionPropertyValue, error)
	// GetValue returns the current value of the property.
	// The returned bool indicates whether a value has been set or not. This can be used to distinguish between a
	// connection where the zero value has explicitly been set as the value and just having the default value.
	GetValue(state *ConnectionState) (any, bool, error)
	// SetUntypedValue sets a new value for the property without knowing the type in advance.
	// This is a synonym for SetValue.
	SetUntypedValue(state *ConnectionState, value any, context Context) error
	// SetLocalUntypedValue sets a new local value for the property without knowing the type in advance.
	// This is a synonym for SetLocalValue.
	SetLocalUntypedValue(state *ConnectionState, value any) error
	// SetDefaultValue sets the value of the property to the default value.
	// This is different from resetting the value, which sets it to the value that the property had when the connection
	// was created.
	SetDefaultValue(state *ConnectionState, context Context) error
	// SetLocalDefaultValue sets the local value of the property to the default value.
	// This is different from resetting the value, which sets it to the value that the property had when the connection
	// was created.
	SetLocalDefaultValue(state *ConnectionState) error
	// ResetValue sets the value of the property to its initial value.
	ResetValue(state *ConnectionState, context Context) error
	// ResetLocalValue sets the local value of the property to its initial value.
	ResetLocalValue(state *ConnectionState) error
	// Convert converts a string to the corresponding value type of the connection property.
	Convert(value string) (any, error)
}

ConnectionProperty defines the public interface for connection properties.

type ConnectionPropertyValue 

type ConnectionPropertyValue interface {
	// ConnectionProperty returns the property that this value is for.
	ConnectionProperty() ConnectionProperty
	// Copy creates a shallow copy of the ConnectionPropertyValue.
	Copy() ConnectionPropertyValue
	// HasValue indicates whether this ConnectionPropertyValue has an explicit value.
	HasValue() bool
	// GetValue gets the current value of the property.
	GetValue() (any, error)
	// ClearValue removes the value of the property.
	ClearValue(context Context) error
	// SetValue sets the value of the property. The given value must be a valid value for the property.
	SetValue(value any, setValueCommand setValueCommand, context Context) error
	// ResetValue resets the value of the property to the value it had at the creation of the connection.
	// This method should only be called when resetting the entire connection state.
	ResetValue(context Context) error
	// RemoveAtReset indicates whether the value should be removed from the ConnectionState when the ConnectionState is
	// reset. This function should return true for property values that have been added to the set after the connection
	// was created, for example because the user executed `set my_extension.my_property='some-value'`.
	RemoveAtReset() bool
	// GetResetValue returns the value that will be assigned to this property value if the value is reset.
	GetResetValue() any
	// contains filtered or unexported methods
}

ConnectionPropertyValue is the public interface for connection state property values.

type ConnectionState 

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

ConnectionState contains connection the state of a connection in a map.

func NewConnectionState 

func NewConnectionState(connectionStateType Type, properties map[string]ConnectionProperty, initialValues map[string]ConnectionPropertyValue) (*ConnectionState, error)

NewConnectionState creates a new ConnectionState instance with the given initial values. The Type must be either TypeTransactional or TypeNonTransactional.

func (*ConnectionState) Begin 

func (cs *ConnectionState) Begin() error

Begin starts a new transaction for this ConnectionState.

func (*ConnectionState) Commit 

func (cs *ConnectionState) Commit() error

Commit the current ConnectionState. This resets all local property values to the value they had before the transaction. If the Type is TypeTransactional, then all pending state changes are committed. If the Type is TypeNonTransactional, all state changes during the transaction have already been persisted during the transaction.

func (*ConnectionState) GetValue 

func (cs *ConnectionState) GetValue(extension, name string) (any, bool, error)

func (*ConnectionState) Reset 

func (cs *ConnectionState) Reset(context Context) error

Reset the state to the initial values. Only the properties with a Context equal to or higher than the given Context will be reset. E.g. if the given Context is ContextUser, then properties with ContextStartup will not be reset.

func (*ConnectionState) Rollback 

func (cs *ConnectionState) Rollback() error

Rollback the current transactional state. This resets all local property values to the value they had before the transaction. If the Type is TypeTransactional, then all pending state changes are rolled back. If the Type is TypeNonTransactional, all state changes during the transaction have already been persisted during the transaction.

func (*ConnectionState) SetLocalValue 

func (cs *ConnectionState) SetLocalValue(extension, name, value string) error

func (*ConnectionState) SetValue 

func (cs *ConnectionState) SetValue(extension, name, value string, context Context) error

type Context 

type Context int

Context indicates when a ConnectionProperty may be set.

func (Context) String 

func (c Context) String() string

type Type 

type Type int

Type represents the type of ConnectionState that is used. ConnectionState can be either transactional or non-transactional. Transactional ConnectionState means that any changes to the state during a transaction will only be persisted and visible after the transaction if the transaction is committed. Non-transactional ConnectionState means that changes that are made to the state during a transaction are persisted directly and will be visible after the transaction regardless whether the transaction was committed or rolled back. 

const (
	// TypeDefault indicates that the default ConnectionState type of the database dialect should be used.
	// GoogleSQL uses non-transactional ConnectionState by default.
	// PostgreSQL uses transactional ConnectionState by default.
	TypeDefault Type = iota
	// TypeTransactional ConnectionState means that changes to the state during a transaction will only be
	// persisted and visible after the transaction if the transaction is committed.
	TypeTransactional
	// TypeNonTransactional ConnectionState means that changes to the state during a transaction are persisted
	// directly and remain visible after the transaction, regardless whether the transaction committed or not.
	TypeNonTransactional
)

type TypedConnectionProperty 

type TypedConnectionProperty[T comparable] struct {
	// contains filtered or unexported fields
}

TypedConnectionProperty implements the ConnectionProperty interface. All fields are unexported to ensure that the values can only be updated in accordance with the semantics of the chosen ConnectionState Type.

func CreateConnectionProperty 

func CreateConnectionProperty[T comparable](name, description string, defaultValue T, hasDefaultValue bool, validValues []T, context Context, converter func(value string) (T, error)) *TypedConnectionProperty[T]

CreateConnectionProperty is used to create a new ConnectionProperty with a specific type. This function is intended for use by driver implementations at initialization time to define the properties that the driver supports.

func CreateConnectionPropertyWithExtension 

func CreateConnectionPropertyWithExtension[T comparable](extension, name, description string, defaultValue T, hasDefaultValue bool, validValues []T, context Context, converter func(value string) (T, error)) *TypedConnectionProperty[T]

CreateConnectionPropertyWithExtension is used to create a new ConnectionProperty with a specific type and an extension. Properties with an extension can be created dynamically during the lifetime of a connection. These are lost when the connection is reset to its original state.

func (*TypedConnectionProperty[T]) Context 

func (p *TypedConnectionProperty[T]) Context() Context

func (*TypedConnectionProperty[T]) Convert 

func (p *TypedConnectionProperty[T]) Convert(value string) (any, error)

func (*TypedConnectionProperty[T]) CreateDefaultValue 

func (p *TypedConnectionProperty[T]) CreateDefaultValue() ConnectionPropertyValue

CreateDefaultValue implements ConnectionProperty.CreateDefaultValue.

func (*TypedConnectionProperty[T]) CreateInitialValue 

func (p *TypedConnectionProperty[T]) CreateInitialValue(value any) (ConnectionPropertyValue, error)

CreateInitialValue implements ConnectionProperty.CreateInitialValue.

func (*TypedConnectionProperty[T]) CreateTypedInitialValue 

func (p *TypedConnectionProperty[T]) CreateTypedInitialValue(value T) ConnectionPropertyValue

CreateTypedInitialValue creates an initial value for a connection property with a known type.

func (*TypedConnectionProperty[T]) GetConnectionPropertyValue 

func (p *TypedConnectionProperty[T]) GetConnectionPropertyValue(state *ConnectionState) ConnectionPropertyValue

GetConnectionPropertyValue returns a reference to the ConnectionPropertyValue in the given ConnectionState. The function returns nil if the property does not exist. The function returns the default value if the property exists, but there is no value for the property in the given ConnectionState.

func (*TypedConnectionProperty[T]) GetValue 

func (p *TypedConnectionProperty[T]) GetValue(state *ConnectionState) (any, bool, error)

GetValue implements ConnectionPropertyValue.GetValue

func (*TypedConnectionProperty[T]) GetValueOrDefault 

func (p *TypedConnectionProperty[T]) GetValueOrDefault(state *ConnectionState) T

GetValueOrDefault returns the current value of the property in the given ConnectionState. It returns the default of the property if no value is found.

func (*TypedConnectionProperty[T]) GetValueOrError 

func (p *TypedConnectionProperty[T]) GetValueOrError(state *ConnectionState) (T, bool, error)

GetValueOrError returns the current value of the property in the given ConnectionState. It returns an error if no value is found.

func (*TypedConnectionProperty[T]) Key 

func (p *TypedConnectionProperty[T]) Key() string

func (*TypedConnectionProperty[T]) ResetLocalValue 

func (p *TypedConnectionProperty[T]) ResetLocalValue(state *ConnectionState) error

ResetLocalValue resets the local value of the property in the given ConnectionState to its original value.

func (*TypedConnectionProperty[T]) ResetValue 

func (p *TypedConnectionProperty[T]) ResetValue(state *ConnectionState, context Context) error

ResetValue resets the value of the property in the given ConnectionState to its original value.

The given Context should indicate the current context where the application tries to reset the value, e.g. it should be ContextUser if the reset happens during the lifetime of a connection, and ContextStartup if the reset happens at the creation of a connection.

func (*TypedConnectionProperty[T]) SetDefaultValue 

func (p *TypedConnectionProperty[T]) SetDefaultValue(state *ConnectionState, context Context) error

SetDefaultValue implements ConnectionProperty.SetDefaultValue.

func (*TypedConnectionProperty[T]) SetLocalDefaultValue 

func (p *TypedConnectionProperty[T]) SetLocalDefaultValue(state *ConnectionState) error

SetLocalDefaultValue implements ConnectionProperty.SetLocalDefaultValue.

func (*TypedConnectionProperty[T]) SetLocalUntypedValue 

func (p *TypedConnectionProperty[T]) SetLocalUntypedValue(state *ConnectionState, value any) error

SetLocalUntypedValue implements ConnectionProperty.SetLocalUntypedValue.

func (*TypedConnectionProperty[T]) SetLocalValue 

func (p *TypedConnectionProperty[T]) SetLocalValue(state *ConnectionState, value T) error

SetLocalValue sets the local value of the property in the given ConnectionState. A local value is only visible for the remainder of the current transaction. The value is reset to the value it had before the transaction when the transaction ends, regardless whether the transaction committed or rolled back.

Setting a local value outside a transaction is a no-op.

func (*TypedConnectionProperty[T]) SetUntypedValue 

func (p *TypedConnectionProperty[T]) SetUntypedValue(state *ConnectionState, value any, context Context) error

SetUntypedValue implements ConnectionProperty.SetUntypedValue.

func (*TypedConnectionProperty[T]) SetValue 

func (p *TypedConnectionProperty[T]) SetValue(state *ConnectionState, value T, context Context) error

SetValue sets the value of the property in the given ConnectionState.

The given Context should indicate the current context where the application tries to reset the value, e.g. it should be ContextUser if the reset happens during the lifetime of a connection, and ContextStartup if the reset happens at the creation of a connection.

func (*TypedConnectionProperty[T]) String 

func (p *TypedConnectionProperty[T]) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.