chpool

Documentation

Index

• type Config
  • func ParseConfig(connString string) (*Config, error)
  • func (c *Config) ConnString() string
  • func (c *Config) Copy() *Config
• type Conn
• type Pool
  • func Connect(ctx context.Context, connString string) (Pool, error)
  • func ConnectConfig(ctx context.Context, config *Config) (Pool, error)
• type Stat
  • func (s *Stat) AcquireCount() int64
  • func (s *Stat) AcquireDuration() time.Duration
  • func (s *Stat) AcquiredConns() int32
  • func (s *Stat) CanceledAcquireCount() int64
  • func (s *Stat) ConstructingConns() int32
  • func (s *Stat) EmptyAcquireCount() int64
  • func (s *Stat) IdleConns() int32
  • func (s *Stat) MaxConns() int32
  • func (s *Stat) TotalConns() int32

Types

type Config

type Config struct {
	ConnConfig *chconn.Config
	// BeforeConnect is called before a new connection is made. It is passed a copy of the underlying chconn.Config and
	// will not impact any existing open connections.
	BeforeConnect func(context.Context, *chconn.Config) error

	// AfterConnect is called after a connection is established, but before it is added to the pool.
	AfterConnect func(context.Context, chconn.Conn) error

	// BeforeAcquire is called before before a connection is acquired from the pool. It must return true to allow the
	// acquire or false to indicate that the connection should be destroyed and a different connection should be
	// acquired.
	BeforeAcquire func(context.Context, chconn.Conn) bool

	// AfterRelease is called after a connection is released, but before it is returned to the pool. It must return true to
	// return the connection to the pool or false to destroy the connection.
	AfterRelease func(chconn.Conn) bool

	// MaxConnLifetime is the duration since creation after which a connection will be automatically closed.
	MaxConnLifetime time.Duration

	// MaxConnIdleTime is the duration after which an idle connection will be automatically closed by the health check.
	MaxConnIdleTime time.Duration

	// MaxConns is the maximum size of the pool.
	MaxConns int32

	// MinConns is the minimum size of the pool. The health check will increase the number of connections to this
	// amount if it had dropped below.
	MinConns int32

	// HealthCheckPeriod is the duration between checks of the health of idle connections.
	HealthCheckPeriod time.Duration

	// If set to true, pool doesn't do any I/O operation on initialization.
	// And connects to the server only when the pool starts to be used.
	// The default is false.
	LazyConnect bool
	// contains filtered or unexported fields
}

Config is the configuration struct for creating a pool. It must be created by ParseConfig and then it can be modified. A manually initialized Config will cause ConnectConfig to panic.

func ParseConfig

func ParseConfig(connString string) (*Config, error)

ParseConfig builds a Config from connString. It parses connString with the same behavior as chconn.ParseConfig with the addition of the following variables:

pool_max_conns: integer greater than 0 pool_min_conns: integer 0 or greater pool_max_conn_lifetime: duration string pool_max_conn_idle_time: duration string pool_health_check_period: duration string

See Config for definitions of these arguments.

# Example DSN
user=vahid password=secret host=clickhouse.example.com port=9000 dbname=mydb sslmode=verify-ca pool_max_conns=10

# Example URL
clickhouse://vahid:secret@ch.example.com:9000/mydb?sslmode=verify-ca&pool_max_conns=10

func (*Config) ConnString

func (c *Config) ConnString() string

ConnString returns the original connection string used to connect to the ClickHouse server.

func (*Config) Copy

func (c *Config) Copy() *Config

Copy returns a deep copy of the config that is safe to use and modify. The only exception is the tls.Config: according to the tls.Config docs it must not be modified after creation.

type Conn

type Conn interface {
	Release()
	// ExecCallback executes a query without returning any rows with the setting option and on progress callback.
	// NOTE: don't use it for insert and select query
	ExecCallback(
		ctx context.Context,
		query string,
		settings *setting.Settings,
		queryID string,
		onProgress func(*chconn.Progress)) (interface{}, error)
	// Select executes a query with the setting option, on progress callback, on profile callback and return select stmt.
	// NOTE: only use for select query
	SelectCallback(
		ctx context.Context,
		query string,
		settings *setting.Settings,
		queryID string,
		onProgress func(*chconn.Progress),
		onProfile func(*chconn.Profile),
	) (chconn.SelectStmt, error)
	// InsertWithSetting executes a query with the setting option and return insert stmt.
	// NOTE: only use for insert query
	InsertWithSetting(ctx context.Context, query string, settings *setting.Settings, queryID string, columns ...column.Column) error
	Conn() chconn.Conn
	Ping(ctx context.Context) error
}

