silverstripe-postgresql/README.md

# PostgreSQL Module Module

[![CI](https://github.com/silverstripe/silverstripe-postgresql/actions/workflows/ci.yml/badge.svg)](https://github.com/silverstripe/silverstripe-postgresql/actions/workflows/ci.yml)
[![Silverstripe supported module](https://img.shields.io/badge/silverstripe-supported-0071C4.svg)](https://www.silverstripe.org/software/addons/silverstripe-commercially-supported-module-list/)

## Requirements

* Silverstripe 4.0
* PostgreSQL >=9.2
* Note: PostgreSQL 10 has not been tested

## Installation

```
composer require silverstripe/postgresql
```

## Configuration

### Environment file

Add the following settings to your `.env` file:

```
SS_DATABASE_CLASS=PostgreSQLDatabase
SS_DATABASE_USERNAME=
SS_DATABASE_PASSWORD=
```

See [environment variables](https://docs.silverstripe.org/en/4/getting_started/environment_management) for more details. Note that a database will automatically be created via `dev/build`.

### Through the installer

Open the installer by browsing to install.php, e.g. http://localhost/install.php
Select PostgreSQL in the database list and enter your database details

## Usage Overview

See [docs/en](docs/en/README.md) for more information about configuring the module.
	
## Known issues

All column and table names must be double-quoted.  PostgreSQL automatically 
lower-cases columns, and your queries will fail if you don't.

Collations have known issues when installed on Alpine, MacOS X and BSD derivatives
(see [PostgreSQL FAQ](https://wiki.postgresql.org/wiki/FAQ#Why_do_my_strings_sort_incorrectly.3F)).
We do not support such installations, although they still may work correctly for you.
As a workaround for PostgreSQL 10+ you could manually switch to ICU collations (e.g. und-x-icu).
There are no known workarounds for PostgreSQL <10.

Ts_vector columns are not automatically detected by the built-in search 
filters.  That means if you're doing a search through the CMS on a ModelAdmin
object, it will use LIKE queries which are very slow.  If you're writing your 
own front-end search system, you can specify the columns to use for search 
purposes, and you get the full benefits of T-Search.

If you are using unsupported modules, there may be instances of MySQL-specific 
SQL queries which will need to be made database-agnostic where possible.
MINOR: update Postgres doc for docviewer support. FIXES: #6681 2012-06-29 07:56:38 +02:00			`# PostgreSQL Module Module`

MNT Use GitHub Actions CI 2022-07-15 02:23:59 +02:00			`[![CI](https://github.com/silverstripe/silverstripe-postgresql/actions/workflows/ci.yml/badge.svg)](https://github.com/silverstripe/silverstripe-postgresql/actions/workflows/ci.yml)`
MNT Standardise modules 2022-08-02 07:55:18 +02:00			`[![Silverstripe supported module](https://img.shields.io/badge/silverstripe-supported-0071C4.svg)](https://www.silverstripe.org/software/addons/silverstripe-commercially-supported-module-list/)`
Added travis support 2014-02-18 05:52:03 +01:00
MINOR: update Postgres doc for docviewer support. FIXES: #6681 2012-06-29 07:56:38 +02:00			`## Requirements`

MNT Standardise modules 2022-08-02 07:55:18 +02:00			`* Silverstripe 4.0`
API Increased support to 9.2 Anything older than 9.3 is unsupported by Postgres: https://www.postgresql.org/support/versioning/. I don't think we should claim support in our module for unsupported versions, particularly if we don't have CI on them. Since we're only running CI on 9.2 at the moment, that's the safe claim for our module support, even though it's already unsupported by Postgres. See https://docs.travis-ci.com/user/database-setup/#using-a-different-postgresql-version I'll raise a separate ticket about testing and supporting newer versions, it's out of scope for this PR. 2019-09-03 05:41:23 +02:00			`* PostgreSQL >=9.2`
			`* Note: PostgreSQL 10 has not been tested`
MINOR: update Postgres doc for docviewer support. FIXES: #6681 2012-06-29 07:56:38 +02:00
MINOR Updating installation instructions 2012-07-04 04:18:29 +02:00			`## Installation`
MINOR: update Postgres doc for docviewer support. FIXES: #6681 2012-06-29 07:56:38 +02:00
API Increased support to 9.2 Anything older than 9.3 is unsupported by Postgres: https://www.postgresql.org/support/versioning/. I don't think we should claim support in our module for unsupported versions, particularly if we don't have CI on them. Since we're only running CI on 9.2 at the moment, that's the safe claim for our module support, even though it's already unsupported by Postgres. See https://docs.travis-ci.com/user/database-setup/#using-a-different-postgresql-version I'll raise a separate ticket about testing and supporting newer versions, it's out of scope for this PR. 2019-09-03 05:41:23 +02:00			```
			`composer require silverstripe/postgresql`
			```

			`## Configuration`

			`### Environment file`

			Add the following settings to your `.env` file:

			```
			`SS_DATABASE_CLASS=PostgreSQLDatabase`
			`SS_DATABASE_USERNAME=`
			`SS_DATABASE_PASSWORD=`
			```

			See [environment variables](https://docs.silverstripe.org/en/4/getting_started/environment_management) for more details. Note that a database will automatically be created via `dev/build`.

			`### Through the installer`

			`Open the installer by browsing to install.php, e.g. http://localhost/install.php`
			`Select PostgreSQL in the database list and enter your database details`
MINOR: update Postgres doc for docviewer support. FIXES: #6681 2012-06-29 07:56:38 +02:00
			`## Usage Overview`

API Increased support to 9.2 Anything older than 9.3 is unsupported by Postgres: https://www.postgresql.org/support/versioning/. I don't think we should claim support in our module for unsupported versions, particularly if we don't have CI on them. Since we're only running CI on 9.2 at the moment, that's the safe claim for our module support, even though it's already unsupported by Postgres. See https://docs.travis-ci.com/user/database-setup/#using-a-different-postgresql-version I'll raise a separate ticket about testing and supporting newer versions, it's out of scope for this PR. 2019-09-03 05:41:23 +02:00			`See [docs/en](docs/en/README.md) for more information about configuring the module.`
MINOR: update Postgres doc for docviewer support. FIXES: #6681 2012-06-29 07:56:38 +02:00
			`## Known issues`

			`All column and table names must be double-quoted. PostgreSQL automatically`
			`lower-cases columns, and your queries will fail if you don't.`

DOCS Known issue about collations Moving from https://docs.silverstripe.org/en/4/getting_started/server_requirements/ since it's too much noise there. Also removing the maintainer contact, that's an outdated concept. 2019-09-03 05:22:14 +02:00			`Collations have known issues when installed on Alpine, MacOS X and BSD derivatives`
Merge branch 'pulls/docs-known-issue' into 2 # Conflicts: # README.md # 2019-11-28 02:33:06 +01:00			`(see [PostgreSQL FAQ](https://wiki.postgresql.org/wiki/FAQ#Why_do_my_strings_sort_incorrectly.3F)).`
			`We do not support such installations, although they still may work correctly for you.`
DOCS Known issue about collations Moving from https://docs.silverstripe.org/en/4/getting_started/server_requirements/ since it's too much noise there. Also removing the maintainer contact, that's an outdated concept. 2019-09-03 05:22:14 +02:00			`As a workaround for PostgreSQL 10+ you could manually switch to ICU collations (e.g. und-x-icu).`
			`There are no known workarounds for PostgreSQL <10.`

MINOR: update Postgres doc for docviewer support. FIXES: #6681 2012-06-29 07:56:38 +02:00			`Ts_vector columns are not automatically detected by the built-in search`
			`filters. That means if you're doing a search through the CMS on a ModelAdmin`
			`object, it will use LIKE queries which are very slow. If you're writing your`
			`own front-end search system, you can specify the columns to use for search`
			`purposes, and you get the full benefits of T-Search.`

			`If you are using unsupported modules, there may be instances of MySQL-specific`
Updated supported SS release in README 2015-11-02 20:45:29 +01:00			`SQL queries which will need to be made database-agnostic where possible.`