Upload Schema Conversion Explained

This page explains the technical details of Prisma schema conversion within Amplication. For a practical guide on uploading your schema, see How to Upload Schema.

When you upload your DB Schema into Amplication, you are initiating a process that transforms your schema into Amplication’s internal entity model. This page dives deep into how Amplication converts your Prisma database schema into Amplication’s internal structure.

The 3-Step Conversion Process

During the schema upload, you’ll see logs detailing a three-phase conversion process:

Validate: Ensuring Schema Integrity

The first step validates the syntax and structure of your schema.prisma file against Prisma’s conventions. This ensures your schema is well-formed and ready for conversion. Crucially, it also checks for the presence of models – the building blocks of your services. Without models, the conversion process cannot proceed, ensuring a valid starting point.

This validation step is your first line of defense against schema errors, preventing issues down the line and ensuring a smooth import process.

Prepare: Aligning with Amplication's Standards

The preparation phase standardizes your schema, applying five key transformations to ensure consistency and maintainability across all services generated by Amplication. This step is critical for platform teams aiming to enforce organizational standards and reduce technical drift.These transformations include:

Model Names: Standardizing to PascalCase, singular, and no underscores.
Field Names: Standardizing to camelCase and no underscores.
Field Types: Ensuring consistent type references between models.
Model IDs: Simplifying primary key definitions for clarity and consistency.
Model ID Field: Guaranteeing a standardized id field for each entity.

Convert: Optimizing Data Types for Amplication

In the final conversion step, Prisma’s data types are mapped to Amplication’s internal data types. This ensures optimal performance and functionality within Amplication’s service generation framework. This mapping includes handling specific DateTime attributes for CreatedAt and UpdatedAt fields, and translating Prisma’s type system to Amplication’s more abstract types like Lookup for relations and OptionSet for Enums.This step ensures that your database schema is not just imported, but intelligently adapted to Amplication’s architecture, maximizing efficiency and developer experience.

Step 1: Validate - First Pass Schema Check

This step acts as an initial quality gate, confirming that your schema.prisma is syntactically correct and contains the essential elements – models – necessary for Amplication to build upon. This quick check prevents wasted time and ensures the conversion process begins with a valid schema.

Step 2: Prepare - Standardizing for Consistency and Maintainability

This phase is where Amplication’s conversion happens. By applying these five operations, Amplication ensures that all generated services adhere to consistent naming conventions and structural patterns.

Model Names: PascalCase, Singular, No Underscores

Amplication enforces PascalCase, singular, and underscore-free naming conventions for models. This standardization is vital for code readability and maintainability, especially across large teams and numerous services.To maintain database compatibility and prevent data loss, Amplication intelligently uses Prisma’s @@map attribute. If your original model name deviates from Amplication’s conventions, @@map is automatically added, preserving the original database table name while using the standardized name within Amplication.

If you have already used @@map attributes in your schema, Amplication respects your existing mappings and does not overwrite them.

Example:

schema.prisma

-model course_rating
+model CourseRating {
  id        String    @id @default(cuid())
  createdAt DateTime  @default(now())
  updatedAt DateTime  @updatedAt
  rating    Int

+@@map("course_rating")
}

This ensures that while your Amplication service code uses CourseRating, the underlying database table remains course_rating, preventing any disruption to existing data or systems.

Field Names: camelCase, No Underscores

Similar to model names, field names are standardized to camelCase and must be underscore-free. This consistency improves code readability and reduces cognitive load for developers working across different services.Just like with model names, Amplication uses Prisma’s @map attribute to preserve your original database column names when necessary. This ensures seamless integration with existing databases and prevents unexpected data mapping issues.

Existing @map attributes on fields are also respected and not overwritten during this process.

Example:

schema.prisma

model Product {
  id          String   @id @default(cuid())
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  name        String?
-item_price  Float?
+itemPrice   Float?    @map("item_price")
  description String?
  orders      Order[]
}

Here, item_price is converted to itemPrice in your Amplication service, while the @map("item_price") attribute ensures the database column remains item_price.

Field Types: Ensuring Model Relationships

This operation focuses on ensuring that field types accurately reflect relationships between models. When you import a schema, especially from an introspected database, Prisma might use generic model names in relation fields. Amplication refines these to use the standardized, PascalCase model names established in the previous step.Example:

schema.prisma

-model products
+model Product {
  id          String   @id @default(cuid())
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  name        String?
  itemPrice   Float?
  description String?
- orders      orders[]
+ orders      Order[]
}

