Skip to main content

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:

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

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

schema.prisma
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​

schema.prisma
datasource db {
  provider = "postgresql"
  url      = "postgresql://janedoe:mypassword@localhost:5432/mydb?schema=sample"
}

MySQL​

schema.prisma
datasource db {
  provider = "mysql"
  url      = "mysql://janedoe:mypassword@localhost:3306/mydb"
}

Microsoft SQL Server​

schema.prisma
datasource db {
  provider = "sqlserver"
  url      = "sqlserver://localhost:1433;initial catalog=sample;user=sa;password=mypassword;"
}

SQLite​

schema.prisma
datasource db {
  provider = "sqlite"
  url      = "file:./dev.db"
}

CockroachDB​

schema.prisma
datasource db {
  provider = "cockroachdb"
  url      = "postgresql://janedoe:mypassword@localhost:26257/mydb?schema=public"
}

MongoDB​

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

schema.prisma
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