Astro

Introduction

This guide shows you how to use Prisma ORM in an Astro site. You scaffold a project that queries users during server rendering and exposes a JSON API route, initialize the schema, see your data render, and deploy the site to Prisma Compute.

Every command below was run end to end against a live Prisma Postgres database.

Quick start

One command scaffolds the project with Prisma ORM wired in:

bun create prisma@latest my-astro-app --template astro --provider postgres

Answer the prompts, then export DATABASE_URL in your shell before running the database scripts. If you do not have a database yet, npx create-db@latest prints a Prisma Postgres connection string.

Prerequisites

• Node.js 22.18 or newer (on the 24 line, 24.11 or newer; 24 recommended)
• A PostgreSQL connection string, or nothing at all: npx create-db@latest can create a Prisma Postgres database for you

Use with your agent

To delegate this guide to your coding agent, copy the prompt below and hand it over:

Create a new Astro app with Prisma ORM, seed it, and deploy it to Prisma Compute.

1. Scaffold: `npm create prisma@latest -- my-astro-app --template astro --provider postgres --yes`. Then run `npx prisma@latest init` in `my-astro-app` so the Prisma agent skills are installed and stay current, and use them. Get a database connection string: use the one I give you, or create a Prisma Postgres database with `npx create-db@latest` 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-astro-app`, run `npm run db:init` with `DATABASE_URL` exported. Sample users are seeded automatically on the app's first query; there is no separate seed script.
3. Start `npm run dev` in the background, wait until it reports ready, verify http://localhost:4321 lists the seeded users and `curl http://localhost:4321/api/users` returns them as JSON, then stop the dev server.
4. Confirm `astro.config.mjs` still sets `output: "server"` and `adapter: node({ mode: "standalone" })` (the template sets both).
5. Deploy: check `npx prisma@latest auth whoami`; if I am not signed in, stop and ask me to run `npx prisma@latest auth login`. Then run `npm run build` followed by `npx prisma@latest deploy module.ts` and verify the live URL's /api/users endpoint with curl. The deployed app provisions and seeds its own Prisma Postgres database; 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 <a unique name>`.

Use the installed Prisma ORM skills.

1. Scaffold and enter the project

bun create prisma@latest my-astro-app --template astro --provider postgres
cd my-astro-app

The scaffold generates the Astro app with Prisma ORM wired in, installs dependencies, and emits the contract your queries are type-checked against.

Next, set the database connection for the local steps. Use your own PostgreSQL connection string, or create a Prisma Postgres database with npx create-db@latest; it prints a connection string and a claim URL you can open to keep the database. Export the variable in the shell you work in; the generated scripts read the environment variable, not .env:

export DATABASE_URL="<your connection string>"

2. Initialize the database

bun run db:init

"summary": "Applied 5 operation(s) across 1 space(s), database signed"

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 and reports Applied 0 operation(s) when there is nothing left to do.

db:init applies your schema (src/prisma/contract.prisma) to the database and signs it. With TypeScript authoring (--authoring typescript) the schema is src/prisma/contract.ts and the emitted files land in src/prisma/generated/. Sample users are seeded automatically the first time the app queries the database.

3. Run and verify

bun run dev

Open http://localhost

Where things live

• src/pages/index.astro: queries users in the frontmatter and renders them
• src/pages/api/users.ts: a JSON API route backed by the same query
• src/prisma/db.ts: the Prisma ORM client both import

Model access is namespace-qualified on PostgreSQL: db.orm.public.User. The Prisma ORM overview covers the contract-first model behind it.

4. Deploy to Prisma Compute

Astro is supported on Prisma Compute, which runs the site as a Node server. The scaffold configures that already: astro.config.mjs sets output: "server" with adapter: node({ mode: "standalone" }), and module.ts with service.ts declare the app for Prisma Composer, pointing at the built dist/server/entry.mjs. Keep those settings: output: "server" renders the page and the API route per request, so the live site reads current data instead of freezing the build-time snapshot into static files, and without the standalone adapter there is no server entrypoint to deploy.

Sign in once (it opens a browser):

bunx prisma@latest auth login

Then build and deploy from the project directory:

bun run build
bunx prisma@latest deploy module.ts

my-astro-app
├─ database   postgres-database db_abc123
└─ app        compute-service cps_abc123
              https://xyz.ewr.prisma.build

The deploy creates a project named after your module in your workspace, and re-running the deploy reuses it: the CLI finds the hosted state it stored on the first run and converges the project to your module. If a project with that name exists but the CLI cannot identify or verify its stored state (one left behind by a different checkout, for example), the deploy stops with HostedStateBootstrapError; deploy under another name with --name <unique-name>, or rename the module in module.ts. The deploy also provisions its own Prisma Postgres database on the platform, declared in module.ts; the DATABASE_URL from your local steps is not involved, and the deployed database seeds on the app's first query. Verify the live API route returns the seeded users:

curl https://xyz.ewr.prisma.build/api/users

The live URL's root page renders the same users server-side. For previews per Git branch and deploy-on-push, see Deploy your first app.

Next steps

• Change the schema in src/prisma/contract.prisma, then run npm run contract:emit and npm run db:update.
• Learn the fundamentals: filtering, sorting, pagination, and writes.
• Read the Prisma ORM overview for the concepts behind contracts and typed queries.