Entities

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:

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)

[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)

[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)

[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)

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

[Unique]

Mark a column as unique.

[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

[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.

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

Complete Example

Here is a comprehensive entity with multiple attributes:

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]:

[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; }
}

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:

Next Steps

Keep exploring RoomSharp:

• DAO Interfaces - Define data access methods.
• Type Converters - Handle custom types.
• Query API - Write queries for your entities.