Enum DbError 

pub enum DbError {
    QueryError(String),
    ConnectionError(String),
    ConnectionRefused(String),
    ConnectionTimeout(String),
    PoolError(PoolError),
    CacheError(CacheError),
    TxError(TxError),
    MigrationError(String),
    Unsupported(String),
    ConfigError(String),
    SerdeError(String),
    NotFound(String),
    AlreadyExists(String),
    ConstraintViolation(String),
    UniqueViolation(String),
    ForeignKeyViolation(String),
    NullValue(String),
    InvalidInput(String),
    Internal(String),
    IoError(String),
    Hook(String),
    TenantError(String),
    Validation(String),
    Contextual {
        source: Box<DbError>,
        context: ErrorContext,
    },
}

数据库错误类型

Variants

QueryError(String)

查询执行失败

ConnectionError(String)

连接失败

ConnectionRefused(String)

连接被拒绝

ConnectionTimeout(String)

连接超时

PoolError(PoolError)

连接池错误

CacheError(CacheError)

缓存错误

TxError(TxError)

事务错误

MigrationError(String)

迁移错误

Unsupported(String)

方言不支持

ConfigError(String)

配置错误

SerdeError(String)

序列化/反序列化错误

NotFound(String)

未找到

AlreadyExists(String)

已存在

ConstraintViolation(String)

约束冲突（通用回退，无法确定具体类型时使用）

UniqueViolation(String)

唯一约束冲突（UNIQUE constraint）

ForeignKeyViolation(String)

外键约束冲突（FOREIGN KEY constraint）

NullValue(String)

非空字段出现 null 值

InvalidInput(String)

输入非法

Internal(String)

内部错误

IoError(String)

IO 错误

Hook(String)

钩子执行失败

TenantError(String)

多租户错误（如租户 ID 缺失、跨租户访问）

Validation(String)

数据验证失败（业务规则校验未通过，由 before_validate 钩子触发）

Contextual

#6 修复：带上下文链的错误

包装原始错误 + 上下文链，用于在错误传播路径上附加调用方上下文。 通过 DbError::with_context("operation") 创建。

Fields

source: Box<DbError>

原始错误（Box 避免递归类型大小爆炸）

context: ErrorContext

上下文链头节点

Implementations

impl DbError

pub fn query(s: impl Into<String>) -> Self

新建查询错误

pub fn connection(s: impl Into<String>) -> Self

新建连接错误

pub fn not_found(s: impl Into<String>) -> Self

新建未找到错误

pub fn with_context(self, context: impl Into<String>) -> Self

#6 修复：附加错误上下文（消费 self，返回带上下文的新错误）

用于在错误传播路径上附加调用方上下文，形成 error.with_context("operation") 链式调用。多次调用会形成上下文链表。

示例

fn fetch_user(id: i64) -> Result<User, DbError> {
    db.query("SELECT * FROM users WHERE id = ?", &[id.into()])
        .await
        .map_err(|e| e.with_context(format!("fetching user id={}", id)))?;
    // ...
}

pub fn with_context_in_span( self, context: impl Into<String>, span: impl Into<String>, ) -> Self

#6 修复：附加错误上下文（含 tracing span 名）

pub fn context(&self) -> Option<&ErrorContext>

#6 修复：获取错误上下文链（None 表示无附加上下文）

pub fn format_context_chain(&self) -> String

#6 修复：格式化错误上下文链为多行字符串

pub fn root_cause(&self) -> &DbError

#6 修复：剥离上下文链，返回原始错误引用

pub fn is_retryable(&self) -> bool

该错误是否可重试

pub fn error_code(&self) -> &'static str

获取错误码（用于日志/监控）

pub fn http_status(&self) -> u16

映射到 HTTP 状态码（RFC 7231）

用于在 HTTP 服务（如 axum/actix）中根据数据库错误返回合适的 HTTP 状态码。

• 400 Bad Request：非法输入、参数校验失败、配置错误
• 404 Not Found：资源未找到
• 409 Conflict：资源已存在、约束冲突（唯一/外键/非空/通用）
• 422 Unprocessable Entity：序列化/反序列化错误
• 500 Internal Server Error：查询失败、内部错误、钩子失败、迁移失败、IO 错误、事务错误、租户错误
• 501 Not Implemented：方言/功能不支持
• 502 Bad Gateway：连接错误、连接被拒绝
• 503 Service Unavailable：连接池耗尽/关闭、缓存错误
• 504 Gateway Timeout：连接超时、连接池获取超时

pub fn grpc_status_code(&self) -> u32

映射到 gRPC 状态码

用于在 gRPC 服务（tonic）中根据数据库错误返回合适的 gRPC 状态码。 参考：https://grpc.io/docs/guides/status-codes/

• 2 UNKNOWN：查询失败、内部错误、钩子失败、迁移失败、IO 错误
• 3 INVALID_ARGUMENT：非法输入、参数校验失败、配置错误
• 4 DEADLINE_EXCEEDED：连接超时、连接池获取超时
• 5 NOT_FOUND：资源未找到
• 6 ALREADY_EXISTS：资源已存在、唯一约束冲突
• 7 PERMISSION_DENIED：租户错误（跨租户访问）
• 8 RESOURCE_EXHAUSTED：连接池耗尽/关闭、缓存错误
• 9 FAILED_PRECONDITION：约束冲突（通用/外键/非空）、事务错误
• 12 UNIMPLEMENTED：方言/功能不支持
• 13 INTERNAL：序列化/反序列化错误
• 14 UNAVAILABLE：连接错误、连接被拒绝、连接创建失败

Trait Implementations

impl Debug for DbError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for DbError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for DbError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<DbError> for LockError

fn from(e: DbError) -> Self

Converts to this type from the input type.

impl From<Error> for DbError

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<Error> for DbError

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<FromUtf8Error> for DbError

fn from(err: FromUtf8Error) -> Self

Converts to this type from the input type.

impl<T> From<PoisonError<T>> for DbError

fn from(err: PoisonError<T>) -> Self

Converts to this type from the input type.

impl From<TryFromIntError> for DbError

fn from(err: TryFromIntError) -> Self

Converts to this type from the input type.