Alchemy

Use Alchemy to create Prisma Postgres databases and deploy applications to Prisma Compute from one alchemy.run.ts file.

Alchemy docs · GitHub · Provider source · TanStack Start example · npm

bun add alchemy@next effect@beta @effect/platform-bun@beta @effect/platform-node@beta

printf '\n.alchemy/\n' >> .gitignore

pnpm add alchemy@next effect@beta @effect/platform-bun@beta @effect/platform-node@beta
printf '\n.alchemy/\n' >> .gitignore

yarn add alchemy@next effect@beta @effect/platform-bun@beta @effect/platform-node@beta
printf '\n.alchemy/\n' >> .gitignore

npm install alchemy@next effect@beta @effect/platform-bun@beta @effect/platform-node@beta
printf '\n.alchemy/\n' >> .gitignore

Create a Prisma service token, then choose how Alchemy should read it.

To store the token in your local Alchemy profile:

bunx alchemy login --configure

pnpm dlx alchemy login --configure

yarn dlx alchemy login --configure

npx alchemy login --configure

export PRISMA_SERVICE_TOKEN="<your-service-token>"

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:

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.

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:

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.

bunx alchemy deploy

curl "<url-from-stack-output>"

pnpm dlx alchemy deploy
curl "<url-from-stack-output>"

yarn dlx alchemy deploy
curl "<url-from-stack-output>"

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:

bunx alchemy deploy

curl "<url-from-stack-output>"

pnpm dlx alchemy deploy
curl "<url-from-stack-output>"

yarn dlx alchemy deploy
curl "<url-from-stack-output>"

npx alchemy deploy
curl "<url-from-stack-output>"

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

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:

const project = yield* Prisma.Project("project", {

  region: "us-east-1",

});

const app = yield* Prisma.Compute("app", {

  project,

  build: "auto",

});

Configure the local app process alongside the database:

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,

  },

});

bunx alchemy dev

pnpm dlx alchemy dev

yarn dlx alchemy dev

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.

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

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.

bunx alchemy deploy --stage "pr-${PR_NUMBER}" --yes

bunx alchemy destroy --stage "pr-${PR_NUMBER}" --yes

pnpm dlx alchemy deploy --stage "pr-${PR_NUMBER}" --yes
pnpm dlx alchemy destroy --stage "pr-${PR_NUMBER}" --yes

yarn dlx alchemy deploy --stage "pr-${PR_NUMBER}" --yes
yarn dlx alchemy destroy --stage "pr-${PR_NUMBER}" --yes

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

• Prisma.Project
• Prisma.Branch
• Prisma.Database and Prisma.Postgres
• Prisma.Connection
• Prisma.Compute
• Prisma.App
• Prisma.Deployment
• Prisma.CustomDomain
• Prisma.EnvironmentVariable
• Prisma.SourceRepository