Connection URLs
Prisma ORM needs a connection URL to be able to connect to your database, e.g. when sending queries with Prisma Client or when changing the database schema with Prisma Migrate.
The connection URL is provided via the url
field of a datasource
block in your Prisma schema. It usually consists of the following components (except for SQLite and Prisma Postgres):
- User: The name of your database user
- Password: The password for your database user
- Host: The IP or domain name of the machine where your database server is running
- Port: The port on which your database server is running
- Database name: The name of the database you want to use
Make sure you have this information at hand when getting started with Prisma ORM. If you don't have a database server running yet, you can either use a local SQLite database file (see the Quickstart) or setup a free PostgreSQL database with Prisma Postgres.
Format
The format of the connection URL depends on the database connector you're using. Prisma ORM generally supports the standard formats for each database. You can find out more about the connection URL of your database on the dedicated docs page:
Special characters
For MySQL, PostgreSQL and CockroachDB you must percentage-encode special characters in any part of your connection URL - including passwords. For example, p@$$w0rd
becomes p%40%24%24w0rd
.
For Microsoft SQL Server, you must escape special characters in any part of your connection string.
Examples
Here are examples for the connection URLs of the databases Prisma ORM supports:
Prisma Postgres
Prisma Postgres is a managed PostgreSQL service running on unikernels. There are several ways to connect to Prisma Postgres:
- via direct TCP connections (lets you connect via any ORM or database tool)
- via Prisma Accelerate (only supported with Prisma ORM)
- locally
The connection string formats of these are covered below.
Direct TCP
When you connect to Prisma Postgres via direct TCP, your connection string looks as follows:
DATABASE_URL="postgres://USER:PASSWORD@postgres.prisma-data.net:5432/?sslmode=require"
The USER
and PASSWORD
values are provided when you generate credentials for your Prisma Postgres instance in the . Here is an example with sample values:
DATABASE_URL="postgres://2f9881cc7eef46f094ac913df34c1fb441502fe66cbe28cc48998d4e6b20336b:sk_QZ3u8fMPFfBzOID4ol-mV@postgres.prisma-data.net:5432/?sslmode=require"
Via Prisma Accelerate (HTTP)
When connecting via Prisma Accelerate, the connection string doesn't require a user/password like a conventional connection string does. Instead, authentication works via an API key:
datasource db {
provider = "postgresql"
url = "prisma+postgres://accelerate.prisma-data.net/?api_key=API_KEY"
}
In this snippet, API_KEY
is a placeholder for the API key you are receiving when setting up a new Prismas Postgres instance via the . Here is an example for what a real connection URL to Prisma Postgres may look like:
datasource db {
provider = "postgresql"
url = "prisma+postgres://accelerate.prisma-data.net/?api_key=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcGlfa2V5IjoiMGNkZTFlMjQtNzhiYi00NTY4LTkyM2EtNWUwOTEzZWUyNjU1IiwidGVuYW50X2lkIjoiNzEyZWRlZTc1Y2U2MDk2ZjI4NDg3YjE4NWMyYzA2OTNhNGMxNzJkMjhhOWFlNGUwZTYxNWE4NWIxZWY1YjBkMCIsImludGVybmFsX3NlY3JldCI6IjA4MzQ2Y2RlLWI5ZjktNDQ4Yy04NThmLTMxNjg4ODEzNmEzZCJ9.N1Za6q6NfInzHvRkud6Ojt_-RFg18a0601vdYWGKOrk"
}
Local Prisma Postgres
The connection string for connecting to a local Prisma Postgres instance mirrors the structure of a remote instance via Accelerate:
datasource db {
provider = "postgresql"
url = "prisma+postgres://accelerate.prisma-data.net/?api_key=API_KEY"
}
However, in this case the API_KEY
doesn't provide authentication details. Instead, it encodes information about the local Prisma Postgres instance. You can obtain a local connection string via the prisma dev
command.
PostgreSQL
datasource db {
provider = "postgresql"
url = "postgresql://janedoe:mypassword@localhost:5432/mydb?schema=sample"
}
MySQL
datasource db {
provider = "mysql"
url = "mysql://janedoe:mypassword@localhost:3306/mydb"
}
Microsoft SQL Server
datasource db {
provider = "sqlserver"
url = "sqlserver://localhost:1433;initial catalog=sample;user=sa;password=mypassword;"
}
SQLite
datasource db {
provider = "sqlite"
url = "file:./dev.db"
}
CockroachDB
datasource db {
provider = "cockroachdb"
url = "postgresql://janedoe:mypassword@localhost:26257/mydb?schema=public"
}
MongoDB
datasource db {
provider = "mongodb"
url = "mongodb+srv://root:<password>@cluster0.ab1cd.mongodb.net/myDatabase?retryWrites=true&w=majority"
}
.env
You can also provide the connection URL as an environment variable:
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
}
You can then either set the environment variable in your terminal or by providing a dotenv file named .env
. This will automatically be picked up by the Prisma CLI.
Prisma ORM reads the connection URL from the dotenv file in the following situations:
- When it updates the schema during build time
- When it connects to the database during run time
DATABASE_URL=postgresql://janedoe:mypassword@localhost:5432/mydb