backend

package
v1.4.0-nextgen.202510.7 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source 
const (
	// DialTimeout is the timeout for each dial.
	DialTimeout = 1 * time.Second
	// ConnectTimeout is the timeout for choosing and connecting to an available backend.
	ConnectTimeout = 15 * time.Second
	// CheckBackendInterval is the interval for checking if the backend is still connected.
	CheckBackendInterval = time.Minute
	// TickerInterval is the interval for checking backend status.
	TickerInterval = 5 * time.Second
)
View Source 
const (
	StatusInTrans uint32 = 1 << iota
	StatusQuit
	StatusPrepareWaitExecute
	StatusPrepareWaitFetch
)
View Source 
const ER_INVALID_SEQUENCE = 8052
View Source 
const SupportedServerCapabilities = pnet.ClientLongPassword | pnet.ClientFoundRows | pnet.ClientConnectWithDB |
	pnet.ClientODBC | pnet.ClientLocalFiles | pnet.ClientInteractive | pnet.ClientLongFlag | pnet.ClientSSL |
	pnet.ClientTransactions | pnet.ClientReserved | pnet.ClientSecureConnection | pnet.ClientMultiStatements |
	pnet.ClientMultiResults | pnet.ClientPluginAuth | pnet.ClientConnectAttrs | pnet.ClientPluginAuthLenencClientData |
	pnet.ClientCompress | pnet.ClientZstdCompressionAlgorithm | requiredFrontendCaps | defRequiredBackendCaps

SupportedServerCapabilities is the default supported capabilities. Other server capabilities are not supported. TiDB supports ClientDeprecateEOF since v6.3.0. TiDB supports ClientCompress and ClientZstdCompressionAlgorithm since v7.2.0.

Variables

View Source 
var (
	ErrCloseConnMgr    = errors.New("failed to close connection manager")
	ErrTargetUnhealthy = errors.New("target backend becomes unhealthy")
	ErrInTxn           = errors.New("connection is in transaction")
	ErrClosing         = errors.New("connection is closing")
)
View Source 
var (
	ErrClientConn  = errors.New("this is an error from the client connection")
	ErrBackendConn = errors.New("this is an error from the backend connection")
)

These errors may not be disconnection errors. They are used for marking whether the error comes from the client or the backend.

View Source 
var (
	ErrClientCap        = errors.New("Verify client capability failed, please upgrade the client")
	ErrClientHandshake  = errors.New("Fails to handshake with the client")
	ErrClientAuthFail   = errors.New("Authentication fails")
	ErrProxyErr         = errors.New("Other serverless error")
	ErrProxyNoBackend   = errors.New("No available TiDB instances, please make sure TiDB is available")
	ErrProxyNoTLS       = errors.New("Require TLS enabled on TiProxy when require-backend-tls=true")
	ErrBackendCap       = errors.New("Verify TiDB capability failed, please upgrade TiDB")
	ErrBackendHandshake = errors.New("TiProxy fails to connect to TiDB, please make sure TiDB is available")
	ErrBackendNoTLS     = errors.New("Require TLS enabled on TiDB when require-backend-tls=true")
	ErrBackendPPV2      = errors.New("TiProxy fails to connect to TiDB, please make sure TiDB proxy-protocol is set correctly. If this error still exists, please contact PingCAP")
)

These errors are used to track internal errors.

Functions

func ErrToClient added in v0.2.0 

func ErrToClient(err error) error

ErrToClient returns the error that needs to be sent to the client.

Types

type Authenticator 

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

Authenticator handshakes with the client and the backend.

func NewAuthenticator added in v1.0.0 

func NewAuthenticator(config *BCConfig) *Authenticator

func (*Authenticator) ConnInfo 

func (auth *Authenticator) ConnInfo() []zap.Field

type BCConfig 

type BCConfig struct {
	HealthyKeepAlive     config.KeepAlive
	UnhealthyKeepAlive   config.KeepAlive
	FromPublicEndpoints  func(addr net.Addr) bool
	DialContext          func(ctx context.Context, backend router.BackendInst, addr string) (net.Conn, error)
	TickerInterval       time.Duration
	CheckBackendInterval time.Duration
	DialTimeout          time.Duration
	ConnectTimeout       time.Duration
	ConnBufferSize       int
	ProxyProtocol        bool
	RequireBackendTLS    bool
}

