@apostrophecms/db-connect

@apostrophecms/db-connect defines the database connection API for ApostropheCMS. It provides adapters for MongoDB, PostgreSQL, and SQLite, and includes the apos-db-dump and apos-db-restore command-line utilities for database migration and backup.

The db-connect API is compatible with a large subset of the MongoDB API. However, after this introductory note, this document describes the db-connect API on its own terms. For projects that need to work across all three databases, it is necessary to use only the functionality defined here.

Supported Connection URLs

MongoDB

mongodb://localhost:27017/mydb
mongodb+srv://user:[email protected]/mydb

Standard MongoDB connection strings. The MongoDB adapter is a thin wrapper around the existing driver.

PostgreSQL

postgres://localhost:5432/mydb

Single-database mode. All collections are stored as tables in the public schema.

SQLite

sqlite:///path/to/database.db

File-based SQLite databases using better-sqlite3. The parent directory is created if it does not exist.

Unlike the others, this is not really a URL: everything after sqlite:// is a filesystem path, taken exactly as written. That matters, because filesystem paths are not URLs — they are not percent-encoded, they may contain characters a URL parser treats as significant, and on Windows they begin with a drive letter that a URL parser reads as host:port. So do not percent-encode the path. A space is a space:

sqlite:///Users/jane/My Project/data/site.db

%20 here means a literal percent, two, zero — not a space. Both absolute and relative paths work, and on Windows both separators do:

sqlite:///var/lib/mysite/data.db          absolute (POSIX)
sqlite://data/site.db                     relative to the working directory
sqlite://C:\Users\jane\site\data\site.db  absolute (Windows)
sqlite://C:/Users/jane/site/data/site.db  absolute (Windows, forward slashes)
sqlite:///C:/Users/jane/site/data/site.db absolute (Windows, file:// spelling)

In-memory databases (sqlite://:memory:) are not supported — the adapter assumes a persistent store suitable for hosting an ApostropheCMS site.

Multi-Schema PostgreSQL (multipostgres)

multipostgres://localhost:5432/shareddb-tenant1

Designed for use with the ApostropheCMS multisite module. In this mode, each site gets its own PostgreSQL schema within a single physical database.

The URL path is split at the last hyphen:

• Everything before the last hyphen is the real PostgreSQL database name (shareddb)
• Everything after is the schema name (tenant1)

Each schema is created automatically on first use and dropped cleanly when the database is dropped. This provides true multi-tenant isolation — no cross-tenant data leakage — while sharing a single PostgreSQL instance efficiently.

Connecting

const connect = require('@apostrophecms/db-connect');

const client = await connect('postgres://localhost:5432/mydb');
const db = client.db();
const articles = db.collection('articles');

// Insert a document
const result = await articles.insertOne({ title: 'Hello', status: 'draft' });

// Query documents
const docs = await articles.find({ status: 'draft' })
  .sort({ title: 1 })
  .limit(10)
  .toArray();

// Update a document
await articles.updateOne(
  { _id: result.insertedId },
  { $set: { status: 'published' } }
);

await client.close();

connect(uri) returns a client. Call client.db() to get a database, then db.collection(name) to get a collection.

Atomicity

insertOne and deleteOne are always atomic.

updateOne without upsert is atomic when it uses only the following operators:

• $set, $inc, $unset, $currentDate — always atomic
• $push, $pull, $addToSet — atomic when all values are scalars (strings, numbers, booleans). Object or array values fall back to read-modify-write.

These operators can be freely combined in a single updateOne call and the entire update will be atomic. This covers the most common patterns: counters, status flags, timestamps, field cleanup, and adding/removing items to/from arrays.

The following operations are NOT guaranteed to be atomic and use a read-modify-write pattern (the document is read, the update is applied in JavaScript, and the result is written back):

• updateOne with $rename or upsert: true
• updateOne with $push, $pull, or $addToSet using non-scalar values
• updateMany, findOneAndUpdate, and replaceOne

For operations that must be atomic and aren't covered above, use advisory locking (apos.lock) to serialize access. Apostrophe core already uses advisory locking where atomicity matters (e.g., apos.lock.lock around critical sections).

API Reference

• Database and Client — client.db(name), listing collections, dropping databases
• Collection Methods — CRUD operations, cursors, and bulk writes
• Query Operators — filtering documents with comparison, logical, element, and array operators
• Update Operators — modifying documents with $set, $inc, $push, and more
• Indexes — creating and managing indexes, including numeric and date types
• Aggregation — pipeline stages and group accumulators
• Dump and Restore — CLI tools and programmatic API for backup and migration