Relational Integrity in FaunaDB: Refs & Unique Indexes

Learn how to implement relational-style data integrity in FaunaDB using Refs and Unique Indexes to avoid orphaned records in a distributed environment.

The Challenge of Distributed Consistency

In traditional SQL databases, foreign keys act as the safety rail for your data. If you try to delete a user who still has active orders, the database stops you. In many NoSQL systems, that responsibility shifts entirely to the application layer, often leading to \"orphaned\" records—data that points to a parent document that no longer exists.

FaunaDB occupies a middle ground. It provides strict serializability (the highest level of isolation, ensuring transactions appear in a specific sequence) but does not use traditional foreign key constraints. The takeaway for engineers is that data integrity in Fauna is achieved through a combination of References (Refs) and Unique Indexes, rather than schema-level constraints.

Linking Data with References

In Fauna, you don't store a raw ID string to link documents. Instead, you use a Ref. A Ref is a first-class object that points directly to another document. While a Ref doesn't automatically prevent the target document from being deleted, it allows the database engine to perform joins—known as \"dereferencing\"—efficiently within a single transaction.

By using Refs, you move the logic of \"joining\" data from the application code into the FQL (Fauna Query Language) engine. This reduces network round-trips, as the database resolves the pointer internally before returning the final result set to your client.

Enforcing Uniqueness via First-Class Indexes

Since you cannot define a \"Unique Foreign Key\" in the traditional sense, you must use Indexes. In Fauna, indexes are not just performance boosters; they are tools for integrity. By marking an index as unique: true, you can prevent duplicate entries for a specific field across a collection.

For example, if you need to ensure a user has only one \"Primary Address,\" you create a unique index on the user_ref field within the addresses collection. Any attempt to insert a second address for that same user will trigger a transaction failure, effectively mimicking a one-to-one relational constraint.

Worked Example: Atomic Order Placement

Consider a scenario where you must create an order and decrement a product's stock. This must be atomic: you cannot have an order without reducing stock, and you cannot reduce stock if the product is sold out.

Run this logic via the Fauna Dashboard or a client SDK using FQL. Note: This example assumes the existence of Products and Orders collections and a unique index on Product.sku.

// FQL Logic for Atomic Order\nLet productRef = Get(Match(Index(\"products_by_sku\" ), \"SKU-123\")),\n    currentStock = productRef.data.stock\nin\n  if (currentStock > 0) {\n    // 1. Decrement stock\n    Update(productRef, {\n      data: { stock: currentStock - 1 }\n    });\n    // 2. Create order record\n    Create(Collection(\"orders\" ), {\n      data: {\n        product: productRef,\n        timestamp: Now(),\n        status: \"confirmed\"\n      }\n    });\n  } else {\n    Abort(\"Product out of stock\" )\n  }\n

Verification: To check the result, query the orders collection and the specific product document. If the Abort was triggered, neither the stock update nor the order creation will persist, confirming the ACID properties of the transaction.

The Trade-off: Latency vs. Consistency

Fauna's commitment to strict serializability across multiple regions comes with a cost. Because the system ensures every node agrees on the order of transactions, you may experience higher write latency compared to \"eventually consistent\" databases (like DynamoDB or Cassandra) during periods of high contention on the same document.

To mitigate this, avoid \"hot documents\"—single records that are updated by thousands of concurrent users. Instead of a single global counter, consider sharding the data or using a more distributed update pattern.

Practical Implementation Check

When moving from a relational DB to Fauna, verify your integrity strategy with these three checks:

Ref Check: Are you storing Ref objects instead of strings? (Strings require manual lookups; Refs allow direct dereferencing).
Index Check: Do all fields requiring uniqueness have a corresponding index with unique: true?
Transaction Check: Are multi-document updates wrapped in a single FQL block to ensure atomicity?

Managing Relational Integrity in FaunaDB without Foreign Keys