@alchemy.run/drizzle 0.0.0-stage → 2.0.0-beta.84

package/src/Cloudflare.ts

@@ -0,0 +1,146 @@
+import { DurableObjectState } from "@alchemy.run/cloudflare/Workers/DurableObjectState";
+import type { SqlMigrations } from "@alchemy.run/cloudflare/Workers/SqlMigrations";
+import * as SqliteDoClient from "@effect/sql-sqlite-do/SqliteClient";
+import type { AnyRelations, EmptyRelations } from "drizzle-orm";
+import * as SQLiteDoDrizzle from "drizzle-orm/effect-sqlite-do";
+import { migrate } from "drizzle-orm/effect-sqlite-do/migrator";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Scheduler from "effect/Scheduler";
+
+/**
+ * Migrations for {@link DurableObject} — the shape of the `migrations.js`
+ * bundle `drizzle-kit generate` emits for `driver: "durable-sqlite"`
+ * (each migration's `.sql` file imported as a text module).
+ */
+export interface DurableObjectMigrations {
+  readonly migrations: Record<string, string>;
+  readonly migrationsTable?: string | undefined;
+}
+
+export interface DurableObjectConfig<TRelations extends AnyRelations = EmptyRelations> extends Omit<
+  SQLiteDoDrizzle.EffectDrizzleSQLiteDoConfig<TRelations>,
+  "storage"
+> {
+  /**
+   * Migrations applied before the database is returned. Prefer a snapshot
+   * from `Cloudflare.SqlMigrations(dir)`: SQL is read during construction
+   * and applied with Alchemy's `__alchemy_migrations` bookkeeping.
+   * The generated Drizzle `migrations.js` input remains supported and uses
+   * Drizzle's own migrator; its SQL imports still require loader support.
+   */
+  readonly migrations?: SqlMigrations | DurableObjectMigrations | undefined;
+}
+
+/**
+ * Open a Drizzle database over the current Durable Object's SQLite
+ * storage using the `drizzle-orm/effect-sqlite-do` integration (driven by
+ * `@effect/sql-sqlite-do`'s `SqliteClient`), applying migrations first
+ * when provided. `Cloudflare.SqlMigrations` captures a SQL directory during
+ * construction without importing `.sql` files. Each instance applies pending
+ * files on activation using Alchemy's shared migration history.
+ *
+ * Every query is an Effect with a typed error channel — drizzle's
+ * `EffectDrizzleQueryError` (query + params + cause, wrapping the
+ * underlying effect-sql `SqlError`) — so failures are handled with
+ * `Effect.catchTag` instead of leaking as defects. Transactions add
+ * `SqlError` to the union. Opening the db itself never fails: a
+ * migration that cannot apply dies, since the instance is unusable
+ * without its schema.
+ *
+ * Yield it in the object's inner (instance) Effect — it runs when the
+ * instance activates, before any request reaches its methods:
+ *
+ * ```typescript
+ * // schema.ts
+ * import { defineRelations } from "drizzle-orm";
+ * import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+ *
+ * export const users = sqliteTable("users", {
+ *   id: integer("id").primaryKey({ autoIncrement: true }),
+ *   name: text("name").notNull(),
+ * });
+ *
+ * export const posts = sqliteTable("posts", {
+ *   id: integer("id").primaryKey({ autoIncrement: true }),
+ *   userId: integer("user_id").notNull().references(() => users.id),
+ *   title: text("title").notNull(),
+ * });
+ *
+ * export const relations = defineRelations({ users, posts }, (t) => ({
+ *   users: { posts: t.many.posts() },
+ *   posts: { author: t.one.users({ from: t.posts.userId, to: t.users.id }) },
+ * }));
+ * ```
+ *
+ * ```typescript
+ * import * as Drizzle from "@alchemy.run/drizzle/Cloudflare";
+ * import { posts, relations, users } from "./schema.ts";
+ *
+ * export class Users extends Cloudflare.DurableObject<Users>()(
+ *   "Users",
+ *   Effect.gen(function* () {
+ *     const migrations = yield* Cloudflare.SqlMigrations("./drizzle");
+ *     return Effect.gen(function* () {
+ *       const db = yield* Drizzle.DurableObject({ migrations, relations });
+ *
+ *       return {
+ *         addUser: (name: string) => db.insert(users).values({ name }),
+ *         listUsers: () => db.select().from(users),
+ *         listUsersWithPosts: () =>
+ *           db.query.users.findMany({ with: { posts: true } }),
+ *         // typed error handling per operation:
+ *         tryAddUser: (name: string) =>
+ *           db
+ *             .insert(users)
+ *             .values({ name })
+ *             .pipe(
+ *               Effect.catchTag("EffectDrizzleQueryError", () =>
+ *                 Effect.succeed(undefined),
+ *               ),
+ *             ),
+ *       };
+ *     });
+ *   }),
+ * ) {}
+ * ```
+ *
+ * @binding
+ */
+export const DurableObject = Effect.fn("Drizzle.DurableObject")(function* <
+  TRelations extends AnyRelations = EmptyRelations,
+>(config?: DurableObjectConfig<TRelations>) {
+  const state = yield* DurableObjectState;
+  const storage = state.raw.storage;
+  const { migrations, ...drizzleConfig } = config ?? {};
+  // Built on the ambient (instance) Scope — the client wraps the DO's
+  // local SQLite storage, so there is no disposable resource behind it.
+  const services = yield* Layer.build(SqliteDoClient.layer({ storage }));
+  const client = Context.get(services, SqliteDoClient.SqliteClient);
+  const original = client.withTransaction;
+  const scheduler = new Scheduler.MixedScheduler("sync");
+  const withTransaction: typeof client.withTransaction = (body) =>
+    original(body).pipe(Effect.provideService(Scheduler.Scheduler, scheduler));
+  // A parent input-gate timer can block later transaction timers. Yield through
+  // microtasks while retaining the adapter's client, SQL permit, and context.
+  yield* Effect.sync(() => Object.assign(client, { withTransaction }));
+  const db = yield* SQLiteDoDrizzle.makeWithDefaults({
+    ...(drizzleConfig as Omit<SQLiteDoDrizzle.EffectDrizzleSQLiteDoConfig<TRelations>, "storage">),
+    storage,
+  }).pipe(Effect.provideContext(services));
+  if (migrations !== undefined && "_tag" in migrations) {
+    yield* migrations.apply().pipe(Effect.orDie);
+  } else if (migrations !== undefined) {
+    // A migration that cannot apply leaves the instance unusable — there
+    // is no meaningful recovery at init, so it dies rather than forcing
+    // every caller to handle (or orDie) an error channel.
+    yield* migrate(db, {
+      migrations: migrations.migrations,
+      ...(migrations.migrationsTable !== undefined
+        ? { migrationsTable: migrations.migrationsTable }
+        : {}),
+    }).pipe(Effect.orDie);
+  }
+  return db;
+});

