plugin

README

The Plugin Framework

https://github.com/pingcap/tidb/blob/master/docs/design/2018-12-10-plugin-framework.md

Documentation

Index

• Constants
• Variables
• func ChangeDisableFlagAndFlush(dom *domain.Domain, pluginName string, disable bool) error
• func ForeachPlugin(kind Kind, fn func(plugin *Plugin) error) error
• func GetAll() map[Kind][]Plugin
• func Init(ctx context.Context, cfg Config) (err error)
• func IsEnable(kind Kind) bool
• func Load(ctx context.Context, cfg Config) (err error)
• func NotifyFlush(dom *domain.Domain, pluginName string) error
• func SetTestHook(...)
• func Shutdown(ctx context.Context)
• type AuditManifest
  • func DeclareAuditManifest(m *Manifest) *AuditManifest
• type AuthenticationManifest
  • func DeclareAuthenticationManifest(m *Manifest) *AuthenticationManifest
• type Config
• type ConnectionEvent
  • func (c ConnectionEvent) String() string
• type DaemonManifest
  • func DeclareDaemonManifest(m *Manifest) *DaemonManifest
• type GeneralEvent
  • func GeneralEventFromString(s string) (GeneralEvent, error)
  • func (e GeneralEvent) String() string
• type ID
  • func (n ID) Decode() (name string, version string, err error)
• type Kind
  • func (k Kind) String() (str string)
• type Manifest
  • func ExportManifest(m any) *Manifest
• type ParseEvent
• type Plugin
  • func Get(kind Kind, name string) *Plugin
  • func (p *Plugin) DisableFlag(disable bool)
  • func (p *Plugin) StateValue() string
• type RejectReasonCtxValue
• type SchemaManifest
  • func DeclareSchemaManifest(m *Manifest) *SchemaManifest
• type State
  • func (s State) String() (str string)

Constants

const (
	// LibrarySuffix defines TiDB plugin's file suffix.
	LibrarySuffix = ".so"
	// ManifestSymbol defines TiDB plugin's entrance symbol.
	// Plugin take manifest info from this symbol.
	ManifestSymbol = "PluginManifest"
)

Variables

var ExecStartTimeCtxKey = execStartTimeCtxKeyType{}

ExecStartTimeCtxKey indicates stmt start execution time.

var StaticPlugins staticPlugins

StaticPlugins is a registry to register plugins for other packages without loading go plugin so

Functions

func ChangeDisableFlagAndFlush

func ChangeDisableFlagAndFlush(dom *domain.Domain, pluginName string, disable bool) error

ChangeDisableFlagAndFlush changes plugin disable flag and notify other nodes to do same change.

func ForeachPlugin

func ForeachPlugin(kind Kind, fn func(plugin *Plugin) error) error

ForeachPlugin loops all ready plugins.

func GetAll

func GetAll() map[Kind][]Plugin

GetAll finds and returns all plugins.

func Init

func Init(ctx context.Context, cfg Config) (err error)

Init initializes the loaded plugin by config param. This method must be called after `Load` but before any other plugin method call, so it call got TiDB domain info.

func IsEnable

func IsEnable(kind Kind) bool

IsEnable checks plugin's enable state.

func Load

func Load(ctx context.Context, cfg Config) (err error)

Load load plugin by config param. This method need be called before domain init to inject global variable info during bootstrap.

func NotifyFlush

func NotifyFlush(dom *domain.Domain, pluginName string) error

NotifyFlush notify plugins to do flush logic.

func SetTestHook

func SetTestHook(fn func(plugin *Plugin, dir string, pluginID ID) (manifest func() *Manifest, err error))

SetTestHook for uint test in custom plugin.

func Shutdown

func Shutdown(ctx context.Context)

Shutdown cleanups all plugin resources. Notice: it just cleanups the resource of plugin, but cannot unload plugins(limited by go plugin).

Types

type AuditManifest

type AuditManifest struct {
	Manifest
	// OnConnectionEvent will be called when TiDB receive or disconnect from client.
	// return error will ignore and close current connection.
	OnConnectionEvent func(ctx context.Context, event ConnectionEvent, info *variable.ConnectionInfo) error
	// OnGeneralEvent will be called during TiDB execution.
	OnGeneralEvent func(ctx context.Context, sctx *variable.SessionVars, event GeneralEvent, cmd string)
	// OnGlobalVariableEvent will be called when Change GlobalVariable.
	OnGlobalVariableEvent func(ctx context.Context, sctx *variable.SessionVars, varName, varValue string)
	// OnParseEvent will be called around parse logic.
	OnParseEvent func(ctx context.Context, sctx *variable.SessionVars, event ParseEvent) error
}

AuditManifest presents a sub-manifest that every audit plugin must provide.

func DeclareAuditManifest

func DeclareAuditManifest(m *Manifest) *AuditManifest

DeclareAuditManifest declares manifest as AuditManifest.

type AuthenticationManifest

type AuthenticationManifest struct {
	Manifest
	AuthenticateUser             func()
	GenerateAuthenticationString func()
	ValidateAuthenticationString func()
	SetSalt                      func()
}

AuthenticationManifest presents a sub-manifest that every audit plugin must provide.

func DeclareAuthenticationManifest

func DeclareAuthenticationManifest(m *Manifest) *AuthenticationManifest

