polardbx

README

polardbx-connector-go

This is a high-availability Golang driver for PolarDB-X. The features implemented so far are as follows:

• Automatically reconnects to the new leader node after switching
• Supports read-write separation
• Supports CoreDNS
• Built-in polardbx driver keyword
• Supports transparent switching
• Supports COM_PING for HA checks
• Supports Load Balancing (random or leastConn)

A simple example using polardbx as drivername:

import (
	_ "github.com/polardb/polardbx-connector-go"
)
db, err := sql.Open("polardbx", "user:password@tcp(ip:port)/dbname")
if err != nil {
    panic(err)
}

db.SetConnMaxLifetime(time.Minute * 3)
db.SetMaxOpenConns(10)
db.SetMaxIdleConns(10)

Installation

go get github.com/polardb/polardbx-connector-go

New Parameters

Standard Edition (Dn):

Parameter Name	Type	Description
clusterId	int64	Cluster identifier. Optional. Automatically obtained on first connection.
connectTimeout	int32	Timeout for acquiring an available DN node, default 10000ms.
haCheckConnectTimeoutMillis	int32	HA connection check timeout, default 3000ms.
haCheckSocketTimeoutMillis	int32	HA query check timeout, default 3000ms.
haCheckIntervalMillis	int32	HA check interval, default 5000ms.
checkLeaderTransferringIntervalMillis	int32	Leader transfer detection interval, default 100ms.
leaderTransferringWaitTimeoutMillis	int32	Maximum wait time for leader transfer, default 5000ms.
ignoreVip	bool	Whether to ignore VIP address, default true.
recordJdbcUrl	bool	Whether to record DSN, default false.
slaveRead	bool	Whether to use follower read, default false.
slaveWeightThreshold	int32	Follower ELECTION_WEIGHT must be greater than this value to connect, default 1.
applyDelayThreshold	int32	Follower APPLY_DELAY_SECONDS must be <= this value to connect, unit: seconds, default 3.
directMode	bool	Whether to skip HA management, default false.
loadBalanceAlgorithm	string	Load balancing algorithm: random or least_connection.
enableLog	bool	Whether to print driver logs, default true.

example:

