Use this skill when you are tasked with using a pre-populated SQLite database
asset that originated from an iOS application (Core Data or SwiftData). Room's
createFromAsset is extremely strict about schema parity, and Core Data's
SQLite format has several idiosyncrasies that differ from standard Room entity
generation.
0. Choose a Seeding Strategy BEFORE Writing Entities
A schema mismatch between a pre-packaged asset and your @Entity classes
compiles cleanly and only fails at runtime, on first database access, with
IllegalStateException: Pre-packaged database has an invalid schema: <TABLE>(<Entity>).
In most migration environments you have no device or emulator, so you will
never see this crash yourself; it will surface as an app stuck on its first
screen.
Pick exactly one strategy:
| Strategy | When to use | Risk |
|---|---|---|
A. RoomDatabase.Callback seeding (default) |
Your entities use clean Android names (items, id, name, …) — the normal case for an idiomatic port. |
None: Room creates the schema itself; you insert seed rows via DAOs in onCreate(). |
B. createFromAsset() with a Room-generated asset |
Large catalogs where runtime inserts are too slow. | Low, if the asset is generated from Room's exported schema (room { schemaDirectory("$projectDir/schemas") } → app/schemas/<Db>/<version>.json) and populated with data transformed from the iOS file. |
C. createFromAsset() with the original iOS .sqlite |
Only when entities intentionally mirror the Core Data file 1:1 (Z* tables/columns, Z_PK, Z_ENT, Z_OPT, exact types/nullability/indices — see §3). |
High. Never combine clean Android entity definitions with a verbatim copy of the iOS file, and never "fix" it by just adding tables to the copied file. |
Mandatory no-device verification for B or C — add a JVM unit test that
forces Room to open (and therefore validate) the pre-packaged database, and run
it with ./gradlew testDebugUnitTest:
@RunWith(RobolectricTestRunner::class)
class PrepackagedDatabaseSchemaTest {
@Test fun prepackagedAssetMatchesRoomSchema() {
val ctx = ApplicationProvider.getApplicationContext<Context>()
val db = Room.databaseBuilder(ctx, AppDatabase::class.java, "schema-check.db")
.createFromAsset("prepopulated.sqlite")
.allowMainThreadQueries()
.build()
db.openHelper.writableDatabase // throws if the asset schema is invalid
db.close()
}
}
If this test fails, read the Expected: / Found: TableInfo diff in the
failure message and apply §2–§3, or switch to Strategy A.
1. Identification
You are likely dealing with a Core Data/SwiftData export if:
- Table names typically start with
Z(e.g.,ZUSER,ZITEM). - Column names are typically all uppercase and start with
Z(e.g.,ZNAME,ZCREATEDAT). - Tables contain technical columns like
Z_PK(Primary Key),Z_ENT(Entity ID), andZ_OPT(Optimistic Locking). - Column types in the SQLite asset are often
VARCHARinstead ofTEXT.
2. Mandatory Diagnostic Workflow
If the schema verification test in §0 fails, or the app crashes on launch with
java.lang.IllegalStateException: Pre-packaged database has an invalid schema,
you MUST follow these steps:
- Read the failure: Use the unit test failure message from §0, or
adb logcat -d/ theread_logcattool if a device is available. - Locate TableInfo Discrepancy: Search for the text
Expected:andFound:. - Compare Schemas Item-by-Item: Room compares the
TableInfoobject it generated from your@Entityclass (Expected) against what it actually read from the database file (Found). Identify every discrepancy in theFoundsection regarding:- Column names
- Column types (e.g.,
TEXTvsVARCHAR) - Nullability (
notNullflag) - Primary Key position and nullability
- Index names and column lists
3. Generic Entity Mapping Rules
Mapping Column Names
Always use the @ColumnInfo(name = "...") annotation to match the exact column
name found in the SQLite asset. Do not rely on Kotlin field name mapping.
kotlin
@ColumnInfo(name = "ZACTUAL_COLUMN_NAME")
val propertyName: String?
Strict Nullability Parity for Columns
Core Data SQLite exports often define columns as nullable even if they are non-optional in the iOS code.
- If the
Foundschema in logcat saysnotNull = 'false'for a non-primary-key column, the Kotlin property MUST be nullable (e.g.,String?,Int?).
Primary Key Non-Nullability (KSP Constraint)
Room's compiler (KSP/KAPT) strictly enforces that all @PrimaryKey properties
in Kotlin must be non-nullable (e.g., String, Int).
- Critical: Even if the SQLite asset schema defines the primary key column
as nullable (
notNull = 'false') or if the iOS source had it optional, you MUST declare it as non-nullable in Kotlin:kotlin @PrimaryKey @ColumnInfo(name = "Z_PK") val pk: Int // Must NOT be Int? - Schema Validation Pass: Declaring a nullable SQLite primary key as non-nullable in Kotlin Room generally passes Room's runtime validation because Room treats primary keys as implicitly non-null at the database level.
- Default Values: If you need to instantiate the entity in Kotlin code
before it is inserted (and before the DB generates the ID), provide a safe
non-null default value (e.g.,
val id: String = UUID.randomUUID().toString()orval pk: Int = 0).
Technical Metadata Columns
You must include the technical columns required by Core Data if they are present
in the Found schema. These are usually:
Z_PK: The Primary Key (Integer, must be non-nullable).Z_ENT: The Entity identifier (Integer, nullable).Z_OPT: The record version for optimistic locking (Integer, nullable).
@PrimaryKey
@ColumnInfo(name = "Z_PK")
val pk: Int, // Non-nullable primary key
@ColumnInfo(name = "Z_ENT")
val ent: Int?,
@ColumnInfo(name = "Z_OPT")
val opt: Int?
Type Affinity mapping
Common mappings from Core Data SQLite types to Room/Kotlin:
VARCHARorTEXT->StringINTEGER->Int,Long, orBoolean(Note: Core Data uses0and1for Booleans).REAL,DOUBLE,FLOAT->DoubleTIMESTAMP->Long(Core Data uses "Mac Absolute Time": seconds since Jan 1, 2001).
Index Replication
If the Found schema contains indices, you must replicate them exactly in the
@Entity annotation using the Index class. The name and value (columns)
must match the asset exactly.
kotlin
@Entity(
tableName = "ZENTITY_NAME",
indices = [
Index(value = ["ZCOLUMN_NAME"], name = "Z_Index_Name_From_Asset", unique = true)
]
)
4. Architectural Implementation
Since Core Data migrations often force entities to use nullable types for many non-primary-key columns, you must handle this cleanly in your architecture:
Repository/Mapper Layer
Do not let nullable database models leak into your UI or Business Logic layers.
Use a dedicated Mapper layer to convert nullable Room Entities into robust,
non-nullable Domain models using the Elvis operator (?:) to provide safe
defaults:
fun StationEntity.toDomain() = Station(
id = sourceID, // Primary key is guaranteed non-null
name = name ?: "Unknown Station", // Handle nullable column safely
coordinate = Coordinate(
latitude = latitude ?: 0.0,
longitude = longitude ?: 0.0
)
)
Filtering Data
When querying flows from the database, filter out invalid or incomplete records
at the repository layer before exposing them:
kotlin
fun getValidStations(): Flow<List<Station>> {
return transitDao.getStationsFlow().map { entities ->
entities.mapNotNull { entity ->
if (entity.name == null) null else entity.toDomain()
}
}
}
5. Success Criteria
- The app launches without
IllegalStateException. - Data is successfully fetched via DAOs and displayed in the UI.
- All technical columns required by the asset schema are accounted for in the entity definitions.
6. Verification Checklist
Before completing any database migration task, the developer and auditor MUST run through this checklist:
- [ ] Primary Key Non-Nullability: Are all
@PrimaryKeyfields in all@Entityclasses declared as non-nullable Kotlin types (e.g.,String,Intinstead ofString?,Int?)? - [ ] KSP Annotations: If using KSP, are primary keys verified to not have nullability warnings?
- [ ] Mapping Completeness: Are all technical metadata columns (like
Z_PK,Z_ENT,Z_OPTif Core Data, or equivalent) mapped correctly? - [ ] Elvis Fallbacks: Do all Mappers use Elvis operators (
?:) to handle nullable database columns and preventNullPointerExceptionwhen building Domain models? - [ ] Unit Tests: Are there unit tests verifying the Mapper logic with mock nullable Entity data?