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