type BackendConnManager 

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

BackendConnManager migrates a session from one BackendConnection to another.

The signal processing goroutine tries to migrate the session once it receives a signal. If the session is not ready at that time, the cmd executing goroutine will try after executing commands.

If redirection fails, it doesn't retry and waits for the next signal, because: - If it disconnects immediately: it's even worse than graceful shutdown. - If it retries after each command: the latency will be unacceptable afterwards if it always fails. - If it stops receiving signals: the previous new backend may be abnormal but the next new backend may be good.

func NewBackendConnManager 

func NewBackendConnManager(logger *zap.Logger, handshakeHandler HandshakeHandler, cpt capture.Capture, connectionID uint64,
	config *BCConfig, meter Meter) *BackendConnManager

NewBackendConnManager creates a BackendConnManager.

func (*BackendConnManager) ClientAddr 

func (mgr *BackendConnManager) ClientAddr() string

func (*BackendConnManager) ClientInBytes 

func (mgr *BackendConnManager) ClientInBytes() uint64

func (*BackendConnManager) ClientOutBytes 

func (mgr *BackendConnManager) ClientOutBytes() uint64

func (*BackendConnManager) Close 

func (mgr *BackendConnManager) Close() error

Close releases all resources.

func (*BackendConnManager) ConnInfo 

func (mgr *BackendConnManager) ConnInfo() []zap.Field

ConnInfo returns detailed info of the connection, which should not be logged too many times. Be careful about deadlocks.

func (*BackendConnManager) Connect 

func (mgr *BackendConnManager) Connect(ctx context.Context, clientIO pnet.PacketIO, frontendTLSConfig, backendTLSConfig *tls.Config, username, password, dbName string) error

Connect connects to the first backend and then start watching redirection signals.

func (*BackendConnManager) ConnectionID 

func (mgr *BackendConnManager) ConnectionID() uint64

ConnectionID implements RedirectableConn.ConnectionID interface. It returns the ID of the frontend connection. The ID stays still after session migration.

func (*BackendConnManager) ExecuteCmd 

func (mgr *BackendConnManager) ExecuteCmd(ctx context.Context, request []byte) (err error)

ExecuteCmd forwards messages between the client and the backend. If it finds that the session is ready for redirection, it migrates the session.

func (*BackendConnManager) ForceClose 

func (mgr *BackendConnManager) ForceClose() bool

ForceClose forces closing the connection when the failover times out.

func (*BackendConnManager) GracefulClose 

func (mgr *BackendConnManager) GracefulClose()

GracefulClose waits for the end of the transaction and closes the session.

func (*BackendConnManager) QuitSource 

func (mgr *BackendConnManager) QuitSource() ErrorSource

func (*BackendConnManager) Redirect 

func (mgr *BackendConnManager) Redirect(backendInst router.BackendInst) bool

Redirect implements RedirectableConn.Redirect interface. It redirects the current session to the newAddr. Note that the caller requires the function to be non-blocking.

func (*BackendConnManager) ServerAddr 

func (mgr *BackendConnManager) ServerAddr() string

func (*BackendConnManager) SetEventReceiver 

func (mgr *BackendConnManager) SetEventReceiver(receiver router.ConnEventReceiver)

SetEventReceiver implements RedirectableConn.SetEventReceiver interface. The receiver sends redirection signals and watches redirecting events.

func (*BackendConnManager) SetQuitSourceByErr 

func (mgr *BackendConnManager) SetQuitSourceByErr(err error)

func (*BackendConnManager) SetValue 

func (mgr *BackendConnManager) SetValue(key, val any)

func (*BackendConnManager) UpdateLogger 

func (mgr *BackendConnManager) UpdateLogger(fields ...zap.Field)

UpdateLogger add fields to the logger. Note: it should be called within the lock.

func (*BackendConnManager) Value 

func (mgr *BackendConnManager) Value(key any) any

