import {
diffMigrations,
migrationsAttrs,
migrationsInputOf,
runMigrations,
stampedOf,
type MigrationsInput,
} from "@alchemy.run/sql/Migrations";
import { applySqlImports, hashImports, splitSqlStatements } from "@alchemy.run/sql/SqlFile";
import * as turso from "@distilled.cloud/turso/turso";
import { Unowned } from "alchemy/AdoptPolicy";
import { deepEqual, isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as HttpClient from "effect/http/HttpClient";
import * as Redacted from "effect/Redacted";
import { organization } from "./Credentials.ts";
import * as Hrana from "./Hrana.ts";
import type { Providers } from "./Providers.ts";
export class DatabaseUnexpectedResponse extends Data.TaggedError("DatabaseUnexpectedResponse")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export interface DatabaseSeed {
/**
* `"database"` copies an existing database (optionally at a point in
* time). `"database_upload"` creates an empty database awaiting an upload
* of a SQLite file.
*/
type: "database" | "database_upload";
/** Name of the source database when `type` is `"database"`. */
name?: string;
/**
* ISO 8601 recovery point within the source database's retention window
* (24 hours, or 30 days on the Scaler plan).
*/
timestamp?: string;
}
export interface DatabaseEncryption {
/**
* Base64-encoded encryption key: 32 bytes for `aes256gcm`,
* `chacha20poly1305`, and the `aegis256` variants; 16 bytes for
* `aes128gcm` and the `aegis128l` variants.
*/
key: Redacted.Redacted<string>;
/** Encryption cipher. */
cipher:
| "aes256gcm"
| "aes128gcm"
| "chacha20poly1305"
| "aegis128l"
| "aegis128x2"
| "aegis128x4"
| "aegis256"
| "aegis256x2"
| "aegis256x4"
| (string & {});
}
export interface DatabaseProps {
/**
* Database name, unique within the organization. Lowercase letters,
* numbers, and dashes, at most 64 characters. If omitted, a unique name
* is generated from the stack, stage, and logical ID. Changing it
* replaces the database.
*/
name?: string;
/**
* Name of the group the database is created in (e.g. `group.name`).
* Changing it replaces the database.
*/
group: string;
/**
* Seed the new database from an existing database or a pending upload.
* Only used when the database is created.
*/
seed?: DatabaseSeed;
/**
* Encrypt the database at rest with your own key. Only used when the
* database is created; changing it replaces the database. Requires a Pro
* or Enterprise plan.
*/
encryption?: DatabaseEncryption;
/**
* Maximum size of the database, in bytes or with a unit (e.g. `"256mb"`,
* `"1gb"`). When omitted, the current limit is left unchanged. Only
* legacy databases support it — Turso rejects it for databases created on
* the current platform ("size_limit is not supported for db-api
* controlled databases").
*/
sizeLimit?: string;
/**
* Allow other databases to be attached to this one with `ATTACH`. Not
* supported on AWS-hosted databases, which reject the setting.
* @default false
*/
allowAttach?: boolean;
/**
* Reject every read query.
* @default false
*/
blockReads?: boolean;
/**
* Reject every write query.
* @default false
*/
blockWrites?: boolean;
/**
* Prevent the database from being deleted. While enabled, destroying or
* replacing the database fails; set it to `false` and deploy first.
* @default false
*/
deleteProtection?: boolean;
/**
* IP addresses and CIDR blocks allowed to connect. Empty or omitted means
* no IP restriction. Requires a paid plan.
*/
allowedIps?: string[];
/**
* AWS VPC endpoint IDs (`vpce-...`) allowed to connect. Empty or omitted
* means no VPC endpoint restriction. Requires a paid plan.
*/
allowedAwsVpcIds?: string[];
/**
* SQL migrations to apply on deploy. Accepts a directory path, a
* `Drizzle.Schema` resource, or `{ dir, table? }`.
*
* Bookkeeping lives in Alchemy's `__alchemy_migrations` table. A database
* previously migrated by drizzle-kit is adopted by a one-way conversion on
* first deploy.
*/
migrations?: MigrationsInput;
/**
* Paths to additional `.sql` files to apply after migrations. Each file is
* hashed; only files whose contents change are re-applied.
*/
importFiles?: string[];
}
export interface DatabaseAttributes {
/** Database UUID. */
dbId: string;
/** Database name. */
name: string;
/** The organization slug that owns the database. */
organization: string;
/** Name of the group the database belongs to. */
group: string;
/** DNS hostname for libSQL and HTTP connections. */
hostname: string;
/** libSQL connection URL (`libsql://<hostname>`), for `@libsql/client`. */
url: string;
/** HTTPS URL (`https://<hostname>`) of the Hrana-over-HTTP endpoint. */
httpUrl: string;
/** Primary location of the database. */
primaryRegion: string;
/** Every location the database runs in. */
regions: string[];
/** Maximum database size, or `undefined` when unlimited. */
sizeLimit: string | undefined;
/** Whether other databases may be attached. */
allowAttach: boolean;
/** Whether reads are blocked. */
blockReads: boolean;
/** Whether writes are blocked. */
blockWrites: boolean;
/** Whether delete protection is enabled. */
deleteProtection: boolean;
/** IP addresses and CIDR blocks allowed to connect. */
allowedIps: string[];
/** AWS VPC endpoint IDs allowed to connect. */
allowedAwsVpcIds: string[];
/** Directory containing migration files, if configured. */
migrationsDir: string | undefined;
/** Table used to track applied migrations, if configured. */
migrationsTable: string | undefined;
/** Content hashes for the last applied migration files. */
migrationsHashes: Record<string, string>;
/** Content hashes for the last applied import files. */
importHashes: Record<string, string>;
}
export type Database = Resource<
"Turso.Database",
DatabaseProps,
DatabaseAttributes,
never,
Providers
>;
/**
* A Turso database: a SQLite database that lives in a {@link Group}.
* Connect to it from a Worker or Lambda with {@link Connect}, or create a
* {@link DatabaseToken} for other apps.
* @see https://docs.turso.tech/concepts#databases
*
* ### Creating a Database
* **Example:** Database in a group
* ```typescript
* const group = yield* Turso.Group("Group", { location: "aws-us-east-1" });
* const db = yield* Turso.Database("Db", { group: group.name });
* ```
*
* **Example:** Database with delete protection and an IP allowlist
* ```typescript
* const db = yield* Turso.Database("Db", {
* group: group.name,
* deleteProtection: true,
* allowedIps: ["203.0.113.0/24"],
* });
* ```
*
* ### Branching
* **Example:** Copy an existing database
* ```typescript
* const preview = yield* Turso.Database("Preview", {
* group: group.name,
* seed: { type: "database", name: db.name },
* });
* ```
*
* ### Migrations
* Point `migrations` at a folder of `.sql` files (or a `Drizzle.Schema`).
* Pending migrations are applied in order on each deploy.
*
* **Example:** Apply migrations from a directory
* ```typescript
* const db = yield* Turso.Database("Db", {
* group: group.name,
* migrations: "./migrations",
* });
* ```
*
* **Example:** Seed with SQL files
* ```typescript
* const db = yield* Turso.Database("Db", {
* group: group.name,
* importFiles: ["./seed/users.sql"],
* });
* ```
*
* ### Querying from a Worker
* **Example:** Drizzle over a Turso database
* ```typescript
* const conn = yield* Turso.Connect(Db);
* const db = yield* Drizzle.LibSQL(conn);
* ```
*
* @resource
* @product Database
*/
export const Database = Resource<Database>("Turso.Database");
const databaseName = (id: string, name: string | undefined) =>
name
? Effect.succeed(name)
: createPhysicalName({ id, lowercase: true, maxLength: 32, delimiter: "-" });
const rootDir = Effect.sync(() => process.cwd());
/**
* Run `use` against a short-lived (10 minute) full-access database token,
* for deploy-time SQL (migrations and imports).
*/
const withConnection = <A, E, R>(
org: string,
database: { name: string; hostname: string },
use: (connection: Hrana.HranaConnection, client: HttpClient.HttpClient) => Effect.Effect<A, E, R>,
) =>
Effect.gen(function* () {
const client = yield* HttpClient.HttpClient;
const { jwt } = yield* turso.createDatabaseToken({
organizationSlug: org,
databaseName: database.name,
expiration: "10m",
authorization: "full-access",
});
if (!jwt) {
return yield* new DatabaseUnexpectedResponse({
message: `Turso returned no token for ${database.name}`,
});
}
return yield* use({ url: `https://${database.hostname}`, authToken: jwt }, client);
});
export const DatabaseProvider = () =>
Provider.effect(
Database,
Effect.gen(function* () {
const observe = (org: string, name: string) =>
turso.getDatabase({ organizationSlug: org, databaseName: name }).pipe(
Effect.map((res) => res.database),
Effect.catchTag("NotFound", () => Effect.undefined),
);
const toAttrs = (
org: string,
db: turso.Database,
config: turso.DatabaseConfigurationResponse,
rest: Pick<
DatabaseAttributes,
"migrationsDir" | "migrationsTable" | "migrationsHashes" | "importHashes"
>,
): DatabaseAttributes => ({
dbId: db.DbId ?? "",
name: db.Name!,
organization: org,
group: db.group ?? "",
hostname: db.Hostname ?? "",
url: `libsql://${db.Hostname}`,
httpUrl: `https://${db.Hostname}`,
primaryRegion: db.primaryRegion ?? "",
regions: db.regions ?? [],
sizeLimit: config.size_limit || undefined,
allowAttach: config.allow_attach ?? false,
blockReads: config.block_reads ?? false,
blockWrites: config.block_writes ?? false,
deleteProtection: config.delete_protection ?? false,
allowedIps: config.allowed_ips ?? [],
allowedAwsVpcIds: config.allowed_aws_vpc_ids ?? [],
...rest,
});
const getConfig = (org: string, name: string) =>
turso.getDatabaseConfiguration({ organizationSlug: org, databaseName: name });
return {
stables: ["dbId", "name", "organization", "group", "hostname", "url", "httpUrl"],
diff: Effect.fn(function* ({ id, olds, news, output }) {
if (!isResolved(news)) return undefined;
const name = output?.name ?? (yield* databaseName(id, olds?.name));
if (news.name !== undefined && news.name !== name) {
return { action: "replace" } as const;
}
if (news.group !== (output?.group ?? olds?.group)) {
return { action: "replace", deleteFirst: news.name !== undefined } as const;
}
if (
news.encryption?.cipher !== olds?.encryption?.cipher ||
(news.encryption &&
olds?.encryption &&
Redacted.value(news.encryption.key) !== Redacted.value(olds.encryption.key))
) {
return { action: "replace", deleteFirst: news.name !== undefined } as const;
}
if (yield* diffMigrations({ news, output })) {
return { action: "update" } as const;
}
if (news.importFiles?.length) {
const hashes = yield* hashImports(news.importFiles, yield* rootDir);
if (!deepEqual(hashes, output?.importHashes ?? {})) {
return { action: "update" } as const;
}
}
}),
read: Effect.fn(function* ({ id, olds, output, previous }) {
const org = output?.organization ?? (yield* organization);
const name = output?.name ?? (yield* databaseName(id, olds?.name));
const db = yield* observe(org, name);
if (!db) return undefined;
const attrs = toAttrs(org, db, yield* getConfig(org, name), {
migrationsDir: output?.migrationsDir,
migrationsTable: output?.migrationsTable,
migrationsHashes: output?.migrationsHashes ?? {},
importHashes: output?.importHashes ?? {},
});
// Turso has no tags: a database found under an explicit,
// user-chosen name without prior state may belong to someone else — unless it
// is the generation a delete-first replacement is about to free.
const ours =
output !== undefined ||
olds?.name === undefined ||
(previous?.organization === org && previous.name === name);
return ours ? attrs : Unowned(attrs);
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const org = output?.organization ?? (yield* organization);
const name = output?.name ?? (yield* databaseName(id, news.name));
// Observe
let db = yield* observe(org, name);
// Ensure
if (!db) {
yield* session.note(`Creating database ${name}...`);
yield* turso
.createDatabase({
organizationSlug: org,
name,
group: news.group,
seed: news.seed,
size_limit: news.sizeLimit,
remote_encryption: news.encryption
? {
encryption_key: Redacted.value(news.encryption.key),
encryption_cipher: news.encryption.cipher,
}
: undefined,
})
.pipe(Effect.catchTag("Conflict", () => Effect.void));
db = yield* observe(org, name);
if (!db) {
return yield* new DatabaseUnexpectedResponse({
message: `Turso database ${name} vanished after create`,
});
}
}
// Sync configuration — diff observed settings against desired
// and PATCH only the fields that differ.
let config = yield* getConfig(org, name);
const patch: Omit<turso.UpdateDatabaseConfigurationRequest, "organizationSlug"> = {
databaseName: name,
};
let dirty = false;
const set = <K extends keyof typeof patch>(
key: K,
observed: unknown,
desired: (typeof patch)[K],
) => {
if (!deepEqual(observed, desired)) {
patch[key] = desired;
dirty = true;
}
};
if (news.sizeLimit !== undefined) set("size_limit", config.size_limit, news.sizeLimit);
// AWS-hosted databases reject `allow_attach` outright, so it is
// only sent when explicitly configured.
if (news.allowAttach !== undefined) {
set("allow_attach", config.allow_attach ?? false, news.allowAttach);
}
set("block_reads", config.block_reads ?? false, news.blockReads ?? false);
set("block_writes", config.block_writes ?? false, news.blockWrites ?? false);
set(
"delete_protection",
config.delete_protection ?? false,
news.deleteProtection ?? false,
);
set("allowed_ips", config.allowed_ips ?? [], news.allowedIps ?? []);
set("allowed_aws_vpc_ids", config.allowed_aws_vpc_ids ?? [], news.allowedAwsVpcIds ?? []);
if (dirty) {
config = yield* turso.updateDatabaseConfiguration({ organizationSlug: org, ...patch });
}
// Sync schema — migrations, then SQL imports.
const target = { name, hostname: db.Hostname! };
const migrationsInput = migrationsInputOf(news);
const migrations = migrationsInput
? yield* runMigrations({
input: migrationsInput,
stamped: stampedOf(output),
withExecutor: (apply) =>
withConnection(org, target, (connection, client) =>
apply(Hrana.makeMigrationExecutor(connection, client)),
),
})
: undefined;
const importHashes = yield* applySqlImports({
importFiles: news.importFiles,
rootDir: yield* rootDir,
previous: output?.importHashes,
apply: (file) =>
session
.note(`Importing ${file.id}...`)
.pipe(
Effect.andThen(
withConnection(org, target, (connection, client) =>
Hrana.transaction(connection, splitSqlStatements(file.sql)).pipe(
Effect.provideService(HttpClient.HttpClient, client),
),
),
),
),
});
return toAttrs(org, db, config, {
...migrationsAttrs({ input: migrationsInput, run: migrations, output }),
importHashes,
});
}),
delete: Effect.fn(function* ({ output }) {
yield* turso
.deleteDatabase({ organizationSlug: output.organization, databaseName: output.name })
.pipe(Effect.catchTag("NotFound", () => Effect.void));
}),
list: Effect.fn(function* () {
const org = yield* organization;
const { databases } = yield* turso.listDatabases({ organizationSlug: org });
return (databases ?? [])
.filter((db) => db.Name !== undefined)
.map((db) =>
toAttrs(
org,
db,
{
allow_attach: db.allow_attach,
block_reads: db.block_reads,
block_writes: db.block_writes,
delete_protection: db.delete_protection,
},
{
migrationsDir: undefined,
migrationsTable: undefined,
migrationsHashes: {},
importHashes: {},
},
),
);
}),
};
}),
);