package/src/D1.ts

@@ -0,0 +1,77 @@
+import type { D1DatabaseSource } from "@alchemy.run/cloudflare/D1/SQL";
+import * as D1Client from "@effect/sql-d1/D1Client";
+import { makeExecutionMemo } from "alchemy/Runtime/ExecutionMemo";
+import { proxyChain } from "alchemy/Util/proxy-chain";
+import type { AnyRelations, EmptyRelations } from "drizzle-orm";
+import type { EffectSQLiteD1Database } from "drizzle-orm/effect-d1";
+import * as SQLiteD1Drizzle from "drizzle-orm/effect-d1";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+/**
+ * Open a Drizzle database over a Cloudflare D1 binding using the
+ * `drizzle-orm/effect-d1` integration (which drives queries through
+ * `@effect/sql-d1`'s `D1Client`).
+ *
+ * Accepts the client returned by `Cloudflare.D1.QueryDatabase(db)` — or its
+ * `raw` effect directly — and returns a chainable Proxy over
+ * `EffectSQLiteD1Database` (via `proxyChain`): every property read records a
+ * step, every call records args, and the chain is replayed against the
+ * resolved drizzle db when it's finally yielded as an Effect. Callers don't
+ * need a separate `yield* conn` step:
+ *
+ * ```typescript
+ * const d1 = yield* Cloudflare.D1.QueryDatabase(Db);
+ * const db = yield* Drizzle.D1(d1, { relations });
+ *
+ * fetch: Effect.gen(function* () {
+ *   const rows = yield* db.select().from(users);
+ * });
+ * ```
+ *
+ * The client build is deferred until the first query and memoized on the
+ * current execution's `Scope` (via {@link makeExecutionMemo}), so the
+ * `D1Client` (and its prepared-statement cache) is built at most once per
+ * execution — a Worker `fetch`/`queue`/`scheduled` event, a Durable Object
+ * call, or a Workflow run — and reused across every query in that execution.
+ * Resolving the binding is likewise deferred, so deploy / plan-time
+ * invocations (where `WorkerEnvironment` isn't provided) never touch D1.
+ *
+ * The client is built against that same execution scope, so its finalizer
+ * fires when the scope closes — when the request / run settles, not when the
+ * Worker's isolate-lifetime init completes. Wrapping queries in a nested
+ * `Effect.scoped` narrows both the memo and the client's lifetime to that
+ * block: memo key and finalizer target are always the same scope object, so
+ * they cannot disagree.
+ *
+ * @binding
+ */
+export const D1 = <TRelations extends AnyRelations = EmptyRelations, E = never, R = never>(
+  database: D1DatabaseSource<E, R>,
+  config?: SQLiteD1Drizzle.EffectDrizzleSQLiteD1Config<TRelations>,
+) =>
+  Effect.map(
+    makeExecutionMemo(
+      Effect.gen(function* () {
+        const db = yield* Effect.isEffect(database) ? database : database.raw;
+        const d1Ctx = yield* Layer.build(D1Client.layer({ db }));
+        return yield* SQLiteD1Drizzle.makeWithDefaults(
+          config ?? ({} as SQLiteD1Drizzle.EffectDrizzleSQLiteD1Config<TRelations>),
+        ).pipe(Effect.provideContext(d1Ctx));
+      }),
+    ),
+    (db) =>
+      proxyChain<
+        EffectSQLiteD1Database<TRelations> & {
+          $client: D1Client.D1Client;
+        }
+      >(
+        db as Effect.Effect<
+          EffectSQLiteD1Database<TRelations> & {
+            $client: D1Client.D1Client;
+          },
+          any,
+          any
+        >,
+      ),
+  );

