Documentation
¶
Index ¶
- Constants
- Variables
- func ComputeDefaultCode(err error) pgcode.Code
- func DangerousStatementf(format string, args ...interface{}) error
- func FullError(err error) string
- func GetPGCode(err error) pgcode.Code
- func GetPGCodeInternal(err error, computeDefaultCode func(err error) (code pgcode.Code)) (code pgcode.Code)
- func GetSeverity(err error) string
- func HasCandidateCode(err error) bool
- func IsSQLRetryableError(err error) bool
- func New(code pgcode.Code, msg string) error
- func NewInternalTrackingError(issue int, detail string) error
- func NewWithDepthf(depth int, code pgcode.Code, format string, args ...interface{}) error
- func Newf(code pgcode.Code, format string, args ...interface{}) error
- func WithCandidateCode(err error, code pgcode.Code) error
- func WithSeverity(err error, severity string) error
- func Wrap(err error, code pgcode.Code, msg string) error
- func WrapWithDepthf(depth int, err error, code pgcode.Code, format string, args ...interface{}) error
- func Wrapf(err error, code pgcode.Code, format string, args ...interface{}) error
- func WrongNumberOfPreparedStatements(n int) error
- type ClientVisibleAmbiguousError
- type ClientVisibleRetryError
- type Error
- func (*Error) Descriptor() ([]byte, []int)
- func (pg *Error) Error() string
- func (pg *Error) ErrorDetail() string
- func (pg *Error) ErrorHint() string
- func (pg *Error) Format(s fmt.State, verb rune)
- func (m *Error) Marshal() (dAtA []byte, err error)
- func (m *Error) MarshalTo(dAtA []byte) (int, error)
- func (*Error) ProtoMessage()
- func (m *Error) Reset()
- func (m *Error) Size() (n int)
- func (m *Error) String() string
- func (m *Error) Unmarshal(dAtA []byte) error
- func (m *Error) XXX_DiscardUnknown()
- func (m *Error) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)
- func (m *Error) XXX_Merge(src proto.Message)
- func (m *Error) XXX_Size() int
- func (m *Error) XXX_Unmarshal(b []byte) error
- type Error_Source
- func (*Error_Source) Descriptor() ([]byte, []int)
- func (m *Error_Source) Marshal() (dAtA []byte, err error)
- func (m *Error_Source) MarshalTo(dAtA []byte) (int, error)
- func (*Error_Source) ProtoMessage()
- func (m *Error_Source) Reset()
- func (m *Error_Source) Size() (n int)
- func (m *Error_Source) String() string
- func (m *Error_Source) Unmarshal(dAtA []byte) error
- func (m *Error_Source) XXX_DiscardUnknown()
- func (m *Error_Source) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)
- func (m *Error_Source) XXX_Merge(src proto.Message)
- func (m *Error_Source) XXX_Size() int
- func (m *Error_Source) XXX_Unmarshal(b []byte) error
Constants ¶
const DefaultSeverity = "ERROR"
DefaultSeverity is the default severity for decoding severity of errors.
const InternalErrorPrefix = "internal error"
InternalErrorPrefix is prepended on internal errors.
const TxnRetryMsgPrefix = "restart transaction"
TxnRetryMsgPrefix is the prefix inserted in an error message when flattened
Variables ¶
var ( ErrInvalidLengthErrors = fmt.Errorf("proto: negative length found during unmarshaling") ErrIntOverflowErrors = fmt.Errorf("proto: integer overflow") )
Functions ¶
func ComputeDefaultCode ¶
ComputeDefaultCode looks at the current error object (not its causes) and returns: - the existing code for Error instances - SerializationFailure for roachpb retry errors that can be reported to clients - StatementCompletionUnknown for ambiguous commit errors - InternalError for assertion failures - FeatureNotSupportedError for unimplemented errors.
It is not meant to be used directly - it is only exported for use by test code. Use GetPGCode() instead.
func DangerousStatementf ¶
DangerousStatementf creates a new error for "rejected dangerous statements".
func GetPGCodeInternal ¶
func GetPGCodeInternal( err error, computeDefaultCode func(err error) (code pgcode.Code), ) (code pgcode.Code)
GetPGCodeInternal retrieves a code for the error. It operates by combining the inner (cause) code and the code at the current level, at each level of cause.
- at each level:
- if there is a candidate code at that level, that is used;
- otherwise, it calls computeDefaultCode(). if the function returns an empty string, UncategorizedError is used. An example implementation for computeDefaultCode is provided below.
after that, it combines the code computed already for the cause (inner) and the new code just computed at the current level (outer) as follows:
if the outer code is uncategorized, the inner code is kept no matter what.
if the outer code has the special XX prefix, that is kept. (The "XX" prefix signals importance in the pg code hierarchy.)
if the inner code is not uncategorized, it is retained.
otherwise the outer code is retained.
This function should not be used directly. It is only exported for use in testing code. Use GetPGCode() instead.
func GetSeverity ¶
GetSeverity attempts to unwrap and find a Severity.
func HasCandidateCode ¶
HasCandidateCode returns tue iff the error or one of its causes has a candidate pg error code.
func IsSQLRetryableError ¶
IsSQLRetryableError returns true if err is retryable. This is true for errors that show a connection issue or an issue with the node itself. This can occur when a node is restarting or is unstable in some other way. Note that retryable errors may occur event in cases where the SQL execution ran to completion.
TODO(bdarnell): Why are RPC errors in this list? These should generally be retried on the server side or transformed into ambiguous result errors ("connection reset/refused" are needed for the pgwire connection, but anything RPC-related should be handled within the cluster). TODO(knz): This should really use the errors library. Investigate how to get rid of the error message comparison.
func NewInternalTrackingError ¶
NewInternalTrackingError instantiates an error meant for use with telemetry.ReportError directly.
Do not use this! Convert uses to AssertionFailedf or similar above.
func NewWithDepthf ¶
NewWithDepthf creates an error with a pg code and extracts the context information at the specified depth level.
func WithCandidateCode ¶
WithCandidateCode decorates the error with a candidate postgres error code. It is called "candidate" because the code is only used by GetPGCode() below conditionally. The code is considered PII-free and is thus reportable.
func WithSeverity ¶
WithSeverity decorates the error with a severity.
func Wrap ¶
Wrap wraps an error and adds a pg error code. Only the code is added if the message is empty.
func WrapWithDepthf ¶
func WrapWithDepthf( depth int, err error, code pgcode.Code, format string, args ...interface{}, ) error
WrapWithDepthf wraps an error. It also annotates the provided pg code as new candidate code, to be used if the underlying error does not have one already.
func Wrapf ¶
Wrapf wraps an error and adds a pg error code. See the doc on WrapWithDepthf for details.
func WrongNumberOfPreparedStatements ¶
WrongNumberOfPreparedStatements creates new an Error for trying to prepare a query string containing more than one statement.
Types ¶
type ClientVisibleAmbiguousError ¶
type ClientVisibleAmbiguousError interface {
ClientVisibleAmbiguousError()
}
ClientVisibleAmbiguousError mirrors roachpb.ClientVisibleAmbiguousError but is defined here to avoid an import cycle.
type ClientVisibleRetryError ¶
type ClientVisibleRetryError interface {
ClientVisibleRetryError()
}
ClientVisibleRetryError mirrors roachpb.ClientVisibleRetryError but is defined here to avoid an import cycle.
type Error ¶
type Error struct {
// standard pg error fields. This can be passed
// over the pg wire protocol.
Code string `protobuf:"bytes,1,opt,name=code,proto3" json:"code,omitempty"`
Message string `protobuf:"bytes,2,opt,name=message,proto3" json:"message,omitempty"`
Detail string `protobuf:"bytes,3,opt,name=detail,proto3" json:"detail,omitempty"`
Hint string `protobuf:"bytes,4,opt,name=hint,proto3" json:"hint,omitempty"`
Severity string `protobuf:"bytes,8,opt,name=severity,proto3" json:"severity,omitempty"`
Source *Error_Source `protobuf:"bytes,5,opt,name=source,proto3" json:"source,omitempty"`
}
Error contains all Postgres wire protocol error fields. See https://www.postgresql.org/docs/current/static/protocol-error-fields.html for a list of all Postgres error fields, most of which are optional and can be used to provide auxiliary error information.
func Flatten ¶
Flatten turns any error into a pgerror with fields populated. As the name implies, the details from the chain of causes is projected into a single struct. This is useful in at least two places:
- to generate Error objects suitable for 19.1 nodes, which only recognize this type of payload.
- to generate an error packet on pgwire.
Additionally, this can be used in the remainder of the code base when an Error object is expected, until that code is updated to use the errors library directly.
Flatten() returns a nil ptr if err was nil to start with.
func (*Error) Descriptor ¶
func (*Error) ErrorDetail ¶
ErrorDetail implements the hintdetail.ErrorDetailer interface.
func (*Error) Format ¶
Format implements the fmt.Formatter interface.
%v/%s prints the error as usual. %#v adds the pg error code at the beginning. %+v prints all the details, including the embedded stack traces.
func (*Error) ProtoMessage ¶
func (*Error) ProtoMessage()
func (*Error) XXX_DiscardUnknown ¶
func (m *Error) XXX_DiscardUnknown()
func (*Error) XXX_Marshal ¶
func (*Error) XXX_Unmarshal ¶
type Error_Source ¶
type Error_Source struct {
File string `protobuf:"bytes,1,opt,name=file,proto3" json:"file,omitempty"`
Line int32 `protobuf:"varint,2,opt,name=line,proto3" json:"line,omitempty"`
Function string `protobuf:"bytes,3,opt,name=function,proto3" json:"function,omitempty"`
}
func (*Error_Source) Descriptor ¶
func (*Error_Source) Descriptor() ([]byte, []int)
func (*Error_Source) Marshal ¶
func (m *Error_Source) Marshal() (dAtA []byte, err error)
func (*Error_Source) ProtoMessage ¶
func (*Error_Source) ProtoMessage()
func (*Error_Source) Reset ¶
func (m *Error_Source) Reset()
func (*Error_Source) Size ¶
func (m *Error_Source) Size() (n int)
func (*Error_Source) String ¶
func (m *Error_Source) String() string
func (*Error_Source) Unmarshal ¶
func (m *Error_Source) Unmarshal(dAtA []byte) error
func (*Error_Source) XXX_DiscardUnknown ¶
func (m *Error_Source) XXX_DiscardUnknown()
func (*Error_Source) XXX_Marshal ¶
func (m *Error_Source) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)
func (*Error_Source) XXX_Merge ¶
func (m *Error_Source) XXX_Merge(src proto.Message)
func (*Error_Source) XXX_Size ¶
func (m *Error_Source) XXX_Size() int
func (*Error_Source) XXX_Unmarshal ¶
func (m *Error_Source) XXX_Unmarshal(b []byte) error
Source Files