Custom Column Types

Overview

Introduction

Sometimes your application needs to store data types that are specific to your business logic or not natively supported out of the box. Custom Column Types let you define your own data types and map them directly to database columns. This feature bridges the gap between your application's TypeScript data models and how values are represented, serialized, and retrieved from your database.

By defining a custom column type, you can control the exact database data type string used for migrations, automatically serialize JavaScript or TypeScript objects into driver-accepted parameters before writing to the database, and deserialize incoming database values back into your desired runtime format.

Defining a Custom Type

To create a custom column type, use the customType function. You provide configuration parameters that dictate how the column behaves during database interactions and type-checking.

Copyimport { customType } from 'drizzle-orm/pg-core';
 
const customVarchar = customType<{
  data: string;
  driverData: string;
  config: { length: number };
  configRequired: true;
}>({
  dataType(config) {
    return `varchar(${config.length})`;
  },
  toDriver(value) {
    return value;
  },
  fromDriver(value) {
    return value;
  },
});

Configuration Options

When defining a custom type, you configure its parameters using standard type definitions:

Mapping Values Between Application and Driver

Custom types allow you to transform data seamlessly as it travels between your TypeScript code and the database driver using two main mapping functions:

1. toDriver: Converts your application data model into a format accepted by the database driver right before an insert or update query executes (for example, serializing an object into a JSON string).
2. fromDriver: Converts raw database values coming from the driver back into your application's preferred runtime data type (for example, parsing a date string into a real JavaScript Date object).

Working with Optional and Required Configurations

You can configure your custom types to accept optional settings or enforce required parameters depending on your database schema needs.

Copy// Example with an optional configuration
const flexibleString = customType<{
  data: string;
  driverData: string;
  config: { length: number };
}>({
  dataType(config) {
    return config ? `varchar(${config.length})` : 'text';
  },
  toDriver(value) {
    return value;
  },
  fromDriver(value) {
    return value;
  },
});
 
// Usage with config
const col1 = flexibleString('col1', { length: 50 });
// Usage without config (falls back to text)
const col2 = flexibleString('col2');

Related

• Declaring Schemas