tests: add way to run all tests with postgres though slow

Also adding note that postgres is not in active use so might not work out the box

Author: Salazareo

config.template.jsonc

@@ -161,6 +161,15 @@
     "database": {
         // `sqlite` for single-node/dev, `mysql` for MariaDB/MySQL,
         // or `postgres` for PostgreSQL.
+        //
+        // NOTE: `postgres` support is a community contribution and is not
+        // exercised by Puter.com production. It boots, passes its own
+        // integration tests against pgmock, and runs the common user/app/
+        // fsentry/session/permission/OIDC flows — but less-traveled code
+        // paths may surface MySQL/SQLite-isms that haven't been ported yet.
+        // Expect rough edges and please file issues if you hit one. For
+        // production self-hosting today, `mysql` (MariaDB) and `sqlite` are
+        // the supported defaults.
         "engine": "sqlite",
         // sqlite — file path on disk
         "path": "volatile/runtime/puter-database.sqlite",

doc/self-hosting.md

@@ -234,6 +234,8 @@ All optional. Drop any of the blocks below into `puter/config/config.json` and `
 
 ### PostgreSQL database
 
+> **Community contribution — expect rough edges.** PostgreSQL support was contributed by the community and is not run by Puter.com production. It boots, applies the bundled schema, and exercises the common user/app/fsentry/session/permission/OIDC flows in the integration tests, but less-traveled SQL call sites may still need porting. If you hit a query that doesn't work on Postgres, please open an issue. For production self-hosting today, MariaDB/MySQL and SQLite are the supported defaults.
+
 The bundled Docker Compose stack still defaults to MariaDB. To use PostgreSQL instead, run a PostgreSQL service yourself, point Puter at it, and use the PostgreSQL migration path:
 
 ```json

package.json

@@ -45,6 +45,7 @@
   },
   "scripts": {
     "test:backend": "vitest run --config src/backend/vitest.config.ts ",
+    "test:backend:postgres": "PUTER_TEST_DB_ENGINE=postgres vitest run --config src/backend/vitest.config.ts ",
     "start=gui": "nodemon --exec \"node dev-server.js\" ",
     "start": "node --enable-source-maps -r ./dist/src/backend/telemetry.js ./dist/src/backend/index.js",
     "prestart": "npm run build:ts",

src/backend/testUtil.ts

@@ -66,6 +66,28 @@ export const createPgMockPostgresDatabaseClient = async (
     };
 };
 
+/**
+ * When `PUTER_TEST_DB_ENGINE=postgres` is set, `setupTestServer` swaps its
+ * default sqlite test database for an in-memory Postgres backed by pgmock
+ * (with the bundled Postgres migrations applied on boot). Tests that
+ * explicitly override `database` still win — the env var only affects the
+ * implicit default used by callers that don't pass any DB overrides.
+ *
+ * Recognized values: `postgres` → pgmock. Anything else (including unset) →
+ * the original sqlite-in-memory default.
+ */
+const testDatabaseDefault = (): IConfig['database'] => {
+    const engine = (process.env.PUTER_TEST_DB_ENGINE ?? '').toLowerCase();
+    if (engine === 'postgres') {
+        return {
+            engine: 'postgres',
+            inMemory: true,
+            migrationPaths: [POSTGRES_TEST_MIGRATIONS_PATH],
+        };
+    }
+    return { engine: 'sqlite', inMemory: true };
+};
+
 export const setupTestServer = async (
     configOverrides?: IConfig,
 ): Promise<PuterServer> => {
@@ -80,7 +102,7 @@ export const setupTestServer = async (
         deepMerge(defaultConfig, {
             extensions: [],
             port: 0,
-            database: { engine: 'sqlite', inMemory: true },
+            database: testDatabaseDefault(),
             dynamo: { inMemory: true, bootstrapTables: true },
             redis: { useMock: true },
             s3: { localConfig: { inMemory: true } },

src/backend/vitest.config.ts

@@ -27,6 +27,16 @@ const isCi = process.env.CI === 'true';
 const backendDir = __dirname;
 const repoRoot = path.resolve(backendDir, '../..');
 
+// pgmock boots a WASM-emulated Postgres on every `setupTestServer()` call —
+// migrations alone take ~60s, and the WASM VM serializes badly across
+// concurrent emulator instances. So in pgmock mode we (a) bump hook/test
+// timeouts well beyond the 10s default and (b) disable file parallelism so
+// only one pgmock VM runs at a time. Tests still race their own logic
+// internally; we only serialize the *files*.
+const isPgmockMode =
+    (process.env.PUTER_TEST_DB_ENGINE ?? '').toLowerCase() === 'postgres';
+const pgmockTimeoutMs = 600_000;
+
 // Vite 8's oxc transform leaves TC39 stage-3 decorators in place
 // (used by `@Controller`/`@Post`), so they reach Node verbatim and
 // crash with "SyntaxError: Invalid or unexpected token". Pre-transform
@@ -72,6 +82,13 @@ export default defineConfig(({ mode }) => ({
     },
     test: {
         globals: true,
+        ...(isPgmockMode
+            ? {
+                  testTimeout: pgmockTimeoutMs,
+                  hookTimeout: pgmockTimeoutMs,
+                  fileParallelism: false,
+              }
+            : {}),
         coverage: {
             provider: 'v8',
             reporter: isCi