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

Deploy Postgres and Compute

1. Install and authenticate

Bash

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

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

Bash

pnpm dlx alchemy@latest create --template typescript

Bash

yarn dlx alchemy@latest create --template typescript

Bash

npx alchemy@latest create --template typescript

Configure provider profiles and credentials:

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

To store the token in your local Alchemy profile:

Bash

bunx alchemy login --configure

Bash

pnpm run alchemy configure

Bash

yarn alchemy configure

Bash

npm run alchemy configure

Authenticate (required for Cloudflare resources):

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

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

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:

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

Bash

bunx alchemy deploy

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

Bash

pnpm run alchemy login

Bash

yarn alchemy login

Bash

npm run alchemy login

Start local development with hot reload:

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:

Bash

bunx alchemy deploy

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

Bash

pnpm run alchemy dev

Bash

yarn alchemy dev

Bash

npm run alchemy dev

Deploy:

Default or explicit database

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

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:

database"

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

  region: "us-east-1",

});

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

  project,

  build: "auto",

});

Local development

Configure the local app process alongside the database:

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,

  },

});

Bash

bunx alchemy dev

Bash

pnpm run alchemy deploy

Bash

yarn alchemy deploy

Bash

npm run alchemy deploy

Tear down:

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:

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

title="CI"

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

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

Bash

pnpm run alchemy destroy

Bash

yarn alchemy destroy

Bash

npm run alchemy destroy

For Prisma Postgres-only resources, configure/login may not be necessary in every setup. They are typically needed when you also manage Cloudflare resources in the same app.

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.