maverick/docbrown
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Expand documentation on how to connect to PostgreSQL (#479)

Browse source 
* Expand documentation on how to connect to PostgreSQL

* Add link to Rails guides and PostgreSQL connection strings

* Expand warning wording
This commit is contained in:
rhymes 2018-08-28 21:56:31 +02:00 • committed by Mac Siri
parent 42d2384430
commit ae3e0b4e8e
1 changed files with 39 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
docs/additional-postgres-setup.md
View file

@ -1,34 +1,58 @@
# Setup your application with PostgreSQL
Follow the instructions in the installation guide below that corresponds to your operating system.
Follow the instructions in the installation guide below that corresponds to your operating system:
1. [Mac OS](https://postgresapp.com/)
2. Linux / Ubuntu
1. macOS
* [Postgres.app](https://postgresapp.com/): PostgreSQL installation as a Mac app
* [Homebrew](https://brew.sh/): if you use Homebrew you can easily install PostgreSQL with `brew install postgresql`
2. Linux (Ubuntu)
* [Ubuntu `14.04`](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-14-04)
* [Ubuntu `16.04 and higher`](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-16-04)
3. [Windows](https://www.postgresql.org/download/windows/)
##### You can find all installation packages for different operating systems [here](https://www.postgresql.org/download/).
_You can find all installation options for a variety of operating systems [on the official PostgreSQL download page](https://www.postgresql.org/download/)_.
##### After installation
## Configuration
1. If your Rails app is unable to connect to the PostgreSQL, then update your `database.yml` file with `username` and `password`.
By default the application is configured to connect to a local database named `PracticalDeveloper_development`. If you need to specify a username and a password you can go about it two ways: using the environment variable `DATABASE_URL` with a connection string (preferred method) or modifying the file `database.yml`.
The [official Rails guides](https://guides.rubyonrails.org/configuring.html#connection-preference) go into depth on how Rails merges the existing `database.yml` with the connection string.
### Setup `DATABASE_URL` in application.yml
1. Open your `config/application.yml`
2. Add the following:
```yml
DATABASE_URL: postgresql://USERNAME:PASSWORD@localhost/PracticalDeveloper_development
```
3. Replace `USERNAME` with your database username, `PASSWORD` with your database password.
You can find more details on connection strings in [PostgreSQL's own documentation](https://www.postgresql.org/docs/10/static/libpq-connect.html#LIBPQ-CONNSTRING).
### Modify connection params in `database.yml`
The other option is to change the `database.yml` directly.
Update your `database.yml` file with `username` and `password`:
```yaml
development:
<<: *default
username: POSTGRESSQL_USERNAME
password: POSTGRESSQL_PASSWORD
username: USERNAME
password: PASSWORD
test:
<<: *default
username: POSTGRESSQL_USERNAME
password: POSTGRESSQL_PASSWORD
username: USERNAME
password: PASSWORD
```
2. While running test cases, if you get an error message `postgresql connection timeout`. Go to your `spec/support/database_cleaner.rb` file. And rename `:truncation` with `:deletion`.
**Keep in mind not to commit your modified `database.yml` containing your credentials under any circumstances to any repository.**
##### Notes
## Troubleshooting tests
1. Don't forget to set up your PostgreSQL with `username` and `password`.
2. Don't commit your `database.yml` or `database_cleaner.rb` files. Or PostgreSQL `username` and `password` to any repository.
3. You can use environment variables for storing `username` and `password`. You can define them inside the `application.yml` file.
* While running test cases, if you get an error message `postgresql connection timeout`. Go to your `spec/support/database_cleaner.rb` file. And rename `:truncation` with `:deletion`.
_Please, do not commit `database_cleaner.rb` to the repository either._