CockroachDB is a distributed SQL database that stores data in range-based key-value shards across nodes. Primary keys determine physical data placement — a monotonically increasing key like UUID v7 concentrates inserts on the right-most range until CockroachDB auto-splits it. For most workloads this is fine; for very high insert rates, hash-sharded indexes spread load evenly. See UUID in Databases for the broader index strategy.

Basic UUID v7 primary key

-- CockroachDB: UUID type is natively supported
CREATE TABLE orders (
  id         UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
  customer   STRING      NOT NULL,
  total      DECIMAL     NOT NULL,
  created_at TIMESTAMPTZ DEFAULT now()
);

CockroachDB lacks a built-in uuidv7() function — generate UUID v7 in the application layer:

// Go with github.com/google/uuid (v7 via Now())
import "github.com/google/uuid"

orderID := uuid.Must(uuid.NewV7())

db.Exec(
  "INSERT INTO orders (id, customer, total) VALUES ($1, $2, $3)",
  orderID, customer, total,
)

Hash-sharded index for high-throughput inserts

-- Hash-sharding distributes UUID v7's monotonic writes across 8 buckets
CREATE TABLE events (
  id         UUID        NOT NULL DEFAULT gen_random_uuid(),
  event_type STRING      NOT NULL,
  payload    JSONB,
  PRIMARY KEY (id) USING HASH WITH (bucket_count = 8)
);

With a hash-sharded primary key, CockroachDB prepends a computed hash bucket to the storage key, spreading writes across ranges while preserving the UUID v7 value for the application. See UUID v7 in Distributed Systems for the broader hotspot discussion.

Multi-region table with UUID v7

-- REGIONAL BY ROW: each row pinned to a region
-- crdb_region is automatically added by CockroachDB
ALTER TABLE orders SET LOCALITY REGIONAL BY ROW;

-- Composite PK: region-based distribution + UUID v7 ordering within region
-- CockroachDB adds (crdb_region, id) automatically
// Insert with explicit region hint
db.Exec(
  "INSERT INTO orders (id, customer, total, crdb_region) VALUES ($1, $2, $3, $4)",
  uuid.Must(uuid.NewV7()), customer, total, "us-east1",
)

GORM with CockroachDB and UUID v7

package models

import (
  "github.com/google/uuid"
  "gorm.io/gorm"
)

type Order struct {
  ID         uuid.UUID `gorm:"type:uuid;primaryKey"`
  CustomerID string    `gorm:"not null"`
  Total      float64   `gorm:"not null"`
}

func (o *Order) BeforeCreate(tx *gorm.DB) error {
  if o.ID == (uuid.UUID{}) {
    id, err := uuid.NewV7()
    if err != nil {
      return err
    }
    o.ID = id
  }
  return nil
}

See UUID v7 ORM Support in 2026 for the state of all ORMs.

Cursor pagination with UUID v7

// CockroachDB: UUID v7 ORDER BY gives chronological order
rows, err := db.Query(`
  SELECT id, customer, total
  FROM orders
  WHERE ($1::uuid IS NULL OR id > $1)
  ORDER BY id
  LIMIT $2
`, cursor, limit)

UUID v7 cursors work without a secondary created_at index. See UUID v7 for Cursor Pagination.

Further reading

External references

Frequently asked questions

Does UUID v7 cause hotspots in CockroachDB?

UUID v7's monotonically increasing prefix means new rows always land on the same range (the "hot" range at the end of the keyspace). CockroachDB automatically detects and splits hot ranges, but for very high insert rates, use a USING HASH WITH (bucket_count = 8) hash-sharded index on the UUID v7 primary key to pre-distribute inserts. See the CockroachDB hash-sharded indexes documentation.

What does CockroachDB use as its default primary key type?

CockroachDB historically recommended UUID DEFAULT gen_random_uuid() (UUID v4) for primary keys because random distribution avoids write hotspots. UUID v7 offers better application-layer ordering but requires hash-sharding for high-throughput inserts. For most workloads, CockroachDB's automatic range splitting handles UUID v7 hotspots without manual intervention.

Can I use UUID v7 with CockroachDB's multi-region tables?

Yes. CockroachDB's REGIONAL BY ROW partitioning routes each row to its home region based on a crdb_region column. UUID v7 works as the primary key alongside a region column — the composite primary key (crdb_region, id) ensures rows are distributed by region while id is time-sorted within each region.