# Bun (/docs/guides/runtimes/bun) > For the complete Prisma documentation index, see [llms.txt](https://www.prisma.io/docs/llms.txt). A markdown version of any docs page is available by appending `.md` to its URL. Scaffold a Prisma ORM app with Bun, run your first typed query, serve users over HTTP, and deploy to Prisma Compute. Location: Guides > Runtimes > Bun ## Introduction [#introduction] In this guide, you scaffold a Prisma ORM project with Bun, initialize a PostgreSQL database from your schema, run your first typed query, serve query results over HTTP with `Bun.serve`, and deploy the server to [Prisma Compute](https://www.prisma.io/docs/compute). Bun runs TypeScript directly, so nothing has to be compiled to work locally; the deploy bundles the server with `tsdown`. Every command and code sample below was run end to end against a live Prisma Postgres database. ## Prerequisites [#prerequisites] - [Bun](https://bun.sh/) 1.3 or later (`bun --version`) - A PostgreSQL connection string, or nothing at all: `bunx create-db` can create a [Prisma Postgres](https://www.prisma.io/docs/postgres) database for you ## 1. Scaffold the project [#1-scaffold-the-project] Create the project with `create-prisma`, and pick Bun as the package manager when prompted, or pass everything up front: ```bash bun create prisma@latest my-bun-app --template minimal --provider postgres --package-manager bun --no-deploy ``` Answer the prompts for contract authoring style and agent skills. The scaffold sets up `src/prisma/` with a starter schema and installs dependencies with Bun. ```bash cd my-bun-app ``` Next, set the database connection for the local steps. Use your own PostgreSQL connection string, or create a Prisma Postgres database with `bunx create-db`, which prints a connection string and a claim URL. Claim the database with a free Prisma account if you want to keep it. Export the variable in the shell you work in; the generated scripts read the environment variable, not `.env`: ```bash export DATABASE_URL="" ``` ## 2. Emit the contract and initialize the database [#2-emit-the-contract-and-initialize-the-database] Prisma ORM compiles your schema (`src/prisma/contract.prisma`) into a contract that your queries are type-checked against. If you chose TypeScript authoring (`--authoring typescript`), the source is `src/prisma/contract.ts` and the emitted files land in `src/prisma/generated/` instead. Emit it, then apply the schema to the database: ```bash bun run contract:emit bun run db:init ``` `db:init` creates the tables and signs the database: ```text no-copy ✔ Applied 5 operation(s) across 1 contract space App space ├─ Create table "Post" ├─ Create table "User" ├─ Add unique constraint on "User" (email) ├─ Create index "Post_authorId_idx_e47547ed" on "Post" ├─ Add foreign key "Post_authorId_fkey" on "Post" └─ marker 920a87b50729a867e21706dd0fa5c3739e273a84ed89eb2f3525633b2d6ef85c ``` If `db:init` stops with `Connection terminated unexpectedly`, a database you just created is still starting; wait a few seconds and run it again. The command is safe to repeat: when there is nothing left to do, it prints `✔ Database already matches contract across 1 contract space`. If `db:init` reports that the contract file is missing, run `bun run contract:emit` first; the emit step generates `src/prisma/contract.json`. ## 3. Write your first query [#3-write-your-first-query] Replace `src/index.ts` with a script that creates a user and reads every user back. On PostgreSQL, you reach a model through the database schema it is in: `db.orm.public.User` is the `User` model in `public`, the default schema. ```ts title="src/index.ts" import { db } from "./prisma/db"; // Create a user, then read every user back const user = await db.orm.public.User.create({ email: `ada+${Date.now()}@prisma.io`, name: "Ada Lovelace", }); console.log(`created user ${user.email}`); const users = await db.orm.public.User.select("id", "email", "name").all(); console.log(`there are now ${users.length} users`); await db.close(); ``` `await db.close()` at the end lets the script exit cleanly; without it, the connection pool keeps the process alive. ## 4. Run it [#4-run-it] The generated `dev` script is `tsx watch src/index.ts`, which re-runs the file on every save. For a single run, call Bun directly: ```bash bun src/index.ts ``` ```text no-copy created user ada+1784893846026@prisma.io there are now 1 users ``` The `pg` driver may print an SSL mode deprecation warning above the output; it comes from the `sslmode=require` setting in the generated connection string and does not affect the query. That is the whole loop: schema to contract, contract to database, typed queries against both. ## 5. Serve it over HTTP [#5-serve-it-over-http] The script pattern works for one-off jobs. To keep the app running and serve query results, add a small HTTP server with `Bun.serve`. Create `src/server.ts`: ```ts title="src/server.ts" import { db } from "./prisma/db"; const server = Bun.serve({ port: Number(process.env.PORT ?? 3000), async fetch(req) { const { pathname } = new URL(req.url); if (pathname === "/users") { const users = await db.orm.public.User.select("id", "email", "name").all(); return Response.json(users); } return new Response("Not found", { status: 404 }); }, }); console.log(`Listening on http://localhost:${server.port}`); ``` Start it and check the endpoint: ```bash bun src/server.ts ``` ```bash curl http://localhost:3000/users ``` ```json no-copy [{ "id": 1, "email": "ada+1784893846026@prisma.io", "name": "Ada Lovelace" }] ``` The server listens on port 3000; set `PORT` to change it. Unlike the script, the server never calls `db.close()`: the connection pool is shared across requests and closes when the process exits. ## 6. Deploy to Prisma Compute [#6-deploy-to-prisma-compute] Plain Bun servers are supported on [Prisma Compute](https://www.prisma.io/docs/compute). The scaffold declares the app for [Prisma Composer](https://www.prisma.io/docs/composer) in `module.ts` and `service.ts`, which deploy whatever the `build` script bundles into `dist/server.mjs`. That script runs `tsdown`, and the generated `tsdown.config.ts` sets its entry to `src/index.ts`, so point the entry at your server instead: ```ts title="tsdown.config.ts" export default defineConfig({ entry: { server: "src/server.ts" }, // the rest of the generated config is unchanged }); ``` Sign in once (it opens a browser): ```bash bunx prisma auth login ``` Then build and deploy from the project directory: ```bash bun run build bunx prisma deploy ``` ```text no-copy my-bun-app ├─ database postgres-database db_abc123 └─ app compute-service cps_abc123 https://xyz.ewr.prisma.build ``` The first deploy creates a project in your workspace named after your module, which is the first argument to `module()` in `module.ts` (`my-bun-app` here). The project gets its own Prisma Postgres database, declared in `module.ts`. The deploy does not use the database from your local steps, so the users you created locally are not in the deployed database. Running `bunx prisma deploy` again updates that same project. The deploy finds the project by that name, so a deploy from any app whose module has the same name, such as two apps both scaffolded as `my-app`, goes to that same project. Give each app its own name in `module.ts`. If a project with that name exists but the CLI cannot identify or verify its stored state (one deployed by an older version of Composer, for example), the deploy stops with `HostedStateBootstrapError`: rename the module in `module.ts`, or deploy under another name with `--name ` and pass the same `--name` on every later deploy. Verify the live endpoint responds with an empty list from the fresh database: ```bash curl https://xyz.ewr.prisma.build/users ``` ```json no-copy [] ``` For previews per Git branch and deploy on push, see [Deploy on push](https://www.prisma.io/docs/compute/deploy-on-push). To run the built server locally the way Prisma Compute runs it, with no `DATABASE_URL` to set, run `bun run dev:composer`. It builds the server, starts a local Prisma Postgres database, applies the committed migrations to it, and prints the server's local URL. ## Change the schema [#change-the-schema] The scaffold also writes a first migration to the `migrations/` directory. A deploy changes the hosted database only by applying the migrations in that directory, so every schema change needs a migration of its own. `migration:plan` writes each new migration as a step after the migration that `migrations/app/refs/db.json` names. That file is the `db` ref, and `db:init` creates it. If you have not run `db:init` in this checkout, for example because you only use `bun run dev:composer`, point the `db` ref at the first migration once. Pass the directory name only, without `migrations/app/` in front: `ls migrations/app` lists it, and its name ends in `_init`, such as `20261120T1011_init`. A path such as `migrations/app/20261120T1011_init` fails with `MIGRATION.REF_NOT_FOUND`. ```bash bunx prisma migration ref set db ``` After you edit `src/prisma/contract.prisma`, for example to add a `bio String?` field to `User`, run: ```bash bun run contract:emit bun run migration:plan --name add-user-bio ``` `contract:emit` updates the files your queries are type-checked against, and `migration:plan` writes the change as a new migration in `migrations/app/`. Then apply the migration to your local database, and point the `db` ref at it so that your next `migration:plan` starts from this migration. Without the ref step, the next plan would include this change a second time. If your development database is in `DATABASE_URL`, one command does both: ```bash bun run migrate --advance-ref db ``` If you use `bun run dev:composer`, restart it: it applies new migrations when it starts. It does not update the `db` ref, so once it is running, set the ref yourself. Pass the last part of the path that `migration:plan` printed on its `app space:` line: for `migrations/app/20261120T1124_add_user_bio`, that is `bunx prisma migration ref set db 20261120T1124_add_user_bio`. ```bash bunx prisma migration ref set db ``` Commit the `migrations/` directory with your change, including `migrations/app/refs/db.json`, then deploy again with `bun run build` and `bunx prisma deploy`. The deploy applies the new migration to the hosted database before it starts the new version of your app. If you skip `migration:plan`, the deploy stops with `MIGRATION_PATH_NOT_FOUND`, because no migration in `migrations/` leads to your new schema. If you changed your database with `db:update`, which makes the database match the schema without writing a migration, `migration:plan` stops with `MIGRATION.HASH_NOT_IN_GRAPH`. Pass the newest migration with `--from`: it is the first migration name in the graph that `bunx prisma migration list` prints, such as `20261120T1124_add_user_bio`. Then apply the migration as above: ```bash bun run migration:plan --from --name add-user-bio ``` ## Use with your agent [#use-with-your-agent] To delegate this guide to your coding agent, copy the prompt below and hand it over: ```text Create a new Bun app with Prisma ORM, run a first typed query, and deploy it to Prisma Compute. 1. Scaffold: `bun create prisma@latest my-bun-app --template minimal --provider postgres --package-manager bun --yes`. The scaffold installs the Prisma agent skills. Get a database connection string: use the one I give you, or create a Prisma Postgres database with `bunx create-db` and show me the claim URL it prints. Export it as `DATABASE_URL` in the shell; the generated scripts read the environment variable, not `.env`. 2. In `my-bun-app`, run `bun run contract:emit`, then `bun run db:init`, with `DATABASE_URL` exported. 3. Replace `src/index.ts` with a script that creates a user and reads all users back via `db.orm.public.User`, following https://www.prisma.io/docs/guides/runtimes/bun.md, and verify `bun src/index.ts` prints the created user (`bun run dev` is `tsx watch`, which does not exit). 4. Add `src/server.ts` with a `Bun.serve` server exposing GET /users, and verify `curl http://localhost:3000/users` returns the users. 5. Deploy: check `bunx prisma auth whoami`; if I am not signed in, stop and ask me to run `bunx prisma auth login`. Then point the build at the server by setting `entry` in `tsdown.config.ts` to `{ server: "src/server.ts" }`, run `bun run build`, then `bunx prisma deploy`, and verify the live URL's /users endpoint returns `[]`. The deployed app provisions its own fresh Prisma Postgres database, so the local users are not there; do not pass the local DATABASE_URL. If the deploy fails with `HostedStateBootstrapError`, a project with the module's name exists in my workspace but its hosted state cannot be verified; re-run the deploy with `--name `. Use the installed Prisma ORM skills. ``` The scaffold installs the [Prisma ORM skills](https://www.prisma.io/docs/ai/tools/skills#available-skills-for-prisma-8) for Claude Code, Cursor, Codex, and Devin when you answer yes to its agent skills prompt. To install them later, run [`bunx prisma@latest init`](https://www.prisma.io/docs/cli/init) in the project. Prompts you can give your agent after this guide: - "Using the prisma-8 skill, add a script that lists the 10 newest users." - "Add a published flag to the Post model in the starter contract, emit the contract, then plan a migration and apply it." ## Next steps [#next-steps] - [Learn the fundamentals](https://www.prisma.io/docs/orm/fundamentals/reading-data): filtering, sorting, pagination, and writes. - [Read the Prisma ORM overview](https://www.prisma.io/docs/orm) for the concepts behind contracts and typed queries. ## Related pages - [Deno](https://www.prisma.io/docs/guides/runtimes/deno): Run a minimal Prisma ORM and PostgreSQL app on Deno.