Postico

User Guide

Getting Started

• Get started with Postgres.app
• Connecting to a local PostgreSQL server

Using Postico

• Working with Favorites
• Using Connection URLs
• Importing and Exporting data
• Using the table DDL view
• Autosaving Queries
• Keyboard Shortcuts

Troubleshooting

• Common Connection Problems
• Reporting Bugs

More Information

• Changelist
• Security Features
• Automatic Update Checking
• Automatic Crash Reporting
• Acknowledgements
• License Terms

Importing and Exporting data in Postico

Copy & Paste

Copy & Paste is the most convenient way to import and export data in Postico.

Postico, like most other Mac apps, copies tabular data in "Tab Separated Values" (TSV) format: columns are separated by tabs, and row are separated with newlines. The limitation of this format is that your data can't contain tabs or newlines. Postico replaces these special characters with spaces when you copy data to the clipboard.

You can also copy data in other formats using the "Copy Special" command. Postico offers the following alternative formats for copying: TSV with headers, CSV, CSV with headers, SQL Insert Statements.

Postico also allows pasting data in TSV format. This is great for importing data from spreadsheets in Excel or Numbers, or from MySQL databases using Sequel Pro, or even from tables on websites in Safari.

Here's how to paste data into Postico:

• Create a target table with all the columns you want to import, or use an existing table.
• Arrange the columns in the target table in the same order as the original data you copied. You can move columns by dragging the column header. (Don't worry if either the source or target table have extra columns at the end; Postico will simply ignore them)
• Make sure that the keyboard focus is on the table view in Postico and paste your data.
• You should now see all your new data highlighted in yellow. Check that everything was pasted correctly, then click save to write changes to the database.

Importing CSV Files

1. Choose "Import CSV…" from the "File" menu (⌘-I)
   Go to "File" → "Import CSV…" or press ⌘-I and select a CSV file you'd like to import. Alternatively, you can select "Import…" from the context menu by right-clicking on the table name in the left sidebar. If your file can't be selected, change its extension to ".csv".
2. Adjust CSV Import Settings
   Postico tries to load a preview of your file contents. If the content isn't diplayed properly, you have to adjust settings by changing the file's encoding, separator, quote and decimal character. If your CSV file has a header, make sure the "First Row is Header" checkbox is enabled.
3. Select your target table
   If your target table hasn't been selected before, choose your target table from the popup button.
4. Select source columns to import
   Each source column can be imported into one column of your target table. Match and arrange source and target columns by selecting the destination from popup menu. If you choose "Do not import", Postico will ignore the column.
5. Fix warnings (if necessary)
   When you select target columns, Postico checks the import file. If problems occur (eg. when trying to import textual data into a numeric column), Postico will display warnings. Postico does not allow importing files with warnings.
   If your CSV file is very large, Postico will only check the beginning of the file. In this case, Postico checks the full file during import. If a problem is found, the import is aborted and changes are reverted.
6. Click "Import"
   Once you've applied your settings, you can start the import procedure by clicking the "Import" button. If the button is disabled, make sure that least one column is selected to import.

File Formats and Encodings

Since CSV files are not standardized, Postico is flexible and supports many configurations. Nevertheless, not all CSV files can be imported and in some cases you have to change the file's encoding. The default settings are such that a file exported from Postico with the "International" setting (see below) can be imported. This is also the same format that the PostgreSQL command COPY (...) CSV HEADER; uses. (Except for the handling of empty strings, see below.)

Character Encoding
Postico can import UTF-8 files only. If your CSV file has a different encoding, use your favorite text editor to convert.

Column Separators
Postico supports CSV files with the most common column separator characters: comma (,), semicolon (;), tab, or pipe (|)

Line Separators
Supported line separators are: Unix (LF), Windows (CRLF), Mac (CR). You do not need to configure this, Postico automatically allows any of these separators.

Quoting
Only double quotes are allowed. When a field contains the quote character, it can be escaped either by doubling (e.g. "") or by preceding it with a backslash (\").

Decimal Separator
Decimal numbers can use either period (.) or comma (,)

Data Types

Postico has special handling for numbers and NULL values. All other types are sent to the server without modification.

Numbers
Postico automatically validates numbers, replaces the decimal separator if necessary and removes optional grouping characters (eg. thousands separator).

NULL values
All empty values in the CSV file are converted to NULL. Postico treats empty strings as NULL.

Dates
Since dates are sent to the server without modification, they will be imported according to the configuration of the database server. The date format YYYY-MM-DD is recommended for importing (should always work). Dates in other formats are interpreted according to the servers DATESTYLE. Make sure that the server and your import file have the same DATESTYLE. (PostgreSQL Documentation)

Transactional Import

Import in Postico is transactional. Either the whole import completes successfully; or the database is not changed at all. You will never end up with a half-finished import.

Postico achieves this by wrapping INSERT statements in a transaction. This allows Postico to rollback (undo) the import in the event of an error.

Before the import, Postico executes "BEGIN" to start a transaction, and after a successful import "COMMIT". If a transaction is already running (e.g. because you manually issued a BEGIN statement), Postico creates a SAFEPOINT instead. After a successful import, the safepoint is released. This means that a failed import will not cause an already running transaction to fail.

Import Errors

This list contains common errors which can occur during the import.

Import cancelled

This means that the import was cancelled by the user.

An error occured while reading the CSV file

The CSV file could'nt be read properly. Fix the affected rows and try again.

Connection lost

The connection to the server has been lost. Re-connect and try again.

Transaction begin error

Postico wasn't able to begin the transaction.

Transaction commit error

Postico wasn't able to commit the transaction.

Rollback failed

An error occurred during import, but the transaction rollback (undo of the import) failed. In most cases (e.g. lost connections) the server will automatically rollback the transaction even though the explicit rollback failed.

Rollback not possible

The import failed and Postico wasn't able to rollback changes to the table. Usually this happens when a transaction was already active at the start of the import, but the server does not support SAVEPOINT. You need to rollback the transaction manually before you can continue.

Exporting CSV Files

Postico can export tables and query results as "Comma Separated Values" (CSV) files. You can export either a single table, or multiple tables at once.

When exporting the current table (by selecting "Export" from the File menu), all rows in the table will be exported, even though Postico only displays the first page. If filters are active, they will be used, and only filtered rows will be exported.

Make sure the keyboard focus is on the table view when selecting export; otherwise you may end up exporting the selected table in the sidebar.

You can export multiple tables by selecting them in the sidebar or in the grid view (hold down the shift or command keys). Then right-click and chose export from the context menu. When exporting multiple tables, Postico will create a folder containing one CSV file per table.

You can also export query results in the SQL Query view.

CSV Export Settings

Unfortunately CSV is a very losely defined format. Applications implement CSV in very different ways. This fact is made even worse by the fact that apps change behavior depending on your system's language & region settings.

I've examined the CSV file support of popular applications, and I came to the conclusion that most apps understand one of two formats, which I call "International" and "Continental":

• The International Format is used in English speaking countries and Asia. It uses a period (.) as the decimal mark and a comma (,) as field separator.
• The Continental Format is used in continental Europe and South America. It uses a comma (,) as decimal mark and a semicolon (;) as field separator.

Most apps allow using double quotes (") around values that can contain special characters. This allows CSV to store data that contains special characters like the field separator or newlines. Postico also uses quotes:

• Numeric values are stored without quotes
• Strings are always surrounded by quotes
• NULL values are stored as empty fields (ie. two consecutive commas)
• When a value contains a quote, the quote is doubled in the output

This produces output compatible with the majority of applications I've tested. However, there are two more settings (mostly for compatibility with Microsoft Excel):

• Allow Newlines: Some apps don't allow newlines in the data. You can uncheck this box to replace newlines with spaces.
• Encoding: You should always choose Unicode/UTF-8 if possible. However, some apps expect a legacy encoding. Postico supports MacRoman and Windows Latin 1 as alternatives.