Skip to main content

Enforce naming conventions for Prisma using Atlas

Prisma models are typically named using PascalCase and camelCase conventions. By default, Prisma creates tables and columns in the database using the same names as the models and fields in the schema.

However, you may want to use a different naming convention for your database schema (lowercase, snake_case, etc).

In such cases, you can use Atlas to enforce naming conventions for your schema, ensuring consistency across your database schema and Prisma models.

Providing custom names for tables and columns with Prisma

Prisma allows you to provide custom names for tables and columns using the @map and @@map directives.

For example, you can define a custom name for a table or column as follows:

prisma/schema.prisma
model Comment {
id Int @id @default(autoincrement())
content String @map("comment_text")
email String @map("commenter_email")

@@map("comments")
}

In this example, the Comment model is mapped to a table named comments in the database. The content field is mapped to a column named comment_text, and the email field is mapped to a column named commenter_email.

Enforcing naming conventions with Atlas

Atlas allows you to enforce naming conventions for your schema using the lint block in the atlas.hcl configuration file.

In this example, we will enforce a naming convention that requires all table and column names to be in lowercase letters.

The lint rule will look like this:

atlas.hcl
env "local" {
// .. other configurations
lint {
review = WARNING
naming {
error = true
match = "^[a-z_]+$" # regex to match lowercase letters
message = "must be lowercase letters" # message to return if a violation is found
}
}
}

Atlas considers this rule whenever you run atlas migrate lint or atlas schema apply (which includes linting as part of the process, for users with a Pro subscription).

Getting started with Atlas and Prisma

To set up, follow along the getting started guide for Prisma and Atlas.

Project Setup

Prisma Schema

Assume we have the following Prisma schema.prisma file:

prisma/schema.prisma
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
}

model Comment {
id Int @id @default(autoincrement())
content String @map("comment_text")
email String @map("commenter_email")
}

@map and @@map allow you to tune the shape of your Prisma Client API by decoupling model and field names from table and column names in the underlying database.

Config File

Before we begin testing, create a config file named atlas.hcl.

In this file we will create an environment, specify the source of our schema, and a URL for our dev database.

atlas.hcl
data "external_schema" "prisma" {
program = [
"npx",
"prisma",
"migrate",
"diff",
"--from-empty",
"--to-schema-datamodel",
"prisma/schema.prisma",
"--script"
]
}

env "local" {
url = getenv("DATABASE_URL")
src = data.external_schema.prisma.url
dev = "docker://postgres/16/dev?search_path=public"
lint {
review = WARNING
naming {
error = true
match = "^[a-z_]+$" # regex to match lowercase letters
message = "must be lowercase letters" # message to return if a violation is found
}
}
}

Lint Naming

When you run atlas schema apply, Atlas will lint the schema against the naming conventions you have defined in the atlas.hcl file.

atlas schema apply --env local

If the schema violates the naming conventions, Atlas will add a diagnostic to the plan and prompt you to approve or abort the plan.

Planning migration statements (1 in total):

-- create "comment" table:
-> CREATE TABLE "Comment" (
"id" serial NOT NULL,
"comment_text" text NOT NULL,
"commenter_email" text NOT NULL,
PRIMARY KEY ("id")
);

-------------------------------------------

Analyzing planned statements (1 in total):

-- naming violations detected:
-- L2: Table named "Comment" violates the naming policy: must be lowercase letters
https://atlasgo.io/lint/analyzers#NM102

-------------------------
-- 21.797708ms
-- 1 schema change
-- 1 diagnostic

-------------------------------------------

? Approve or abort the plan:
▸ Approve and apply
Abort

To fix the violation, update the schema to match the naming convention and re-run atlas schema apply.

prisma/schema.prisma
model Comment {
id Int @id @default(autoincrement())
content String @map("comment_text")
email String @map("commenter_email")
@@map("comments")
}

Then, re-run atlas schema apply, and the schema will be applied successfully.

atlas schema apply --env local
Planning migration statements (1 in total):

-- create "comments" table:
-> CREATE TABLE "comments" (
"id" serial NOT NULL,
"comment_text" text NOT NULL,
"commenter_email" text NOT NULL,
PRIMARY KEY ("id")
);

-------------------------------------------

Analyzing planned statements (1 in total):

-- no diagnostics found

-------------------------
-- 30.21ms
-- 1 schema change

-------------------------------------------

Approved by review policy: no errors or warnings were found.

-------------------------------------------

Applying approved migration (1 statement in total):

-- create "comments" table
-> CREATE TABLE "comments" (
"id" serial NOT NULL,
"comment_text" text NOT NULL,
"commenter_email" text NOT NULL,
PRIMARY KEY ("id")
);
-- ok (2.331333ms)

-------------------------
-- 2.360041ms
-- 1 migration
-- 1 sql statement

Conclusion

Atlas allows you to enforce naming conventions for your schema, ensuring consistency across your database schema and Prisma models. This can help prevent errors and make it easier to maintain your database schema as your application grows.