@barakxyz/better-sqlite3 12.6.2 → 12.8.0

package/lib/database.js

@@ -76,7 +76,9 @@ Database.prototype.prepare = wrappers.prepare;
 Database.prototype.transaction = require('./methods/transaction');
 Database.prototype.pragma = require('./methods/pragma');
 Database.prototype.backup = require('./methods/backup');
+Database.prototype.backupFrom = require('./methods/backupFrom');
 Database.prototype.serialize = require('./methods/serialize');
+Database.prototype.deserialize = require('./methods/deserialize');
 Database.prototype.function = require('./methods/function');
 Database.prototype.aggregate = require('./methods/aggregate');
 Database.prototype.table = require('./methods/table');

package/lib/methods/backupFrom.js

@@ -0,0 +1,31 @@
+'use strict';
+const { cppdb } = require('../util');
+
+/**
+ * Synchronous backup from another database to this database.
+ * Matches wa-sqlite's sqlite3.backup(dest, destName, source, sourceName) pattern.
+ *
+ * @param {Database} sourceDb - The source Database instance to backup from
+ * @param {string} [destName='main'] - The attached database name for destination
+ * @param {string} [srcName='main'] - The attached database name for source
+ * @returns {this} The database instance for chaining
+ */
+module.exports = function backupFrom(sourceDb, destName, srcName) {
+	// Validate sourceDb is a Database instance (must have cppdb symbol)
+	if (sourceDb == null || typeof sourceDb !== 'object' || !sourceDb[cppdb]) {
+		throw new TypeError('Expected first argument to be a Database instance');
+	}
+
+	// Validate optional string arguments
+	if (destName !== undefined && typeof destName !== 'string') {
+		throw new TypeError('Expected second argument to be a string');
+	}
+	if (srcName !== undefined && typeof srcName !== 'string') {
+		throw new TypeError('Expected third argument to be a string');
+	}
+
+	// Pass the native cppdb object from source, not the JS wrapper
+	// The C++ side unwraps it to get the Database pointer
+	this[cppdb].backupFrom(sourceDb[cppdb], destName, srcName);
+	return this;
+};

package/lib/methods/deserialize.js

