overwriteDatabaseFile

Replace the contents of the SQLite database file.

Usage

Access or destructure overwriteDatabaseFile from the SQLocal client.

import { SQLocal } from 'sqlocal';

const { overwriteDatabaseFile } = new SQLocal('database.sqlite3');

NOTE

If you are using the Kysely Query Builder or Drizzle ORM for type-safe queries, you will initialize the client with a child class of SQLocal. See the corresponding setup page. Usage is the same otherwise.

The overwriteDatabaseFile method takes a database file as a File, Blob, ReadableStream, ArrayBuffer, or Uint8Array object and returns a Promise to replace the SQLocal instance's associated database file with the one provided.

For example, you can download a database file from your server to replace the local file.

const response = await fetch('https://example.com/download?id=12345');
const databaseFile = await response.blob();
await overwriteDatabaseFile(databaseFile);

If the database file might be large, you could alternatively pass the ReadableStream from the response's body, and SQLocal will stream the database to the client in chunks.

const response = await fetch('https://example.com/download?id=12345');
const databaseStream = response.body;
if (databaseStream === null) throw new Error('No database found');
await overwriteDatabaseFile(databaseStream);

Or, your app may allow the user to import a database file through a form.

const fileInput = document.querySelector('input[type="file"]');
const databaseFile = fileInput.files[0];
await overwriteDatabaseFile(databaseFile);

The method also accepts a second, optional argument: a callback function to run after the overwrite but before connections from other SQLocal client instances are allowed to access the new database, a good time to run migrations.

await overwriteDatabaseFile(databaseFile, async () => {
	// Run your migrations
});

Since calling overwriteDatabaseFile will reset all connections to the database file, the onConnect hook will re-run on any SQLocal clients connected to the database when it is overwritten. The client that initiated the overwrite will have its onConnect hook run first, before the method's callback, and the other clients' onConnect hooks will run after the callback.