# PostgreSQL

Create a Prisma ORM app with PostgreSQL and run your first query against seeded data.

:::callout{intent="note"}
Using Prisma ORM 7?

Prisma ORM 8 is the current release, as a release candidate. Prisma ORM 7 remains fully supported; its docs live at [/orm/v7](/guides/introduction-7-v7) and its setup paths at [/v7/getting-started](/guides/getting-started-2-getting-started).

For what release candidate means, when the final release is expected, and how to stay on version 7, see [Release status](/guides/prisma-orm-orm-release-status). For the Prisma ORM 8 name of every Prisma ORM 7 API, see [Coming from Prisma ORM 7](/guides/introduction-2-orm-coming-from-prisma-orm-7).
:::

## [Quick start](#quick-start)

::::tabs
:::tab{title="bun"}
```
bun create prisma@latest --provider postgres --no-deploy
```
:::

:::tab{title="pnpm"}
```bash
pnpm create prisma@latest --provider postgres --no-deploy
```
:::

:::tab{title="yarn"}
```bash
yarn create prisma@latest --provider postgres --no-deploy
```
:::

:::tab{title="npm"}
```bash
npm create prisma@latest -- --provider postgres --no-deploy
```

Run this from a Node.js 22.18 or newer (on the 24 line, 24.11 or newer) environment; Node.js 24 is recommended. The command preselects PostgreSQL and prompts you for the project name, the template, the contract authoring style (PSL or TypeScript), your package manager, and whether to install agent skills. If you would rather add Prisma ORM to a project by hand, without the generated template, follow [Set up Prisma ORM from scratch](/guides/prisma-orm-from-scratch).

Setup gives you the app template, a starter contract, `prisma-8.md`, project-level Prisma ORM skills for your coding agent, and package scripts for the database steps below. Answer no at the skills prompt, or pass `--skills none`, to skip the agent skill files; to remove them later, see [`skills sync`](/guides/utility-skills) and the [`skills` config section](/guides/introduction-6-configuration#agent-skills). Sample users are seeded automatically the first time the app queries the database, so there is no separate seed step.

From here you have two paths: let [Prisma Composer](/guides/build-composer) run a local Prisma Postgres database for you, or connect a PostgreSQL database you provide.
:::
::::

Run this from a Node.js 22.18 or newer (on the 24 line, 24.11 or newer) environment; Node.js 24 is recommended. The command preselects PostgreSQL and prompts you for the project name, the template, the contract authoring style (PSL or TypeScript), your package manager, and whether to install agent skills. If you would rather add Prisma ORM to a project by hand, without the generated template, follow [Set up Prisma ORM from scratch](/guides/prisma-orm-from-scratch).

Setup gives you the app template, a starter contract, `prisma-8.md`, project-level Prisma ORM skills for your coding agent, and package scripts for the database steps below. Answer no at the skills prompt, or pass `--skills none`, to skip the agent skill files; to remove them later, see [`skills sync`](/guides/utility-skills) and the [`skills` config section](/guides/introduction-6-configuration#agent-skills). Sample users are seeded automatically the first time the app queries the database, so there is no separate seed step.

From here you have two paths: let [Prisma Composer](/guides/build-composer) run a local Prisma Postgres database for you, or connect a PostgreSQL database you provide.

## [Path A: Run with a local database](#path-a-run-with-a-local-database)

Composer builds the app, starts a local Prisma Postgres database, and applies the starter contract for you, so you do not need a connection string.

:::code-group
```title="bun"
bun run dev:composer
```

```bash title="pnpm"
pnpm run dev:composer
```

```bash title="yarn"
yarn dev:composer
```

```bash title="npm"
npm run dev:composer
```
:::

Open the URL the command prints. You should see the seeded users returned from PostgreSQL.

## [Path B: Connect your own database](#path-b-connect-your-own-database)

### [1. Set the database connection](#1-set-the-database-connection)

Export `DATABASE_URL` in the shell you run the commands from. The generated scripts read the variable from the environment, not from `.env`.

```
export DATABASE_URL="postgresql://username:password@host:5432/database?sslmode=require"
```

If you don't have a PostgreSQL database yet, `npx create-db@latest` creates a temporary Prisma Postgres database and prints its connection string, plus a claim URL if you want to keep it.

### [2. Initialize the database](#2-initialize-the-database)

From the generated project directory, run `db:init` to apply the starter contract to PostgreSQL and sign the database.

:::code-group
```title="bun"
bun run db:init
```

```bash title="pnpm"
pnpm run db:init
```

```bash title="yarn"
yarn db:init
```

```bash title="npm"
npm run db:init
```
:::

The output ends with a summary like `Applied 5 operation(s) across 1 space(s), database signed`.

### [3. Run the app](#3-run-the-app)

Start the app and confirm the sample query runs successfully.

::::tabs
:::tab{title="bun"}
```
bun run dev
```
:::

:::tab{title="pnpm"}
```bash
pnpm run dev
```
:::

:::tab{title="yarn"}
```bash
yarn dev
```
:::

:::tab{title="npm"}
```bash
npm run dev
```

Use the URL or terminal output shown by your template. You should see the seeded users returned from PostgreSQL. If the response is `Could not query users yet`, `DATABASE_URL` is not set in the environment the app runs in; export it in the same shell and restart.
:::
::::

Use the URL or terminal output shown by your template. You should see the seeded users returned from PostgreSQL. If the response is `Could not query users yet`, `DATABASE_URL` is not set in the environment the app runs in; export it in the same shell and restart.

## [Next steps](#next-steps)

- Open `src/prisma/contract.prisma` or `src/prisma/contract.ts` and change the starter model.
- Use the [PostgreSQL existing-project guide](/guides/prisma-orm-2-prisma-orm-add-to-existing-project-postgresql) if you already have an app and database.
- Read the [Prisma ORM overview](/guides/introduction-2-orm) when you want the concepts behind contracts, query APIs, and migrations.

## Related pages

- [Authentication & Tools](./authentication-tools-index.md)
- [Build](./build-index.md)
- [Changelog](../changelog.md)
- [Concepts](./concepts-index.md)
- [Console commands](./console-commands-index.md)
- [Contract Authoring](./contract-authoring-index.md)
- [Core Concepts](./core-concepts-index.md)
- [Data Modeling](./data-modeling-index.md)
- [Database](./database-index.md)
- [DB commands](./db-commands-index.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.