# Alchemy (/docs/postgres/iac/alchemy)

Location: Postgres > Infrastructure as Code > Alchemy

Use [Alchemy](https://alchemy.run) to manage Prisma Postgres resources directly in your infrastructure code.

Alchemy provides Prisma Postgres resources for:

* Projects
* Databases
* Connections
* Workspace references

Conceptual model [#conceptual-model]

[Alchemy](https://alchemy.run/) is a TypeScript library that creates and manages infrastructure when you run it.

Instead of a separate declarative config format, you write a normal TypeScript program (commonly `alchemy.run.ts`) and execute it.

Alchemy resources follow lifecycle phases (`create`, `update`, `delete`) and manage provider APIs for you:

* You compose resources in code (`Project`, `Database`, `Connection`).
* Alchemy handles dependency ordering between those resources.
* Resource defaults can include safety behavior, such as delete protection on projects and databases.
* `await app.finalize()` cleans up orphaned resources that are no longer in your program.

This makes it useful when you want infrastructure code that feels close to your application runtime and platform integrations.

When to use Alchemy [#when-to-use-alchemy]

Alchemy is a strong fit when:

* You are already deploying with Alchemy and want Prisma Postgres in the same graph.
* You want resource composition with first-class platform integrations (for example, Hyperdrive + Workers).
* You prefer lifecycle-driven resource code with safe deletion defaults.

Typical workflow [#typical-workflow]

If you follow the Alchemy getting started flow, the common lifecycle is:

Create a project scaffold (optional):

  

#### npm

```bash
npx alchemy@latest create --template typescript
```

#### pnpm

```bash
pnpm dlx alchemy@latest create --template typescript
```

#### yarn

```bash
yarn dlx alchemy@latest create --template typescript
```

#### bun

```bash
bunx --bun alchemy@latest create --template typescript
```

Configure provider profiles and credentials:

  

#### npm

```bash
npm run alchemy configure
```

#### pnpm

```bash
pnpm run alchemy configure
```

#### yarn

```bash
yarn alchemy configure
```

#### bun

```bash
bun run alchemy configure
```

Authenticate (required for Cloudflare resources):

  

#### npm

```bash
npm run alchemy login
```

#### pnpm

```bash
pnpm run alchemy login
```

#### yarn

```bash
yarn alchemy login
```

#### bun

```bash
bun run alchemy login
```

Start local development with hot reload:

  

#### npm

```bash
npm run alchemy dev
```

#### pnpm

```bash
pnpm run alchemy dev
```

#### yarn

```bash
yarn alchemy dev
```

#### bun

```bash
bun run alchemy dev
```

Deploy:

  

#### npm

```bash
npm run alchemy deploy
```

#### pnpm

```bash
pnpm run alchemy deploy
```

#### yarn

```bash
yarn alchemy deploy
```

#### bun

```bash
bun run alchemy deploy
```

Tear down:

  

#### npm

```bash
npm run alchemy destroy
```

#### pnpm

```bash
pnpm run alchemy destroy
```

#### yarn

```bash
yarn alchemy destroy
```

#### bun

```bash
bun 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.

Prerequisites [#prerequisites]

* An [Alchemy project](https://alchemy.run/)
* A Prisma service token
* `PRISMA_SERVICE_TOKEN` configured in your environment
* `ALCHEMY_PASSWORD` configured when your resources contain secrets

Authentication [#authentication]

Alchemy reads Prisma credentials from environment variables by default.

```bash
export PRISMA_SERVICE_TOKEN="prsc_your_token_here"
export ALCHEMY_PASSWORD="choose-a-strong-password"
```

If you need multiple workspaces/accounts, you can override auth per resource with `serviceToken`.

`ALCHEMY_PASSWORD` is used to encrypt/decrypt secret values in Alchemy state.

Minimal example [#minimal-example]

```ts file=alchemy.run.ts
import alchemy from "alchemy";
import { Connection, Database, Project } from "alchemy/prisma-postgres";

const app = await alchemy("prisma-postgres-example");

const project = await Project("project");

const database = await Database("database", {
  project,
  region: "us-east-1",
});

const connection = await Connection("connection", {
  database,
  name: "app-connection",
});

export const projectId = project.id;
export const databaseId = database.id;
export const host = connection.host;
export const user = connection.user;
export const connectionString = connection.connectionString;
export const prismaConnectionString = connection.prismaConnectionString;

await app.finalize();
```

Complete example with Hyperdrive + Worker [#complete-example-with-hyperdrive--worker]

```ts file=alchemy.run.ts
import alchemy from "alchemy";
import { Hyperdrive, Worker } from "alchemy/cloudflare";
import { Connection, Database, Project } from "alchemy/prisma-postgres";

const app = await alchemy("prisma-postgres-example");

const project = await Project("project");

const database = await Database("database", {
  project,
  region: "us-east-1",
});

const connection = await Connection("connection", {
  database,
  name: "connection",
});

const db = await Hyperdrive("prisma-postgres", {
  origin: connection.connectionString.unencrypted,
});

export const worker = await Worker("worker", {
  entrypoint: "src/worker.ts",
  bindings: {
    HYPERDRIVE: db,
  },
  compatibilityFlags: ["nodejs_compat"],
});

await app.finalize();
```

```ts file=src/worker.ts
import { Client } from "pg";
import type { worker } from "../alchemy.run.ts";

export default {
  async fetch(_request: Request, env: typeof worker.Env): Promise<Response> {
    const client = new Client({
      connectionString: env.HYPERDRIVE.connectionString,
    });

    try {
      await client.connect();
      const result = await client.query("SELECT * FROM pg_tables");

      return Response.json({
        success: true,
        result: result.rows,
      });
    } catch (error: any) {
      return new Response(`Database error: ${error.message}`, { status: 500 });
    }
  },
};
```

Working with multiple workspaces [#working-with-multiple-workspaces]

Prisma service tokens are workspace-scoped. You can pass different tokens to different resources:

```ts
import alchemy from "alchemy";
import { Project } from "alchemy/prisma-postgres";

const app = await alchemy("prisma-workspaces");

const workspaceAProject = await Project("workspace-a-project", {
  serviceToken: alchemy.env.PRISMA_SERVICE_TOKEN_WORKSPACE_A,
});

const workspaceBProject = await Project("workspace-b-project", {
  serviceToken: alchemy.env.PRISMA_SERVICE_TOKEN_WORKSPACE_B,
});

await app.finalize();
```

If you need to resolve a workspace by name or id, use `WorkspaceRef`:

```ts
import { WorkspaceRef } from "alchemy/prisma-postgres";

const workspace = await WorkspaceRef("my-workspace");
```

Deletion behavior [#deletion-behavior]

`Project` and `Database` default to delete protection in Alchemy.

* `Project`: `delete` defaults to `false`
* `Database`: `delete` defaults to `false`

For ephemeral environments, set `delete: true` explicitly:

```ts
const testDatabase = await Database("test-db", {
  project,
  region: "us-east-1",
  delete: true,
});
```

Common troubleshooting [#common-troubleshooting]

Missing token [#missing-token]

If resource creation fails with an auth error, confirm `PRISMA_SERVICE_TOKEN` is set for the process running Alchemy.

Wrong workspace [#wrong-workspace]

Prisma service tokens are workspace-scoped. If resources appear in the wrong workspace, use per-resource `serviceToken` overrides.

References [#references]

* [Alchemy](https://alchemy.run)
* [Alchemy getting started](https://alchemy.run/getting-started)
* [What is Alchemy?](https://alchemy.run/what-is-alchemy/)
* [Alchemy package on npm](https://www.npmjs.com/package/alchemy)
* [Prisma Postgres](https://www.prisma.io/postgres)

## Related pages

- [`Pulumi`](https://www.prisma.io/docs/postgres/iac/pulumi): Provision and manage Prisma Postgres with Pulumi using the Prisma Terraform provider bridge.
- [`Terraform`](https://www.prisma.io/docs/postgres/iac/terraform): Provision and manage Prisma Postgres projects, databases, and connections using Terraform.