ORM 支持传递自定义的 context 上下文变量，用于异步 IO 控制、上下文信息传递（特别是链路跟踪信息的传递）、以及嵌套事务支持。

我们可以通过 Ctx 方法传递自定义的上下文变量给 ORM 对象， Ctx 方法其实是一个链式操作方法，该上下文传递进去后仅对当前 DB 接口对象有效，方法定义如下：

func Ctx(ctx context.Context) DB

示例1，请求超时控制

我们来看一个通过上下文变量控制请求超时时间的示例。

ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()
_, err := db.Ctx(ctx).Query("SELECT SLEEP(10)")
fmt.Println(err)

该示例中执行会 sleep 10 秒中，因此必定会引发请求的超时。执行后，输出结果为：

context deadline exceeded, SELECT SLEEP(10)

示例2，链路跟踪信息

上下文变量也可以传递链路跟踪信息，并且可以和日志组件结合，将链路信息打印到日志中（仅当 ORM 日志开启时）。

我们来看一个示例。

1、数据库配置示例：

[database]
    [database.logger]
        Path    = "/tmp/log/gf-app/sql"
        Level   = "all"
        Stdout  = true
        CtxKeys = ["Trace-Id"]
    [database.default]
        link   = "mysql:root:12345678@tcp(127.0.0.1:3306)/test"
        debug  = true

其中，我们通过日志组件的 CtxKeys 配置来指定需要打印到日志中的上下文信息中的变量名称，因此当 context 上下文变量中存在键名为 Trace-Id 的变量时，将会被自动打印到日志中。关于日志组件的上下文特性介绍具体请参考 日志组件-Context上下文 章节。同时，仅当数据库配置的 debug 打开时才会记录完整的 SQL 执行日志，因此这里配置中的 debug=true。

ORM 组件同时支持 goframe 框架的 logger 组件 CtxKeys 特性（自定义链路信息传递），同时也支持标准的 OpenTelemetry 链路跟踪信息传递，具体请参考章节： 链路跟踪

2、 Golang 代码示例

package main

import (
    "context"
    "github.com/gogf/gf/frame/g"
)

func main() {
    ctx := context.WithValue(context.Background(), "Trace-Id", "123456789")
    _, err := g.DB().Ctx(ctx).Query("SELECT 1")
    if err != nil {
        panic(err)
    }
}

为简化示例，我们这里手动构造了一个 ctx 变量，并存放了一个 Trace-Id 的键值对，键值为 123456789。执行后，终端输出为：

2020-12-28 23:43:03.055 [DEBU] {Trace-Id: 123456789} [  3 ms] [default] SELECT 1

示例3，模型上下文操作

模型对象也支持上下文变量的传递，同样也是通过 Ctx 方法。我们来看一个简单的示例，我们将示例2的例子通过模型操作调整一下。

package main

import (
    "context"
    "github.com/gogf/gf/frame/g"
)

func main() {
    ctx := context.WithValue(context.Background(), "Trace-Id", "123456789")
    _, err := g.DB().Model("user").Ctx(ctx).All()
    if err != nil {
        panic(err)
    }
}

执行后，终端输出为：

2020-12-28 23:46:56.349 [DEBU] {Trace-Id: 123456789} [  5 ms] [default] SHOW FULL COLUMNS FROM `user`
2020-12-28 23:46:56.354 [DEBU] {Trace-Id: 123456789} [  5 ms] [default] SELECT * FROM `user`

其中 SHOW FULL COLUMNS FROM `user` 为 ORM 组件的数据表字段获取查询，每个表在执行操作之前仅会查询一次并缓存结果到内存中。

示例4，嵌套事务支持

嵌套事务的支持依赖 Context 上下文变量的层级传递，具体请参考章节： ORM事务处理