Switch to Bun.sql + drizzle-orm v1 beta

[evantahler]

Summary

• Replace pg (node-postgres) with Bun's native SQL client (drizzle-orm/bun-sql) for PostgreSQL connections — drops pg and @types/pg dependencies
• Upgrade from drizzle-orm@0.45.x to drizzle-orm@1.0.0-beta.18
• Replace drizzle-zod with built-in drizzle-orm/zod (consolidated in v1)
• Migrate to drizzle v1 migration folder format (timestamp-prefixed directories, no more meta/_journal.json)
• Update scaffold/generator to produce v1-compatible migration structures

Breaking changes

• api.db.pool (pg.Pool) → api.db.client (Bun.SQL)
• drizzle-zod peer dep removed → use drizzle-orm/zod
• Existing projects must run drizzle-kit up --dialect postgresql --out drizzle to upgrade migration folders

Notable implementation detail

Bun.sql has a bug where rapidly creating and closing many SQL instances (e.g., in test suites that start/stop the server per file) causes "Failed query" errors. Worked around this by caching the SQL client instance and reusing it across start/stop cycles when the connection string hasn't changed.

Closes #263

Test plan

• All 312 package tests pass
• All 193 example backend tests pass
• Lint passes
• Full CI passes (bun run ci)
• Docs updated (initializers guide, utilities reference)

🤖 Generated with Claude Code

[theintjengineer]

I have been playing around with the file keryx/initializers/db.ts from the package itself; please take a look at the comments to see some modifications|comments|stuff I've observed [look for the ✅ marks].

import { $ } from "bun";
import { DefaultLogger, type LogWriter, sql } from "drizzle-orm";
import { drizzle } from "drizzle-orm/bun-sql";
import { migrate } from "drizzle-orm/bun-sql/migrator";
import fs from "node:fs";
import { unlink } from "node:fs/promises";
import path from "path";
import { SQL } from "bun";
import { api, logger } from "../api";
import { Initializer } from "../classes/Initializer";
import { ErrorType, TypedError } from "../classes/TypedError";
import { config } from "../config";
import { formatConnectionStringForLogging } from "../util/connectionString";

const namespace = "db";

declare module "../classes/API" {
  export interface API {
    [namespace]: Awaited<ReturnType<DB["initialize"]>>;
  }
}

export class DB extends Initializer {
  constructor() {
    super(namespace);
    this.loadPriority = 100;
    this.startPriority = 100;
    this.stopPriority = 910;
  }

  async initialize() {
    const dbContainer = {} as {
      db: ReturnType<typeof drizzle>;
      client: InstanceType<typeof SQL>;
    };
    return Object.assign(
      {
        generateMigrations: this.generateMigrations,
        clearDatabase: this.clearDatabase,
      },
      dbContainer,
    );
  }

  async start() {
    api.db.client = new SQL(config.database.connectionString);

    class DrizzleLogger implements LogWriter {
      write(message: string) {
        logger.debug(message);
      }
    }

    api.db.db = drizzle({
      client: api.db.client,
      logger: new DefaultLogger({ writer: new DrizzleLogger() }),
    });

    try {
      await api.db.db.execute(sql`SELECT NOW()`);
    } catch (e) {
      throw new TypedError({
        type: ErrorType.SERVER_INITIALIZATION,
        message: `Cannot connect to database (${formatConnectionStringForLogging(config.database.connectionString)}): ${e}`,
      });
    }

    if (config.database.autoMigrate) {
      try {
        const migrationsFolder = path.join(api.rootDir, "drizzle");
        const journalPath = path.join(
          migrationsFolder,
          "meta",
          "_journal.json",
        );
        if (!fs.existsSync(journalPath)) {
          fs.mkdirSync(path.dirname(journalPath), { recursive: true });
          fs.writeFileSync(journalPath, JSON.stringify({ entries: [] }));
          logger.info("created empty drizzle migrations journal");
        }
        // ✅ MOD 1: Pass object with migrationsFolder property
        // `migrate()` from drizzle-orm/bun-sql/migrator expects an object with migrationsFolder property,
        // not just a string path --> { migrationsFolder }
        await migrate(api.db.db, { migrationsFolder });
        logger.info("database migrated successfully");
      } catch (e) {
        throw new TypedError({
          type: ErrorType.SERVER_INITIALIZATION,
          message: `Cannot migrate database (${formatConnectionStringForLogging(config.database.connectionString)}): ${e}`,
        });
      }
    }

    logger.info(
      `database connection established (${formatConnectionStringForLogging(config.database.connectionString)})`,
    );
  }

  async stop() {
    if (api.db.db && api.db.client) {
      try {
        await api.db.client.close();
        logger.info("database connection closed");
      } catch (e) {
        logger.error("error closing database connection", e);
      }
    }
  }