-model orders
+model Order {
  id         String    @id @default(cuid())
  createdAt  DateTime  @default(now())
  updatedAt  DateTime  @updatedAt
  totalPrice Int?
- product    products?  @relation(fields: [productId], references: [id])
+ product    Product?  @relation(fields: [productId], references: [id])
  productId  String?
}

Here, products and orders are corrected to Product and Order respectively, ensuring the relationship is clearly defined and consistent with Amplication’s model naming standards.

Model IDs: Simplifying Primary Keys

Amplication standardizes the way primary keys are defined in your schema. It simplifies the @@id attribute, which in Prisma can define composite IDs, to focus on single-field primary keys, which aligns with Amplication’s entity structure.

Composite IDs (@@id([field1, field2])) are currently not fully supported in Amplication.

This operation performs several key transformations:

@@id([field]) is converted to @@unique([field]). The original @@id is replaced with a @@unique constraint to maintain uniqueness in the database.
The field originally designated as the primary key via @@id now becomes the actual ID field within Amplication. The @id attribute is added to this field.
If the field lacks a @default() attribute (like cuid() for String IDs or autoincrement() for Int IDs), Amplication adds one based on the field’s type. This ensures every entity has a properly configured default ID generation strategy.
If the primary key field isn’t named “id”, it’s renamed to “id”, and a @map attribute is added to preserve the original field name in the database.
Finally, the @@unique attribute is updated to reference the new “id” field: @@unique([originalFieldName]) becomes @@unique([id]).

Example:

schema.prisma

model DomainUnit {
+ id   String @id @default(cuid()) @map("domainId")
- domainId String
  unitId   String

- @@id([domainId])
+ @@unique([id])
}

This ensures a consistent and predictable ID structure across all entities in Amplication.

Model ID Field: Ensuring a Standard 'id' Field

The final preparation step guarantees that every model has a standardized id field. This is a fundamental principle in Amplication, ensuring consistent entity identification across your services.This operation handles two main scenarios:

Non-ID fields named ‘id’: If a field is named id but isn’t an ID field (doesn’t have the @id attribute), it’s renamed to ${modelName}Id to avoid naming conflicts with the actual ID field that Amplication will ensure exists. A @map attribute is added to preserve the original name in the database.
ID fields with different names: If an ID field (with the @id attribute) has a name other than id, it’s renamed to id. Again, a @map attribute is used to maintain the original field name in the database.

Example:

schema.prisma

model RandomName {
- randomId         Int     @id
+ id                Int     @id @map("randomId")
- id               Int?
+ randomNameId      Int?    @map("id")
  fullName          String
}

This operation ensures that every Amplication entity has a clearly defined and consistently named id field, simplifying data access and relationships within your services.

Step 3: Convert - Mapping Prisma Types to Amplication Data Types

The final conversion step maps Prisma’s data types to Amplication’s internal data types, optimizing them for service generation and functionality within the Amplication ecosystem. This step ensures that your data is represented in a way that best leverages Amplication’s features and capabilities. Here’s a table summarizing the Prisma to Amplication data type conversions:

Prisma	Amplication	Description
`String` (ID)	`Id`	Converts ID fields with `String` type to Amplication `Id` type, defaulting to `cuid()` for ID generation.
`Int` (ID)	`Id (autoincrement)`	Converts ID fields with `Int` type to Amplication `Id` type, using `autoincrement()` for ID generation.
`Boolean`	`Boolean`	Direct mapping for Boolean types.
`DateTime` (`@default(now())`)	`CreatedAt`	`DateTime` fields with `@default(now())` are converted to Amplication’s specialized `CreatedAt` type.
`DateTime` (`@updatedAt`)	`UpdatedAt`	`DateTime` fields with `@updatedAt` are converted to Amplication’s specialized `UpdatedAt` type.
`DateTime`	`DateTime`	Plain `DateTime` fields remain as `DateTime` in Amplication.
`Float`, `Decimal`	`Decimal Number`	Prisma’s `Float` and `Decimal` types are converted to Amplication’s `Decimal Number` type.
`Int`, `BigInt`	`WholeNumber`	Prisma’s `Int` and `BigInt` types are converted to Amplication’s `WholeNumber` type.
`String`	`SingleLineText`	Standard `String` fields are converted to Amplication’s `SingleLineText` type, suitable for short text inputs.
`Json`	`Json`	`Json` types are directly equivalent.
`Enum`	`OptionSet`	Prisma `Enum` types are converted to Amplication’s `OptionSet`, providing structured choice options.
`Enum[]`	`MultiSelectOptionSet`	Prisma `Enum[]` arrays are converted to `MultiSelectOptionSet`, allowing multiple selections from options.
Model relation	`Lookup`	Relations to other models are converted to Amplication’s `Lookup` type, establishing entity relationships.