type CmdProcessor 

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

CmdProcessor maintains the transaction and prepared statement status and decides whether the session can be redirected.

func NewCmdProcessor 

func NewCmdProcessor(logger *zap.Logger) *CmdProcessor

type ConnContext 

type ConnContext interface {
	ClientAddr() string
	ServerAddr() string
	ClientInBytes() uint64
	ClientOutBytes() uint64
	UpdateLogger(fields ...zap.Field)
	SetValue(key, val any)
	Value(key any) any
}

ConnContext saves the connection attributes that are read by HandshakeHandler. These interfaces should not request for locks because HandshakeHandler already holds the lock.

type ConnContextKey 

type ConnContextKey string

Context keys. 

const (
	ConnContextKeyTLSState ConnContextKey = "tls-state"
	ConnContextKeyConnID   ConnContextKey = "conn-id"
	ConnContextKeyConnAddr ConnContextKey = "conn-addr"
)

type CustomHandshakeHandler 

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

func (*CustomHandshakeHandler) GetCapability 

func (h *CustomHandshakeHandler) GetCapability() pnet.Capability

func (*CustomHandshakeHandler) GetRouter 

func (h *CustomHandshakeHandler) GetRouter(ctx ConnContext, resp *pnet.HandshakeResp) (router.Router, error)

func (*CustomHandshakeHandler) GetServerVersion 

func (h *CustomHandshakeHandler) GetServerVersion() string

func (*CustomHandshakeHandler) HandleHandshakeErr 

func (h *CustomHandshakeHandler) HandleHandshakeErr(ctx ConnContext, err *mysql.MyError) bool

func (*CustomHandshakeHandler) HandleHandshakeResp 

func (h *CustomHandshakeHandler) HandleHandshakeResp(ctx ConnContext, resp *pnet.HandshakeResp) error

func (*CustomHandshakeHandler) OnConnClose 

func (h *CustomHandshakeHandler) OnConnClose(ctx ConnContext, src ErrorSource) error

func (*CustomHandshakeHandler) OnHandshake 

func (h *CustomHandshakeHandler) OnHandshake(ctx ConnContext, addr string, err error, src ErrorSource)

func (*CustomHandshakeHandler) OnTraffic 

func (h *CustomHandshakeHandler) OnTraffic(ctx ConnContext)

type DefaultHandshakeHandler 

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

func NewDefaultHandshakeHandler 

func NewDefaultHandshakeHandler(nsManager namespace.NamespaceManager) *DefaultHandshakeHandler

func (*DefaultHandshakeHandler) GetCapability 

func (handler *DefaultHandshakeHandler) GetCapability() pnet.Capability

func (*DefaultHandshakeHandler) GetRouter 

func (handler *DefaultHandshakeHandler) GetRouter(ctx ConnContext, resp *pnet.HandshakeResp) (router.Router, error)

func (*DefaultHandshakeHandler) GetServerVersion 

func (handler *DefaultHandshakeHandler) GetServerVersion() string

func (*DefaultHandshakeHandler) HandleHandshakeErr 

func (handler *DefaultHandshakeHandler) HandleHandshakeErr(ctx ConnContext, err *mysql.MyError) bool

func (*DefaultHandshakeHandler) HandleHandshakeResp 

func (handler *DefaultHandshakeHandler) HandleHandshakeResp(ConnContext, *pnet.HandshakeResp) error

func (*DefaultHandshakeHandler) OnConnClose 

func (handler *DefaultHandshakeHandler) OnConnClose(ConnContext, ErrorSource) error

func (*DefaultHandshakeHandler) OnHandshake 

func (handler *DefaultHandshakeHandler) OnHandshake(ConnContext, string, error, ErrorSource)

func (*DefaultHandshakeHandler) OnTraffic 

func (handler *DefaultHandshakeHandler) OnTraffic(ConnContext)

type ErrorSource 