  /**
   * Generate migrations for the database schema.
   */
  async generateMigrations() {
    // ✅ MOD 2: Use `defineConfig` from `drizzle-kit` instead of the `Config` type
    // - the `url` property isn't recognized in the `DrizzleMigrateConfig` type
    // - for Bun SQL, we need a different approach
    // - also, see comment at the end of the file
    const migrationConfig = {
      dialect: "postgresql" as const,
      schema: path.join(api.rootDir, "schema", "*"),
      driver: "bun" as const, // ✅ Specify Bun driver
      dbCredentials: {
        url: config.database.connectionString,
      },
      out: path.join(api.rootDir, "drizzle"),
    };

    const fileContent = `export default ${JSON.stringify(migrationConfig, null, 2)}`;
    const tmpfilePath = path.join(api.rootDir, "drizzle", "config.tmp.ts");

    try {
      await Bun.write(tmpfilePath, fileContent);
      const { exitCode, stdout, stderr } =
        await $`bun drizzle-kit generate --config ${tmpfilePath}`;
      logger.trace(stdout.toString());
      if (exitCode !== 0) {
        {
          throw new TypedError({
            message: `Failed to generate migrations: ${stderr.toString()}`,
            type: ErrorType.SERVER_INITIALIZATION,
          });
        }
      }
    } finally {
      const filePointer = Bun.file(tmpfilePath);
      if (await filePointer.exists()) await unlink(tmpfilePath);
    }
  }

  /**
   * Erase all the tables in the active database.
   */
  async clearDatabase(restartIdentity = true, cascade = true) {
    if (Bun.env.NODE_ENV === "production") {
      throw new TypedError({
        message: "clearDatabase cannot be called in production",
        type: ErrorType.SERVER_INITIALIZATION,
      });
    }

    const result = await api.db.db.execute(
      sql`SELECT tablename FROM pg_tables WHERE schemaname = CURRENT_SCHEMA`,
    );

    for (const row of result) {
      logger.debug(`truncating table ${row.tablename}`);
      await api.db.db.execute(
        sql.raw(
          `TRUNCATE TABLE "${row.tablename}" ${restartIdentity ? "RESTART IDENTITY" : ""} ${cascade ? "CASCADE" : ""} `,
        ),
      );
    }
  }
}

extra comments

// before, we had something like
const migrationConfig: DrizzleMigrateConfig = {
  dialect: "postgresql" as const,
  schema: path.join("schema", "*"),
  dbCredentials: {
    url: config.database.connectionString,
  },
  out: path.join("drizzle"),
};

// after:
const migrationConfig = {
  dialect: "postgresql" as const,
  schema: path.join(api.rootDir, "schema", "*"),
  driver: "bun" as const, // Required for Bun SQL
  dbCredentials: {
    url: config.database.connectionString,
  },
  out: path.join(api.rootDir, "drizzle"),
};

I, basically,

• removed the DrizzleMigrateConfig type annotation [it doesn’t support Bun driver yet]
  • I don't fully like this, as we lose to type annotation, but we can think of a cleaner variant later on
    • maybe extend DrizzleMigrateConfig, or create an issue on Drizzle's GitHub, or create our own interface for the config so we can also remove those consts, etc., whatever; at least now I've got an idea about the stuff that works|doesn't work
• added the driver: "bun" property ⟹ tells drizzle-kit to use Bun’s native driver
• used api.rootDir for absolute paths [important for schema and out directories]

Also, the url in dbCredentials is valid when we specify driver: "bun"; there was an error there when I was trying things out, and was using the Config type; basically, drizzle-kit's Config type somehow doesn’t fully support the Bun driver yet, but the runtime itself does.

I used this file with the project generated by the CLI itself¹ and the full integration worked—creating a user, creating a session, getting the user session, destroying the session, ensuring there's no user session—worked.

It's not production ready haha, but it highlights some of the stuff one could take note of|pay attention to when implementing the version with Bun's native SQL driver.

Anyway. Looking forward to seeing this becoming more and more Bun-native.

Cheers!
TIE

Footnotes

1. The only thing I changed in the project was changing the 3rd argument of pgTable() in schema/users.ts, since the deprecated warning was driving me crazy haha; but that's unrelated to the SQL driver we're talking about. ↩

[evantahler]

Thanks for this! Would you be able to make this a PR so we can see the diff and comment line-by-line?

[theintjengineer]

Evan, check this https://github.com/theintjengineer/tie-keryx, if you can.
Cheers.

[evantahler]

@theintjengineer I think I missing the meta about your PR. What problem are you trying to solve or feature are your adding? I'm missing something...

[evantahler]

The changes in #285 will confound this work a bit further