DeclareAuthenticationManifest declares manifest as AuthenticationManifest.

type Config

type Config struct {
	Plugins      []string
	PluginDir    string
	SkipWhenFail bool
	EnvVersion   map[string]uint16
	EtcdClient   *clientv3.Client
}

Config presents the init configuration for plugin framework.

type ConnectionEvent

type ConnectionEvent byte

ConnectionEvent presents TiDB connection event.

const (
	// Connected represents new connection establish event(finish auth).
	Connected ConnectionEvent = iota
	// Disconnect represents disconnect event.
	Disconnect
	// ChangeUser represents change user.
	ChangeUser
	// PreAuth represents event before start auth.
	PreAuth
	// Reject represents event reject connection event.
	Reject
)

func (ConnectionEvent) String

func (c ConnectionEvent) String() string

type DaemonManifest

type DaemonManifest struct {
	Manifest
}

DaemonManifest presents a sub-manifest that every DaemonManifest plugins must provide.

func DeclareDaemonManifest

func DeclareDaemonManifest(m *Manifest) *DaemonManifest

DeclareDaemonManifest declares manifest as DaemonManifest.

type GeneralEvent

type GeneralEvent byte

GeneralEvent presents TiDB generate event.

const (
	// Starting represents a GeneralEvent that is about to start
	Starting GeneralEvent = iota
	// Completed represents a GeneralEvent that has completed
	Completed
	// Error represents a GeneralEvent that has error (and typically couldn't start)
	Error
	// GeneralEventCount is the count for the general events
	// The new events MUST be added before it
	GeneralEventCount
)

func GeneralEventFromString

func GeneralEventFromString(s string) (GeneralEvent, error)

GeneralEventFromString gets the `GeneralEvent` from the given string

func (GeneralEvent) String

func (e GeneralEvent) String() string

String returns the string for the `GeneralEvent`

type ID

type ID string

ID present plugin identity.

func (ID) Decode

func (n ID) Decode() (name string, version string, err error)

Decode decodes a plugin id into name, version parts.

type Kind

type Kind uint8

Kind presents the kind of plugin.

const (
	// Audit indicates it is a Audit plugin.
	Audit Kind = 1 + iota
	// Authentication indicate it is a Authentication plugin.
	Authentication
	// Schema indicate a plugin that can change TiDB schema.
	Schema
	// Daemon indicate a plugin that can run as daemon task.
	Daemon
)

func (Kind) String

func (k Kind) String() (str string)

type Manifest

type Manifest struct {
	Name           string
	Description    string
	RequireVersion map[string]uint16
	License        string
	BuildTime      string
	// Validate defines the validate logic for plugin.
	// returns error will stop load plugin process and TiDB startup.
	Validate func(ctx context.Context, manifest *Manifest) error
	// OnInit defines the plugin init logic.
	// it will be called after domain init.
	// return error will stop load plugin process and TiDB startup.
	OnInit func(ctx context.Context, manifest *Manifest) error
	// OnShutDown defines the plugin cleanup logic.
	// return error will write log and continue shutdown.
	OnShutdown func(ctx context.Context, manifest *Manifest) error
	// OnFlush defines flush logic after executed `flush tidb plugins`.
	// it will be called after OnInit.
	// return error will write log and continue watch following flush.
	OnFlush func(ctx context.Context, manifest *Manifest) error

	Version uint16
	Kind    Kind
	// contains filtered or unexported fields
}

Manifest describes plugin info and how it can do by plugin itself.

func ExportManifest

func ExportManifest(m any) *Manifest

ExportManifest exports a manifest to TiDB as a known format. it just casts sub-manifest to manifest.

type ParseEvent

type ParseEvent byte

ParseEvent presents events happen around parser.

const (
	// PreParse presents event before parse.
	PreParse ParseEvent = 1 + iota
	// PostParse presents event after parse.
	PostParse
)

type Plugin

type Plugin struct {
	*Manifest

	Path     string
	Disabled uint32
	State    State
	// contains filtered or unexported fields
}

Plugin presents a TiDB plugin.

func Get

func Get(kind Kind, name string) *Plugin

Get finds and returns plugin by kind and name parameters.

func (*Plugin) DisableFlag

func (p *Plugin) DisableFlag(disable bool)

DisableFlag changes the disable flag of plugin.

func (*Plugin) StateValue

func (p *Plugin) StateValue() string

StateValue returns readable state string.

type RejectReasonCtxValue

type RejectReasonCtxValue struct{}

RejectReasonCtxValue will be used in OnConnectionEvent to pass RejectReason to plugin.

type SchemaManifest

type SchemaManifest struct {
	Manifest
}

SchemaManifest presents a sub-manifest that every schema plugins must provide.

func DeclareSchemaManifest

func DeclareSchemaManifest(m *Manifest) *SchemaManifest

DeclareSchemaManifest declares manifest as SchemaManifest.

type State

type State uint8

State present the state of plugin.

const (
	// Uninitialized indicates plugin is uninitialized.
	Uninitialized State = iota
	// Ready indicates plugin is ready to work.
	Ready
	// Dying indicates plugin will be close soon.
	Dying
	// Disable indicate plugin is disabled.
	Disable
)

func (State) String

func (s State) String() (str string)