Skip to content

Building a Postgres Database

Simmate employs the Django ORM for database management, meaning any database supported by Django can be used.

This encompasses PostgreSQL, MariaDB, MySQL, Oracle, SQLite, and others via third-party providers. Comprehensive documentation for Django databases is available here.

However, we strongly recommend using Postgres, which we discuss in the following section.

Warning

Our team only uses SQLite (as the default for beginners) and PostgreSQL (for production). While you're free to use other backends, we have not tested them and may not be able to assist with troubleshooting.

Deployment Options

Postgres is free and open-source, so you can set it up on your own computer or a cloud server.

While you can manually build a Postgres server, we strongly recommend one of the two options below. Managed cloud services are easier for long-term projects, while Docker is perfect for local testing and development.

Option A: DigitalOcean (Cloud)

Our team uses DigitalOcean, where a basic database server (~$15/month) is sufficient for most Simmate projects. You'll only need a larger plan if you're running hundreds of thousands of calculations or storing very large datasets.

1. Account Creation

Start by creating an account on DigitalOcean using this link (our referral). This link should provide you a $200 credit for 60 days, which is more than enough to test things for free.

DigitalOcean Referral Badge

2. Cloud Database Creation

  1. On the DigitalOcean dashboard, click the green "Create" button in the top right and select Databases.
  2. Select the latest version of PostgreSQL.
  3. Choose a plan (the $15/month basic plan is a good starting point).
  4. Select a data center region close to your primary compute resource (e.g., if your supercomputer is in the US East, choose NYC).
  5. Click Create Database Cluster.

Option B: Docker (Local)

If you want to test Postgres locally for free before moving to the cloud, Docker is the best way to do so. This requires Docker Desktop to be installed and running on your computer.

1. Local Database Creation

To start a Postgres server locally, run the following command in your terminal:

simmate database start

This command will automatically download the required Postgres image, start a container named simmate_db, and update your Simmate settings to connect to it.

To stop and remove the container when you are finished, run:

simmate database stop

What is happening under the hood?

The simmate database start command is a shortcut for a longer docker command. For beginners, here is a breakdown of what that command does:

docker run \
    --name simmate_db \
    -e POSTGRES_PASSWORD=postgres \
    -v ~/simmate/database:/var/lib/postgresql/data \
    -p 5432:5432 \
    -d informaticsmatters/rdkit-cartridge-debian:Release_2025_03_3
  • docker run: Tells Docker to start a new container.
  • --name simmate_db: Gives your container a friendly name so you can find it later.
  • -e POSTGRES_PASSWORD=postgres: Sets an environment variable (-e) for the database password.
  • -v ~/simmate/database:/var/lib/postgresql/data: This "mounts a volume" (-v). It maps a folder on your computer (~/simmate/database) to the folder where Postgres stores data inside the container. This ensures your database results are saved to your actual hard drive even if the container is stopped or deleted.
  • -p 5432:5432: Maps the container's port to your computer's port (-p). 5432 is the default port for Postgres.
  • -d ...: Tells Docker to run the container in the background ("detached" mode) using an official Postgres image that includes RDKit support.

Next Steps

Now that you have a Postgres instance running, you can connect Simmate to it in the next step.

Connect to Postgres