PostgreSQLX.app informations

English is not my native language, so I'm sorry if this documentation is not very clear.

This program may be used to setup and customize a PostgreSQL server : Just drop PostgreSQLX.app in your application folder, launch it, and customize your server(s). 3 versions are available :

An application with an embedded server : There is no need to download or install anything because the last version of the server (PostgreSQL 7.4.3) is already embedded within PostgreSQLX.app.
An application without the server : You MUST have a valid PostgreSQL setup somewhere.
A preference pane without the server : You MUST have a valid PostgreSQL setup somewhere (This can be the full PostgreSQLX.app application).

In this document the word "PostgreSQLX.app" refers to this macOSX application, and the word "PostgreSQL" refers to the real server from http://www.postgresql.org/.

Installation

To install one of the two applications, just drop "PostgreSQLX.app" somewhere on your hard drive. The location must be readable by everyone, so a good location is the "/Application" folder or the "/Users/Shared" folder.

To install the preference pane :

Drop the pref pane in the "/Library/PreferencePanes" folder (You may have to create this folder)
Drop the pref pane in the "~/Library/PreferencePanes" folder (You may have to create this folder)
DO NOT Drop the pref pane in the "/System/Library/PreferencePanes" folder. This one SHOULD NOT BE MODIFIED

Documentation

The PostgreSQL server documentation is accessible via the "Help / PostgreSqLServer documentation" menu.

The PostgreSQLX.app documentation is under your eyes.

Upgrading from previous versions

If you're upgrading from a previous version, select the existing instance of PostgreSQL and click the "Save configuration" button : This operation will upgrade the StartupItem to the last version.

Quickstart

This chapter shows how to setup a server using the full PostgreSQLX.app. If you have any problem, look at the bottom left of the window : PostgreSQLX.app will display a few tips.

Remark : This basic setting will not allow acces to the PostgresSQL server via the network.

Install PostgreSQLX.app in an accessible location (That means NOT in your home folder, but in the "/Application" or any global folder like "/Users/Shared").
Launch PostgreSQLX.app.
Authenticate using the "Lock" (Bottom left).
Click on the "New" button (Top right).
Enter a unique "Service name". This name must not contain any fancy characters (Only use alphanumerics and underscores, the default value is OK).
Verify that the "Use builtin binaries" button is checked.
Choose an empty folder to store your data. The default value should be OK. You can also browse your hard drives with the small round button on the right.
Enter a user name. ALWAYS USE A DEDICATED USER NAME AND NOT YOUR USER NAME (The default value should be OK).
Verify that the "Enable this service" button is checked.
Click on the "Save configuration" button.
Click on the "Create database cluster" button and let the server work a few minutes.

Troubleshooting

This chapter will give a few tips to avoid (and resolve) problems. But, before anything, look for the little tips in the bottom left of the "Service settings" tab, they may help.

If nothing help, you can still drop me a mail (I probably need the console output).

The "Save configuration" does nothing

