Nile extends PostgreSQL with tenant-native features — each tenant gets virtual database isolation without separate database instances. UUID v7 as a record ID gives tenant records time-ordered, RFC-standard identifiers. See UUID in PostgreSQL for the base PostgreSQL patterns.

Multi-tenant schema with UUID v7

-- Nile tenant-aware table
CREATE TABLE orders (
  tenant_id   UUID         NOT NULL,          -- Nile tenant context
  id          UUID         NOT NULL DEFAULT gen_random_uuid(),
  customer_id UUID         NOT NULL,
  total       NUMERIC(10,2) NOT NULL,
  status      TEXT         NOT NULL DEFAULT 'pending',
  PRIMARY KEY (tenant_id, id),
  FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);

-- Index for per-tenant cursor pagination
CREATE INDEX idx_orders_tenant_id ON orders (tenant_id, id);

Insert with UUID v7 (TypeScript)

import { Pool } from 'pg';
import { v7 as uuidv7 } from 'uuid';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

async function createOrder(tenantId: string, customerId: string, total: number) {
  const id = uuidv7();  // UUID v7 — time-ordered within this tenant

  await pool.query(
    'INSERT INTO orders (tenant_id, id, customer_id, total) VALUES ($1, $2, $3, $4)',
    [tenantId, id, customerId, total]
  );
  return id;
}

Per-tenant cursor pagination

// Cursor pagination scoped to a single tenant
async function listTenantOrders(tenantId: string, cursor?: string, limit = 20) {
  const { rows } = cursor
    ? await pool.query(
        'SELECT id, total, status FROM orders WHERE tenant_id = $1 AND id > $2 ORDER BY id LIMIT $3',
        [tenantId, cursor, limit]
      )
    : await pool.query(
        'SELECT id, total, status FROM orders WHERE tenant_id = $1 ORDER BY id LIMIT $2',
        [tenantId, limit]
      );

  return {
    items:      rows,
    nextCursor: rows.length === limit ? rows.at(-1)?.id : null,
  };
}

Row-level security policy

-- Nile enforces tenant isolation via RLS
ALTER TABLE orders ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON orders
  USING (tenant_id = current_setting('nile.tenant_id')::UUID);

Time-range query within a tenant

// Find orders created in the last 24h using UUID v7 range
function uuidV7MinAt(date: Date): string {
  const ms  = BigInt(date.getTime());
  const hex = ms.toString(16).padStart(12, '0');
  return `${hex.slice(0,8)}-${hex.slice(8,12)}-7000-8000-000000000000`;
}

async function recentTenantOrders(tenantId: string) {
  const since = uuidV7MinAt(new Date(Date.now() - 86_400_000));
  const { rows } = await pool.query(
    'SELECT id, total FROM orders WHERE tenant_id = $1 AND id > $2 ORDER BY id',
    [tenantId, since]
  );
  return rows;
}

Further reading

External references

Frequently asked questions

What is Nile Postgres?

Nile is a serverless PostgreSQL platform designed for multi-tenant SaaS applications. It provides built-in tenant isolation, virtual tenant databases, and per-tenant row-level security. Each table can include a tenant_id column that Nile uses to enforce isolation. See UUID in PostgreSQL for standard PostgreSQL UUID patterns.

How does UUID v7 work with Nile tenant IDs?

Nile tenant IDs are UUIDs — Nile generates them as UUID v4 by default. Records in tenant tables use a composite key of (tenant_id, id). Using UUID v7 as the id component gives each tenant's records a time-ordered identifier, enabling per-tenant cursor pagination with WHERE tenant_id = $1 AND id > $2.

Does UUID v7 help with multi-tenant cursor pagination in Nile?

Yes. In a multi-tenant schema, each tenant's records are isolated by tenant_id. UUID v7 as the record id enables WHERE tenant_id = $1 AND id > cursor ORDER BY id pagination — time-ordered within each tenant without a separate created_at sort. See UUID v7 for Cursor Pagination.