Try the demoGet Started

Choosing a database for your ApostropheCMS project

ApostropheCMS supports SQLite, PostgreSQL, and MongoDB, and all three run the same ApostropheCMS schemas and content APIs. The right choice depends less on how you model CMS content and more on how you develop, deploy, scale, and operate the project. In this guide, we'll cover the differences between them.

    • Beginner
    • 9 min read
    • Deployment and DevOps
    • Evaluation and Onboarding
    • Last Updated August 3, 2026

What you'll learn

  • Choose SQLite for the fastest local setup, evaluation, and small single-server projects.

  • Choose PostgreSQL when your team already operates it or wants to standardize on an open source relational database.

  • Choose MongoDB when you need the complete MongoDB API or want the database model with the longest history in ApostropheCMS.

  • Choose MongoDB Atlas when you want MongoDB without operating the database infrastructure yourself.

  • You can move an ApostropheCMS project between supported databases later using portable dump-and-restore tools.

Database options at a glance
Features
SQLite
PostgreSQL
MongoDB, self-hosted
MongoDB Atlas
Best for
Evaluation, local development, prototypes, and small single-server sites Production projects whose teams already use PostgreSQL or prefer open source relational infrastructure Teams that need the complete MongoDB API and have the expertise to operate MongoDB securely Production projects that want MongoDB with backups, monitoring, scaling, and availability handled as a service
Hosting model
A database file stored with the application Self-hosted or available from many cloud database providers Infrastructure managed by your team MongoDB's managed service on AWS, Azure, or Google Cloud
Managed?
Not included for SQLite Optional Not included for MongoDB, self-hosted Included for MongoDB Atlas

If you are evaluating ApostropheCMS, start with SQLite. For a new production project without an established database standard, MongoDB Atlas is the simplest general recommendation. If your organization already has PostgreSQL infrastructure and expertise, use PostgreSQL rather than introducing another database platform.

SQLite

What SQLite is

SQLite is an embedded, open source relational database. Unlike PostgreSQL and MongoDB, it runs inside the application process and writes to a file rather than communicating with a separate database server.

ApostropheCMS accesses SQLite through its @apostrophecms/db-connect compatibility layer. Your schemas, content queries, and normal module code work the same way as they do with the other supported databases.

Best for

SQLite is the right choice when you want to start an ApostropheCMS project without installing or connecting to a database server. It stores the database in a single local file, making it especially useful for evaluation, local development, prototypes, automated tests, and small sites deployed to one persistent server.

Choose SQLite when

  • You are trying ApostropheCMS and want the shortest path from installation to a working project.

  • You do not want every developer to install MongoDB or PostgreSQL locally.

  • You are building a prototype, demonstration, or automated test environment.

  • Your production site will run as a single application instance with persistent local storage.

  • Simple file-based backups fit your operational needs.

SQLite is an excellent default for local development even if the eventual production database will be PostgreSQL or MongoDB. ApostropheCMS provides portable database tools for moving content between backends.

Consider another database when

Avoid SQLite when your production architecture needs more than one ApostropheCMS application server. A database file on one server cannot act as shared storage for multiple application instances, and placing it on a network filesystem does not turn it into a replacement for a client-server database.

SQLite is also a poor fit when your hosting platform uses an ephemeral filesystem. If the application instance can be replaced and the database file is not on a persistent volume, the site's content can be lost.

Hosting and operations

SQLite does not require a separate database host or managed database account. The database file must live on persistent storage, be excluded from source control, and be included in your backup plan.

For production, confirm that your deployment platform preserves the file across releases, restarts, and server replacements. If you cannot guarantee that, choose PostgreSQL or MongoDB instead.

PostgreSQL

What PostgreSQL is

PostgreSQL is an open source relational database server. ApostropheCMS supports it through @apostrophecms/db-connect, which translates the database operations used by ApostropheCMS into PostgreSQL-compatible operations.

That adapter allows the same ApostropheCMS schemas, queries, cursors, and aggregations to work across PostgreSQL, SQLite, and MongoDB. Developers generally do not need to write SQL or change application code when selecting PostgreSQL.

