Stash is now known as Bitbucket Server.
See the

Unknown macro: {spacejump}

of this page, or visit the Bitbucket Server documentation home page.

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. See Getting started.
  • 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. See Using the Database Migration Wizard.

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. For additional information review this page on tuning.

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:

Related pages:

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. The maximum number of connections is a configurable system property – see Database pool.
  • Note that Stash requires the datebase to keep idle connections alive for at least 10 minutes. If the database is configured with less than a 10 minute connection timeout, there will be seemingly random connection errors. 

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;

If the server that is hosting the PostgreSQL database is not the same server as Stash, then please ensure that the Stash server can connect to the database server. Please also refer to the PostgreSQL documentation on how to set up pg_hba.conf. If the pg_hba.conf file is not set properly, remote communication to the PostgreSQL server will fail.

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. In the Stash administration area, click 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.

PortThe 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 name
The name of the database that Stash should connect to.
Database usernameThe username that Stash should use to access the database.
Database passwordThe password that Stash should use to access the database.

Install the JDBC driver

This section is only relevant to some distributions of Stash, for example if you are running Stash via the Atlassian Plugin SDK, or have built Stash from source.

If the PostgreSQL JDBC driver is not bundled with Stash, you will need to download and install the driver yourself.

  1. Download the appropriate JDBC driver from the Postgres download site.
  2. Copy the downloaded jar file to your <Stash home directory>/lib directory (for Stash 2.1 or later).
  3. Stop, then restart, Stash. See Starting and stopping Stash.
  • No labels
 

 

 

 

 Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.