# CustomDateTime

The CustomDateTime type wraps time.Time with SurrealDB-compatible CBOR encoding at nanosecond precision.

The `CustomDateTime` struct wraps Go's `time.Time` and handles CBOR encoding with tag 12 as specified by SurrealDB. It preserves nanosecond precision and stores datetimes as a `[seconds, nanoseconds]` pair.

**Package:** `github.com/surrealdb/surrealdb.go/pkg/models`

**Source:** [pkg/models/datetime.go](https://github.com/surrealdb/surrealdb.go/blob/main/pkg/models/datetime.go)

---

## Definition

```go
type CustomDateTime struct {
    time.Time
}
```

`CustomDateTime` embeds `time.Time`, so all standard `time.Time` methods are available directly.

---

## Methods

### `.String()` {#string}

Returns the datetime formatted as `"2006-01-02T15:04:05Z"` in UTC.

```go title="Syntax"
s := dt.String()
```

**Returns:** `string`

### `.SurrealString()` {#surrealstring}

Returns the SurrealQL representation: `<datetime> '2006-01-02T15:04:05Z'`.

```go title="Syntax"
s := dt.SurrealString()
```

**Returns:** `string`

### `.IsZero()` {#iszero}

Returns `true` if the datetime is nil or the zero time.

```go title="Syntax"
zero := dt.IsZero()
```

**Returns:** `bool`

---

## Usage

```go
import "github.com/surrealdb/surrealdb.go/pkg/models"

now := models.CustomDateTime{Time: time.Now()}

type Event struct {
    ID        *models.RecordID     `json:"id,omitempty"`
    CreatedAt models.CustomDateTime `json:"created_at"`
}
```

Zero-valued `CustomDateTime` is encoded as CBOR tag 6 (`NONE`).

---

## See also

- [RecordID](/docs/reference/golang/api/values/record-id.md) for the record identifier type
- [Duration](/docs/reference/golang/api/values/duration.md) for the duration type
- [Value types](/docs/reference/golang/concepts/value-types.md) for the full type mapping
- [Data manipulation](/docs/reference/golang/concepts/data-manipulation.md) for using datetime values in CRUD operations
- [SurrealQL datetime type](/docs/reference/query-language/language-primitives/data-types/datetimes.md) for the underlying data model