Best for

PostgreSQL is the right choice when your team or hosting environment already standardizes on PostgreSQL. It gives ApostropheCMS projects a mature, open source client-server database with a broad choice of self-hosted and managed deployment options.

Choose PostgreSQL when

  • Your organization already hosts, monitors, and backs up PostgreSQL.

  • Your hosting provider has a preferred managed PostgreSQL service.

  • An open source database license is an organizational requirement.

  • You want a production database that can support multiple application instances.

For teams with existing PostgreSQL expertise, it is usually the most practical production choice. The operational knowledge and tooling you already have are more valuable than selecting a different database solely because it has a longer history with ApostropheCMS.

Consider another database when

Avoid PostgreSQL if custom project code or a third-party ApostropheCMS module depends on MongoDB features that db-connect does not implement. ApostropheCMS core and code written against its documented database patterns are supported, but db-connect does not reproduce the entire MongoDB API.

Examples of specialized MongoDB features that may not be portable include uncommon aggregation stages, server-side JavaScript, change streams, and some geospatial operators. Review the db-connect compatibility reference before committing to PostgreSQL if your project performs low-level database work.

Hosting and operations

You can install and operate PostgreSQL yourself, but managed PostgreSQL is available from most major cloud and database providers. A managed service can take responsibility for routine infrastructure work such as backups, patching, monitoring, replication, and failover, although the exact features depend on the provider and service tier.

For production, a managed PostgreSQL service is usually the better choice unless your organization already has a database operations team. Select a provider and region that keep the database close to the ApostropheCMS application to reduce latency and network costs.

Self-hosted MongoDB

What self-hosted MongoDB is

MongoDB is a document database that stores structured content as BSON documents. Its document model is a natural match for ApostropheCMS pages, pieces, areas, widgets, and fields, which can be represented together without translating them into conventional application tables.

MongoDB was ApostropheCMS's original database and remains its default backend. Like PostgreSQL and SQLite, it connects through @apostrophecms/db-connect, but as a thin wrapper around the native MongoDB driver rather than a translation layer, since db-connect's API is modeled directly on MongoDB's.

Best for

Self-hosted MongoDB is the right choice when your project needs direct access to the complete MongoDB API and your team is prepared to operate a production MongoDB deployment. It gives you maximum control, but it also gives you full responsibility for security, backups, monitoring, upgrades, replication, and recovery.

Choose self-hosted MongoDB when

  • Your custom code needs MongoDB operators or capabilities outside the db-connect compatibility layer.

  • Your organization already operates MongoDB reliably.

  • You need infrastructure, network, or deployment control that a managed service cannot provide.

  • Regulatory or data-location requirements require the database to run in an environment your team controls.

  • Your team is equipped to configure and test replica sets, backups, monitoring, upgrades, and disaster recovery.

Self-hosting can also make sense when an established platform team already provides MongoDB as an internal service. In that case, it may be operationally equivalent to a managed service from the application team's perspective.

Consider another option when

Avoid self-hosting MongoDB simply to reduce the database bill. The server cost does not include the engineering time required to secure the deployment, monitor it, apply upgrades, maintain replicas, test backups, and respond to failures.

Do not treat a single MongoDB process on the same server as the application as a resilient production architecture. If your team does not already know how it will handle authentication, TLS, replication, backup restoration, monitoring, and failover, use MongoDB Atlas or managed PostgreSQL instead.

MongoDB's server license may also matter to organizations with policies that require an OSI-approved open source database. Review the current MongoDB licensing terms as part of the architectural decision.

Hosting and operations

Your team provides and maintains the database servers or containers. A production deployment should use authentication, restricted network access, encrypted connections, replication, monitoring, automated backups, and a tested recovery process.

The application and database do not need to run on the same server. In a scalable deployment, all ApostropheCMS instances connect to the same MongoDB replica set over a private or otherwise secured network.

MongoDB Atlas

What MongoDB Atlas is

MongoDB Atlas is MongoDB's managed cloud database service. It runs MongoDB on AWS, Microsoft Azure, or Google Cloud and provides deployment, monitoring, security controls, scaling, replication, and backup features through a managed platform.

