feat(sqlite): add bun:sqlite compatibility

Author: Ralph Küpper

changelog.d/8525-bun-sqlite.md

@@ -0,0 +1,8 @@
+### Added
+
+- Add a native `bun:sqlite` compatibility facade backed by the same rusqlite
+  engine as Perry's `node:sqlite` implementation. `Database` construction,
+  prepared statements, positional and named parameters, object and array row
+  modes, blobs, safe integers, transactions, change metadata, serialization,
+  extension loading, and handle lifetime operations now support OpenCode's Bun
+  SQLite adapter without leaving an unresolved `bun:` import in the graph.

crates/perry-api-manifest/src/entries.rs

@@ -59,6 +59,7 @@ pub const NATIVE_MODULES: &[&str] = &[
     // #6562: Bun FFI (C-ABI). The `bun:` prefix is part of the specifier
     // (unlike `node:`, which is stripped) — `import { dlopen } from "bun:ffi"`.
     "bun:ffi",
+    "bun:sqlite", // Bun facade over Perry's native SQLite engine
     "node-cron",  // cron-style scheduler (npm node-cron; aliases `cron`)
     "nodemailer", // SMTP email sending
     // ── Node.js builtin modules ──

crates/perry-api-manifest/src/entries/part_1.rs

@@ -230,6 +230,26 @@ pub(crate) const API_MANIFEST_PART_1: &[ApiEntry] = &[
         .stub_note("stage ≥2 — not yet implemented, throws at runtime (#6562)"),
     method("bun:ffi", "read", false, None)
         .stub_note("stage ≥2 — not yet implemented, throws at runtime (#6562)"),
+    // bun:sqlite (#8510) shares node:sqlite's rusqlite handles while keeping
+    // Bun's public constructor and statement vocabulary.
+    class("bun:sqlite", "Database"),
+    class("bun:sqlite", "Statement"),
+    method("bun:sqlite", "Database", false, None),
+    method("bun:sqlite", "query", true, Some("Database")),
+    method("bun:sqlite", "prepare", true, Some("Database")),
+    method("bun:sqlite", "run", true, Some("Database")),
+    method("bun:sqlite", "close", true, Some("Database")),
+    method("bun:sqlite", "serialize", true, Some("Database")),
+    method("bun:sqlite", "loadExtension", true, Some("Database")),
+    method("bun:sqlite", "transaction", true, Some("Database")),
+    property("bun:sqlite", "filename"),
+    property("bun:sqlite", "inTransaction"),
+    method("bun:sqlite", "run", true, Some("Statement")),
+    method("bun:sqlite", "get", true, Some("Statement")),
+    method("bun:sqlite", "all", true, Some("Statement")),
+    method("bun:sqlite", "values", true, Some("Statement")),
+    method("bun:sqlite", "safeIntegers", true, Some("Statement")),
+    method("bun:sqlite", "finalize", true, Some("Statement")),
     class("sqlite", "DatabaseSync"),
     class("sqlite", "Session"),
     class("sqlite", "SQLTagStore"),

crates/perry-codegen/src/lower_call/builtin.rs

@@ -637,6 +637,29 @@ pub(super) fn lower_builtin_new<'a>(
             let handle = blk.call(I64, "js_pg_pool_new", &[(DOUBLE, &config_val)]);
             Ok(Some(nanbox_pointer_inline(blk, &handle)))
         }
+        // bun:sqlite Database — distinct internal name avoids colliding with
+        // better-sqlite3's exported `Database` while preserving full JS values
+        // for Bun's optional filename and flags object.
+        "BunSqliteDatabase" => {
+            let path_idx = adopt_optional_arg(ctx, args, 0, group)?;
+            let options_idx = adopt_optional_arg(ctx, args, 1, group)?;
+            let undef = || double_literal(f64::from_bits(crate::nanbox::TAG_UNDEFINED));
+            let path_value = match path_idx {
+                Some(i) => group.reread(ctx, i)?,
+                None => undef(),
+            };
+            let options_value = match options_idx {
+                Some(i) => group.reread(ctx, i)?,
+                None => undef(),
+            };
+            let blk = ctx.block();
+            let handle = blk.call(
+                I64,
+                "js_bun_sqlite_database_new",
+                &[(DOUBLE, &path_value), (DOUBLE, &options_value)],
+            );
+            Ok(Some(nanbox_pointer_inline(blk, &handle)))
+        }
         // better-sqlite3 Database — `new Database(filename)` opens a SQLite
         // connection. Without this, `new Database(...)` falls into lower_new's
         // empty-object placeholder, so `db` is a generic ObjectHeader pointer

crates/perry-codegen/src/lower_call/native_table/databases.rs

@@ -717,6 +717,133 @@ pub(super) const DATABASES_ROWS: &[NativeModSig] = &[
         args: &[],
         ret: NR_VOID,
     },
+    // ========== bun:sqlite ==========
+    NativeModSig {
+        module: "bun:sqlite",
+        has_receiver: false,
+        method: "Database",
+        class_filter: None,
+        runtime: "js_bun_sqlite_database_call",
+        args: &[NA_F64, NA_F64],
+        ret: NR_PTR,
+    },
+    NativeModSig {
+        module: "bun:sqlite",
+        has_receiver: true,
+        method: "query",
+        class_filter: Some("Database"),
+        runtime: "js_bun_sqlite_database_query",
+        args: &[NA_F64],
+        ret: NR_PTR,
+    },
+    NativeModSig {
+        module: "bun:sqlite",
+        has_receiver: true,
+        method: "prepare",
+        class_filter: Some("Database"),
+        runtime: "js_bun_sqlite_database_query",
+        args: &[NA_F64],
+        ret: NR_PTR,
+    },
+    NativeModSig {
+        module: "bun:sqlite",
+        has_receiver: true,
+        method: "run",
+        class_filter: Some("Database"),
+        runtime: "js_bun_sqlite_database_run",
+        args: &[NA_F64, NA_VARARGS],
+        ret: NR_PTR,
+    },
+    NativeModSig {
+        module: "bun:sqlite",
+        has_receiver: true,
+        method: "close",
+        class_filter: Some("Database"),
+        runtime: "js_node_sqlite_database_sync_close",
+        args: &[],
+        ret: NR_I32,
+    },
+    NativeModSig {
+        module: "bun:sqlite",
+        has_receiver: true,
+        method: "serialize",
+        class_filter: Some("Database"),
+        runtime: "js_node_sqlite_database_sync_serialize",
+        args: &[NA_F64],
+        ret: NR_PTR,
+    },
+    NativeModSig {
+        module: "bun:sqlite",
+        has_receiver: true,
+        method: "loadExtension",
+        class_filter: Some("Database"),
+        runtime: "js_node_sqlite_database_sync_load_extension",
+        args: &[NA_F64],
+        ret: NR_I32,
+    },
+    NativeModSig {
+        module: "bun:sqlite",
+        has_receiver: true,
+        method: "transaction",
+        class_filter: Some("Database"),
+        runtime: "js_bun_sqlite_database_transaction",
+        args: &[NA_F64],
+        ret: NR_PTR,
+    },
+    NativeModSig {
+        module: "bun:sqlite",
+        has_receiver: true,
+        method: "run",
+        class_filter: Some("Statement"),
+        runtime: "js_node_sqlite_statement_sync_run",
+        args: &[NA_VARARGS],
+        ret: NR_PTR,
+    },
+    NativeModSig {
+        module: "bun:sqlite",
+        has_receiver: true,
+        method: "get",
+        class_filter: Some("Statement"),
+        runtime: "js_node_sqlite_statement_sync_get",
+        args: &[NA_VARARGS],
+        ret: NR_F64,
+    },
+    NativeModSig {
+        module: "bun:sqlite",
+        has_receiver: true,
+        method: "all",
+        class_filter: Some("Statement"),
+        runtime: "js_node_sqlite_statement_sync_all",
+        args: &[NA_VARARGS],
+        ret: NR_PTR,
+    },
+    NativeModSig {
+        module: "bun:sqlite",
+        has_receiver: true,
+        method: "values",
+        class_filter: Some("Statement"),
+        runtime: "js_bun_sqlite_statement_values",
+        args: &[NA_VARARGS],
+        ret: NR_PTR,
+    },
+    NativeModSig {
+        module: "bun:sqlite",
+        has_receiver: true,
+        method: "safeIntegers",
+        class_filter: Some("Statement"),
+        runtime: "js_bun_sqlite_statement_safe_integers",
+        args: &[NA_F64],
+        ret: NR_F64,
+    },
+    NativeModSig {
+        module: "bun:sqlite",
+        has_receiver: true,
+        method: "finalize",
+        class_filter: Some("Statement"),
+        runtime: "js_bun_sqlite_statement_finalize",
+        args: &[],
+        ret: NR_VOID,
+    },
     // ========== node:sqlite ==========
     NativeModSig {
         module: "sqlite",

crates/perry-codegen/src/runtime_decls/stdlib_ffi/data_stores.rs

@@ -103,6 +103,19 @@ pub(crate) fn declare_data_stores(module: &mut LlModule) {
     module.declare_function("js_sqlite_transaction", I64, &[I64, I64]);
     module.declare_function("js_sqlite_transaction_commit", VOID, &[I64]);
     module.declare_function("js_sqlite_transaction_rollback", VOID, &[I64]);
+    module.declare_function("js_bun_sqlite_database_call", I64, &[DOUBLE, DOUBLE]);
+    module.declare_function("js_bun_sqlite_database_new", I64, &[DOUBLE, DOUBLE]);
+    module.declare_function("js_bun_sqlite_database_query", I64, &[I64, DOUBLE]);
+    module.declare_function("js_bun_sqlite_database_run", I64, &[I64, DOUBLE, I64]);
+    module.declare_function("js_bun_sqlite_database_filename", I64, &[I64]);
+    module.declare_function("js_bun_sqlite_database_transaction", I64, &[I64, DOUBLE]);
+    module.declare_function("js_bun_sqlite_statement_values", I64, &[I64, I64]);
+    module.declare_function(
+        "js_bun_sqlite_statement_safe_integers",
+        DOUBLE,
+        &[I64, DOUBLE],
+    );
+    module.declare_function("js_bun_sqlite_statement_finalize", VOID, &[I64]);
     module.declare_function("js_node_sqlite_backup", I64, &[DOUBLE, DOUBLE, DOUBLE]);
     module.declare_function("js_node_sqlite_database_sync_call", I64, &[DOUBLE, DOUBLE]);
     module.declare_function("js_node_sqlite_database_sync_new", I64, &[DOUBLE, DOUBLE]);

crates/perry-hir/src/js_transform/local_natives.rs

@@ -1151,6 +1151,31 @@ pub fn fix_native_instance_expr_with_locals(
             }
             fix_native_instance_expr_with_locals(inner, native_instances, local_id_instances);
         }
+        // #8510: the AST lowerer's any-receiver fallback folds a zero-argument
+        // `.values()` into ArrayValues before this pass knows that the local is
+        // a bun:sqlite Statement. Recover the native call once the statement
+        // result from Database.query()/prepare() has been tracked. Without
+        // this, `statement.values()` runs the Array iterator helper against a
+        // native statement handle and produces undefined rows.
+        Expr::ArrayValues(array) => {
+            if let Expr::LocalGet(local_id) = array.as_ref() {
+                if matches!(
+                    local_id_instances.get(local_id),
+                    Some((module, class)) if module == "bun:sqlite" && class == "Statement"
+                ) {
+                    let object = std::mem::replace(array.as_mut(), Expr::Undefined);
+                    *expr = Expr::NativeMethodCall {
+                        module: "bun:sqlite".to_string(),
+                        class_name: Some("Statement".to_string()),
+                        object: Some(Box::new(object)),
+                        method: "values".to_string(),
+                        args: Vec::new(),
+                    };
+                    return;
+                }
+            }
+            fix_native_instance_expr_with_locals(array, native_instances, local_id_instances);
+        }
         // Recurse into other expressions
         Expr::Binary { left, right, .. } => {
             fix_native_instance_expr_with_locals(left, native_instances, local_id_instances);
@@ -1398,6 +1423,9 @@ pub fn detect_native_instance_creation_with_context(
                 ("sqlite", "DatabaseSync", "createSession") => {
                     Some((module.clone(), "Session".to_string()))
                 }
+                ("bun:sqlite", "Database", "query" | "prepare") => {
+                    Some((module.clone(), "Statement".to_string()))
+                }
                 _ => None,
             }
         }
@@ -1434,6 +1462,9 @@ pub fn detect_native_instance_creation_with_context(
                             ("sqlite", "DatabaseSync", "createSession") => {
                                 Some((module.clone(), "Session".to_string()))
                             }
+                            ("bun:sqlite", "Database", "query" | "prepare") => {
+                                Some((module.clone(), "Statement".to_string()))
+                            }
                             _ => None,
                         };
                     }
@@ -1457,6 +1488,7 @@ pub fn detect_native_instance_creation_with_context(
                 "Database" => Some(("better-sqlite3".to_string(), "Database".to_string())),
                 "DatabaseSync" => Some(("sqlite".to_string(), "DatabaseSync".to_string())),
                 "StatementSync" => Some(("sqlite".to_string(), "StatementSync".to_string())),
+                "BunSqliteDatabase" => Some(("bun:sqlite".to_string(), "Database".to_string())),
                 _ => None,
             }
         }