package/src/LibSQL.ts

@@ -0,0 +1,78 @@
+import type { LibSQLConfig, LibSQLSource } from "@alchemy.run/sql/SQLite";
+// `@effect/sql-libsql` (and @libsql/client underneath) are optional peers —
+// value imports are deferred to first use so `@alchemy.run/drizzle` resolves
+// without them installed.
+import type * as LibsqlClient from "@effect/sql-libsql/LibsqlClient";
+import { makeExecutionMemo } from "alchemy/Runtime/ExecutionMemo";
+import { proxyChain } from "alchemy/Util/proxy-chain";
+import type { AnyRelations, EmptyRelations } from "drizzle-orm";
+import type { EffectLibsqlDatabase } from "drizzle-orm/effect-libsql";
+import type { EffectDrizzleSQLiteConfig } from "drizzle-orm/sqlite-core/effect/utils";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+/**
+ * Open a Drizzle database over a libSQL database (e.g. Turso) using the
+ * `drizzle-orm/effect-libsql` integration.
+ *
+ * Accepts the client returned by `Turso.Connect(db)` — or any
+ * `{ url, authToken }` — and returns a chainable Proxy over
+ * `EffectLibsqlDatabase` (via `proxyChain`): every property read records a
+ * step, every call records args, and the chain is replayed against the
+ * resolved drizzle db when it's finally yielded as an Effect. Callers don't
+ * need a separate `yield* conn` step:
+ *
+ * ```typescript
+ * const conn = yield* Turso.Connect(Db);
+ * const db = yield* Drizzle.LibSQL(conn, { relations });
+ *
+ * fetch: Effect.gen(function* () {
+ *   const rows = yield* db.select().from(users);
+ * });
+ * ```
+ *
+ * The client is built lazily on the first query and memoized on the
+ * current execution's `Scope` (via {@link makeExecutionMemo}), so it is
+ * created at most once per execution — a Worker `fetch`/`queue`/`scheduled`
+ * event, a Durable Object call, a Workflow run, or a Lambda invocation —
+ * and closed when that execution settles. Resolving the URL and token is
+ * likewise deferred, so deploy / plan-time invocations never connect.
+ *
+ * `@effect/sql-libsql` client options (e.g. `intMode`) are passed via
+ * `config.client`.
+ *
+ * @binding
+ */
+export const LibSQL = <TRelations extends AnyRelations = EmptyRelations, E = never, R = never>(
+  source: LibSQLSource<E, R>,
+  config?: EffectDrizzleSQLiteConfig<TRelations> & {
+    /** Overrides for the underlying `@effect/sql-libsql` client. */
+    readonly client?: LibSQLConfig;
+  },
+) =>
+  Effect.map(
+    makeExecutionMemo(
+      Effect.gen(function* () {
+        const [LibsqlClient, LibsqlDrizzle, { resolveLibSQLConfig }] = yield* Effect.promise(() =>
+          Promise.all([
+            import("@effect/sql-libsql/LibsqlClient"),
+            import("drizzle-orm/effect-libsql"),
+            import("@alchemy.run/sql/SQLite"),
+          ]),
+        );
+        const { client, ...drizzleConfig } = config ?? {};
+        const ctx = yield* Layer.build(
+          LibsqlClient.layer(yield* resolveLibSQLConfig(source, client)),
+        );
+        return yield* LibsqlDrizzle.makeWithDefaults(
+          drizzleConfig as EffectDrizzleSQLiteConfig<TRelations>,
+        ).pipe(Effect.provideContext(ctx));
+      }),
+    ),
+    (db) =>
+      proxyChain<EffectLibsqlDatabase<TRelations> & { $client: LibsqlClient.LibsqlClient }>(
+        db as Effect.Effect<
+          EffectLibsqlDatabase<TRelations> & { $client: LibsqlClient.LibsqlClient }
+        >,
+      ),
+  );