From ApostropheCMS's perspective, Atlas is still MongoDB. You connect with a MongoDB connection URI, commonly one beginning with mongodb+srv://, and use the same ApostropheCMS features and database APIs as a self-hosted MongoDB deployment.

Best for

MongoDB Atlas is the right choice when you want the native MongoDB backend without taking on day-to-day database operations. For a new production ApostropheCMS project with no existing organizational preference, Atlas is the strongest general-purpose default.

Choose MongoDB Atlas when

  • You want the most established ApostropheCMS database path without operating MongoDB yourself.

  • You need the complete MongoDB API for custom queries or integrations.

  • Your application may scale to multiple instances.

  • Your team wants managed monitoring, replication, upgrades, and backup options.

  • You want to deploy the database in a region and cloud provider close to the application.

Atlas is especially attractive to small development teams: it replaces a significant database-operations workload with a service designed specifically around MongoDB.

Consider another option when

Avoid Atlas when your organization is already committed to managed PostgreSQL and has no MongoDB-specific requirements. Introducing a second database platform creates additional billing, access control, compliance, and operational work even when the database itself is managed.

Atlas may also be unsuitable when procurement rules, data residency requirements, network architecture, or database licensing policies exclude it. Review the service tier carefully: backup, availability, scaling, and compliance capabilities vary, and a low-cost development tier should not automatically be treated as a production architecture.

Hosting and operations

Atlas provisions MongoDB within a selected AWS, Azure, or Google Cloud region. MongoDB manages the underlying database infrastructure, while your team remains responsible for choosing an appropriate tier, configuring database users and network access, enabling the required backup policy, monitoring costs, and testing restoration.

For production, place the Atlas deployment near the ApostropheCMS application and restrict network access to the application environment. High availability and backup are related but separate concerns: replication keeps the database available during infrastructure failures, while backups provide recovery from accidental deletion or corrupted data.

Does the database choice change how I build an ApostropheCMS project?

For most projects, no. ApostropheCMS uses a shared database interface, so content schemas, module configuration, editor features, REST APIs, and standard query builders work across SQLite, PostgreSQL, and MongoDB.

The important exception is custom code that accesses the database at a low level. If you limit that code to the operations supported by @apostrophecms/db-connect, it remains portable. If you use MongoDB-specific features beyond that compatibility layer, the project will require MongoDB.

This portability lets a developer use SQLite locally while a deployed environment uses PostgreSQL or MongoDB. However, using the same database engine in development, staging, and production still provides the closest test environment, particularly when the project contains custom low-level queries.

Can you change databases later?

Yes. ApostropheCMS provides apos-db-dump and apos-db-restore through @apostrophecms/db-connect. These tools use a portable JSON Lines format that can export content from one supported backend and restore it to another.

Changing APOS_DB_URI selects a different database, but it does not migrate the data automatically. Export the existing database, restore it to the new backend, and test the migrated project before changing production traffic.

Making the final choice

If your production architecture will run multiple ApostropheCMS application instances, rule out SQLite regardless of which path above you land on — a SQLite file can't act as shared storage across instances.

Use this order of preference:

  1. Evaluating ApostropheCMS or starting local development? Choose SQLite. It removes database setup from the critical path.

  2. Does your organization already standardize on PostgreSQL? Choose PostgreSQL. Reuse its existing expertise, hosting, monitoring, and backup practices.

  3. Do you need MongoDB-specific capabilities but not want to operate the database? Choose MongoDB Atlas. This is the best general production default when there is no established database standard.

  4. Do you need to control and operate the MongoDB infrastructure yourself? Choose self-hosted MongoDB. Make this choice because you have a concrete requirement and the operational capacity, not because it initially appears less expensive.

  5. Planning to run multiple ApostropheCMS application instances? Do not choose SQLite. Use PostgreSQL, MongoDB, or MongoDB Atlas so every instance can connect to the same database service.

Select the database your team can operate confidently, keep custom database access within ApostropheCMS's portable APIs when possible, and revisit the decision if the deployment's needs change.