Django Support

This document describes how to use Google Cloud SQL instances with the Django web framework.

Django is a popular third-party Python web framework. When coupled with Google Cloud SQL, all of its functionality can be fully supported by applications running on App Engine. Support for using Google Cloud SQL with Django is provided by a custom Django database backend which wraps Django's MySQL backend. This page provides instructions for setting up an App Engine project which uses Django with a Google Cloud SQL database.

For more information about developing Python applications that access Cloud SQL, see the Developer Guide for Cloud SQL (Python) . For more information about Django, see the Django project homepage .

To learn more about Google Cloud SQL, see the Google Cloud SQL documentation.

Prerequisites

The following are prerequisite steps that must be completed before you can use Django with Google Cloud SQL. If you have already worked through the steps in Using Google Cloud SQL with App Engine Python SDK , then you have satisified the first two prerequisites.

Complete the steps for Getting Started with Google Cloud SQL
Read and complete the steps from the Getting Started documentation to create a Google Cloud SQL instance and to create a database . Additionally, if you would like to use a local MySQL server during development, ensure that you have completed the steps to install MySQL on your machine.
Download the Python App Engine SDK
All of the libraries needed for using Django with Google Cloud SQL have been bundled with the App Engine SDK starting at version 1.6.2. If you haven't done so already, download and install the latest version of the Python SDK to your computer.
Complete the Django tutorial
This guide assumes the reader has a basic level of familiarity with Django. If you haven't done so already, complete the Django tutorial on Writing your first Django app . You can use the resulting project from the tutorial as a base for enabling integration with Google Cloud SQL.

Usage

You can use Django with Google Cloud SQL on Google App Engine by using the Django database backend django.db.backends.mysql module. This module enables a Django app running in production to communicate with a production Google Cloud SQL instance.

To use the Google Cloud SQL backend in Django, edit your project's settings.py database configuration, and set the 'ENGINE' parameter to 'django.db.backends.mysql' . You will also need to provide values for the required settings below.

HOST: The Google Cloud SQL instance to which you're connecting, in the format '/cloudsql/ your-project-id:your-instance-name ' or '/cloudsql/ domain:your-project-id:your-instance_name '.
NAME: The database to which you're connecting.
USER: The name of MySQL user with which you're connecting.

These values should correspond to the names you chose when creating your Google Cloud SQL instance and database. A simple configuration would look something like this:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'HOST': '/cloudsql/your-project-id:your-instance-name',
        'NAME': 'database-name',
        'USER': 'mysql-user',
    }
}

For an example of using the settings.py file to manage multiple database definitions, see Alternate development database and settings .

Authentication

The backend communicates with Google Cloud SQL using one of two different connection transports depending on the current runtime environment, and each of these transports has its own authentication requirements for accessing your Google Cloud SQL instance.

Authentication on Production App Engine

When running on production App Engine, the Django backend gains access to a Google Cloud SQL instance by authenticating as your App Engine application. If you haven't done so already, ensure that your App Engine application can access your Google Cloud SQL instance by following the access control instructions .

Authentication on the Python Development Web Server

When running on dev_appserver.py during development, the Django backend communicates with Google Cloud SQL over an HTTP API, which requires a valid OAuth2 user token to authenticate the request.

Before using this transport on dev_appserver.py , you must first run one of the Django manage.py commands that interacts with the database (e.g., syncdb ). These tools will trigger the backend to present instructions for obtaining an OAuth2 token on the command prompt, and persist it to disk for subsequent use in dev_appserver.py at:

~/.googlesql_oauth2.dat

Or on Windows, at:

%USERPROFILE%\.googlesql_oauth2.dat

Management commands

Note: Before running the following manage.py commands, you'll need to ensure that all of the necessary libraries are available for import by adding them to your PYTHONPATH . For example, if you downloaded the App Engine SDK to your home directory in /home/user/google_appengine , the following command could be used to ensure that the django and google packages would be found when running manage.py

export PYTHONPATH="$PYTHONPATH:/home/user/google_appengine:/home/user/google_appengine/lib/django_1_3"

syncdb

The following syncdb invocation demonstrates the process of obtaining an OAuth2 token, and the subsequent db schema creation.

./manage.py syncdb
Go to the following link in your browser:
https://accounts.google.com/o/oauth2/auth?scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fsqlservice&state;=None&redirect;_uri=http%3A%2F%2Flocalhost%3A8080%2F&response;_type=code&client;_id=*******.apps.googleusercontent.com

Authentication successful.
Creating table django_admin_log
Creating table django_content_type
Creating table auth_permission
Creating table auth_group_permissions
Creating table auth_group
Creating table auth_user_user_permissions
Creating table auth_user_groups
Creating table auth_user
Creating table auth_message
Creating table django_session

You just installed Django's auth system, which means you don't have any superusers defined.
Would you like to create one now? (yes/no): yes
Username (Leave blank to use 'user'): test
E-mail address: [email protected]
Password:
Password (again):
Superuser created successfully.
Installing index for admin.LogEntry model
Installing index for auth.Permission model
Installing index for auth.Group_permissions model
Installing index for auth.User_user_permissions model
Installing index for auth.User_groups model
Installing index for auth.Message model
No fixtures found.

In addition to syncdb , you can also use any of the other management commands bundled with Django to interact with your data:

dbshell

./manage.py dbshell
Google SQL Client

Type "help" or "?" for help.

Connecting to Google SQL database "example.com:project:test|test" on host None.
Using readline for history management.
Loading history file "/home/user/.googlesql/example.com:project:test.hist"

