---
title: "Entities"
description: "Define database tables using entity classes and attributes with compile-time mapping."
canonical: "https://roomsharp.dev/docs/v0.4.7/entities"
source: "src/content/v0.4.7/entities.mdx"
---

# Entities

Define database tables using entity classes and attributes with compile-time mapping.

> **Tip:** Import `RoomSharp.Attributes` once at the top of your file to access all entity annotations.

## What are Entities?

Entities are POCOs that represent database tables. Decorating a class with `[Entity]` lets RoomSharp generate compile-time mappings between your C# model and the database schema.

## Basic Entity Definition

Here is a simple entity:

```csharp
using RoomSharp.Attributes;

[Entity(TableName = "users")]
public class User
{
    [PrimaryKey(AutoGenerate = true)]
    public long Id { get; set; }

    [Unique]
    public required string Email { get; set; }
    
    public string? Name { get; set; }
}
```

## Entity Attributes

### `[Entity]`

Marks a class as a database table.

**Properties:**
- `TableName` - Database table name (required)

```csharp
[Entity(TableName = "todo_lists")]
public class TodoList
{
    // properties...
}
```

### `[PrimaryKey]`

Designates a property as the primary key.

**Properties:**
- `AutoGenerate` - Enable auto-increment for numeric keys (default: false)

```csharp
[PrimaryKey(AutoGenerate = true)]
public long Id { get; set; }
```

### `[ColumnInfo]`

Customize column mapping and type affinity.

**Properties:**
- `Name` - Custom column name
- `TypeAffinity` - SQLite type hint (INTEGER, TEXT, REAL, BLOB)

```csharp
[ColumnInfo(TypeAffinity = "INTEGER")]
public DateTime CreatedAt { get; set; }

[ColumnInfo(Name = "updated_at")]
public DateTime? UpdatedAt { get; set; }
```

### `[Index]`

Create database indexes for improved query performance.

**Properties:**
- `Value` - Array of column names to index
- `Unique` - Create a unique index (default: false)

```csharp
[Entity(TableName = "users")]
[Index(Value = ["Email"], Unique = true)]
[Index(Value = ["CreatedAt"])]
public class User
{
    // properties...
}
```

### `[Unique]`

Mark a column as unique.

```csharp
[Unique]
public required string Email { get; set; }
```

### `[ForeignKey]`

Define foreign key relationships.

**Properties:**
- `Entity` - Referenced entity type
- `OnDelete` - Foreign key delete action
- `OnUpdate` - Foreign key update action

```csharp
[Entity(TableName = "todos")]
public class Todo
{
    [PrimaryKey(AutoGenerate = true)]
    public long Id { get; set; }

    [ForeignKey(Entity = typeof(TodoList), OnDelete = ForeignKeyAction.Cascade)]
    public long ListId { get; set; }
    
    public required string Title { get; set; }
}
```

### `[Ignore]`

Exclude a property from database mapping.

```csharp
[Ignore]
public string TemporaryField { get; set; }
```

## Complete Example

Here is a comprehensive entity with multiple attributes:

```csharp
using RoomSharp.Attributes;

[Entity(TableName = "todo_lists")]
[Index(Value = ["Name"], Unique = true)]
public class TodoList
{
    [PrimaryKey(AutoGenerate = true)]
    public long Id { get; set; }

    public required string Name { get; set; }
    
    public string? Description { get; set; }

    [ColumnInfo(TypeAffinity = "INTEGER")]
    public DateTime CreatedAt { get; set; }

    [ColumnInfo(Name = "updated_at")]
    public DateTime? UpdatedAt { get; set; }
    
    [Ignore]
    public int TodoCount { get; set; } // Computed, not stored
}
```

## Database Views

RoomSharp supports database views via `[DatabaseView]`:

```csharp
[DatabaseView(ViewName = "completed_todos_view")]
public class CompletedTodoView
{
    public long Id { get; set; }
    public string Title { get; set; }
    public string ListName { get; set; }
    public DateTime CompletedAt { get; set; }
}
```

> **Tip:** Views are read-only projections. Keep the shape aligned with your query output.

## Best Practices

- Use the `required` keyword for non-nullable reference properties (C# 11+).
- Add `[Index]` to frequently queried columns.
- Apply `[ColumnInfo]` for explicit SQLite type affinity.
- Select foreign key actions (`Cascade`, `SetNull`, etc.) intentionally.
- Choose meaningful table and column names for readable SQL.

## Type Mapping

RoomSharp automatically maps C# types to database types:

| C# Type | SQLite Type | Notes |
|---------|-------------|-------|
| `int`, `long`, `short` | INTEGER | Numeric types |
| `string` | TEXT | Text data |
| `double`, `float`, `decimal` | REAL | Floating point |
| `byte[]` | BLOB | Binary data |
| `DateTime` | INTEGER | Stored as Unix ticks |
| `bool` | INTEGER | 0 or 1 |
| `Guid` | TEXT | String representation |

## Next Steps

Keep exploring RoomSharp:

- [DAO Interfaces](/docs/v0.4.7/dao-interfaces) - Define data access methods.
- [Type Converters](/docs/v0.4.7/type-converters) - Handle custom types.
- [Query API](/docs/v0.4.7/query-api) - Write queries for your entities.