Skip to main content

Work library for Forge

Project description


Use Postgres for local Django development via Docker.


First, install forge-db from PyPI:

pip install forge-db

Now you will have access to the db command:

forge db

You will need to have a DATABASE_URL environment variable, which is where the database name, username, password, and port are parsed from:

# .env

You can use a POSTGRES_VERSION environment variable to override the default Postgres version (13):

# .env

In most cases you will want to use dj_database_url in your to easily set the same settings (works in most deployment environments too):

import dj_databse_url

    "default": dj_database_url.parse(
        environ["DATABASE_URL"], conn_max_age=environ.get("DATABASE_CONN_MAX_AGE", 600)

You will also notice a new .forge directory in your project root. This contains your local database files and should be added to .gitignore.


If you use forge-work, then most of the time you won't need to interact with forge-db directly. But it has a few commands that come in handy.

  • forge db start - starts a new database container and runs it in the background (use --logs to foreground it or connect to the logs)
  • forge db stop - stop the database container
  • forge db reset - drops and creates a new database
  • forge db pull - pulls the latest database backup from Heroku and imports it into the local database

In the end, the database container is like any other Docker container. You can use the standard Docker commands and tools to interact with it when needed.


The forge db snapshot command manages local copies of your development database. This is useful for testing migrations or switching between git branches that have different db states.

Snapshots are simply additional Postgres databases that are created and dropped as needed (createdb {snapshot_name} -T postgres).

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

forge_db-1.2.0.tar.gz (7.2 kB view hashes)

Uploaded Source

Built Distribution

forge_db-1.2.0-py3-none-any.whl (8.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page