3/20/14

Postgres.app Documentation

Documentation
Postgres.app is the easiest way to get started with PostgreSQL on the Mac. Open the app, and you have a PostgreSQL server ready and awaiting new connections. Close the app, and the server shuts down. Whether you're a command line aficionado, prefer GUIs, or just want to start making things with your framework of choice, connecting to Postgres.app is easy.

Upgrading From A Previous Version

Starting with Version 9.2.2.0, Postgres.app is using semantic versioning, tied to the release of PostgreSQL provided in the release, with the final number corresponding to the individual releases of PostgresApp for each distribution. Upgrading between bugfix versions (eg. 9.3.0.0 to 9.3.1.0, or 9.3.1.0 to 9.3.1.1) is as simple as replacing Postgres.app in your Applications directory. Make sure that the app is closed, though. When updating between minor PostgreSQL releases (eg. 9.3.x to 9.4.x), Postgres.app will create a new, empty data directory. You are responsible for migrating the data yourself. We suggest using p g _ d u m p _ a l l to export your data, and then import it using p s q l. Starting with Version 9.3.2.0, the default the data directory is:
~ / L i b r a r y / A p p l i c a t i o nS u p p o r t / P o s t g r e s / v a r 9 . 3

Command-Line Tools
p s q l is the PostgreSQL command-line interface to your database. Mac OS 10.7 ships with an older

version of PostgreSQL, which can be started with the following command:

$p s q lhl o c a l h o s t

When Postgres.app first starts up, it creates the $USER database, which is the default database for p s q l when none is specified. The default user is $USER, with no password. PostgreSQL ships with a constellation of useful binaries, like p g _ d u m p or p g _ r e s t o r e, that you will likely want to use. Go ahead and add the / b i n directory that ships with Postgres.app to your P A T H (preferably in . p r o f i l e, . b a s h r c, . z s h r c, or the like to make sure this gets set for every Terminal session):
P A T H = " / A p p l i c a t i o n s / P o s t g r e s . a p p / C o n t e n t s / V e r s i o n s / 9 . 3 / b i n : $ P A T H "

postgresapp.com/documentation/

1/6

3/20/14

Postgres.app Documentation

Once your path is correctly set up, you should be able to run p s q l without a host. (If not, check that the correct version is being loaded in the P A T H by doing w h i c hp s q l) Postgres.app creates a PostgreSQL user with your current username ($USER). It also creates a database with this name, which will be the default one p s q l connects to if you don't specify otherwise. To create a new database, connect with p s q l and enter the following:
C R E A T ED A T A B A S Ey o u r _ d a t a b a s e _ n a m e ;

To delete it, enter:

D R O PD A T A B A S Ey o u r _ d a t a b a s e _ n a m e ;

You can get a list of all of p s q l's commands and shortcuts with \ ?. A complete reference for PostgreSQL is available on the PostgreSQL.org (http://www.postgresql.org/docs/9.1/interactive/index.html).

Man pages
Postgres.app ships with man pages. If you've configured your P A T H as described above, just type m a np s q l to read the official docs.