sql> SELECT id,
  ->   username,
  ->   email
  -> FROM auth_user;
Execution time: 0.396 seconds
+----+----------+------------------+
| id | username |      email       |
+----+----------+------------------+
|  1 | test     | [email protected] |
+----+----------+------------------+

inspectdb

./manage.py inspectdb
# This is an auto-generated Django model module.
# You'll have to do the following manually to clean this up:
#     * Rearrange models' order
#     * Make sure each model has one field with primary_key=True
# Feel free to rename the models, but don't rename db_table values or field names.
#
# Also note: You'll have to insert the output of 'django-admin.py sqlcustom appname'
# into your database.

from django.db import models

class AuthGroup(models.Model):
    id = models.IntegerField(primary_key=True)
    name = models.CharField(unique=True)
    class Meta:
        db_table = u'auth_group'

class AuthGroupPermissions(models.Model):
    id = models.IntegerField(primary_key=True)
    group = models.ForeignKey(AuthGroup)
    permission = models.ForeignKey(AuthPermission)
    class Meta:
        db_table = u'auth_group_permissions'

...

class DjangoSession(models.Model):
    session_key = models.CharField(primary_key=True)
    session_data = models.TextField() # This field type is a guess.
    expire_date = models.DateTimeField()
    class Meta:
        db_table = u'django_session'

Porting your Django project to App Engine

In order to use a Django project on App Engine, you'll need to make a few modifications.

app.yaml

First, start by adding an app.yaml configuration file similar to the one below to your project directory.

application: appname
version: 1
runtime: python27
api_version: 1
threadsafe: true

libraries:
- name: django
  version: "1.3"

builtins:
- django_wsgi: on

Note: If you're using the older python runtime instead of python27 , you'll need to remove the libraries stanza from the sample app.yaml file. Additionally, you will also need to select the version of Django to be used by creating a file named appengine_config.py in your application's root directory, and defining the webapp_django_version constant within it (see the Python Module Configuration documentation for details).

settings.py

Next, modify your project settings.py file to use the database settings described in the Usage section above.

That's it! Your Django project is now ready to use with App Engine and Google Cloud SQL.

Running the Development Web Server

Instead of running the development server provided by Django (i.e., python manage.py runserver ), you should instead use the Python Development Web Server provided by the App Engine SDK to test your application.

dev_appserver.py mysite

Deploying your application to Google App Engine

When you're ready to upload your finished application to App Engine, simply follow the usual steps for deployment.

appcfg.py update mysite

Alternate development database and settings

In an ideal setup, you would use an alternate database during development to avoid corrupting your production data while working on your project. You could create another database on your Google Cloud SQL instance for this, or you can even use a local MySQL database instead. There are a number of ways you can enable this type of switching between project settings. Here, we will show how to do it using settings.py .

In the project switching scenario we illustrate here, use the:

standard django.db.backends.mysql when running in production and accessing a production Google Cloud SQL instance.
standard django.db.backends.mysql when running on a developer workstation and accessing a local MySQL instance. In this case, the application uses the system MySQLdb driver.
custom backend google.appengine.ext.django.backends.rdbms when running on a developer workstation and accessing a production Cloud SQL instance. In this case, the application uses the Google Cloud SQL Service and requires OAuth 2.0 credentials (same as the command line tool ).

import os
if os.getenv('SERVER_SOFTWARE', '').startswith('Google App Engine'):
    # Running on production App Engine, so use a Google Cloud SQL database.
    DATABASES = {
        'default': {
            'ENGINE': 'django.db.backends.mysql',
            'HOST': '/cloudsql/your-project-id:your-instance-name',
            'NAME': 'django_test',
            'USER': 'root',
        }
    }
elif os.getenv('SETTINGS_MODE') == 'prod':
    # Running in development, but want to access the Google Cloud SQL instance
    # in production.
    DATABASES = {
        'default': {
            'ENGINE': 'google.appengine.ext.django.backends.rdbms',
            'INSTANCE': 'your-project-id:your-instance-name',
            'NAME': 'django_test',
            'USER': 'root',
        }
    }
else:
    # Running in development, so use a local MySQL database.
    DATABASES = {
        'default': {
            'ENGINE': 'django.db.backends.mysql',
            'NAME': 'django_test',
            'USER': 'root',
            'PASSWORD': 'root',
        }
    }

Since the standard django.db.backends.mysql backend uses MySQLdb internally, app.yaml must reference MySQLdb in the list of libraries.

With this setup, you could force manage.py commands to run against your production database by setting the SETTINGS_MODE environment variable.

SETTINGS_MODE='prod' ./manage.py syncdb

Feel free to use this, or whatever system works best for your needs to switch between development and production settings.

Managing and Serving Static Files

Django-1.3 or higher version includes the django.contrib.staticfiles Django app which is a convenient way to manage and serve your static files.

To enable and configure django.contrib.staticfiles , add the following information to your settings file, usually named settings.py :

INSTALLED_APPS = (
    # Other apps here
    # ...
    'django.contrib.staticfiles',
)
# Other settings here
# ...
STATIC_ROOT = 'static'
STATIC_URL  = '/static/'

Then, run ./manage.py collectstatic to copy your static files into the directory that you specified in STATIC_ROOT . After this command completes, add a URL mapping in your app.yaml file to serve those static files at the URL specified in STATIC_URL .

For more details about managing static files in Django, please refer to the the Django documentation.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .

Last updated May 21, 2014.

Python