Check in the "/Library/StartupItems" folder to be sure it does nothing. If a server is already present, trash it and retry.
Check that you have enough rights (You're an admin ?)

The "Create database cluster" does nothing

Check that the "Data folder" folder is empty, and is writable by the "User name" account (With a little "Get info" of the finder).

The service does start very slowly

This will append if you moved the PostgreSQLX.app after the creation of a database cluster (PostgreSQL server does not like movement). To correct this you will have to :

Go in the "Configuration" tab.
Select "Connection defaults 2" item in the pop-up menu.
Correct the "Dynamic library path" field. This field contains two strings, separated by ":", and both must give a path inside to the PostgreSQL server folders.

For example, if your "PostgreSQLX.app" is in the "/Application" folder, this string should be :

/Applications/PostgreSQLX.app/Contents/Resources/PostgreSQL/lib: /Applications/PostgreSQLX.app/Contents/Resources/PostgreSQL/lib/postgresql
Or
/Applications/PostgreSQLX.app/Contents/Resources/PostgreSQL/bin/../lib: /Applications/PostgreSQLX.app/Contents/Resources/PostgreSQL/bin/../lib/postgresql

The service does not start

This will append if

The PostgreSQLX.app is not readable by everyone (eg : you put PostgreSQLX.app in your home folder). Try moving the program in the "/Applications" folder.
The cluster is owned by someone else than the postgres account. Check, with the "Get infos" windows of the finder, who is the owner of the cluster folder : It must match the "User name" field of the "Service settings" tab.
The cluster is damaged : You didn't play with it did you ?

The service is slow to stop

Stopping the server is slower than starting it... be patient.

Interface details

The "Selected instance" part

The list is used to select the server to customize. Do not create many servers if you don't know exactly what you're doing !

The "New" button is her to create a new instance.

The "service settings" tab

This tab allow basic customization of the service settings. You cannot change this settings if the service is running.

The "LOCK"

It will authenticate you, allowing changes into "/Library/StartupItems" and start/stop/restart. Many controls are disabled if you're not authenticated.

The "Service name" field

This is the unique name of the service and must not include any fancy characters. This name will be used to create the StartupItem.

The "Use builtin binaries" button

Tell PostgreSQLX.app to use its embedded PostgreSQL server. NEVER CHECK THIS BOX WITH THE PREFERENCE PANE VERSION.

The "Binaries folder" field

This is the full path to the server.

The "Data folder" field

This is the full path to the server's data.

The "User name" field

This is the user account used by the server. For security reasons, always use a dedicated user name.

The "Enable this service" button

If this button is checked, the server will start with your MacOS X. This button must always be checked to start the server (But it can be unchecked after).

The "Bottom left empty space"

A few tips will be displayed here. They are sorted by priority.

The "Bottom right buttons"

They allow to :

Create an empty database.
Start the service : The "Enable this service" button must be checked.
Stop the service : It must be running !
Restart the service : It must be running and the "Enable this service" button must be checked.

The "Bottom buttons"

They allow to :

Delete an instance : This will completly remove the StartupItem (The data are not removed !).
Revert an instance : This will revert all changes.
Save the configuration : This will save the changes.

The "Backup" tab

This tab allows you to backup your databases. This backup are realized with the "pg_dump' and 'pg_dumpall' tools.

The top part

Allow to choose a user name to connect to the server. The default values should be goods.

The backup details part

Two backup styles are available. Each one has it's limitations. The only required field is the "Destination" one.

All databases backup

This backup mode will not save large objects (images)
The only available format is "Plain text"

Single database backup

This backup mode will not save users account and other global parameters.
It will only save one database at once.

The "Configuration" tab

This tab is used to modifiy the postgresql.conf file. See the postgreSQL server manual for more informations.

The "Security" tab

This tab is used to modifiy the pg_hba.conf file. See the postgreSQL server manual for more informations.

The "Log" tab

It will display the server log file !

Feedback

You can use this e-mails to drop me a word, ask for bug-fixes or improvements.

bruno at bgauf dot net
b dot gaufier at mac dot com
bgaufier at club-internet dot fr

Security considerations.

The startup script

The startup script (/Library/StartupItems/PostgreSQLServer_login) contains a few chmod on files inside the "log" and "data" folders. This is required to allow PostgreSQLX to modify the "pg_hba.conf" and "postgresql.conf" files.

This changes should be relatively secure : The ADMIN group has :

rx access on the "data" folder.
rw acces on the pg_hba.conf and postgresql.conf.
rx access on the "log" folder.
r acces on the log file.

The server settings

The PostgreSQl server settings are its defaults : this means that everyone using your workstation, will have a full access to your databases.

On the first startup, the only valid user is the "User name" from the "Service settings" tab.

Version history.

Version 0.3

Misc bug-fixes.
numerous GUI modifications.
PostgreSQL server documentation is accessible wia the "Help" menu.
PostgreSQLX.app documentation is accessible wia the "Help" menu.
Tips are displayed on the "Service settings" tab to help during setup.
Instance management is operational. It is now possible to manage an arbitrary number of servers.
PostgreSQLX can now create the user account for the server.
Each instance can be disabled without dropping the startupItem.
Modifications on each tab can be reverted, saved and reset.
The bugs with the check boxes in the "Configuration" panel has been fixed.
The "Configuration" tab should work better (I re-checked all bindings and validity conditions).
The "Log" tab has been added.
The "Backup" tab has been added. It will allow to make backups (full or single database).
A preference pane has been created (It does not include the server but can manage other servers).

Version 0.2

A few bugfixes

The "user name" used by the server can now be anything (Of course, it must have read access to PostgreSQLX.app).
The embedded PostgreSQLServer has been modified to allow relocation of exe files.
Helper tools have been rewritten from scratch : Authentication code did not work well with shell scripts, so the helper is now an exe.
The setup procedure was not clear ! So a "Quick setup" button has been added.
The maximum number of connection was not saved ; now, it is.

Version 0.1

Initial release.

PostgreSQLServer modifications.

A few things have been modified inside PostgreSQL : This modifications were required to allow "relocation" of the server executable. This hack will not be necessary with the 8.0 version of PostgreSQL server.

All references to $libdir have been removed from "conversion.createdb.sql".
The generation of the file "postgresql.conf" in the "initdb" script has been modified : the option "dynamic_library_path" is now filled with the libraries paths.

Warranty, license ...

The version number (0.x) means that this is not a full featured commercial application. However, all comments are welcome and I'll do my best to kill all bugs !

This program comes with ABSOLUTELY NO WARRANTY, so use it at your own risks. You can do anything with it as long as :

You don't make money with it (either directly or indirectly).
You're providing this readme file with the program.

PostgreSQLX copyright

PostgreSQL Database Management System copyright

PostgreSQL Database Management System

(formerly known as Postgres, then as Postgres95)

Permission to use, copy, modify, and distribute this software and its documentation for any purpose, without fee, and without a written agreement is hereby granted, provided that the above copyright notice and this paragraph and the following two paragraphs appear in all copies.

IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

PostgreSQLX

Navigation

Languages