Choose a database

Simfinity 3.7.0 supports MongoDB and PostgreSQL through separate packages. Choose one when creating your application. The database adapter stays fixed for that deployment; this is not a runtime database switch or a MongoDB-to-PostgreSQL data migration tool.

Both adapters generate the same GraphQL operation names and input shapes from the same type registrations and relationship metadata. Validation, authorization, query scopes, controllers, state machines, and optional MCP use the shared API. Native database access and physical storage have the differences below.

	MongoDB	PostgreSQL
Application package	@simtlix/simfinity-js	@simtlix/simfinity-postgres
Start here	MongoDB quick start	PostgreSQL quick start
Storage	Mongoose models and MongoDB collections	Generated SQL schemas, tables, indexes, and constraints
Generated identity	MongoDB ObjectId, exposed as GraphQL ID	UUID, exposed as GraphQL ID
Single references and one-to-many	Mongoose references and generated resolvers	UUID reference columns with real foreign keys; inverse collections use the child's FK
Referential integrity	Optional transactional adapter enforcement, default off	Native database FKs
Batched collection reads	Opt-in with createMongoAdapter({ batchedCollections: true })	Opt-in with batchedCollections: true in createPostgres() or configure()
Many-to-many	Explicit link entity	Explicit link table with a foreign key for each reference
Embedded objects/lists	Embedded documents	JSONB for ordinary embedded trees; private owned tables for trees with references or unique fields
Native model access	Mongoose Model, documents and sessions	PostgresModel, plain records and PostgreSQL sessions
Database setup	Connect Mongoose before creating the GraphQL schema	Create the GraphQL schema, then await initializeDatabase({ mode: 'create' }) or read-only mode: 'validate'
MCP	Compatibility exports or optional MCP package	Optional @simtlix/simfinity-mcp package

PostgreSQL enforces generated FKs, required values, UUID/scalar types, and embedded integrity in the database. Its uniqueness rules are stronger than the indexes generated by the MongoDB facade. Read relationships, the PostgreSQL storage reference, and the compatibility contract for the exact boundaries.

To compare both backends in a complete app, run the Barber examples. They share a Next.js frontend and booking domain, with separate Docker stacks and native database implementations.

Version 3.3.0 also exposes a driver-free SQL core and PostgreSQL plugin. createPostgres remains supported and uses the same implementation; the plugin extraction preserves generated storage from 3.2.0.

Install from npm

Both adapters are released at v3.7.0. Choose one package in your application:

MongoDB

npm install @simtlix/simfinity-js@3.7.0 graphql@^16.11.0 mongoose@^8.24.2

PostgreSQL

npm install @simtlix/simfinity-postgres@3.7.0 graphql@^16.11.0 pg@^8.16.3

Shared core dependencies install automatically. Add @simtlix/simfinity-mcp@3.7.0 only when your PostgreSQL application exposes MCP tools; transport factories also require @modelcontextprotocol/sdk. See the MCP guide.

The optional MongoDB transactional reference integrity mode is available from 3.4.0.

Download the starters

Download both v3.7.0 starters. Extract the ZIP and choose one application:

MongoDB

cd simfinity-3.7.0-starters/mongodb
npm install
# Configure MongoDB using the MongoDB quick start.
npm start

PostgreSQL

cd simfinity-3.7.0-starters/postgres
npm install
# Set DATABASE_URL using the PostgreSQL quick start.
npm start

These starters require Node.js 22.15.0 or newer and pin all Simfinity packages to 3.7.0 on npm. Their manifests override @graphql-tools/utils to the patched ^12.0.1 range for Yoga; retain that override when copying the starter setup. Both manifests declare @simtlix/simfinity-core directly for shared helpers. MongoDB keeps reference integrity off by default; enable the transactional adapter when needed. PostgreSQL installs neither Mongoose nor MCP by default. For an existing application, review the upgrade notes before updating its dependencies.

The MongoDB example uses embedded seasons. The PostgreSQL example uses a one-to-many relation to demonstrate real generated FKs. That example choice accounts for their different nested inputs; both adapters support both relationship shapes. Use the operation shown in the corresponding quick start.

Verify the download

Download the ZIP SHA-256 checksum beside the ZIP and check it before extraction:

shasum -a 256 -c simfinity-3.7.0-starters.zip.sha256.txt

The v3.7.0 GitHub release contains the tagged source, package archives and integrity manifest. Keep installed Simfinity packages at the same version.

Runtime setup for shared examples

The topic guides use import { simfinity } from './runtime.js'. This is an application-owned module that exports your chosen runtime. Create one of the following files and register your types on that same instance:

MongoDB · runtime.js

import mongoose from 'mongoose';
import * as simfinity from '@simtlix/simfinity-js';

await mongoose.connect(process.env.MONGODB_URI);
export { simfinity };

PostgreSQL · runtime.js

import pg from 'pg';
import { createPostgres } from '@simtlix/simfinity-postgres';

export const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
export const simfinity = createPostgres({ pool, schema: 'series_api' });

The MongoDB facade registers its models on your application's default Mongoose instance and does not change global Mongoose options such as strictQuery. After all registrations, call simfinity.createSchema() once. PostgreSQL then requires await simfinity.initializeDatabase({ mode: 'create' }) before serving operations; use mode: 'validate' to check already provisioned storage without DDL. Close the PostgreSQL pool or disconnect Mongoose during shutdown.

The quick starts include their connection and runtime setup inline. When splitting them into modules, move that setup into runtime.js, keep schema registration in schema.js, and export schema only after initialization. Helper-only imports such as validators, scalars, errors, and auth come directly from @simtlix/simfinity-core; MCP functions come from @simtlix/simfinity-mcp.

Earlier downloads

The v3.6.0 starters (checksum) remain available with their original dependency pins.

The v3.5.9 starters (checksum) remain available with their original dependency pins.

The v3.5.8 starters (checksum) remain available with their original dependency pins.

The v3.5.7 starters (checksum) remain available with their original dependency pins.

The v3.5.6 starters (checksum) remain available with their original dependency pins.

The v3.5.3 starters (checksum) remain available with their original dependency pins.

The v3.5.2 starters (checksum) and v3.5.1 starters (checksum) remain available for applications pinned to those releases.

The v3.3.0 starters (checksum) and v3.2.0 starters (checksum) remain available as historical snapshots with their original dependency pins. New applications should use the current starters above.

For an application using the published 3.0.1 MongoDB release, the original MongoDB starter remains available. It pins @simtlix/simfinity-js to 3.0.1 and supports the MongoDB quick start's operations. The wider API reference documents v3.7.0 and may include APIs or fixes absent from 3.0.1.

Check compatibility and releases before upgrading an existing application. The Series Sample Project is a separate MongoDB application; it is not a PostgreSQL starter.

The original pre-release archive kit and its manifest remain available for reproducibility. That snapshot predates the final release documentation and has its own archive hashes. New applications should use npm or the released starters above.