db, err := sql.Open("polardbx", "user:password@tcp(ip:port)/dbname?slaveRead=false&slaveWeightThreshold=1&applyDelayThreshold=3)

Enterprise Edition (CN):

Parameter Name	Type	Description
connectTimeout	int32	Timeout for acquiring an available CN node.
haCheckIntervalMillis	int32	HA check interval, default 5000ms.
zoneName	string	Zone name (AZ name), default empty (random selection). Example: AZ0, AZ1.
minZoneNodes	int32	Minimum number of nodes in the zone (greater than), default 0.
backupZoneName	string	Backup zone name used when minZoneNodes is not satisfied.
slaveRead	bool	Whether to use R instance, default false.
instanceName	string	CN instance name, default empty.
mppRole	string	Default W for primary, R for secondary. Can also be set to CR.
enableFollowerRead	int32	0: Use primary; 1: Use secondary for normal read; 2: Secondary for consistent read; -1: No operation (default).
loadBalanceAlgorithm	string	Load balancing algorithm: random or least_connection.
enableLog	bool	Whether to print driver logs, default false.

example:

db, err := sql.Open("polardbx", "user:password@tcp(ip:port)/dbname?slaveRead=true&loadBalanceAlgorithm=random")

Development

Download the Repository

git clone http://github.com/polardb/polardbx-connector-go.git

Install Dependencies

cd polardbx-connector-go
go mod tidy

Build and Test

go test -v -args -dnAddr="ip1:port1, ip2:port2" -dnUser="user1" -dnPasswd="passwd1" -cnAddr="ip3:port3, ip4:port4" -cnUser="user2" -cnPasswd="passwd2" -zoneName="name1" -backupZoneName="name2" -instanceName="name3"

Documentation

Index

• Constants
• Variables
• func IsEnabledFor(l int) bool
• func NewConnector(pCfg *PolarDBXConfig) (driver.Connector, error)
• func ParseLevel(levelStr string) int
• func SetLevel(l int)
• type Address
• type BasicInFoQuery
• type HaManager
  • func GetManager(pCfg *PolarDBXConfig) (*HaManager, error)
  • func (hm *HaManager) CnHaChecker()
  • func (hm *HaManager) DnHaChecker()
• type LeaderTransferInfo
• type Logger
  • func (logger *Logger) Debug(msg string, enableLog bool)
  • func (logger *Logger) Error(msg string, enableLog bool)
  • func (logger *Logger) ErrorWithStack(err error, enableLog bool)
  • func (logger *Logger) Info(msg string, enableLog bool)
  • func (logger *Logger) Warn(msg string, enableLog bool)
• type MppInfo
• type NodeWithLoadWeight
• type PolarDBXConfig
  • func NewPolarDBXConfig() *PolarDBXConfig
  • func ParsePolarDBXDSN(dsn string) (pCfg *PolarDBXConfig, err error)
  • func (pCfg *PolarDBXConfig) Clone() *PolarDBXConfig
  • func (pCfg *PolarDBXConfig) FormatMYSQLDSN(addr string) (string, bool)
  • func (pCfg *PolarDBXConfig) FormatPolarDBXDSN(addr string) string
• type PolarDBXDriver
  • func (d PolarDBXDriver) Open(dsn string) (driver.Conn, error)
  • func (d PolarDBXDriver) OpenConnector(dsn string) (driver.Connector, error)
• type XClusterInfo
• type XClusterNodeBasic
  • func (n *XClusterNodeBasic) Equals(other *XClusterNodeBasic) bool
  • func (x *XClusterNodeBasic) String() string

Constants

const (
	LevelSilent = iota
	LevelError
	LevelWarn
	LevelInfo
	LevelDebug
)

const ILLEGAL_CHARS = `[\\/:*?"<>|\n\r\t]`

Variables

var (
	ErrNoNodeFound     = errors.New("communications link failure: no available nodes meet the conditions")
	ErrInvalidPort     = errors.New("invalid port number")
	ErrClusterMismatch = errors.New("cluster id mismatch")
)

Various errors the driver might return. Can change between driver versions.

var (
	ErrInvalidDSNUnescaped = errors.New("invalid DSN: did you forget to escape a param value?")
	ErrInvalidDSNAddr      = errors.New("invalid DSN: network address not terminated (missing closing brace)")
	ErrInvalidDSNNoSlash   = errors.New("invalid DSN: missing the slash separating the database name")
)

var Version = "v1.0.1"

Functions

func IsEnabledFor

func IsEnabledFor(l int) bool

func NewConnector

func NewConnector(pCfg *PolarDBXConfig) (driver.Connector, error)

NewConnector returns new driver.Connector.

func ParseLevel

func ParseLevel(levelStr string) int

func SetLevel

func SetLevel(l int)

Types

type Address

type Address struct {
	Hostname string
	Port     int32
}

type BasicInFoQuery

type BasicInFoQuery struct {
	Version   string
	ClusterID int64
	Port      int32
}

type HaManager

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

func GetManager

func GetManager(pCfg *PolarDBXConfig) (*HaManager, error)

GetManager 根据集群信息获取或创建并返回一个HaManager实例。 如果集群信息中未指定集群ID，将尝试自动探测。 如果指定或自动生成了集群ID，将根据集群信息和系统临时目录路径生成一个JSON文件路径。 此函数还负责设置或更新HaManager实例的属性，如用户、密码。

func (*HaManager) CnHaChecker

func (hm *HaManager) CnHaChecker()

func (*HaManager) DnHaChecker

func (hm *HaManager) DnHaChecker()

type LeaderTransferInfo

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

type Logger

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

func (*Logger) Debug

func (logger *Logger) Debug(msg string, enableLog bool)

func (*Logger) Error

func (logger *Logger) Error(msg string, enableLog bool)

func (*Logger) ErrorWithStack

func (logger *Logger) ErrorWithStack(err error, enableLog bool)

func (*Logger) Info

func (logger *Logger) Info(msg string, enableLog bool)

func (*Logger) Warn

func (logger *Logger) Warn(msg string, enableLog bool)

type MppInfo

type MppInfo struct {
	Tag          string   `json:"tag"` // NODE(ip:port)
	Role         string   `json:"role"`
	InstanceName string   `json:"instance_name"` // ID
	ZoneList     []string `json:"zone_list"`     // sub_cluster
	IsLeader     string   `json:"is_leader"`
	LoadWeight   int64    `json:"load_weight"`
}

type NodeWithLoadWeight

type NodeWithLoadWeight struct {
	Tag        string
	LoadWeight int64
}

type PolarDBXConfig

type PolarDBXConfig struct {
	// Dsn before Slash
	User   string // Username
	Passwd string // Password (requires User)
	Net    string // Network (e.g. "tcp", "tcp6", "unix". default: "tcp")
	Addr   string // Address (default: "127.0.0.1:3306" for "tcp" and "/tmp/mysql.sock" for "unix")
	Dbname string // Database name

	JsonFile string // json file path

	// PolarDBX params
	ClusterID                             int64
	HaTimeoutMillis                       int32 // connect timeout for getting node, default: 10000
	HaCheckConnectTimeoutMillis           int32 // dial timeout for HA mysql connection
	HaCheckSocketTimeoutMillis            int32 // read timeout for HA mysql connection
	HaCheckIntervalMillis                 int32 // the same as CheckLeaderTransferringIntervalMillis in DN
	CheckLeaderTransferringIntervalMillis int32
	LeaderTransferringWaitTimeoutMillis   int32 // timeout for leader transferring
	SmoothSwitchover                      bool  // TODO: to be supported
	IgnoreVip                             bool
	RecordJdbcUrl                         bool
	SlaveOnly                             bool // read write separation, slaveRead
	SlaveWeightThreshold                  int32
	ApplyDelayThreshold                   int32 // second
	DirectMode                            bool
	LoadBalanceAlgorithm                  string
	EnableLog                             bool
	EnableProbeLog                        bool

	// PolarDBX params: CN only
	ZoneName           string
	MinZoneNodes       int32
	BackupZoneName     string
	InstanceName       string
	MppRole            string
	EnableFollowerRead int32
	CnGroup            string
	BackupCnGroup      string

	// MYSQL params
	MysqlParams map[string]string

	// PolarDBX param set
	PropertiesSet mapset.Set
}

func NewPolarDBXConfig

func NewPolarDBXConfig() *PolarDBXConfig

func ParsePolarDBXDSN

func ParsePolarDBXDSN(dsn string) (pCfg *PolarDBXConfig, err error)

ParsePolarDBXDSN parses the DSN string to polardb-x and mysql Config

func (*PolarDBXConfig) Clone

func (pCfg *PolarDBXConfig) Clone() *PolarDBXConfig

func (*PolarDBXConfig) FormatMYSQLDSN

func (pCfg *PolarDBXConfig) FormatMYSQLDSN(addr string) (string, bool)

func (*PolarDBXConfig) FormatPolarDBXDSN

func (pCfg *PolarDBXConfig) FormatPolarDBXDSN(addr string) string

type PolarDBXDriver

type PolarDBXDriver struct{}

func (PolarDBXDriver) Open

func (d PolarDBXDriver) Open(dsn string) (driver.Conn, error)

Open new Connection. See https://github.com/go-sql-driver/mysql#dsn-data-source-name for how the DSN string is formatted

func (PolarDBXDriver) OpenConnector

func (d PolarDBXDriver) OpenConnector(dsn string) (driver.Connector, error)

OpenConnector implements driver.DriverContext.

type XClusterInfo

type XClusterInfo struct {
	LeaderInfo         *XClusterNodeBasic
	LeaderTransferInfo *LeaderTransferInfo
	GlobalPortGap      int32
	LongConnection     *sql.Conn
}

type XClusterNodeBasic

type XClusterNodeBasic struct {
	Tag         string               `json:"tag"`
	Connectable bool                 `json:"connectable"`
	Host        string               `json:"host"`
	Port        int32                `json:"port"`
	PaxosPort   int32                `json:"paxos_port"`
	Role        string               `json:"role"`
	Peers       []*XClusterNodeBasic `json:"peers"`
	Version     string               `json:"version"`
	ClusterID   int64                `json:"cluster_id"`
	UpdateTime  string               `json:"update_time"`
}

func (*XClusterNodeBasic) Equals

func (n *XClusterNodeBasic) Equals(other *XClusterNodeBasic) bool

func (*XClusterNodeBasic) String

func (x *XClusterNodeBasic) String() string

String returns a string representation of XClusterNodeBasic