typeorm-binary-uuid

Store and retrieve UUIDs as BINARY(16) in MySQL with zero boilerplate. Designed for NestJS + TypeORM projects that need compact, indexed UUID primary keys.

Why BINARY(16)?

| Storage | Bytes | Indexed size | |---------------|-------|--------------| | VARCHAR(36) | 36 | 36 | | BINARY(16) | 16 | 16 |

Half the storage, much faster index lookups — especially for large tables.

Installation

npm install typeorm-binary-uuid

Peer dependency: typeorm >= 0.3.0

Usage

Option 1 — Extend BinaryUuidBaseEntity (recommended)

The base entity auto-generates a UUID v4 on @BeforeInsert.

import { Entity, Column } from 'typeorm';
import { BinaryUuidBaseEntity } from 'typeorm-binary-uuid';

@Entity()
export class User extends BinaryUuidBaseEntity {
  @Column()
  name: string;
}

// id is auto-generated — no manual uuid() call needed:
const user = new User();
user.name = 'Zakaria';
await repo.save(user); // user.id = "550e8400-e29b-41d4-a716-446655440000"

Option 2 — Decorator shortcuts

Use @BinaryUuidPrimaryColumn() and @BinaryUuidColumn() directly.

import { Entity, Column } from 'typeorm';
import { BinaryUuidPrimaryColumn, BinaryUuidColumn } from 'typeorm-binary-uuid';
import { randomUUID } from 'crypto';

@Entity()
export class Order {
  @BinaryUuidPrimaryColumn()
  id: string = randomUUID();

  // Non-nullable FK
  @BinaryUuidColumn()
  userId: string;

  // Nullable FK
  @BinaryUuidColumn({ nullable: true })
  parentOrderId: string | null;

  @Column()
  amount: number;
}

Option 3 — Column option presets

import { Entity, PrimaryColumn, Column, ManyToOne, JoinColumn } from 'typeorm';
import {
  BinaryUuidPrimaryColumnOptions,
  BinaryUuidFkColumnOptions,
  BinaryUuidFkColumnOptionsRequired,
} from 'typeorm-binary-uuid';

@Entity()
export class Invoice {
  @PrimaryColumn(BinaryUuidPrimaryColumnOptions)
  id: string;

  @Column(BinaryUuidFkColumnOptionsRequired) // non-nullable
  organizationId: string;

  @Column(BinaryUuidFkColumnOptions) // nullable
  approvedById: string | null;
}

Option 4 — Raw transformer on any column

import { Entity, PrimaryColumn, Column } from 'typeorm';
import { BinaryUuidTransformer } from 'typeorm-binary-uuid';

@Entity()
export class Product {
  @PrimaryColumn({ type: 'binary', length: 16, transformer: BinaryUuidTransformer })
  id: string;
}

Relations work as normal

TypeORM handles relations using the string value — the transformer fires on the leaf column.

@Entity()
export class Order extends BinaryUuidBaseEntity {
  @ManyToOne(() => User)
  @JoinColumn({ name: 'user_id' })
  user: User;

  @BinaryUuidColumn()
  userId: string;
}

Utilities

import { uuidToBuffer, bufferToUuid, isValidUuid } from 'typeorm-binary-uuid';

// Convert for raw queries
const buf = uuidToBuffer('550e8400-e29b-41d4-a716-446655440000');
// Buffer <55 0e 84 00 e2 9b 41 d4 a7 16 44 66 55 44 00 00>

const uuid = bufferToUuid(buf);
// "550e8400-e29b-41d4-a716-446655440000"

// Use in TypeORM QueryBuilder with raw BINARY params:
const user = await repo
  .createQueryBuilder('u')
  .where('u.id = :id', { id: uuidToBuffer(someUuidString) })
  .getOne();

Safe transformer (no-throw)

For migration scenarios with potentially dirty data:

import { BinaryUuidTransformerSafe } from 'typeorm-binary-uuid';

@Column({ type: 'binary', length: 16, transformer: BinaryUuidTransformerSafe })
legacyId: string | null; // returns null instead of throwing on bad data

MySQL schema

CREATE TABLE `user` (
  `id`   BINARY(16)   NOT NULL,
  `name` VARCHAR(255) NOT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `order` (
  `id`      BINARY(16) NOT NULL,
  `user_id` BINARY(16) NOT NULL,
  PRIMARY KEY (`id`),
  INDEX `IDX_order_user_id` (`user_id`),
  CONSTRAINT `FK_order_user` FOREIGN KEY (`user_id`) REFERENCES `user` (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

API Reference

| Export | Type | Description | |---------------------------------|------------------------|-----------------------------------------------------| | BinaryUuidBaseEntity | abstract class | Base entity with auto-UUID PK | | BinaryUuidPrimaryColumn(opts) | decorator | @PrimaryColumn with BINARY(16) + transformer | | BinaryUuidColumn(opts) | decorator | @Column with BINARY(16) + transformer | | BinaryUuidPrimaryColumnOptions| PrimaryColumnOptions | Column options object for PK | | BinaryUuidFkColumnOptions | ColumnOptions | Column options object for nullable FK | | BinaryUuidFkColumnOptionsRequired | ColumnOptions | Column options object for non-nullable FK | | BinaryUuidTransformer | ValueTransformer | Strict transformer — throws on invalid data | | BinaryUuidTransformerSafe | ValueTransformer | Lenient transformer — returns null on invalid data | | uuidToBuffer(uuid) | (string) => Buffer | Convert UUID string to 16-byte Buffer | | bufferToUuid(buffer) | (Buffer) => string | Convert 16-byte Buffer to UUID string | | isValidUuid(value) | type guard | Returns true if value is a valid UUID string | | isValidUuidBuffer(value) | type guard | Returns true if value is a 16-byte Buffer |

License

MIT