How to interact with your project’s database¶
The Postgres database for your Divio Cloud project runs:
- in a Docker container for your local projects: Interact with the local database
- on a dedicated cluster for your Cloud-deployed sites: Interact with the Cloud database
In either case, you will mostly only need to interact with the database via Django. However, if you need to interact with it directly, the option exists.
Interact with the local database¶
This is the recommended and most useful way to interact with the project’s database.
From the project’s local web container¶
docker-compose run --rm web python ./manage.py dbshell
Connecting to the database manually¶
You can also make the connection manually from within the
web container, for example:
docker-compose run --rm web psql -h postgres -U postgres db
As well as
psql you can run commands such as
pg_restore. This is useful
for a number of common operations, below.
Another way of interacting with the database is via the database container itself, using
exec. This requires that the database container already be up and running.
For example, if your database container is called
docker exec -i example_db_1 psql -U postgres
From your host environment¶
If you have a preferred Postgres management tool that runs on your own computer, you can also connect to the database from outside the application.
Expose the database’s port¶
In order to the connect to the database from a tool running directly on your own machine, you will need to expose its port (5432).
Add a ports section to the
db service in
docker-compose.yml and map the
port to your host:
db: image: postgres:9.4 ports: - 5432:5432
This means that external traffic reaching the container on port 5432 will be routed to port 5432 internally.
The ports are
<host port>:<container port> - you can choose another host
port if you are already using 5432 on your host.
Now restart the
db container with:
docker-compose up -d db
Connect to the database¶
You will need to use the following details:
- password: not required
Access the database using your Postgres tool of choice. Note that you must
specify the host address,
For example, if you’re using the
psql command line tool, you can connect to the project
psql -h 127.0.0.1 -U postgres db
Interact with the Cloud database¶
It’s often more appropriate to pull down the Cloud database to a local project to interact with it there:
divio project pull db live # or test
See the divio project command reference for more on using these commands.
From the project’s Cloud application container¶
SSH access to an application container on the Cloud is available on Managed Cloud projects only.
Log into your Cloud project’s container (Test or Live) over SSH.
This will drop you into the
psql command-line client, connected to your database.
Connecting to the database manually¶
You can also make the connection manually. Run
env to list your environment variables. Amongst
them you’ll find
DATABASE_URL, which will be in the form:
You can use these credentials in the
From your own computer¶
Access to Cloud databases other than from the associated application containers is not possible - it is restricted, for security reasons, to containers running on our own infrastructure.
Usage examples for common basic operations¶
It’s beyond the scope of this article to give general guidance on using Postgres, but these examples will help give you an idea of some typical operations that you might undertake while using Divio Cloud.
All the examples assume that you are interacting with the local database, running in its
In each case, we launch the command from within the
web container with
--rm web and we specify:
- host name:
- user name:
Dump the database¶
Dump the database
db to a file named
docker-compose run --rm web pg_dump -h postgres -U postgres db > database.dump
Drop the database¶
Drop (delete) the database named
docker-compose run --rm web dropdb -h postgres -U postgres db
Create the database¶
Create a database named
docker-compose run --rm web createdb -h postgres -U postgres db
hstore extension (required on a newly-created local database) to he database named
docker-compose run --rm web psql -h postgres -U postgres db -c "CREATE EXTENSION hstore"
Restore the database¶
Restore a database named
db from a file named
docker-compose run --rm web pg_restore -h postgres -U postgres -d db database.dump --no-owner
Reset the database¶
docker-compose run --rm web python manage.py migrate