Don't provision a Postgres database by default (#203)

* The app no longer provisions a Postgres addon by default (since the Postgres
   adapter dependency in `requirements.txt` is commented out, which is what
   the Python buildpack uses to determine whether to auto-provision), so that it's
   possible to try the main part of the guide without incurring any additional
  charges beyond the eco dyno plan.
* The Postgres DB addon has been removed from `app.json` too, which prevents
   it from being auto-provisioned for Review Apps too.
* Help comments has been added to the `db` view function, to try and help prevent
   confusion due to errors on Heroku from the DB not being auto-provisioned.
* The Postgres adapter has been switched from `psycopg2` to `psycopg`, which
   counter-intuitively is newer (`psycopg` is the v3 implementation of the adapter).
   The binary version of the package is now also used when not in production, to speed
   up local installation and reduce the chance of running into library/header issues.
* The new Django DB connection health check feature has been enabled.
* The unnecessary `HerokuDiscoverRunner` custom test runner and database`TEST`
   options have been removed.
* An example `release` process entry has been added (commented out) to `Procfile`,
   which runs the Django DB migrations using the Heroku Release Phase feature.
   
GUS-W-13152716.

Author: edmorley

Procfile

@@ -1 +1,7 @@
 web: gunicorn gettingstarted.wsgi
+
+# Uncomment this `release` process if you are using a database, so that Django's model
+# migrations are run as part of app deployment, using Heroku's Release Phase feature:
+# https://docs.djangoproject.com/en/4.2/topics/migrations/
+# https://devcenter.heroku.com/articles/release-phase
+#release: ./manage.py migrate --no-input

app.json

@@ -4,7 +4,6 @@
   "image": "heroku/python",
   "repository": "https://github.com/heroku/python-getting-started",
   "keywords": ["python", "django"],
-  "addons": ["heroku-postgresql"],
   "env": {
     "DJANGO_SECRET_KEY": {
       "description": "The secret key for the Django application.",

gettingstarted/settings.py

@@ -15,14 +15,11 @@
 from pathlib import Path
 
 import dj_database_url
-from django.test.runner import DiscoverRunner
 
 # Build paths inside the project like this: BASE_DIR / 'subdir'.
 BASE_DIR = Path(__file__).resolve().parent.parent
 
 
-IS_HEROKU = "DYNO" in os.environ
-
 # Before using your Heroku app in production, make sure to review Django's deployment checklist:
 # See https://docs.djangoproject.com/en/4.2/howto/deployment/checklist/
 
@@ -40,15 +37,20 @@
     default=secrets.token_urlsafe(nbytes=64),
 )
 
+# The `DYNO` env var is set on Heroku CI, but it's not a real Heroku app, so we have to
+# also explicitly exclude CI:
+# https://devcenter.heroku.com/articles/heroku-ci#immutable-environment-variables
+IS_HEROKU_APP = "DYNO" in os.environ and not "CI" in os.environ
+
 # SECURITY WARNING: don't run with debug turned on in production!
-if not IS_HEROKU:
+if not IS_HEROKU_APP:
     DEBUG = True
 
 # On Heroku, it's safe to use a wildcard for `ALLOWED_HOSTS``, since the Heroku router performs
 # validation of the Host header in the incoming HTTP request. On other platforms you may need
 # to list the expected hostnames explicitly to prevent HTTP Host header attacks. See:
 # https://docs.djangoproject.com/en/4.2/ref/settings/#std-setting-ALLOWED_HOSTS
-if IS_HEROKU:
+if IS_HEROKU_APP:
     ALLOWED_HOSTS = ["*"]
 else:
     ALLOWED_HOSTS = []
@@ -109,25 +111,28 @@
 # Database
 # https://docs.djangoproject.com/en/4.2/ref/settings/#databases
 
-MAX_CONN_AGE = 600
-
-DATABASES = {
-    "default": {
-        "ENGINE": "django.db.backends.sqlite3",
-        "NAME": BASE_DIR / "db.sqlite3",
+if IS_HEROKU_APP:
+    # In production on Heroku the database configuration is derived from the `DATABASE_URL`
+    # environment variable by the dj-database-url package. `DATABASE_URL` will be set
+    # automatically by Heroku when a database addon is attached to your Heroku app. See:
+    # https://devcenter.heroku.com/articles/provisioning-heroku-postgres
+    # https://github.com/jazzband/dj-database-url
+    DATABASES = {
+        "default": dj_database_url.config(
+            conn_max_age=600,
+            conn_health_checks=True,
+            ssl_require=True,
+        ),
+    }
+else:
+    # When running locally in development or in CI, a sqlite database file will be used instead
+    # to simplify initial setup. Longer term it's recommended to use Postgres locally too.
+    DATABASES = {
+        "default": {
+            "ENGINE": "django.db.backends.sqlite3",
+            "NAME": BASE_DIR / "db.sqlite3",
+        }
     }
-}
-
-if "DATABASE_URL" in os.environ:
-    # Configure Django for DATABASE_URL environment variable.
-    DATABASES["default"] = dj_database_url.config(
-        conn_max_age=MAX_CONN_AGE,
-        ssl_require=True,
-    )
-
-    # Enable test database if found in CI environment.
-    if "CI" in os.environ:
-        DATABASES["default"]["TEST"] = DATABASES["default"]
 
 
 # Password validation
@@ -180,21 +185,6 @@
 WHITENOISE_KEEP_ONLY_HASHED_FILES = True
 
 
-# Test Runner Config
-class HerokuDiscoverRunner(DiscoverRunner):
-    """Test Runner for Heroku CI, which provides a database for you.
-    This requires you to set the TEST database (done for you by settings().)"""
-
-    def setup_databases(self, **kwargs):
-        self.keepdb = True
-        return super(HerokuDiscoverRunner, self).setup_databases(**kwargs)
-
-
-# Use HerokuDiscoverRunner on Heroku CI
-if "CI" in os.environ:
-    TEST_RUNNER = "gettingstarted.settings.HerokuDiscoverRunner"
-
-
 # Default primary key field type
 # https://docs.djangoproject.com/en/4.2/ref/settings/#default-auto-field
 

hello/views.py

@@ -10,6 +10,16 @@ def index(request):
 
 
 def db(request):
+    # If you encounter errors visiting the `/db/` page on the example app, check that:
+    #
+    # When running the app on Heroku:
+    #   1. You have added the Postgres database to your app.
+    #   2. You have uncommented the `psycopg` dependency in `requirements.txt`, and the `release`
+    #      process entry in `Procfile`, git committed your changes and re-deployed the app.
+    #
+    # When running the app locally:
+    #   1. You have run `./manage.py migrate` to create the `hello_greeting` database table.
+
     greeting = Greeting()
     greeting.save()
 

requirements.txt

@@ -1,5 +1,12 @@
-django>=4.0,<5.0
+django>=4.2,<5.0
 gunicorn>=20.0,<21.0
 dj-database-url>=2.0,<3.0
 whitenoise[brotli]>=6.0,<7.0
-psycopg2>=2.0,<3.0
+
+# Uncomment these lines to use a Postgres database. Both are needed, since in production
+# (which uses Linux) we want to install from source, so that security updates from the
+# underlying Heroku stack image are picked up automatically, thanks to dynamic linking.
+# On other platforms/in development, the precompiled binary package is used instead, to
+# speed up installation and avoid errors from missing libraries/headers.
+#psycopg; sys_platform == "linux"
+#psycopg[binary]; sys_platform != "linux"