spooder 4.3.1 → 4.4.0

package/README.md

@@ -71,8 +71,6 @@ The `CLI` component of `spooder` is a global command-line tool for running serve
 	- [`set_cookie(res: Response, name: string, value: string, options?: CookieOptions)`](#api-state-management-set-cookie)
 	- [`get_cookies(source: Request | Response): Record<string, string>`](#api-state-management-get-cookies)
 - [API > Database Schema](#api-database-schema)
-	- [`db_update_schema_sqlite(db: Database, schema: string): Promise<void>`](#api-database-schema-db-update-schema-sqlite)
-	- [`db_init_schema_sqlite(db_path: string, schema: string): Promise<Database>`](#api-database-schema-db-init-schema-sqlite)
 
 # Installation
 
@@ -225,6 +223,10 @@ server.webhook(process.env.WEBHOOK_SECRET, '/webhook', payload => {
 });
 ```
 
+### Skip Updates
+
+In addition to being skipped in [dev mode](#cli-dev-mode), updates can also be skipped in production mode by passing the `--no-update` flag.
+
 <a id="cli-canary"></a>
 ## CLI > Canary
 
@@ -1325,13 +1327,52 @@ const cookies = get_cookies(req, true);
 
 `spooder` provides a straightforward API to manage database schema in revisions through source control.
 
+Database schema is updated with `db_update_schema_DRIVER` where `DRIVER` corresponds to the database driver being used.
+
 > [!NOTE]
-> Currently, only SQLite is supported. This may be expanded once Bun supports more database drivers.
+> Currently, only SQLite and MySQL are supported. This may be expanded once Bun supports more database drivers.
 
-<a id="api-database-schema-db-update-schema-sqlite"></a>
-### 🔧 `db_update_schema_sqlite(db: Database, schema: string): Promise<void>`
+```ts
+// sqlite example
+import { db_update_schema_sqlite } from 'spooder';
+import { Database } from 'bun:sqlite';
 
-`db_update_schema_sqlite` takes a [`Database`](https://bun.sh/docs/api/sqlite) instance and a schema directory.
+const db = new Database('./database.sqlite');
+await db_update_schema_sqlite(db, './schema');
+```
+
+```ts
+// mysql example
+import { db_update_schema_mysql } from 'spooder';
+import mysql from 'mysql2';
+
+const db = await mysql.createConnection({
+	// connection options
+	// see https://github.com/mysqljs/mysql#connection-options
+})
+```
+
+> [!IMPORTANT]
+> MySQL requires the optional dependency `mysql2` to be installed - this is not automatically installed with spooder. This will be replaced when bun:sql supports MySQL natively.
+
+Database initiation and schema updating can be streamlined with the `db_init_schema_DRIVER` functions. The following examples are equivalent to the above ones.
+
+```ts
+// sqlite example
+import { db_init_schema_sqlite } from 'spooder';
+const db = await db_init_schema_sqlite('./database.sqlite', './schema');
+```
+
+```ts
+// mysql example
+import { db_init_schema_mysql } from 'spooder';
+const db = await db_init_schema_mysql({
+	// connection options
+	// see https://github.com/mysqljs/mysql#connection-options
+}, './schema');
+```
+
+### Schema Files
 
 The schema directory is expected to contain an SQL file for each table in the database with the file name matching the name of the table.
 
@@ -1404,26 +1445,6 @@ try {
 }
 ```
 
-<a id="api-database-schema-db-init-schema-sqlite"></a>
-### 🔧 `db_init_schema_sqlite(db_path: string, schema: string): Promise<Database>`
-
-`db_init_schema_sqlite` exists as a convenience function to create a new database and apply the schema in one step.
-
-```ts
-import { db_init_schema_sqlite } from 'spooder';
-const db = await db_init_schema_sqlite('./database.sqlite', './schema');
-```
-
-The above is equivalent to the following.
-
-```ts
-import { db_update_schema_sqlite } from 'spooder';
-import { Database } from 'bun:sqlite';
-
-const db = new Database('./database.sqlite', { create: true });
-await db_update_schema_sqlite(db, './schema');
-```
-
 ## Legal
 This software is provided as-is with no warranty or guarantee. The authors of this project are not responsible or liable for any problems caused by using this software or any part thereof. Use of this software does not entitle you to any support or assistance from the authors of this project.
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "spooder",
 	"type": "module",
-	"version": "4.3.1",
+	"version": "4.4.0",
 	"exports": {
 		".": {
 			"bun": "./src/api.ts",
@@ -12,6 +12,9 @@
 	"devDependencies": {
 		"@types/bun": "^1.0.5"
 	},
+	"optionalDependencies": {
+		"mysql2": "^3.11.0"
+	},
 	"bin": {
 		"spooder": "./src/cli.ts"
 	}

package/src/api.ts

@@ -6,6 +6,16 @@ import { log } from './utils';
 import crypto from 'crypto';
 import { Blob } from 'node:buffer';
 import { Database } from 'bun:sqlite';
+import type * as mysql_types from 'mysql2/promise';
+
+let mysql: typeof mysql_types | undefined;
+try {
+	mysql = await import('mysql2/promise') as typeof mysql_types;
+} catch (e) {
+	// mysql2 optional dependency not installed.
+	// this dependency will be replaced once bun:sql supports mysql.
+	// db_update_schema_mysql and db_init_schema_mysql will throw.
+}
 
 export const HTTP_STATUS_CODE = http.STATUS_CODES;
 
@@ -207,6 +217,66 @@ export async function generate_hash_subs(length = 7, prefix = 'hash=', hashes?:
 }
 
 type Row_DBSchema = { db_schema_table_name: string, db_schema_version: number };
+type SchemaVersionMap = Map<string, number>;
+
+async function db_load_schema(schema_dir: string, schema_versions: SchemaVersionMap) {
+	const schema_out = [];
+	const schema_files = await fs.readdir(schema_dir);
+
+	for (const schema_file of schema_files) {
+		const schema_file_lower = schema_file.toLowerCase();
+		if (!schema_file_lower.endsWith('.sql'))
+			continue;
+
+		log('[{db}] parsing schema file {%s}', schema_file_lower);
+
+		const schema_name = path.basename(schema_file_lower, '.sql');
+		const schema_path = path.join(schema_dir, schema_file);
+		const schema = await fs.readFile(schema_path, 'utf8');
+
+		const revisions = new Map();
+		let current_rev_id = 0;
+		let current_rev = '';
+
+		for (const line of schema.split(/\r?\n/)) {
+			const rev_start = line.match(/^--\s*\[(\d+)\]/);
+			if (rev_start !== null) {
+				// New chunk definition detected, store the current chunk and start a new one.
+				if (current_rev_id > 0) {
+					revisions.set(current_rev_id, current_rev);
+					current_rev = '';
+				}
+
+				const rev_number = parseInt(rev_start[1]);
+				if (isNaN(rev_number) || rev_number < 1)
+					throw new Error(rev_number + ' is not a valid revision number in ' + schema_file_lower);
+				current_rev_id = rev_number;
+			} else {
+				// Append to existing revision.
+				current_rev += line + '\n';
+			}
+		}
+
+		// There may be something left in current_chunk once we reach end of the file.
+		if (current_rev_id > 0)
+			revisions.set(current_rev_id, current_rev);
+
+		if (revisions.size === 0) {
+			log('[{db}] {%s} contains no valid revisions', schema_file);
+			continue;
+		}
+
+		const current_schema_version = schema_versions.get(schema_name) ?? 0;
+		schema_out.push({
+			revisions,
+			name: schema_name,
+			current_version: current_schema_version,
+			chunk_keys: Array.from(revisions.keys()).filter(chunk_id => chunk_id > current_schema_version).sort((a, b) => a - b)
+		});
+	}
+
+	return schema_out;
+}
 
 export async function db_update_schema_sqlite(db: Database, schema_dir: string) {
 	log('[{db}] updating database schema for {%s}', db.filename);
@@ -228,67 +298,68 @@ export async function db_update_schema_sqlite(db: Database, schema_dir: string)
 			ON CONFLICT(db_schema_table_name) DO UPDATE SET db_schema_version = EXCLUDED.db_schema_version
 		`);
 
-		const schema_files = await fs.readdir(schema_dir);
-		for (const schema_file of schema_files) {
-			const schema_file_lower = schema_file.toLowerCase();
-			if (!schema_file_lower.endsWith('.sql'))
-				continue;
-
-			log('[{db}] parsing schema file {%s}', schema_file_lower);
-
-			const schema_name = path.basename(schema_file_lower, '.sql');
-			const schema_path = path.join(schema_dir, schema_file);
-			const schema = await fs.readFile(schema_path, 'utf8');
-
-			const revisions = new Map();
-			let current_rev_id = 0;
-			let current_rev = '';
-
-			for (const line of schema.split(/\r?\n/)) {
-				const rev_start = line.match(/^--\s*\[(\d+)\]/);
-				if (rev_start !== null) {
-					// New chunk definition detected, store the current chunk and start a new one.
-					if (current_rev_id > 0) {
-						revisions.set(current_rev_id, current_rev);
-						current_rev = '';
-					}
+		const schemas = await db_load_schema(schema_dir, schema_versions);
 
-					const rev_number = parseInt(rev_start[1]);
-					if (isNaN(rev_number) || rev_number < 1)
-						throw new Error(rev_number + ' is not a valid revision number in ' + schema_file_lower);
-					current_rev_id = rev_number;
-				} else {
-					// Append to existing revision.
-					current_rev += line + '\n';
-				}
+		for (const schema of schemas) {
+			let newest_schema_version = schema.current_version;
+			for (const rev_id of schema.chunk_keys) {
+				const revision = schema.revisions.get(rev_id);
+				log('[{db}] applying revision {%d} to {%s}', rev_id, schema.name);
+				db.transaction(() => db.run(revision))();
+				newest_schema_version = rev_id;
 			}
+	
+			if (newest_schema_version > schema.current_version) {
+				log('[{db}] updated table {%s} to revision {%d}', schema.name, newest_schema_version);
+				update_schema_query.run(newest_schema_version, schema.name);
+			}
+		}
+	})();
+}
 
-			// There may be something left in current_chunk once we reach end of the file.
-			if (current_rev_id > 0)
-				revisions.set(current_rev_id, current_rev);
+export async function db_update_schema_mysql(db: mysql_types.Connection, schema_dir: string) {
+	if (mysql === undefined)
+		throw new Error('{db_update_schema_mysql} cannot be called without optional dependency {mysql2} installed');
 
-			if (revisions.size === 0) {
-				log('[{db}] {%s} contains no valid revisions', schema_file);
-				continue;
-			}
+	log('[{db}] updating database schema for {%s}', db.config.database);
 
-			const current_schema_version = schema_versions.get(schema_name) ?? 0;
-			const chunk_keys = Array.from(revisions.keys()).filter(chunk_id => chunk_id > current_schema_version).sort((a, b) => a - b);
+	const schema_versions = new Map();
 
-			let newest_schema_version = current_schema_version;
-			for (const rev_id of chunk_keys) {
-				const revision = revisions.get(rev_id);
-				log('[{db}] applying revision {%d} to {%s}', rev_id, schema_name);
-				db.transaction(() => db.run(revision))();
-				newest_schema_version = rev_id;
-			}
+	try {
+		const [rows] = await db.query('SELECT db_schema_table_name, db_schema_version FROM db_schema');
+		for (const row of rows as Array<Row_DBSchema>)
+			schema_versions.set(row.db_schema_table_name, row.db_schema_version);
+	} catch (e) {
+		log('[{db}] creating {db_schema} table');
+		await db.query('CREATE TABLE db_schema (db_schema_table_name VARCHAR(255) PRIMARY KEY, db_schema_version INT)');
+	}
 
-			if (newest_schema_version > current_schema_version) {
-				log('[{db}] updated table {%s} to revision {%d}', schema_name, newest_schema_version);
-				update_schema_query.run(newest_schema_version, schema_name);
-			}
+	await db.beginTransaction();
+	
+	const update_schema_query = await db.prepare(`
+		INSERT INTO db_schema (db_schema_version, db_schema_table_name) VALUES (?, ?)
+		ON DUPLICATE KEY UPDATE db_schema_version = VALUES(db_schema_version);
+	`);
+
+	const schemas = await db_load_schema(schema_dir, schema_versions);
+	for (const schema of schemas) {
+		let newest_schema_version = schema.current_version;
+		for (const rev_id of schema.chunk_keys) {
+			const revision = schema.revisions.get(rev_id);
+			log('[{db}] applying revision {%d} to {%s}', rev_id, schema.name);
+
+			await db.query(revision);
+			newest_schema_version = rev_id;
 		}
-	})();
+
+		if (newest_schema_version > schema.current_version) {
+			log('[{db}] updated table {%s} to revision {%d}', schema.name, newest_schema_version);
+			
+			await update_schema_query.execute([newest_schema_version, schema.name]);
+		}
+	}
+
+	await db.commit();
 }
 
 export async function db_init_schema_sqlite(db_path: string, schema_dir: string): Promise<Database> {
@@ -297,6 +368,19 @@ export async function db_init_schema_sqlite(db_path: string, schema_dir: string)
 	return db;
 }
 
+export async function db_init_schema_mysql(db_info: mysql_types.ConnectionConfig, schema_dir: string): Promise<mysql_types.Connection> {
+	if (mysql === undefined)
+		throw new Error('{db_init_schema_mysql} cannot be called without optional dependency {mysql2} installed');
+
+	// required for parsing multiple statements from schema files
+	db_info.multipleStatements = true;
+
+	const db = await mysql.createConnection(db_info);
+	await db_update_schema_mysql(db, schema_dir);
+
+	return db;
+}
+
 type CookieOptions = {
 	same_site?: 'Strict' | 'Lax' | 'None',
 	secure?: boolean,

package/src/cli.ts

@@ -8,13 +8,18 @@ async function start_server() {
 
 	const argv = process.argv.slice(2);
 	const is_dev_mode = argv.includes('--dev');
+	const skip_updates = argv.includes('--no-update');
 
 	if (is_dev_mode)
 		log('[{dev}] spooder has been started in {dev mode}');
 
 	const config = await get_config();
 
-	if (!is_dev_mode) {
+	if (is_dev_mode) {
+		log('[{update}] skipping update commands in {dev mode}');
+	} else if (skip_updates) {
+		log('[{update}] skipping update commands due to {--no-update} flag');
+	} else {
 		const update_commands = config.update;
 		const n_update_commands = update_commands.length;
 
@@ -42,8 +47,6 @@ async function start_server() {
 				}
 			}
 		}
-	} else {
-		log('[{dev}] skipping update commands in {dev mode}');
 	}
 
 	const crash_console_history = config.canary.crash_console_history;