crates/perry-hir/src/lower/expr_new.rs

@@ -73,6 +73,20 @@ pub(super) fn lower_new(ctx: &mut LoweringContext, new_expr: &ast::NewExpr) -> R
     }
 
     if let ast::Expr::Ident(callee_ident) = callee_expr {
+        // Keep Bun's `Database` distinct from better-sqlite3's same-named
+        // constructor while still allocating the shared native SQLite handle.
+        if matches!(
+            ctx.lookup_native_module(callee_ident.sym.as_ref()),
+            Some(("bun:sqlite", Some("Database")))
+        ) {
+            return Ok(Expr::New {
+                class_name: "BunSqliteDatabase".to_string(),
+                args: lower_optional_args(ctx, new_expr.args.as_deref())?,
+                type_args: Vec::new(),
+                byte_offset: new_byte_offset,
+                cap_args_appended: 0,
+            });
+        }
         let module_constructor = ctx
             .lookup_native_module(callee_ident.sym.as_ref())
             .map(|(module_name, method)| {

crates/perry-hir/src/lower/expr_new/member.rs

@@ -404,6 +404,15 @@ pub(crate) fn lower_new_member_native(
             }
             if let Some((module_name, _)) = ctx.lookup_native_module(module_alias) {
                 let class_name = prop_ident.sym.as_ref();
+                if module_name == "bun:sqlite" && class_name == "Database" {
+                    return Ok(Some(Expr::New {
+                        class_name: "BunSqliteDatabase".to_string(),
+                        args: lower_optional_args(ctx, new_expr.args.as_deref())?,
+                        type_args: Vec::new(),
+                        byte_offset: new_byte_offset,
+                        cap_args_appended: 0,
+                    }));
+                }
                 if matches!(
                     (module_name, class_name),
                     ("events", "EventEmitter")

crates/perry-hir/src/lower/tests.rs

@@ -646,6 +646,41 @@ fn test_perry_ui_state_value_uses_native_getter() {
     );
 }
 
+/// #8510: `.values()` on a bun:sqlite Statement is not Array.prototype.values.
+/// The statement is discovered by the post-lowering native-instance pass, so
+/// that pass must repair the eager any-receiver ArrayValues fold.
+#[test]
+fn test_bun_sqlite_statement_values_uses_native_dispatch() {
+    use crate::ir::clear_current_module_source;
+    use crate::js_transform::fix_local_native_instances;
+
+    let source = r#"
+        import { Database } from "bun:sqlite";
+        const db = new Database(":memory:");
+        const statement = db.query("SELECT 1");
+        const rows = statement.values();
+        console.log(rows[0][0]);
+    "#;
+    let module = perry_parser::parse_typescript(source, "bun_sqlite_values.ts")
+        .expect("source should parse");
+    let mut hir =
+        super::lower_module(&module, "test", "bun_sqlite_values.ts").expect("source should lower");
+    clear_current_module_source();
+    fix_local_native_instances(&mut hir);
+
+    let dump = format!("{hir:#?}");
+    assert!(
+        dump.contains("module: \"bun:sqlite\"")
+            && dump.contains("class_name: Some(\n                        \"Statement\"")
+            && dump.contains("method: \"values\""),
+        "Statement.values() must lower through bun:sqlite native dispatch: {dump}"
+    );
+    assert!(
+        !dump.contains("ArrayValues"),
+        "Statement.values() must not retain the Array iterator fold: {dump}"
+    );
+}
+
 /// #6642: the Widget `.addChild()` compatibility method must use the same
 /// native FFI dispatch as the canonical `widgetAddChild(parent, child)` free
 /// function, including for basic widget factories such as VStack and Text.