# Stash Latest : Connecting Stash to PostgreSQL

This page last changed on Aug 06, 2012 by dpinn.

This page describes how to connect Stash to a PostgreSQL database. The overall process for using a PostgreSQL database with Stash is: Install PostgreSQL where it is accessible to Stash. Create a database and user on the PostgreSQL server for Stash to use. Install Stash on Windows, or on Linux or Mac. Either: at Stash install time, run the Setup Wizard to connect Stash to the PostgreSQL database, or at a later time, migrate Stash to the PostgreSQL database. It is assumed here that you already have PostgreSQL installed and running. For more information about PostgreSQL installation and operation, refer to the PostgreSQL documentation. PostgreSQL has the idea of schemas. When you create a PostgreSQL database, a 'public' schema is created and set as the default for that database. It is possible to create a different schema (e.g. 'stash') and set that as the default schema. Stash will use whatever schema is set as the default for the logged-in user. Stash does not provide a way for a user to nominate the schema to use; it uses schema that is set as the PostgreSQL default. See Supported platforms for the versions of PostgreSQL supported by Stash. | On this page: 1. Prerequisites 2. Connect Stash to the PostgreSQL database Related pages: Connecting Stash to an external database Connecting Stash to MySQL Connecting Stash to Oracle Connecting Stash to SQL Server

### 1. Prerequisites

#### Backup

If you are migrating your Stash data from the HSQL internal database, back up the Stash home directory.

If you are migrating your Stash data from another external database, back up that database by following the instructions provided by the database vendor before proceeding with these instructions.

See Data recovery and backups.

#### Create the Stash database

Before you can use Stash with PostgreSQL, you must:

- Create a role for Stash to use when it connects to the database.
  We strongly recommend that this role be established for Stash's use exclusively; it should not be shared by other applications or people.
- Create a database in which Stash can store its data.
  The database must be configured to use the UTF-8 character set.
  During normal operation, Stash will acquire 25–30 connections to the database.

Here is an example of how to create a user called `stashuser` with password `jellyfish`, and a database called `stash`, which is configured for use by `stashuser`. Using a PostgreSQL client application like psql or pgAdmin, run the following commands, replacing the user name, password, and database name with your own values.

    CREATE ROLE stashuser WITH LOGIN PASSWORD 'jellyfish' VALID UNTIL 'infinity';

    CREATE DATABASE stash WITH ENCODING='UTF8' OWNER=stashuser CONNECTION LIMIT=-1;

### 2. Connect Stash to the PostgreSQL database

You can now connect Stash to the PostgreSQL database, either:

- when you run the Setup Wizard, at install time,
- when you wish to migrate Stash to PostgreSQL, either from the embedded HSQL database or from another external database.

When running the Setup Wizard at install time:

1. Select External at the 'Database' step.
2. Select PostgreSQL for Database Type.
3. Complete the form. See the table below for details.
4. Click Next, and follow the instructions in the Stash Setup Wizard.

When migrating to PostgreSQL:

1. Click Administration and then Database (under 'Settings').
2. Click Migrate database.
3. Select PostgreSQL for Database Type.
4. Complete the form. See the table below for details.
5. Click Start Migration.

Hostname | The host name or IP address of the computer running the database server.
Port | The TCP port with which Stash can connect to the database server. The default value is the default port that PostgreSQL runs against. You can change that if you know the port that your PostgreSQL instance is using.
Database | The name of the database that Stash should connect to.
Username | The username that Stash should use to access the database.
Password | The password that Stash should use to access the database.

## Attachments:

Stash_012_postgresql.png (image/png)