import * as AWS from "@alchemy.run/aws";
import type * as rdsdata from "@distilled.cloud/aws/rds-data";
import type { RuntimeContext } from "alchemy";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Schedule from "effect/Schedule";
import type * as Scope from "effect/Scope";
import { Database, type DatabaseService, type DirectDatabase } from "./Database.ts";
import { BetterAuthMigrationError } from "./Errors.ts";
/**
* Minimal shape of the RDS Data API surface the Kysely dialect drives —
* promise-based so the same dialect serves the runtime (backed by the
* `AWS.RDSData.*` bindings) and deploy-time migrations (backed by
* distilled with ambient credentials).
*
* @internal
*/
export interface DataApiExecutor {
readonly execute: (request: {
sql: string;
parameters?: rdsdata.SqlParameter[];
includeResultMetadata?: boolean;
transactionId?: string;
}) => Promise<DataApiResponse>;
readonly begin: () => Promise<{ transactionId?: string }>;
readonly commit: (transactionId: string) => Promise<unknown>;
readonly rollback: (transactionId: string) => Promise<unknown>;
}
interface DataApiResponse {
records?: rdsdata.Field[][];
columnMetadata?: rdsdata.ColumnMetadata[];
numberOfRecordsUpdated?: number;
}
/**
* Build a Kysely dialect over the RDS Data API.
*
* Postgres-flavoured, with `$n` placeholders rewritten to the Data API's
* named `:n` parameters. Streaming is unsupported (the Data API is
* request/response).
*
* @internal
*/
export const makeDataApiDialect = (
executor: DataApiExecutor,
): Effect.Effect<import("kysely").Dialect> =>
Effect.promise(async () => {
const {
CastNode,
DataTypeNode,
OperationNodeTransformer,
PostgresAdapter,
PostgresIntrospector,
PostgresQueryCompiler,
ReferenceNode,
} = await import("kysely");
class DataApiIntrospectionTransformer extends OperationNodeTransformer {
protected override transformAlias(node: import("kysely").AliasNode) {
const alias = super.transformAlias(node);
const reference = alias.node;
if (
ReferenceNode.is(reference) &&
reference.column.kind === "ColumnNode" &&
reference.column.column.name === "relkind"
) {
// The Data API cannot return PostgreSQL's internal "char" type.
return {
...alias,
node: CastNode.create(reference, DataTypeNode.create("text")),
};
}
return alias;
}
}
const introspectionTransformer = new DataApiIntrospectionTransformer();
const introspectionPlugin: import("kysely").KyselyPlugin = {
transformQuery: ({ node }) => introspectionTransformer.transformNode(node),
transformResult: async ({ result }) => result,
};
class DataApiQueryCompiler extends PostgresQueryCompiler {
protected override getCurrentParameterPlaceholder(): string {
return `:${this.numParameters}`;
}
}
class DataApiConnection {
transactionId: string | undefined;
async executeQuery(compiledQuery: { sql: string; parameters: ReadonlyArray<unknown> }) {
const response = await executor.execute({
sql: compiledQuery.sql,
parameters: compiledQuery.parameters.map((value, index) =>
AWS.RDSData.toSqlParameter(`${index + 1}`, value),
),
includeResultMetadata: true,
...(this.transactionId === undefined ? {} : { transactionId: this.transactionId }),
});
return {
rows: AWS.RDSData.toRows(response) as never[],
numAffectedRows: BigInt(response.numberOfRecordsUpdated ?? 0),
};
}
async *streamQuery(): AsyncIterableIterator<never> {
throw new Error("RDS Data API does not support streaming queries");
}
}
class DataApiDriver {
async init() {}
async acquireConnection() {
return new DataApiConnection();
}
async beginTransaction(connection: DataApiConnection) {
const { transactionId } = await executor.begin();
connection.transactionId = transactionId;
}
async commitTransaction(connection: DataApiConnection) {
if (connection.transactionId !== undefined) {
await executor.commit(connection.transactionId);
connection.transactionId = undefined;
}
}
async rollbackTransaction(connection: DataApiConnection) {
if (connection.transactionId !== undefined) {
await executor.rollback(connection.transactionId);
connection.transactionId = undefined;
}
}
async releaseConnection() {}
async destroy() {}
}
return {
createAdapter: () => new PostgresAdapter(),
createDriver: () => new DataApiDriver(),
createQueryCompiler: () => new DataApiQueryCompiler(),
createIntrospector: (db: import("kysely").Kysely<unknown>) =>
new PostgresIntrospector(db.withPlugin(introspectionPlugin)),
} as unknown as import("kysely").Dialect;
});
export interface AuroraDataApiOptions {
/**
* Secrets Manager secret holding the database credentials. Required when
* passing a bare `DBCluster`; defaults to the composite's `secret` when
* passing an `AWS.RDS.Aurora` result.
*/
readonly secret?: AWS.SecretsManager.Secret;
/** Database name inside the cluster. */
readonly database?: string;
/**
* Deploy-time automatic migration (over the Data API with ambient
* credentials). `false` disables.
* @default enabled
*/
readonly migrate?: false;
}
/** The `AWS.RDS.Aurora` composite pieces this layer consumes. */
interface AuroraLike {
readonly cluster: AWS.RDS.DBCluster;
readonly secret: AWS.SecretsManager.Secret;
readonly writer: AWS.RDS.DBInstance;
}
const isAuroraLike = (value: object): value is AuroraLike =>
"cluster" in value && "secret" in value && "writer" in value;
/**
* A freshly-created cluster answers `DatabaseNotFoundException` until its
* writer instance registers, and a Serverless v2 cluster answers
* `DatabaseResumingException` while scaling from zero — both transient.
* Bounded per the speed doctrine (~1 minute of backoff).
*/
const transientRetry = <A, E extends { _tag: string }, R>(
effect: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
effect.pipe(
Effect.retry({
while: (error) =>
error._tag === "DatabaseResumingException" || error._tag === "DatabaseNotFoundException",
schedule: Schedule.exponential("2 seconds", 1.5),
times: 8,
}),
);
/**
* Aurora (RDS Data API) database layer for Better Auth — the optimal
* Lambda → Aurora pairing: SQL over HTTPS with IAM auth, no VPC
* attachment, no `pg`, no connection pooling concerns.
*
* Runtime access flows through the `AWS.RDSData.*` bindings, which grant
* the host `rds-data:*` + `secretsmanager:GetSecretValue` IAM and inject
* the cluster/secret ARNs. Requires the cluster to have the Data API
* enabled (`AWS.RDS.Aurora` enables it by default).
*
*
* ### Lambda with an Aurora-backed BetterAuth
* Pass the `AWS.RDS.Aurora` composite directly — the layer wires the
* cluster, credentials secret, and the writer-instance dependency (so
* deploy-time migrations wait for the cluster to be queryable) from one
* value.
* **Example:** Function URL serving auth over the Data API
* ```typescript
* import { BetterAuth } from "@alchemy.run/better-auth";
* import { AuroraDataApi } from "@alchemy.run/better-auth/AuroraDataApi";
* import * as AWS from "@alchemy.run/aws";
*
* export const Db = AWS.RDS.Aurora("AuthDb", { subnetIds, securityGroupIds });
*
* export default AuthFunction.make(
* { main, url: true, memorySize: 512 },
* Effect.gen(function* () {
* const auth = yield* BetterAuth({ emailAndPassword: { enabled: true } });
* return { fetch: ... };
* }).pipe(Effect.provide(AuroraDataApi(Db, { database: "postgres" }))),
* );
* ```
*
* ### Serverless v2 scale-from-zero
* A paused cluster answers `DatabaseResumingException` while waking; the
* layer retries the transient window with bounded backoff at both deploy
* and runtime.
* **Example:** Bare cluster + explicit secret
* ```typescript
* AuroraDataApi(cluster, { secret, database: "auth" })
* ```
*
* @layer
* @provides BetterAuth.Database
* @peer kysely
* @peer @distilled.cloud/aws
* @product Aurora
*/
export const AuroraDataApi = (
cluster:
| AWS.RDS.DBCluster
| AuroraLike
| Effect.Effect<AWS.RDS.DBCluster | AuroraLike, never, any>,
options?: AuroraDataApiOptions,
) =>
Layer.effect(
Database,
Effect.gen(function* () {
const source = Effect.isEffect(cluster)
? yield* cluster as Effect.Effect<AWS.RDS.DBCluster | AuroraLike>
: cluster;
const composite = isAuroraLike(source) ? source : undefined;
const db = composite?.cluster ?? (source as AWS.RDS.DBCluster);
const secret = options?.secret ?? composite?.secret;
if (secret === undefined) {
return yield* Effect.die(
new Error(
"AuroraDataApi: pass the AWS.RDS.Aurora composite, or a DBCluster together with `options.secret`.",
),
);
}
const bindingOptions = {
secret,
...(options?.database === undefined ? {} : { database: options.database }),
};
const executeStatement = yield* AWS.RDSData.ExecuteStatement(db, bindingOptions);
const beginTransaction = yield* AWS.RDSData.BeginTransaction(db, bindingOptions);
const commitTransaction = yield* AWS.RDSData.CommitTransaction(db, bindingOptions);
const rollbackTransaction = yield* AWS.RDSData.RollbackTransaction(db, bindingOptions);
const runtime = Effect.gen(function* () {
const context = yield* Effect.context<RuntimeContext>();
const run = <A, E>(effect: Effect.Effect<A, E, RuntimeContext>): Promise<A> =>
Effect.runPromiseWith(context)(effect);
const dialect = yield* makeDataApiDialect({
execute: (request) =>
executeStatement(request as AWS.RDSData.ExecuteStatementRequest).pipe(
transientRetry,
run,
),
begin: () => beginTransaction().pipe(transientRetry, run),
commit: (transactionId) => run(commitTransaction({ transactionId })),
rollback: (transactionId) => run(rollbackTransaction({ transactionId })),
});
return { dialect, type: "postgres" as const };
});
const service: DatabaseService = {
provider: "postgres",
runtime: runtime as DatabaseService["runtime"],
};
// Deploy-time migrations call the Data API through distilled with the
// ambient stack credentials (mirroring D1's deploy-time HTTP client).
// DCE'd from runtime bundles.
if (!globalThis.__ALCHEMY_RUNTIME__ && options?.migrate !== false) {
return {
...service,
migrate: {
identity: {
clusterArn: db.dbClusterArn,
// depend on the WRITER instance too: a cluster with no
// registered instance answers DatabaseNotFoundException
...(composite === undefined ? {} : { writerArn: composite.writer.dbInstanceArn }),
} as Record<string, unknown>,
connect: Effect.gen(function* () {
// Init half — capture the ARNs as Action dependencies.
const clusterArn = yield* db.dbClusterArn;
const secretArn = yield* secret.secretArn;
if (composite !== undefined) {
// capture-only: the migration must wait for the writer
yield* composite.writer.dbInstanceArn.asEffect().pipe(Effect.asVoid);
}
const ambient = yield* Effect.context<never>();
// Apply half — Data API dialect over distilled.
return Effect.gen(function* () {
const resourceArn = yield* clusterArn;
const resolvedSecretArn = yield* secretArn;
const rdsdata = yield* Effect.promise(
() => import("@distilled.cloud/aws/rds-data"),
);
const base = {
resourceArn,
secretArn: resolvedSecretArn,
...(options?.database === undefined ? {} : { database: options.database }),
};
const run = <A>(effect: Effect.Effect<A, any, any>) =>
Effect.runPromiseWith(ambient)(effect as Effect.Effect<A, any, never>);
const dialect = yield* makeDataApiDialect({
execute: (request) =>
rdsdata
.executeStatement({
...base,
...request,
} as never)
.pipe(transientRetry, run),
begin: () => rdsdata.beginTransaction(base).pipe(transientRetry, run),
commit: (transactionId) =>
run(
rdsdata.commitTransaction({
resourceArn,
secretArn: resolvedSecretArn,
transactionId,
}),
),
rollback: (transactionId) =>
run(
rdsdata.rollbackTransaction({
resourceArn,
secretArn: resolvedSecretArn,
transactionId,
}),
),
});
return { dialect, type: "postgres" } as DirectDatabase;
}).pipe(
Effect.catchDefect((cause: unknown) =>
Effect.fail(
new BetterAuthMigrationError({
message:
"Failed to reach the Aurora Data API for Better Auth schema migrations",
cause,
}),
),
),
);
}) as Effect.Effect<
Effect.Effect<DirectDatabase, BetterAuthMigrationError, Scope.Scope>,
never,
RuntimeContext
>,
},
} satisfies DatabaseService;
}
return service;
}),
).pipe(
Layer.provide(AWS.RDSData.ExecuteStatementHttp),
Layer.provide(AWS.RDSData.BeginTransactionHttp),
Layer.provide(AWS.RDSData.CommitTransactionHttp),
Layer.provide(AWS.RDSData.RollbackTransactionHttp),
);