@@ -0,0 +1,34 @@
+'use strict';
+const { cppdb } = require('../util');
+
+/**
+ * Deserialize a buffer into the database.
+ *
+ * Uses the safe pattern (matches wa-sqlite's import pattern):
+ * 1. Create temp in-memory database
+ * 2. Deserialize buffer into temp
+ * 3. Backup from temp to current database
+ * 4. Close temp database
+ *
+ * This preserves file-based persistence and works with both in-memory and file databases.
+ *
+ * @param {Buffer} buffer - The serialized database buffer
+ * @param {Object} [options] - Options object
+ * @param {string} [options.attached='main'] - The attached database name
+ * @returns {this} The database instance for chaining
+ */
+module.exports = function deserialize(buffer, options) {
+	if (options == null) options = {};
+
+	// Validate arguments
+	if (!Buffer.isBuffer(buffer)) throw new TypeError('Expected first argument to be a buffer');
+	if (typeof options !== 'object') throw new TypeError('Expected second argument to be an options object');
+
+	// Interpret and validate options
+	const attachedName = 'attached' in options ? options.attached : 'main';
+	if (typeof attachedName !== 'string') throw new TypeError('Expected the "attached" option to be a string');
+	if (!attachedName) throw new TypeError('The "attached" option cannot be an empty string');
+
+	this[cppdb].deserialize(buffer, attachedName);
+	return this; // Return the JS Database instance for chaining
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barakxyz/better-sqlite3",
-  "version": "12.6.2",
+  "version": "12.8.0",
   "description": "The fastest and simplest library for SQLite in Node.js. Fork with session extension enabled.",
   "homepage": "https://github.com/BarakXYZ/better-sqlite3",
   "author": "Joshua Wise <joshuathomaswise@gmail.com>",

package/src/objects/database.cpp

@@ -131,7 +131,9 @@ INIT(Database::Init) {
 	SetPrototypeMethod(isolate, data, t, "prepare", JS_prepare);
 	SetPrototypeMethod(isolate, data, t, "exec", JS_exec);
 	SetPrototypeMethod(isolate, data, t, "backup", JS_backup);
+	SetPrototypeMethod(isolate, data, t, "backupFrom", JS_backupFrom);
 	SetPrototypeMethod(isolate, data, t, "serialize", JS_serialize);
+	SetPrototypeMethod(isolate, data, t, "deserialize", JS_deserialize);
 	SetPrototypeMethod(isolate, data, t, "function", JS_function);
 	SetPrototypeMethod(isolate, data, t, "aggregate", JS_aggregate);
 	SetPrototypeMethod(isolate, data, t, "table", JS_table);
@@ -295,6 +297,176 @@ NODE_METHOD(Database::JS_serialize) {
 	);
 }
 
+NODE_METHOD(Database::JS_backupFrom) {
+	// Synchronous backup from another database to this database.
+	// Matches wa-sqlite's sqlite3.backup(dest, destName, source, sourceName) pattern.
+	// Uses SQLite backup API: sqlite3_backup_init, sqlite3_backup_step, sqlite3_backup_finish.
+
+	Database* destDb = Unwrap<Database>(info.This());
+	REQUIRE_DATABASE_OPEN(destDb);
+	REQUIRE_DATABASE_NOT_BUSY(destDb);
+	REQUIRE_DATABASE_NO_ITERATORS(destDb);
+
+	UseAddon;
+	UseIsolate;
+
+	// First argument: source Database object
+	// Validate using wa-sqlite's verifyDatabase pattern: check if pointer is in tracked set
+	if (info.Length() < 1 || !info[0]->IsObject()) {
+		ThrowTypeError("Expected first argument to be a Database instance");
+		return;
+	}
+	v8::Local<v8::Object> srcObj = info[0].As<v8::Object>();
+	if (srcObj->InternalFieldCount() < 1) {
+		ThrowTypeError("Expected first argument to be a Database instance");
+		return;
+	}
+	Database* srcDb = Unwrap<Database>(srcObj);
+	if (addon->dbs.find(srcDb) == addon->dbs.end()) {
+		ThrowTypeError("Expected first argument to be a Database instance");
+		return;
+	}
+	if (!srcDb->open) {
+		ThrowTypeError("The source database is closed");
+		return;
+	}
+
+	// Optional second argument: attached database name for destination (default "main")
+	v8::Local<v8::String> destName;
+	if (info.Length() > 1 && !info[1]->IsUndefined()) {
+		if (!info[1]->IsString()) {
+			ThrowTypeError("Expected second argument to be a string");
+			return;
+		}
+		destName = info[1].As<v8::String>();
+	} else {
+		destName = StringFromUtf8(isolate, "main", -1);
+	}
+	v8::String::Utf8Value dest_name(isolate, destName);
+
+	// Optional third argument: attached database name for source (default "main")
+	v8::Local<v8::String> srcName;
+	if (info.Length() > 2 && !info[2]->IsUndefined()) {
+		if (!info[2]->IsString()) {
+			ThrowTypeError("Expected third argument to be a string");
+			return;
+		}
+		srcName = info[2].As<v8::String>();
+	} else {
+		srcName = StringFromUtf8(isolate, "main", -1);
+	}
+	v8::String::Utf8Value src_name(isolate, srcName);
+
+	// Initialize backup: sqlite3_backup_init(dest, destName, source, sourceName)
+	sqlite3_backup* backup_handle = sqlite3_backup_init(destDb->db_handle, *dest_name, srcDb->db_handle, *src_name);
+	if (backup_handle == NULL) {
+		destDb->ThrowDatabaseError();
+		return;
+	}
+
+	// Copy all pages in one step (-1 = all pages)
+	int status = sqlite3_backup_step(backup_handle, -1);
+	sqlite3_backup_finish(backup_handle);
+
+	if (status != SQLITE_DONE) {
+		ThrowSqliteError(addon, sqlite3_errstr(status), status);
+		return;
+	}
+
+	info.GetReturnValue().Set(info.This());
+}
+
+NODE_METHOD(Database::JS_deserialize) {
+	// Deserialize a buffer into the current database using the safe pattern:
+	// 1. Create temp in-memory database
+	// 2. Deserialize buffer into temp
+	// 3. Backup from temp to current database
+	// 4. Close temp database
+	//
+	// This preserves file-based persistence and matches wa-sqlite's import pattern.
+
+	Database* db = Unwrap<Database>(info.This());
+	REQUIRE_DATABASE_OPEN(db);
+	REQUIRE_DATABASE_NOT_BUSY(db);
+	REQUIRE_DATABASE_NO_ITERATORS(db);
+
+	UseAddon;
+	UseIsolate;
+
+	// First argument: buffer containing serialized database
+	v8::Local<v8::Value> bufferArg = info[0];
+	if (!node::Buffer::HasInstance(bufferArg)) {
+		ThrowTypeError("Expected first argument to be a buffer");
+		return;
+	}
+	v8::Local<v8::Object> buffer = bufferArg.As<v8::Object>();
+
+	// Second argument: attached database name (default "main")
+	v8::Local<v8::String> attachedName;
+	if (info.Length() > 1 && !info[1]->IsUndefined()) {
+		if (!info[1]->IsString()) {
+			ThrowTypeError("Expected second argument to be a string");
+			return;
+		}
+		attachedName = info[1].As<v8::String>();
+	} else {
+		attachedName = StringFromUtf8(isolate, "main", -1);
+	}
+	v8::String::Utf8Value attached_name(isolate, attachedName);
+
+	// Step 1: Create a temporary in-memory database
+	sqlite3* temp_handle;
+	int status = sqlite3_open_v2(":memory:", &temp_handle, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, NULL);
+	if (status != SQLITE_OK) {
+		ThrowSqliteError(addon, "Failed to create temporary database", status);
+		return;
+	}
+
+	// Step 2: Deserialize the buffer into the temporary database
+	size_t length = node::Buffer::Length(buffer);
+	unsigned char* data = (unsigned char*)sqlite3_malloc64(length);
+	unsigned int flags = SQLITE_DESERIALIZE_FREEONCLOSE | SQLITE_DESERIALIZE_RESIZEABLE;
+
+	if (length) {
+		if (!data) {
+			sqlite3_close(temp_handle);
+			ThrowError("Out of memory");
+			return;
+		}
+		memcpy(data, node::Buffer::Data(buffer), length);
+	}
+
+	status = sqlite3_deserialize(temp_handle, "main", data, length, length, flags);
+	if (status != SQLITE_OK) {
+		sqlite3_close(temp_handle);
+		ThrowSqliteError(addon, status == SQLITE_ERROR ? "unable to deserialize database" : sqlite3_errstr(status), status);
+		return;
+	}
+
+	// Step 3: Backup from temp to current database (matches wa-sqlite backup pattern)
+	// sqlite3_backup_init(dest, destName, source, sourceName)
+	sqlite3_backup* backup_handle = sqlite3_backup_init(db->db_handle, *attached_name, temp_handle, "main");
+	if (backup_handle == NULL) {
+		sqlite3_close(temp_handle);
+		db->ThrowDatabaseError();
+		return;
+	}
+
+	// Copy all pages in one step (-1 = all pages)
+	status = sqlite3_backup_step(backup_handle, -1);
+	sqlite3_backup_finish(backup_handle);
+
+	// Step 4: Close temporary database
+	sqlite3_close(temp_handle);
+
+	if (status != SQLITE_DONE) {
+		ThrowSqliteError(addon, "Failed to restore database from buffer", status);
+		return;
+	}
+
+	info.GetReturnValue().Set(info.This());
+}
+
 NODE_METHOD(Database::JS_function) {
 	Database* db = Unwrap<Database>(info.This());
 	REQUIRE_ARGUMENT_FUNCTION(first, v8::Local<v8::Function> fn);

package/src/objects/database.hpp

@@ -80,7 +80,9 @@ private:
 	static NODE_METHOD(JS_prepare);
 	static NODE_METHOD(JS_exec);
 	static NODE_METHOD(JS_backup);
+	static NODE_METHOD(JS_backupFrom);
 	static NODE_METHOD(JS_serialize);
+	static NODE_METHOD(JS_deserialize);
 	static NODE_METHOD(JS_function);
 	static NODE_METHOD(JS_aggregate);
 	static NODE_METHOD(JS_table);

package/src/objects/session.cpp

@@ -30,6 +30,7 @@ INIT(Session::Init) {
 	v8::Local<v8::FunctionTemplate> t = NewConstructorTemplate(isolate, data, JS_new, "Session");
 	SetPrototypeMethod(isolate, data, t, "attach", JS_attach);
 	SetPrototypeMethod(isolate, data, t, "changeset", JS_changeset);
+	SetPrototypeMethod(isolate, data, t, "enable", JS_enable);
 	SetPrototypeMethod(isolate, data, t, "close", JS_close);
 	return t->GetFunction(OnlyContext).ToLocalChecked();
 }
@@ -92,6 +93,24 @@ NODE_METHOD(Session::JS_attach) {
 	}
 }
 
+NODE_METHOD(Session::JS_enable) {
+	Session* session = Unwrap<Session>(info.This());
+	if (!session->alive) return ThrowTypeError("The session has been closed");
+	REQUIRE_DATABASE_OPEN(session->db->GetState());
+
+	UseIsolate;
+
+	// Require a boolean argument (matches wa-sqlite API pattern)
+	if (info.Length() < 1 || !info[0]->IsBoolean()) {
+		return ThrowTypeError("Expected first argument to be a boolean");
+	}
+
+	int enable_flag = info[0]->BooleanValue(isolate) ? 1 : 0;
+	sqlite3session_enable(session->session_handle, enable_flag);
+
+	// Return void (matches wa-sqlite API)
+}
+
 // Custom destructor for sqlite3_free
 static void FreeSqliteMemory(char* data, void* hint) {
 	sqlite3_free(data);

package/src/objects/session.hpp

@@ -24,6 +24,7 @@ private:
 	static NODE_METHOD(JS_new);
 	static NODE_METHOD(JS_attach);
 	static NODE_METHOD(JS_changeset);
+	static NODE_METHOD(JS_enable);
 	static NODE_METHOD(JS_close);
 
 	Database* const db;