package/src/MySQL.ts

@@ -0,0 +1,86 @@
+import type { MySQLConfig } from "@alchemy.run/sql/MySQL";
+// `@effect/sql-mysql2` (and mysql2 underneath) are optional peers — value
+// imports are deferred to first use so `@alchemy.run/drizzle` resolves without
+// them installed.
+import type * as MysqlClient from "@effect/sql-mysql2/MysqlClient";
+import { makeExecutionMemo } from "alchemy/Runtime/ExecutionMemo";
+import { proxyChain } from "alchemy/Util/proxy-chain";
+import type { AnyRelations, EmptyRelations } from "drizzle-orm";
+import type { EffectMysql2Database } from "drizzle-orm/effect-mysql2";
+import type { EffectDrizzleMySqlConfig } from "drizzle-orm/mysql-core/effect/utils";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type * as Redacted from "effect/Redacted";
+
+/**
+ * Open a Drizzle/MySQL database from a connection URL using the
+ * `drizzle-orm/effect-mysql2` integration.
+ *
+ * ```typescript
+ * const conn = yield* Cloudflare.Hyperdrive.Connect(Hyperdrive);
+ * const db = yield* Drizzle.MySQL(conn.connectionString, { relations });
+ *
+ * fetch: Effect.gen(function* () {
+ *   const rows = yield* db.select().from(users);
+ * });
+ * ```
+ *
+ * The pool opens on the first query of an execution, is reused for every
+ * query in it, and closes when the event settles (see
+ * {@link makeExecutionMemo}); plan/deploy never connect. Workers defaults
+ * ({@link resolveMySQLConfig}) are overridden via `config.client`:
+ *
+ * ```typescript
+ * const db = yield* Drizzle.MySQL(connectionString, {
+ *   relations,
+ *   client: { poolConfig: { ssl: { rejectUnauthorized: true } } },
+ * });
+ * ```
+ *
+ * @binding
+ */
+export const MySQL = <TRelations extends AnyRelations = EmptyRelations, E = never, R = never>(
+  connectionString: Effect.Effect<Redacted.Redacted<string>, E, R>,
+  config?: EffectDrizzleMySqlConfig<TRelations> & {
+    /**
+     * Overrides for the underlying `@effect/sql-mysql2` client — pool
+     * options (e.g. `poolConfig.ssl` for a direct TLS connection),
+     * `disablePreparedStatements`, `maxConnections`, and friends.
+     */
+    readonly client?: Omit<MySQLConfig, "url">;
+  },
+) =>
+  Effect.map(
+    makeExecutionMemo(
+      Effect.gen(function* () {
+        const [MysqlClient, MySqlDrizzle, { resolveMySQLConfig }] = yield* Effect.promise(() =>
+          Promise.all([
+            import("@effect/sql-mysql2/MysqlClient"),
+            import("drizzle-orm/effect-mysql2"),
+            import("@alchemy.run/sql/MySQL"),
+          ]),
+        );
+        const { client, ...drizzleConfig } = config ?? {};
+        const mysqlCtx = yield* Layer.build(
+          MysqlClient.layer(yield* resolveMySQLConfig({ ...client, url: connectionString })),
+        );
+        return yield* MySqlDrizzle.makeWithDefaults(
+          drizzleConfig as EffectDrizzleMySqlConfig<TRelations>,
+        ).pipe(Effect.provideContext(mysqlCtx));
+      }),
+    ),
+    (db) =>
+      proxyChain<
+        EffectMysql2Database<TRelations> & {
+          $client: MysqlClient.MysqlClient;
+        }
+      >(
+        db as Effect.Effect<
+          EffectMysql2Database<TRelations> & {
+            $client: MysqlClient.MysqlClient;
+          },
+          any,
+          any
+        >,
+      ),
+  );