GUI Applications
Explore, query, and visualize your data with Induction (http://inductionapp.com/). Although still in early development, Induction is fast and easy to use, and is our go-to application when working with data. If you are running Mac OS X 10.8 and enjoy the cutting edge, check out PG Commander (http://eggerapps.at/pgcommander/). If you're looking for something more fully-featured and don't mind getting the kitchen sink in the process, check out pgAdmin (http://www.pgadmin.org/).

Connection parameters
When using a GUI program, here are the connection parameters you need to enter: Host: localhost Port: 5432 (default) User: your user name Password: blank Database: same as user name If you need to provide an URL (eg. for Induction), use
p o s t g r e s q l : / / Y O U R U S E R N A M E @ l o c a l h o s t / Y O U R U S E R N A M E
postgresapp.com/documentation/ 2/6

3/20/14

Postgres.app Documentation

Configuration Settings
Building a web application and want to skip to the part where everything works? Select the connection settings for your language, framework, and library of choice:

Ruby
Install the p g gem with g e mi n s t a l lp g, or just add g e m' p g ' to your application's G e m f i l e and run b u n d l ei n s t a l l If you are running your application with Foreman (https://github.com/ddollar/foreman), set the D A T A B A S E _ U R L config variable in . e n v:
D A T A B A S E _ U R L = p o s t g r e s : / / p o s t g r e s @ l o c a l h o s t / [ Y O U R _ D A T A B A S E _ N A M E ]

You can learn more about environment variables from this Heroku Dev Center article (https://devcenter.heroku.com/articles/config-vars).

Rails (http://rubyonrails.org/)
In c o n f i g / d a t a b a s e . y m l, use the following settings:
d e v e l o p m e n t : a d a p t e r :p o s t g r e s q l d a t a b a s e :[ Y O U R _ D A T A B A S E _ N A M E ] h o s t :l o c a l h o s t

Sinatra (http://www.sinatrarb.com/)
In c o n f i g . r u or your application code:
s e t: d a t a b a s e ,E N V [ ' D A T A B A S E _ U R L ' ]| |' p o s t g r e s : / / l o c a l h o s t / [ Y O U R _ D A T A B A S E _ N A M E ] '

ActiveRecord (http://ar.rubyonrails.org/)
Install the a c t i v e r e c o r d gem and r e q u i r e' a c t i v e _ r e c o r d ', and establish a database connection:
A c t i v e R e c o r d : : B a s e . e s t a b l i s h _ c o n n e c t i o n ( E N V [ " D A T A B A S E _ U R L " ] )

DataMapper (http://datamapper.org/)
Install and require the d a t a m a p p e r and d o _ p o s t g r e s gems, and create a database connection:
D a t a M a p p e r . s e t u p ( : d e f a u l t ,E N V [ ' D A T A B A S E _ U R L ' ]| |" p o s t g r e s : / / l o c a l h o s t / [ Y O U R _ D A T A B A S E _ N A M E ] " )

Sequel (http://sequel.rubyforge.org/)
postgresapp.com/documentation/ 3/6

3/20/14

Postgres.app Documentation

Install and require the s e q u e l gem, and create a database connection:

D B=S e q u e l . c o n n e c t ( E N V [ ' D A T A B A S E _ U R L ' ]| |" p o s t g r e s : / / l o c a l h o s t / [ Y O U R _ D A T A B A S E _ N A M E ] " )

Python
Install the p s y c o p g 2 library with with p i pi n s t a l lp s y c o p g 2 or add it to your pip requirements file.

Django (http://www.djangoproject.com/)
In your s e t t i n g s . p y, add an entry to your D A T A B A S E S setting:
D A T A B A S E S={ " d e f a u l t " :{ " E N G I N E " :" d j a n g o . d b . b a c k e n d s . p o s t g r e s q l _ p s y c o p g 2 " , " N A M E " :" [ Y O U R _ D A T A B A S E _ N A M E ] " , " U S E R " :" " , " P A S S W O R D " :" " , " H O S T " :" l o c a l h o s t " , " P O R T " :" " , } }

Flask (Flask)
When using the Flask-SQLAlchemy (http://packages.python.org/Flask-SQLAlchemy/) extension you can add to your application code:
f r o mf l a s ki m p o r tF l a s k f r o mf l a s k . e x t . s q l a l c h e m yi m p o r tS Q L A l c h e m y a p p=F l a s k ( _ _ n a m e _ _ ) a p p . c o n f i g [ ' S Q L A L C H E M Y _ D A T A B A S E _ U R I ' ]=' p o s t g r e s q l : / / l o c a l h o s t / [ Y O U R _ D A T A B A S E _ N A M E ] ' d b=S Q L A l c h e m y ( a p p )

SQLAlchemy (http://www.sqlalchemy.org/)
In your application code add:
f r o ms q l a l c h e m yi m p o r tc r e a t e _ e n g i n e e n g i n e=c r e a t e _ e n g i n e ( ' p o s t g r e s q l : / / l o c a l h o s t / [ Y O U R _ D A T A B A S E _ N A M E ] ' )

PHP
PDO (http://www.php.net/manual/en/book.pdo.php)
postgresapp.com/documentation/ 4/6

3/20/14

Postgres.app Documentation

Make sure your PHP setup has PDO installed (it is enabled by default in PHP 5.1.0 or above), and the PostgreSQL PDO driver (http://www.php.net/manual/en/ref.pdo-pgsql.php) is enabled. Then a database connection can be established with:
< ? p h p $ d b h=n e wP D O ( ' p g s q l : h o s t = l o c a l h o s t ; d b n a m e = [ Y O U R _ D A T A B A S E _ N A M E ] ' ) ; ? >

Removing Existing PostgreSQL Installations

For best results, you should remove any existing installation of PostgreSQL. Here's a run-down of the most common ways you may have installed it previously:

Homebrew
$b r e wr e m o v ep o s t g r e s q l

MacPorts
$s u d op o r tu n i n s t a l lp o s t g r e s

EnterpriseDB
In the EnterpriseDB installation directory, open u n i n s t a l l p o s t g r e s q l . a p p.

Included Packages
Each release of Postgres.app comes with the latest stable release of PostgreSQL, as well a few choice extensions. Here's a rundown of what's under the hood: PostgreSQL (http://www.postgresql.org/) PostGIS (http://postgis.refractions.net/) plv8 (http://code.google.com/p/plv8js/wiki/PLV8)

Installation Directories
Binaries: / A p p l i c a t i o n s / P o s t g r e s . a p p / C o n t e n t s / V e r s i o n s / 9 . 3 / b i n
postgresapp.com/documentation/ 5/6

3/20/14

Postgres.app Documentation

Headers: / A p p l i c a t i o n s / P o s t g r e s . a p p / C o n t e n t s / V e r s i o n s / 9 . 3 / i n c l u d e Libraries: / A p p l i c a t i o n s / P o s t g r e s . a p p / C o n t e n t s / V e r s i o n s / 9 . 3 / l i b Man pages: / A p p l i c a t i o n s / P o s t g r e s . a p p / C o n t e n t s / V e r s i o n s / 9 . 3 / s h a r e Default data directory: ~ / L i b r a r y / A p p l i c a t i o n \S u p p o r t / P o s t g r e s / v a r 9 . 3

Uninstalling
Uninstall Postgres.app just like you would any application: quit, drag to the Trash, and Empty Trash. Postgres.app data and configuration resides at ~ / L i b r a r y / A p p l i c a t i o n \S u p p o r t / P o s t g r e s, so remove that when uninstalling, or if you need to do a hard reset on the database.

Troubleshooting
If you run into any issues using Postgres.app, your first stop should be the issue tracker (https://github.com/postgresapp/postgresapp/issues) on Github. You can also ask @Postgresapp (https://twitter.com/Postgresapp) on Twitter.

Additional Resources
PostgreSQL Website (http://www.postgresql.org/) - The source for all of the latest PostgreSQL news and information. PostgreSQL Docs (http://www.postgresql.org/docs/9.2/interactive/index.html) - The canonical reference for everything you need to know about PostgreSQL. Postgres Guide (http://postgresguide.com/) - A promising new PostgreSQL resource that reads well and introduces advanced topics in a way that's easy to understand. Heroku Postgres (https://postgres.heroku.com/) - The largest and most reliable Postgres service in the world, for when it comes time to deploy and scale your database in production.

postgresapp.com/documentation/

6/6