https://github.com/icflorescu/openshift-cartridge-postgresql
Custom OpenShift cartridge aiming to provide the most recent stable PostgreSQL version packaged by bigsql.org.
https://github.com/icflorescu/openshift-cartridge-postgresql
cartridge database database-engine gear openshift postgresql sql
Last synced: 9 months ago
JSON representation
Custom OpenShift cartridge aiming to provide the most recent stable PostgreSQL version packaged by bigsql.org.
- Host: GitHub
- URL: https://github.com/icflorescu/openshift-cartridge-postgresql
- Owner: icflorescu
- License: isc
- Created: 2016-05-25T15:46:21.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2017-04-01T13:54:17.000Z (almost 9 years ago)
- Last Synced: 2024-05-02T05:32:56.538Z (almost 2 years ago)
- Topics: cartridge, database, database-engine, gear, openshift, postgresql, sql
- Language: Shell
- Homepage:
- Size: 15.6 KB
- Stars: 6
- Watchers: 2
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Custom PostgreSQL cartridge for OpenShift
This is a custom OpenShift cartridge aiming to provide the most recent stable PostgreSQL version packaged by [bigsql.org](http://www.bigsql.org/).
## Installation
**Warning! You're using this cartridge on your own responsibility**.
### Using the [web console](https://openshift.redhat.com/app/console/applications)
To install this cartridge in your existing OpenShift application, go to **"See the list of cartridges you can add"**, paste the URL below in **"Install your own cartridge"** textbox at the bottom of the page and click "Next".
https://raw.githubusercontent.com/icflorescu/openshift-cartridge-postgresql/master/metadata/manifest.yml
### Using the command line
To add this cartridge to an existing application named `awesomeapp`, run:
rhc cartridge add -a awesomeapp \
https://raw.githubusercontent.com/icflorescu/openshift-cartridge-postgresql/master/metadata/manifest.yml
Using `rhc` utility, you can also create "from scratch" an applocation based on multiple cartridges. For instance, assuming you'd want a primary Node.js web application provided by [this community cartridge](https://hub.openshift.com/quickstarts/243-node-js-latest), run:
rhc app create awesomeapp \
https://raw.githubusercontent.com/icflorescu/openshift-cartridge-nodejs/master/metadata/manifest.yml \
https://raw.githubusercontent.com/icflorescu/openshift-cartridge-postgresql/master/metadata/manifest.yml
## Usage
### Connect from a web application cartridge
Use the following environment variables to connect from an application running in the main web cartridge:
- `OPENSHIFT_PG_HOST`
- `OPENSHIFT_PG_PORT`
- `OPENSHIFT_PG_USERNAME`
- `OPENSHIFT_PG_PASSWORD`
- `OPENSHIFT_PG_DATABASE`
For instance, here's how you'd do it in a Node.js application using Knex.js:
var knex = require('knex')({
client: 'pg',
connection: {
host : process.env.OPENSHIFT_PG_HOST,
port: : process.env.OPENSHIFT_PG_PORT,
user : process.env.OPENSHIFT_PG_USERNAME',
password : process.env.OPENSHIFT_PG_PASSWORD,
database : process.env.OPENSHIFT_PG_DATABASE
}
});
### Connect from a local development environment using `rhc port-forward`
You can use `rhc port-forward` to connect from a client application running on your local development machine.
If your PostgreSQL instance is running in a separate gear, you can find its gear id by running:
rhc app show application-name --gears
Then you can do port forwarding like this:
rhc port-forward application-name -g gear-id
Connect your client application to the port forwarded on `127.0.0.1`.
**Please don't open issues in this repository to ask for help on using `rhc port-forward`, or `rhc` utility in general.** Refer to the [OpenShift Online Documentation](https://developers.openshift.com/en/managing-port-forwarding.html) instead. If you still can't find what you're looking for, Google for it or ask on Stackoverflow. And if you still can't figure it out, it's probably not safe for you to use it.
### Connect from a local development environment using SSH tunnels
Some SQL clients (like [DBeaver](http://dbeaver.jkiss.org/) or [Valentina Studio](https://www.valentina-db.com/en/valentina-studio-overview)) can create SSH tunnels, in which case you won't have to use the `rhc port-forward`. For instance, if you've deployed PostgreSQL in a separate gear, you'll have to configure the connection as following:
- **Host** is the gear SSH URL **without the username part** as the host (could be something like `xxxxxxxxxxxxxxxxxxxxxxxx-awesomeapp.rhcloud.com`) and `$OPENSHIFT_PG_PROXY_PORT`;
- **Database, username and password** are what you have in `$OPENSHIFT_PG_USERNAME`, `$OPENSHIFT_PG_USERNAME` and `$OPENSHIFT_PG_PASSWORD`;
- In the **SSH tunnel config section**, use the same host and username and public key authentication with your SSH key (usually found in `~/ssh` folder).
But your specific configuration may differ, so you'll have to figure it out by trial, error and consulting the appropriate documentation. **Please refrain from opening issues in this repository to ask for help on configuring your SQL client**. If you can't figure it out by yourself, it's probably not safe you to use it.
## Notes
### Files and folder locations
- Upon installation, the [DevOps linux64 sandbox](http://www.bigsql.org/postgresql/installers.jsp) is downloaded from [bigsql.org](http://www.bigsql.org/) and expanded automatically in `${OPENSHIFT_DATA_DIR}.bigsql`;
- The PostgreSQL data folder is `${OPENSHIFT_DATA_DIR}.pgdata`;
- The configuration files `pg_hba.conf` and `postgresql.conf` are stored in the PostgreSQL data folder;
- Log files are created in `${OPENSHIFT_LOG_DIR}` folder;
- `psql` history files are created in `${OPENSHIFT_DATA_DIR}` folder;
- The PostgreSQL shared folder is `${OPENSHIFT_DATA_DIR}.bigsql/pg95/share/postgresql`;
### Unsupported features
The autovacuum and statistics collection features are not supported by OpenShift setups (more info available [here](http://stackoverflow.com/questions/23215429/autovacuum-is-not-running-on-openshift-online-postgres-cartridge) and [here](https://bugzilla.redhat.com/show_bug.cgi?id=849428)).
A `vacuumdb -a -f` command is issued when executing the cartridge `tidy` script, so you can periodically use `rhc app tidy` to regain storage space.
### Optional features
This cartridge **does not autoupdate**. If you need this feature and are willing to contribute, feel free to PR.
In order to conserve space, the `postgis` extension is not installed by default, but the cartridge includes a handy script to install it. You'll have to login to your gear and run `postgres/bin/install-postgis`, then execute the SQL statement `CREATE EXTENSION postgis`.
### Full-text search for languages other than English
You can alter the default full-text search behavior by changing/adding the necessary files in `${OPENSHIFT_DATA_DIR}.bigsql/pg95/share/postgresql/tsearch_data`. The files distributed by default in the PostgreSQL package are insufficient for languages other than English, but you can add your own `*.stop` or dictionary files, or even modify the standard `unaccent.rules` as needed. Have a look at [this repo](https://github.com/icflorescu/postgresql-tsearch-utils) to learn more.
## Read carefully before raising issues
I'm getting lots of questions from people just learning to do web development or simply looking to solve a very specific problem they're dealing with. While I will answer some of them for the benefit of the community, please understand that open-source is a shared effort and it's definitely not about piggybacking on other people's work. On places like GitHub, that means raising issues is encouraged, but **coming up with useful pull-requests is a lot better**. If I'm willing to share some of my code for free, I'm doing it for a number of reasons: my own intellectual challenges, pride, arrogance, stubbornness to believe I'm bringing a contribution to common progress and freedom, etc. Your particular well-being is probably not one of those reasons. I'm not in the business of providing free consultancy, so if you need my help to solve your specific problem, there's a fee for that.
## Asking for help or a new feature
See the note above. If you need help and are willing to pay for it, drop me a message. If you have an idea about a new feature that doesn't break existing ones and you're willing to invest effort to make it happen, have a look at the code and feel free to make a PR.
## Helping to release a new version
You can find the PostgreSQL version installed by this cartridge by looking at the `Version` token in [metadata/manifest.yml](https://github.com/icflorescu/openshift-cartridge-postgresql/blob/master/metadata/manifest.yml).
If you notice it's behind the latest stable release from [bigsql.org](http://www.bigsql.org/postgresql/installers.jsp), fork the repo, change the version number, **make sure to test** a fresh deployment on your OpenShift account, then submit a PR.
## Credits
Built by [icflorescu](https://github.com/icflorescu). See contributors [here](https://github.com/icflorescu/openshift-cartridge-postgresql/graphs/contributors).
If you find this repo useful, don't hesitate to give it a star and [spread the word](http://twitter.com/share?text=Checkout%20this%20custom%20PostgreSQL%20cartridge%20for%20OpenShift!&url=http%3A%2F%2Fgithub.com/icflorescu/openshift-cartridge-postgresql&hashtags=PostgreSQL,database,OpenShift&via=icflorescu).
## License
The [ISC License](http://github.com/icflorescu/openshift-cartridge-postgresql/blob/master/LICENSE).