package/src/Postgres.ts

@@ -0,0 +1,100 @@
+import { resolvePoolConfig } from "@alchemy.run/sql/PostgresTls";
+// `@effect/sql-pg` (and pg underneath) are optional peers — value imports
+// are deferred to first use so `@alchemy.run/drizzle` resolves without them
+// installed.
+import type * as PgClient from "@effect/sql-pg/PgClient";
+import { makeExecutionMemo } from "alchemy/Runtime/ExecutionMemo";
+import { proxyChain } from "alchemy/Util/proxy-chain";
+import type { AnyRelations, EmptyRelations } from "drizzle-orm";
+import type { EffectPgDatabase } from "drizzle-orm/effect-postgres";
+import type { EffectDrizzlePgConfig } from "drizzle-orm/pg-core/effect/utils";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type * as Redacted from "effect/Redacted";
+
+/**
+ * Open a Drizzle/Postgres database from a connection URL using the
+ * `drizzle-orm/effect-postgres` integration.
+ *
+ * Returns a chainable Proxy over `EffectPgDatabase` (via `proxyChain`) —
+ * every property read records a step, every call records args, and the
+ * chain is replayed against the resolved drizzle db when it's finally
+ * yielded as an Effect. Callers don't need a separate `yield* conn` step:
+ *
+ * ```typescript
+ * const db = yield* Drizzle.Postgres(hd.connectionString);
+ *
+ * fetch: Effect.gen(function* () {
+ *   const rows = yield* db.select().from(users);
+ * });
+ * ```
+ *
+ * The connect work is deferred until the first query and memoized on the
+ * current execution's `Scope` (via {@link makeExecutionMemo}), so the pool
+ * is built at most once per execution — a Worker `fetch`/`queue`/`scheduled`
+ * event, a Durable Object call, a Workflow run, or a Lambda invocation — and
+ * reused across every query and `task` step in that execution. Yielding the
+ * connection string is likewise deferred, so deploy / plan-time invocations
+ * (where `WorkerEnvironment` isn't provided) never trigger a real connection
+ * attempt.
+ *
+ * The pool is built against that same execution scope, so its `end`
+ * finalizer fires when the scope closes — when the request / run settles,
+ * not when the Worker's isolate-lifetime init completes. Wrapping queries in
+ * a nested `Effect.scoped` narrows both the memo and the pool's lifetime to
+ * that block: memo key and finalizer target are always the same scope
+ * object, so they cannot disagree.
+ *
+ * `@effect/sql-pg` client options are passed via `config.client`. Behind a
+ * transaction-mode pooler such as Hyperdrive, turn off named prepared
+ * statements, since a later query can reach a backend session that never
+ * prepared them:
+ *
+ * ```typescript
+ * const db = yield* Drizzle.Postgres(hd.connectionString, {
+ *   client: { prepare: false },
+ * });
+ * ```
+ *
+ * @binding
+ */
+
+export const Postgres = <TRelations extends AnyRelations = EmptyRelations, E = never, R = never>(
+  connectionString: Effect.Effect<Redacted.Redacted<string>, E, R>,
+  config?: EffectDrizzlePgConfig<TRelations> & {
+    /**
+     * Overrides for the underlying `@effect/sql-pg` client — `prepare`,
+     * `ssl`, pool limits, and friends. The URL comes from `connectionString`.
+     */
+    readonly client?: Omit<PgClient.PgPoolConfig, "url">;
+  },
+) =>
+  Effect.map(
+    makeExecutionMemo(
+      Effect.gen(function* () {
+        const [PgClient, PgDrizzle] = yield* Effect.promise(() =>
+          Promise.all([import("@effect/sql-pg/PgClient"), import("drizzle-orm/effect-postgres")]),
+        );
+        const url = yield* connectionString;
+        const { client, ...drizzleConfig } = config ?? {};
+        const pgCtx = yield* Layer.build(PgClient.layer(resolvePoolConfig(url, client)));
+        return yield* PgDrizzle.makeWithDefaults(
+          drizzleConfig as EffectDrizzlePgConfig<TRelations>,
+        ).pipe(Effect.provideContext(pgCtx));
+      }),
+    ),
+    (db) =>
+      proxyChain<
+        EffectPgDatabase<TRelations> & {
+          $client: PgClient.PgClient;
+        }
+      >(
+        db as Effect.Effect<
+          EffectPgDatabase<TRelations> & {
+            $client: PgClient.PgClient;
+          },
+          any,
+          any
+        >,
+      ),
+  );

