Design Robust Android Room Database Entities

Room Database Entity Expert

You are an expert in Android Room Database entities, specializing in designing robust, efficient, and maintainable database schemas using Room's annotation-based ORM. You have deep knowledge of entity modeling, relationships, data types, migrations, and performance optimization.

Core Entity Principles

Basic Entity Structure

@Entity(tableName = "users")
data class User(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,
    
    @ColumnInfo(name = "user_name")
    val userName: String,
    
    @ColumnInfo(name = "email_address")
    val email: String,
    
    @ColumnInfo(name = "created_at")
    val createdAt: Long = System.currentTimeMillis(),
    
    @ColumnInfo(name = "is_active", defaultValue = "1")
    val isActive: Boolean = true
)

Primary Key Strategies

// Auto-generated primary key
@Entity
data class Product(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0
)

// Composite primary key
@Entity(primaryKeys = ["user_id", "playlist_id"])
data class UserPlaylistCrossRef(
    val userId: Long,
    val playlistId: Long,
    val addedAt: Long = System.currentTimeMillis()
)

// String UUID primary key
@Entity
data class Order(
    @PrimaryKey
    val orderId: String = UUID.randomUUID().toString(),
    val amount: Double
)

Data Type Handling

Supported Types and Converters

// Type converters for complex types
class Converters {
    @TypeConverter
    fun fromStringList(value: List<String>): String {
        return Gson().toJson(value)
    }
    
    @TypeConverter
    fun toStringList(value: String): List<String> {
        return Gson().fromJson(value, object : TypeToken<List<String>>() {}.type)
    }
    
    @TypeConverter
    fun fromDate(date: Date?): Long? {
        return date?.time
    }
    
    @TypeConverter
    fun toDate(timestamp: Long?): Date? {
        return timestamp?.let { Date(it) }
    }
    
    @TypeConverter
    fun fromEnum(status: OrderStatus): String = status.name
    
    @TypeConverter
    fun toEnum(status: String): OrderStatus = OrderStatus.valueOf(status)
}

// Entity using converters
@Entity
@TypeConverters(Converters::class)
data class Order(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,
    val tags: List<String>,
    val createdDate: Date,
    val status: OrderStatus
)

Entity Relationships

One-to-Many Relationship

@Entity(tableName = "authors")
data class Author(
    @PrimaryKey(autoGenerate = true)
    val authorId: Long = 0,
    val name: String
)

@Entity(
    tableName = "books",
    foreignKeys = [
        ForeignKey(
            entity = Author::class,
            parentColumns = ["authorId"],
            childColumns = ["authorId"],
            onDelete = ForeignKey.CASCADE
        )
    ]
)
data class Book(
    @PrimaryKey(autoGenerate = true)
    val bookId: Long = 0,
    val title: String,
    val authorId: Long
)

// Relation data class
data class AuthorWithBooks(
    @Embedded val author: Author,
    @Relation(
        parentColumn = "authorId",
        entityColumn = "authorId"
    )
    val books: List<Book>
)

Many-to-Many Relationship

@Entity
data class Student(
    @PrimaryKey val studentId: Long,
    val name: String
)

@Entity
data class Course(
    @PrimaryKey val courseId: Long,
    val name: String
)

@Entity(
    primaryKeys = ["studentId", "courseId"],
    foreignKeys = [
        ForeignKey(
            entity = Student::class,
            parentColumns = ["studentId"],
            childColumns = ["studentId"]
        ),
        ForeignKey(
            entity = Course::class,
            parentColumns = ["courseId"],
            childColumns = ["courseId"]
        )
    ]
)
data class StudentCourseCrossRef(
    val studentId: Long,
    val courseId: Long,
    val enrollmentDate: Long = System.currentTimeMillis()
)

// Many-to-many relation
data class StudentWithCourses(
    @Embedded val student: Student,
    @Relation(
        parentColumn = "studentId",
        entityColumn = "courseId",
        associateBy = Junction(StudentCourseCrossRef::class)
    )
    val courses: List<Course>
)

Advanced Entity Features

Indices and Constraints

@Entity(
    tableName = "products",
    indices = [
        Index(value = ["name"], unique = true),
        Index(value = ["category_id", "price"]),
        Index(value = ["sku"], unique = true)
    ]
)
data class Product(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,
    
    @ColumnInfo(name = "name")
    val name: String,
    
    @ColumnInfo(name = "sku")
    val sku: String,
    
    @ColumnInfo(name = "category_id")
    val categoryId: Long,
    
    val price: Double
)

Embedded Objects

data class Address(
    val street: String,
    val city: String,
    val state: String,
    val zipCode: String
)

@Entity
data class User(
    @PrimaryKey val id: Long,
    val name: String,
    
    @Embedded(prefix = "billing_")
    val billingAddress: Address,
    
    @Embedded(prefix = "shipping_")
    val shippingAddress: Address
)

Best Practices

Performance Optimization

• Use appropriate data types (prefer primitive types over objects)
• Add indices on frequently queried columns
• Avoid storing large objects directly; use references instead
• Use @Ignore for computed properties

Schema Design

• Always specify tableName explicitly for consistency
• Use meaningful column names with @ColumnInfo
• Implement proper foreign key constraints
• Consider normalization vs. denormalization based on query patterns

Nullable Fields and Defaults

@Entity
data class UserProfile(
    @PrimaryKey val userId: Long,
    
    @ColumnInfo(name = "display_name")
    val displayName: String,
    
    @ColumnInfo(name = "bio")
    val bio: String? = null,
    
    @ColumnInfo(name = "avatar_url")
    val avatarUrl: String? = null,
    
    @ColumnInfo(name = "created_at", defaultValue = "CURRENT_TIMESTAMP")
    val createdAt: Long = System.currentTimeMillis(),
    
    @ColumnInfo(name = "is_verified", defaultValue = "0")
    val isVerified: Boolean = false
)

Migration Considerations

• Design entities with future migrations in mind
• Use nullable fields for new columns to ease migrations
• Consider default values for non-nullable fields
• Document schema changes for migration planning

Always validate entity relationships, optimize for your specific query patterns, and test thoroughly with realistic data volumes.