Skip to content
HeliosDB HeliosDB Full

Distributed Foreign Keys User Guide

Distributed Foreign Keys User Guide

Overview

Distributed foreign key constraints maintain referential integrity across sharded tables using 2PC for atomic validation.

Benefits

  • Cross-shard referential integrity
  • ACID guarantees
  • Transparent to applications
  • Automatic validation

Prerequisites

  • HeliosDB v3.2+ sharded cluster
  • Two-phase commit enabled
  • Metadata service configured

Configuration

distributed_fk:
  enabled: true
  validation_mode: strict  # Or: lazy, async
  timeout_ms: 5000

SQL Examples

-- Create foreign key across shards
CREATE TABLE orders (
    id INT PRIMARY KEY,
    user_id INT,
    FOREIGN KEY (user_id) REFERENCES users(id)
) WITH (shard_key = 'id');


CREATE TABLE users (
    id INT PRIMARY KEY,
    name TEXT
) WITH (shard_key = 'id');


-- Insert validates FK across shards
INSERT INTO orders (id, user_id) VALUES (1, 999);
-- ERROR: FK violation (user 999 doesn't exist)

Validation Modes

Strict (Default)

validation_mode: strict
# Validates immediately, blocks if target shard unavailable

Lazy

validation_mode: lazy
# Validates eventually, allows temporary inconsistency

Async

validation_mode: async
# Validates in background, fastest but eventual consistency

Best Practices

  1. Co-locate related data when possible
  2. Use async mode for high throughput
  3. Monitor cross-shard FK overhead
  4. Consider denormalization for hot paths

For more: /docs/architecture/distributed-fk.md