type ErrorSource int
const (
	// SrcNone includes: succeed for OnHandshake; client normally quit for OnConnClose
	SrcNone ErrorSource = iota
	// SrcClientNetwork includes: EOF; reset by peer; connection refused; io timeout
	SrcClientNetwork
	// SrcClientHandshake includes: client capability unsupported; TLS handshake fails
	SrcClientHandshake
	// SrcClientAuthFail includes: backend returns auth fail
	SrcClientAuthFail
	// SrcClientSQLErr includes: SQL error
	SrcClientSQLErr
	// SrcProxyQuit includes: proxy graceful shutdown
	SrcProxyQuit
	// SrcProxyMalformed includes: malformed packet
	SrcProxyMalformed
	// SrcProxyNoBackend includes: no backends
	SrcProxyNoBackend
	// SrcProxyErr includes: HandshakeHandler returns error; proxy disables TLS; unexpected errors
	SrcProxyErr
	// SrcBackendNetwork includes: EOF; reset by peer; connection refused; io timeout
	SrcBackendNetwork
	// SrcBackendHandshake includes: dial failure; backend capability unsupported; backend disables TLS; TLS handshake fails; proxy protocol fails
	SrcBackendHandshake
)

func Error2Source added in v0.2.0 

func Error2Source(err error) ErrorSource

Error2Source returns the ErrorSource by the error.

func (ErrorSource) GetSourceComp added in v0.2.0 

func (es ErrorSource) GetSourceComp() SourceComp

GetSourceComp returns which component does this error belong to.

func (ErrorSource) Normal added in v0.2.0 

func (es ErrorSource) Normal() bool

Normal returns whether this error source is expected.

func (ErrorSource) String 

func (es ErrorSource) String() string

String is used for metrics labels and log.

type HandshakeHandler 

type HandshakeHandler interface {
	HandleHandshakeResp(ctx ConnContext, resp *pnet.HandshakeResp) error
	HandleHandshakeErr(ctx ConnContext, err *mysql.MyError) bool // return true means retry connect
	GetRouter(ctx ConnContext, resp *pnet.HandshakeResp) (router.Router, error)
	OnHandshake(ctx ConnContext, to string, err error, src ErrorSource)
	OnConnClose(ctx ConnContext, src ErrorSource) error
	OnTraffic(ctx ConnContext)
	GetCapability() pnet.Capability
	GetServerVersion() string
}

HandshakeHandler contains the hooks that are called during the connection lifecycle. All the interfaces should be called within a lock so that the interfaces of ConnContext are thread-safe.

type Meter 

type Meter interface {
	IncTraffic(clusterID string, respBytes, crossAZBytes int64, fromPublicEndpoint bool)
}

type SourceComp added in v0.2.0 

type SourceComp int
const (
	CompNone SourceComp = iota
	CompClient
	CompProxy
	CompBackend
)

type StaticHandshakeHandler 

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

func NewStaticHandshakeHandler 

func NewStaticHandshakeHandler(addr string) *StaticHandshakeHandler

NewStaticHandshakeHandler creates a StaticHandshakeHandler.

func (*StaticHandshakeHandler) GetCapability 

func (handler *StaticHandshakeHandler) GetCapability() pnet.Capability

func (*StaticHandshakeHandler) GetRouter 

func (handler *StaticHandshakeHandler) GetRouter(ConnContext, *pnet.HandshakeResp) (router.Router, error)

func (*StaticHandshakeHandler) GetServerVersion 

func (handler *StaticHandshakeHandler) GetServerVersion() string

func (*StaticHandshakeHandler) HandleHandshakeErr 

func (handler *StaticHandshakeHandler) HandleHandshakeErr(ConnContext, *mysql.MyError) bool

func (*StaticHandshakeHandler) HandleHandshakeResp 

func (handler *StaticHandshakeHandler) HandleHandshakeResp(ConnContext, *pnet.HandshakeResp) error

func (*StaticHandshakeHandler) OnConnClose 

func (handler *StaticHandshakeHandler) OnConnClose(ConnContext, ErrorSource) error

func (*StaticHandshakeHandler) OnHandshake 

func (handler *StaticHandshakeHandler) OnHandshake(ConnContext, string, error, ErrorSource)

func (*StaticHandshakeHandler) OnTraffic 

func (handler *StaticHandshakeHandler) OnTraffic(ConnContext)

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.