{% setvar lang_is_python %}1{% endsetvar %} {% setvar lang_name %}python{% endsetvar %} {% setvar lang_name_uc %}Python{% endsetvar %}

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.


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 Google Cloud SDK

    All of the libraries needed for using Django with Google Cloud SQL have been bundled with the Google Cloud SDK. If you haven't done so already, install and initialize the SDK.

  • 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.

This article does not describe using Django on Google App Engine in detail. See this example Django App Engine app for reference.


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.

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'.
The database to which you're connecting.
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:

    'default': {
        'ENGINE': 'django.db.backends.mysql',
        '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.

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.5"


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:

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: test@example.com
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:


./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     | test@example.com |


./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.


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

runtime: python27
api_version: 1
threadsafe: true

- name: django
  version: "1.5"

- 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).


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 with the python manage.py runserver command, you should instead use the local development server:

dev_appserver.py mysite

Deploying your application to Google App Engine

When you're ready to upload your finished application to App Engine, run the following command from within the mysite directory of the application where the app.yaml file is located:

cd mysite
gcloud app deploy

To learn more about deploying your app from the command line, see Deploying a Python App.

Viewing your application

To launch your browser and view the app at http://[YOUR_PROJECT_ID].appspot.com, run the following command:

gcloud app browse

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 production Cloud SQL instance using IP address. In this case, you first need to configure your Cloud SQL instance to allow IP connection from your developer workstation. The configuration is the same as using command line tool.
  • 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.
import os
if os.getenv('SERVER_SOFTWARE', '').startswith('Google App Engine'):
    # Running on production App Engine, so use a Google Cloud SQL database.
        '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.
        'default': {
            'ENGINE': 'django.db.backends.mysql',
            'HOST': 'your-instance-ip-address',
            'NAME': 'django_test',
            'USER': 'root',
            'PASSWORD': 'password',
    # Running in development, so use a local MySQL database.
        'default': {
            'ENGINE': 'django.db.backends.mysql',
            'NAME': 'django_test',
            'USER': 'root',
            'PASSWORD': 'password',

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:

    # Other apps here
    # ...
# 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.

Send feedback about...

App Engine standard environment for Python