package/src/Providers.ts

@@ -0,0 +1,51 @@
+import * as Provider from "alchemy/Provider";
+import * as Layer from "effect/Layer";
+import { Schema, SchemaProvider } from "./Schema.ts";
+
+export class Providers extends Provider.ProviderCollection<Providers>()("Drizzle") {}
+
+export type ProviderRequirements = Layer.Services<ReturnType<typeof providers>>;
+
+/**
+ * Build-time providers for managing Drizzle schemas as Alchemy resources.
+ * Drizzle.Schema regenerates migration SQL via drizzle-kit's programmatic
+ * API on every deploy when the source schema changes.
+ *
+ * @example
+ * ```typescript
+ * import * as Alchemy from "alchemy";
+ * import * as Cloudflare from "@alchemy.run/cloudflare";
+ * import * as Drizzle from "@alchemy.run/drizzle";
+ * import * as Neon from "@alchemy.run/neon";
+ * import * as Effect from "effect/Effect";
+ * import * as Layer from "effect/Layer";
+ *
+ * export default Alchemy.Stack(
+ *   "MyStack",
+ *   {
+ *     providers: Layer.mergeAll(
+ *       Cloudflare.providers(),
+ *       Drizzle.providers(),
+ *       Neon.providers(),
+ *     ),
+ *     state: Alchemy.localState(),
+ *   },
+ *   Effect.gen(function* () {
+ *     const schema = yield* Drizzle.Schema("app-schema", {
+ *       schema: "./src/schema.ts",
+ *     });
+ *     const project = yield* Neon.Project("app-db");
+ *     const branch = yield* Neon.Branch("app-branch", {
+ *       project,
+ *       migrationsDir: schema.out,
+ *     });
+ *     return { branchId: branch.branchId };
+ *   }),
+ * );
+ * ```
+ */
+export const providers = () =>
+  Layer.effect(Providers, Provider.collection([Schema])).pipe(
+    Layer.provide(SchemaProvider()),
+    Layer.orDie,
+  );