Conn is an acquired *chconn.Conn from a Pool.

type Pool

type Pool interface {
	// Close closes all connections in the pool and rejects future Acquire calls. Blocks until all connections are returned
	// to pool and closed.
	Close()
	Acquire(ctx context.Context) (Conn, error)
	// AcquireFunc acquires a *Conn and calls f with that *Conn. ctx will only affect the Acquire. It has no effect on the
	// call of f. The return value is either an error acquiring the Conn or the return value of f. The Conn is
	// automatically released after the call of f.
	AcquireFunc(ctx context.Context, f func(Conn) error) error
	// AcquireAllIdle atomically acquires all currently idle connections. Its intended use is for health check and
	// keep-alive functionality. It does not update pool statistics.
	AcquireAllIdle(ctx context.Context) []Conn
	// Exec executes a query without returning any rows.
	// NOTE: don't use it for insert and select query
	Exec(ctx context.Context, sql string) (interface{}, error)
	// ExecWithSetting executes a query without returning any rows with the setting option.
	// NOTE: don't use it for insert and select query
	ExecWithSetting(ctx context.Context, query string, settings *setting.Settings) (interface{}, error)
	// ExecCallback executes a query without returning any rows with the setting option and on progress callback.
	// NOTE: don't use it for insert and select query
	ExecCallback(
		ctx context.Context,
		sql string,
		settings *setting.Settings,
		queryID string,
		onProgress func(*chconn.Progress),
	) (interface{}, error)
	// Select executes a query and return select stmt.
	// NOTE: only use for select query
	Select(ctx context.Context, query string) (chconn.SelectStmt, error)
	// Select executes a query with the setting option and return select stmt.
	// NOTE: only use for select query
	SelectWithSetting(ctx context.Context, query string, settings *setting.Settings) (chconn.SelectStmt, error)
	// Select executes a query with the setting option, on progress callback, on profile callback and return select stmt.
	// NOTE: only use for select query
	SelectCallback(
		ctx context.Context,
		query string,
		settings *setting.Settings,
		queryID string,
		onProgress func(*chconn.Progress),
		onProfile func(*chconn.Profile),
	) (chconn.SelectStmt, error)
	// Insert executes a query and commit all columns
	// NOTE: only use for insert query
	Insert(ctx context.Context, query string, columns ...column.Column) error
	// InsertWithSetting executes a query with the setting option and commit all columns
	// NOTE: only use for insert query
	InsertWithSetting(ctx context.Context, query string, settings *setting.Settings, queryID string, columns ...column.Column) error
	// Ping sends a ping to check that the connection to the server is alive.
	Ping(ctx context.Context) error
	Stat() *Stat
}

Pool is a connection pool for chconn

func Connect

func Connect(ctx context.Context, connString string) (Pool, error)

Connect creates a new Pool and immediately establishes one connection. ctx can be used to cancel this initial connection. See ParseConfig for information on connString format.

func ConnectConfig

func ConnectConfig(ctx context.Context, config *Config) (Pool, error)

ConnectConfig creates a new Pool and immediately establishes one connection. ctx can be used to cancel this initial connection. config must have been created by ParseConfig.

type Stat

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

Stat of connection pool

func (*Stat) AcquireCount

func (s *Stat) AcquireCount() int64

AcquireCount returns the cumulative count of successful acquires from the pool.

func (*Stat) AcquireDuration

func (s *Stat) AcquireDuration() time.Duration

AcquireDuration returns the total duration of all successful acquires from the pool.

func (*Stat) AcquiredConns

func (s *Stat) AcquiredConns() int32

AcquiredConns returns the number of currently acquired connections in the pool.

func (*Stat) CanceledAcquireCount

func (s *Stat) CanceledAcquireCount() int64

CanceledAcquireCount returns the cumulative count of acquires from the pool that were canceled by a context.

func (*Stat) ConstructingConns

func (s *Stat) ConstructingConns() int32

ConstructingConns returns the number of conns with construction in progress in the pool.

func (*Stat) EmptyAcquireCount

func (s *Stat) EmptyAcquireCount() int64

EmptyAcquireCount returns the cumulative count of successful acquires from the pool that waited for a resource to be released or constructed because the pool was empty.

func (*Stat) IdleConns

func (s *Stat) IdleConns() int32

IdleConns returns the number of currently idle conns in the pool.

func (*Stat) MaxConns

func (s *Stat) MaxConns() int32

MaxConns returns the maximum size of the pool.

func (*Stat) TotalConns

func (s *Stat) TotalConns() int32

TotalConns returns the total number of resources currently in the pool. The value is the sum of ConstructingConns, AcquiredConns, and IdleConns.