# DB Constants

Reference for DbDefaults and DbValues.ForeignKey constants — portable SQL expressions for defaults and referential actions.

## Overview

`DbDefaults` and `DbValues.ForeignKey` are constant classes that provide named SQL expressions for use in attribute arguments. Using these constants instead of raw SQL strings keeps your model annotations readable, avoids typos, and makes intent explicit.

> **NOTE** These constants are cross-database design helpers. Prefer them over raw SQL strings for portability — if the library ever adds support for additional platforms, the constants will emit the correct dialect automatically.

## DbDefaults Constants

All `DbDefaults` constants are used as the argument to `[Default(...)]`:

```csharp
[Default(DbDefaults.Guid.Random)]
public Guid Id { get; set; }
```

### DbDefaults.Guid

| Constant | SQL emitted | When to use |
|----------|-------------|-------------|
| `DbDefaults.Guid.Random` | `gen_random_uuid()` | General-purpose UUIDs. Fully random, no ordering. |
| `DbDefaults.Guid.Sequential` | `uuid_generate_v1mc()` | UUIDs that sort roughly in insertion order. Reduces index fragmentation on large tables. |

> **TIP** Use `DbDefaults.Guid.Sequential` for primary keys on high-write tables to reduce B-tree index fragmentation. Use `DbDefaults.Guid.Random` when sequential ordering of IDs would leak information.

> **NOTE** `uuid_generate_v1mc()` requires the `uuid-ossp` PostgreSQL extension. Add `CREATE EXTENSION IF NOT EXISTS "uuid-ossp";` to your initial migration if you use `DbDefaults.Guid.Sequential`.

### DbDefaults.Time

| Constant | SQL emitted | When to use |
|----------|-------------|-------------|
| `DbDefaults.Time.Now` | `timezone('utc', now())` | UTC timestamp. Use for `created_at`, `updated_at`, audit columns. |
| `DbDefaults.Time.NowLocal` | `now()` | Server-local timestamp (session time zone). Use only when the database is explicitly configured to a known time zone. |
| `DbDefaults.Time.Date` | `current_date` | Calendar date only (no time component). Use for date-only columns such as `birth_date` or `expiry_date`. |

> **WARNING** Prefer `DbDefaults.Time.Now` over `DbDefaults.Time.NowLocal` in most applications. `now()` returns the session time zone, which varies by connection and can produce inconsistent data if clients connect with different zone settings.

### DbDefaults.Bool

| Constant | SQL emitted | When to use |
|----------|-------------|-------------|
| `DbDefaults.Bool.True` | `TRUE` | Default a boolean column to true (e.g., `is_active`, `email_verified`). |
| `DbDefaults.Bool.False` | `FALSE` | Default a boolean column to false (e.g., `is_deleted`, `is_suspended`). |

### DbDefaults.Number

| Constant | SQL emitted | When to use |
|----------|-------------|-------------|
| `DbDefaults.Number.Zero` | `0` | Default a numeric column to zero (e.g., counters, balances). |
| `DbDefaults.Number.One` | `1` | Default a numeric column to one (e.g., version fields, minimum quantities). |

### DbDefaults.Text

| Constant | SQL emitted | When to use |
|----------|-------------|-------------|
| `DbDefaults.Text.Empty` | `''` | Default a text column to an empty string. |

## DbValues.ForeignKey Constants

All `DbValues.ForeignKey` constants are used as the `OnDelete` or `OnUpdate` argument to `[ForeignKey(...)]`:

```csharp
[ForeignKey(typeof(User), OnDelete = DbValues.ForeignKey.Cascade)]
public Guid UserId { get; set; }
```

| Constant | SQL emitted | Behaviour |
|----------|-------------|-----------|
| `DbValues.ForeignKey.Cascade` | `CASCADE` | Automatically delete or update child rows when the parent row is deleted or updated. |
| `DbValues.ForeignKey.SetNull` | `SET NULL` | Set the foreign key column to `NULL` when the parent row is deleted. The column must be nullable. |
| `DbValues.ForeignKey.SetDefault` | `SET DEFAULT` | Set the foreign key column to its `DEFAULT` value when the parent row is deleted. |
| `DbValues.ForeignKey.Restrict` | `RESTRICT` | Prevent deletion of the parent row if any child rows exist. Checked immediately within the statement. |
| `DbValues.ForeignKey.NoAction` | `NO ACTION` | Like `RESTRICT` but the check is deferred to the end of the transaction. This is the PostgreSQL default when no action is specified. |

> **TIP** Use `DbValues.ForeignKey.Cascade` for owned entities (e.g., a user's addresses) and `DbValues.ForeignKey.Restrict` or `DbValues.ForeignKey.NoAction` for shared references (e.g., a product category that must not be deleted while products exist).