Common `Id` Field Conversion Scenarios

The id field is central to Amplication’s entity model, and its conversion requires careful handling. Here are common scenarios you might encounter:

Scenario 1: Existing @default Attribute on 'id' Field

If your id field already has a @default attribute, Amplication removes it. This is because Amplication automatically adds a @default attribute that aligns with the id type (e.g., cuid() or autoincrement()) during conversion. Having multiple @default attributes is invalid in Prisma schema.Example:

// Original model (After Introspection)
model User {
  id Int @default(0)
  name String
}

// After Importing Into Amplication
model User {
  id Int @default(autoincrement())
  name String
}

Scenario 2: Model Without a Suitable 'id' Field

If a model lacks a field that can serve as the id, Amplication proactively adds an id field. This ensures every entity in Amplication has a clearly defined primary identifier. The added id field is of type String and defaults to cuid() for generating unique IDs.Example:

// Original model (After Introspection)
model Product {
  price Decimal @unique
  name String
}

// After Importing Into Amplication
model Product {
  id String @id @default(cuid())
  price Decimal @unique
  name String
}

Scenario 3: Multiple Unique Fields, One Named 'id'

If multiple fields could potentially become the id field (e.g., multiple @unique fields), and one of them is already named id, Amplication prioritizes the field named id. This field is then designated as the primary @id and configured with an appropriate @default attribute (like autoincrement() for Int types).Example:

// Original Model (After Introspection)
model User {
  email String @unique
  name String @unique
  id Int @unique
}

// After Importing Into Amplication
model User {
  email String @unique
  name String @unique
  id Int @unique @id @default(autoincrement())
}

Scenario 4: No Unique Field Named 'id'

In cases where no unique field is named id, Amplication selects a unique field (often the first one encountered) and renames it to id. To maintain database integrity, a @map attribute is added, mapping the new id field back to its original name in the database.Example:

// Original Model (After Introspection)
model User {
  email String @unique
  name String @unique
  username Int @unique
}

// After Importing Into Amplication
model User {
  id String @unique @map("email")
  name String @unique
  username Int @unique
}

Log Warnings: Addressing Potential Issues

During schema processing, Amplication provides logs, including (Info) and (Warning) messages. While the schema will still process with warnings, it’s crucial to review them. Warnings indicate potential discrepancies or areas where the conversion might not perfectly align with your original schema’s intent. Addressing warnings proactively can prevent unexpected behavior in your generated services.

Here are the most common warning scenarios you might encounter and how to address them:

Custom Attributes on Enum Keys

Composite IDs on Models

Conclusion

By understanding how Amplication converts your Prisma schema, you gain valuable insight into how Amplication helps you establish and maintain a standardized data model. Review the conversion logs after uploading your schema and explore your newly created entities in Amplication’s ERD view.

Upload Your Schema

Learn how to upload your Prisma schema to Amplication and jumpstart your service development.

Customize Your Entities

Discover how to further customize your entities and fields within Amplication after schema import.

Day One

Self-Serve Resource Creation

Accelerate with AI

Resource Configuration

Install & Configure Plugins

Model Data

Define APIs & DTOs

Manage Authentication & Roles

Generate Code

Upload Schema Conversion Explained

The 3-Step Conversion Process

Step 1: Validate - First Pass Schema Check

Step 2: Prepare - Standardizing for Consistency and Maintainability

Step 3: Convert - Mapping Prisma Types to Amplication Data Types

Common `Id` Field Conversion Scenarios

Log Warnings: Addressing Potential Issues

Conclusion

Upload Your Schema

Customize Your Entities

Day One

Self-Serve Resource Creation

Accelerate with AI

Resource Configuration

Install & Configure Plugins

Model Data

Define APIs & DTOs

Manage Authentication & Roles

Generate Code

​The 3-Step Conversion Process

​Step 1: Validate - First Pass Schema Check

​Step 2: Prepare - Standardizing for Consistency and Maintainability

​Step 3: Convert - Mapping Prisma Types to Amplication Data Types

​Common Id Field Conversion Scenarios

​Log Warnings: Addressing Potential Issues

​Conclusion

Upload Your Schema

Customize Your Entities

The 3-Step Conversion Process

Step 1: Validate - First Pass Schema Check

Step 2: Prepare - Standardizing for Consistency and Maintainability

Step 3: Convert - Mapping Prisma Types to Amplication Data Types

Common `Id` Field Conversion Scenarios

Log Warnings: Addressing Potential Issues

Conclusion