# Alchemy (/docs/compute/alchemy)

Provision Prisma Postgres and deploy applications to Prisma Compute in one TypeScript stack.

Location: Compute > Alchemy

Use [Alchemy](https://alchemy.run/) to create Prisma Postgres databases and deploy applications to Prisma Compute from one `alchemy.run.ts` file.

[Alchemy docs](https://alchemy.run/prisma/) · [GitHub](https://github.com/alchemy-run/alchemy) · [Provider source](https://github.com/alchemy-run/alchemy/tree/main/packages/alchemy/src/Prisma) · [TanStack Start example](https://github.com/alchemy-run/alchemy/tree/main/examples/prisma-tanstack-start) · [npm](https://www.npmjs.com/package/alchemy)

## Deploy Postgres and Compute

### 1. Install and authenticate

#### bun

```bash title="Terminal"
bun add alchemy@next effect@beta @effect/platform-bun@beta @effect/platform-node@beta
printf '\n.alchemy/\n' >> .gitignore
```

#### pnpm

```bash title="Terminal"
pnpm add alchemy@next effect@beta @effect/platform-bun@beta @effect/platform-node@beta
printf '\n.alchemy/\n' >> .gitignore
```

#### yarn

```bash title="Terminal"
yarn add alchemy@next effect@beta @effect/platform-bun@beta @effect/platform-node@beta
printf '\n.alchemy/\n' >> .gitignore
```

#### npm

```bash title="Terminal"
npm install alchemy@next effect@beta @effect/platform-bun@beta @effect/platform-node@beta
printf '\n.alchemy/\n' >> .gitignore
```

Create a Prisma [service token](/guides/authentication-tools-authentication#service-tokens), then choose how Alchemy should read it.

To store the token in your local Alchemy profile:

#### bun

```bash title="Terminal"
bunx alchemy login --configure
```

#### pnpm

```bash title="Terminal"
pnpm dlx alchemy login --configure
```

#### yarn

```bash title="Terminal"
yarn dlx alchemy login --configure
```

#### npm

```bash title="Terminal"
npx alchemy login --configure
```

Choose **Service Token** for Prisma and paste the token when prompted. Alchemy stores it under `~/.alchemy/credentials/<profile>/`.

For CI or an ephemeral shell, choose **Environment Variable** and export the token before running Alchemy:

```bash title="Terminal"
export PRISMA_SERVICE_TOKEN="<your-service-token>"
```

If the profile uses **Environment Variable**, `alchemy login` only verifies that the variable is available. Run `alchemy login --configure` to switch the profile to a stored token.

### 2. Create the stack

```ts title="alchemy.run.ts"
import * as Alchemy from "alchemy";
import * as Prisma from "alchemy/Prisma";
import * as Effect from "effect/Effect";

export default Alchemy.Stack(
  "MyApp",
  {
    providers: Prisma.providers(),
    state: Alchemy.localState(),
  },
  Effect.gen(function* () {
    const project = yield* Prisma.Project("project", {
      createDatabase: false,
    });

    const postgres = yield* Prisma.Postgres("database", {
      project,
      region: "us-east-1",
    });

    const connection = yield* Prisma.Connection("app-connection", {
      database: postgres,
    });

    const app = yield* Prisma.Compute("app", {
      project,
      build: "auto",
      env: {
        DATABASE_URL: connection.databaseUrl,
      },
    });

    return { url: app.url };
  }),
);
```

`build: "auto"` detects and builds Bun, Next.js, Nuxt, Astro, TanStack Start, and NestJS applications from the current directory. It expects deployable server output: Next.js needs standalone output, Astro needs the Node adapter in standalone mode, and TanStack Start needs its Nitro deployment adapter (`bunx @tanstack/cli@latest add nitro`). Plain Bun servers must listen on `process.env.PORT` and bind to `0.0.0.0`.

Alchemy provisions the database but does not infer or run production schema migrations. For Prisma ORM 7, pass `connection.directConnectionString` to the migration process as `DIRECT_URL` and read it from `prisma.config.ts`:

```ts title="prisma.config.ts"
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  datasource: {
    url: env("DIRECT_URL"),
  },
});
```

Keep `connection.databaseUrl` as the application's pooled `DATABASE_URL`. Run migrations separately or model them as a dependency before Compute, as shown in the linked TanStack Start example.

### 3. Deploy and verify

#### bun

```bash title="Terminal"
bunx alchemy deploy
curl "<url-from-stack-output>"
```

#### pnpm

```bash title="Terminal"
pnpm dlx alchemy deploy
curl "<url-from-stack-output>"
```

#### yarn

```bash title="Terminal"
yarn dlx alchemy deploy
curl "<url-from-stack-output>"
```

#### npm

```bash title="Terminal"
npx alchemy deploy
curl "<url-from-stack-output>"
```

Alchemy shows the plan before creating the project, database, connection, and Compute deployment. Copy the printed `url` into the `curl` command.

After changing your application or infrastructure, run the same commands again:

#### bun

```bash title="Terminal"
bunx alchemy deploy
curl "<url-from-stack-output>"
```

#### pnpm

```bash title="Terminal"
pnpm dlx alchemy deploy
curl "<url-from-stack-output>"
```

#### yarn

```bash title="Terminal"
yarn dlx alchemy deploy
curl "<url-from-stack-output>"
```

#### npm

```bash title="Terminal"
npx alchemy deploy
curl "<url-from-stack-output>"
```

## Default or explicit database

The complete stack above declares its database explicitly. The important wiring is:

```ts title="Explicit database"
const postgres = yield* Prisma.Postgres("database", { project });
const connection = yield* Prisma.Connection("connection", {
  database: postgres,
});

const app = yield* Prisma.Compute("app", {
  project,
  build: "auto",
  env: {
    DATABASE_URL: connection.databaseUrl,
  },
});
```

Alternatively, let the project create its default database:

```ts title="Default database"
const project = yield* Prisma.Project("project", {
  region: "us-east-1",
});

const app = yield* Prisma.Compute("app", {
  project,
  build: "auto",
});
```

> \[!WARNING]
> Prisma injects the default database's system-managed `DATABASE_URL` and `DATABASE_URL_POOLED` variables. Do not add either key to `env` when using the default database.

## Local development

Configure the local app process alongside the database:

```ts title="alchemy.run.ts"
const postgres = yield* Prisma.Postgres("database", {
  project,
  dev: {
    persistenceMode: "stateful",
  },
});

const connection = yield* Prisma.Connection("connection", {
  database: postgres,
});

const app = yield* Prisma.Compute("app", {
  project,
  build: "auto",
  env: {
    DATABASE_URL: connection.databaseUrl,
  },
  dev: {
    command: "bun run dev",
    port: 3000,
  },
});
```

#### bun

```bash title="Terminal"
bunx alchemy dev
```

#### pnpm

```bash title="Terminal"
pnpm dlx alchemy dev
```

#### yarn

```bash title="Terminal"
yarn dlx alchemy dev
```

#### npm

```bash title="Terminal"
npx alchemy dev
```

Alchemy starts a local Prisma Postgres server, passes its connection string to the application, and runs the configured development command. Use `dev.migrate` on `Prisma.Postgres` when the local database needs a setup command before the application starts.

## Production options

Use an application directory, health check, and old-deployment cleanup when needed:

```ts title="alchemy.run.ts"
const app = yield* Prisma.Compute("app", {
  project,
  path: "./apps/web",
  build: "auto",
  env: {
    DATABASE_URL: connection.databaseUrl,
  },
  healthCheck: {
    path: "/health",
  },
  destroyOldDeployment: true,
});

const domain = yield* Prisma.CustomDomain("domain", {
  app,
  hostname: "app.example.com",
});

return {
  url: app.url,
  dnsRecords: domain.dnsRecords,
};
```

Your application must return a successful response from the configured health-check path before promotion. Add the returned `dnsRecords` at your DNS provider to activate the custom domain. Custom domains can only attach to applications on the project's default branch.

## CI and cleanup

#### bun

```bash title="CI"
bunx alchemy deploy --stage "pr-${PR_NUMBER}" --yes
bunx alchemy destroy --stage "pr-${PR_NUMBER}" --yes
```

#### pnpm

```bash title="CI"
pnpm dlx alchemy deploy --stage "pr-${PR_NUMBER}" --yes
pnpm dlx alchemy destroy --stage "pr-${PR_NUMBER}" --yes
```

#### yarn

```bash title="CI"
yarn dlx alchemy deploy --stage "pr-${PR_NUMBER}" --yes
yarn dlx alchemy destroy --stage "pr-${PR_NUMBER}" --yes
```

#### npm

```bash title="CI"
npx alchemy deploy --stage "pr-${PR_NUMBER}" --yes
npx alchemy destroy --stage "pr-${PR_NUMBER}" --yes
```

Use a unique preview stage for each pull request and destroy that same stage when it closes. Cleanup must never target `prod`.

Use a shared [Alchemy state store](https://alchemy.run/state-store/) for team and CI deployments. State can contain database credentials, so never commit `.alchemy/`.

Replace `Alchemy.localState()` before deploying from CI. Local state is only suitable when one machine owns the stack.

Destroying the stack deletes the Prisma project and everything inside it, including databases and applications.

## API reference

- [`Prisma.Project`](https://alchemy.run/providers/prisma/project/)
- [`Prisma.Branch`](https://alchemy.run/providers/prisma/branch/)
- [`Prisma.Database` and `Prisma.Postgres`](https://alchemy.run/providers/prisma/database/)
- [`Prisma.Connection`](https://alchemy.run/providers/prisma/connection/)
- [`Prisma.Compute`](https://alchemy.run/providers/prisma/compute/)
- [`Prisma.App`](https://alchemy.run/providers/prisma/app/)
- [`Prisma.Deployment`](https://alchemy.run/providers/prisma/deployment/)
- [`Prisma.CustomDomain`](https://alchemy.run/providers/prisma/customdomain/)
- [`Prisma.EnvironmentVariable`](https://alchemy.run/providers/prisma/environmentvariable/)
- [`Prisma.SourceRepository`](https://alchemy.run/providers/prisma/sourcerepository/)

## Related pages

- [`Branching`](/guides/features-2-compute-branching): Branches are isolated environments that map to your Git branches, so preview work never touches production.
- [`Deploy Button`](/guides/integrations-deploy-button): Add a Deploy with Prisma button that copies a public Composer repository and starts a Composer-managed deployment.
- [`Deploy on push`](/guides/integrations-deploy-on-push): Graduate a Composer app from manual deploys to a Git workflow, with production deploys on push and an isolated preview environment per branch.
- [`Deployments`](/guides/features-2-compute-deployments): How deploys create service versions on Prisma Compute, and how to inspect, promote, roll back, start, and stop them.
- [`Domains`](/guides/features-2-compute-domains): Point a custom domain at a production app and the platform verifies DNS and provisions TLS for you.

## 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.