{"id":19040791,"url":"https://github.com/cloudfoundry/postgres-release","last_synced_at":"2025-08-21T10:32:17.881Z","repository":{"id":9900002,"uuid":"63715111","full_name":"cloudfoundry/postgres-release","owner":"cloudfoundry","description":"BOSH release for PostgreSQL","archived":false,"fork":false,"pushed_at":"2024-09-14T03:02:02.000Z","size":14772,"stargazers_count":14,"open_issues_count":2,"forks_count":38,"subscribers_count":14,"default_branch":"main","last_synced_at":"2024-09-14T16:00:33.133Z","etag":null,"topics":["bosh","postgres"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudfoundry.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-07-19T17:40:32.000Z","updated_at":"2024-09-14T03:02:05.000Z","dependencies_parsed_at":"2022-07-24T20:30:05.533Z","dependency_job_id":"95659dbf-fbf4-44f9-ad9e-466842dceaa5","html_url":"https://github.com/cloudfoundry/postgres-release","commit_stats":null,"previous_names":[],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfoundry%2Fpostgres-release","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfoundry%2Fpostgres-release/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfoundry%2Fpostgres-release/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudfoundry%2Fpostgres-release/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudfoundry","download_url":"https://codeload.github.com/cloudfoundry/postgres-release/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230507051,"owners_count":18236944,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bosh","postgres"],"created_at":"2024-11-08T22:25:12.144Z","updated_at":"2025-08-21T10:32:17.868Z","avatar_url":"https://github.com/cloudfoundry.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# postgres-release\n---\n\nThis is a [BOSH](https://www.bosh.io) release for [PostgreSQL](https://www.postgresql.org/).\n\n## Contents\n\n* [Deploying](#deploying)\n* [Customizing](#customizing)\n* [Contributing](#contributing)\n* [Known Limitation](#known-limitation)\n* [Upgrading](#upgrading)\n* [CI](#ci)\n\n## Deploying\n\nIn order to deploy the postgres-release you must follow the standard steps for deploying software with BOSH.\n\n1. Deploy and run a BOSH director.\n   Please refer to [BOSH documentation](http://bosh.io/docs) for instructions on how to do that.\n   Bosh-lite specific instructions can be found [here](https://github.com/cloudfoundry/bosh-lite).\n\n1. Install the BOSH command line Interface (CLI) v2+.\n   Please refer to [BOSH CLI documentation](https://bosh.io/docs/cli-v2.html#install). Use the CLI to target your director.\n\n1. Upload the desired stemcell directly to bosh. [bosh.io](http://bosh.io/stemcells) provides a resource to find and download stemcells.\n\n   ```\n   # Example for bosh-lite\n   bosh upload-stemcell https://bosh.io/d/stemcells/bosh-warden-boshlite-ubuntu-xenial-go_agent\n   ```\n\n1. Upload the latest release from [bosh.io](http://bosh.io/releases/github.com/cloudfoundry/postgres-release?all=1):\n\n   ```\n   bosh upload-release https://bosh.io/d/github.com/cloudfoundry/postgres-release\n   ```\n\n   or create and upload a development release:\n\n   ```\n   cd ~/workspace/postgres-release\n   bosh -n create-release --force \u0026\u0026 bosh -n upload-release\n   ```\n\n1. Generate the manifest. You can provide in input an [operation file](https://bosh.io/docs/cli-ops-files.html) to customize the manifest:\n\n   ```\n   ~/workspace/postgres-release/scripts/generate-deployment-manifest \\\n   -o OPERATION-FILE-PATH \u003e OUTPUT_MANIFEST_PATH\n   ```\n\n   You can use the operation file to specify `postgres` job properties or to override the configuration if your BOSH director [cloud-config](http://bosh.io/docs/cloud-config.html) is not compatible.\n\n   [This example operation file](templates/operations/set_properties.yml) is a great starting point.\n   Note: when using this operation file, you will need to inject `pgadmin_database_password` at `bosh deploy`-time, which is a good pattern for keeping credentials out of manifests.\n\n   You are also provided with options to enable TLS in the PostgreSQL server or to use static ips.\n\n1. Deploy:\n\n   ```\n   bosh -d DEPLOYMENT_NAME deploy OUTPUT_MANIFEST_PATH\n   ```\n\n   Example, injecting the `pgadmin_database_password` variable:\n\n   ```\n   bosh -d DEPLOYMENT_NAME deploy -v pgadmin_database_password=foobarbaz OUTPUT_MANIFEST_PATH\n   ```\n\n## Customizing\n\nThe table below shows the most significant properties you can use to customize your PostgreSQL installation.\nThe complete list of available properties can be found in the [spec](jobs/postgres/spec).\n\nProperty | Description\n-------- | -------------\ndatabases.version | Define the used PostgreSQL major version. Default: 16\ndatabases.port | The database port. Default: 5432\ndatabases.databases | A list of databases and associated properties to create when Postgres starts\ndatabases.databases[n].name | Database name\ndatabases.databases[n].citext | If `true` the citext extension is created for the db\ndatabases.roles | A list of database roles and associated properties to create\ndatabases.roles[n].name | Role name\ndatabases.roles[n].password | Login password for the role. If not provided, TLS certificate authentication is assumed for the user.\ndatabases.roles[n].common_name| The cn attribute of the certificate for the user. It only applies to TLS certificate authentication.\ndatabases.roles[n].permissions| A list of attributes for the role. For the complete list of attributes, refer to [ALTER ROLE command options](https://www.postgresql.org/docs/9.4/static/sql-alterrole.html).\ndatabases.tls.certificate | PEM-encoded certificate for secure TLS communication\ndatabases.tls.private_key | PEM-encoded key for secure TLS communication\ndatabases.tls.ca | PEM-encoded certification authority for secure TLS communication. Only needed to let users authenticate with TLS certificate.\ndatabases.max_connections | Maximum number of database connections\ndatabases.log_line\\_prefix | The postgres `printf` style string that is output at the beginning of each log line. Default: `%m:`\ndatabases.collect_statement\\_statistics | Enable the `pg_stat_statements` extension and collect statement execution statistics. Default: `false`\ndatabases.additional_config | A map of additional key/value pairs to include as extra configuration properties in `postgresql.conf`\ndatabases.monit_timeout | Monit timout in seconds for the postgres job start. Default: `90`.\ndatabases.trust_local_connection | Whether or not postgres must trust local connections. `vcap` is always trusted. It defaults to `true`.\ndatabases.skip_data_copy_in_minor | Whether or not a copy of the data directory is created during PostgreSQL minor upgrades. A copy is created by default.\ndatabases.hooks.timeout | Time limit in seconds for the hook script. By default, it's set to `0` that means no time limit.\ndatabases.hooks.pre-start | Script to run before starting PostgreSQL.\ndatabases.hooks.post-start | Script to run after PostgreSQL has started.\ndatabases.hooks.pre-stop | Script to run before stopping PostgreSQL.\ndatabases.hooks.post-stop | Script to run after PostgreSQL has stopped.\ndatabases.logging.format.timestamp | Format for timestamp in control jobs logs. By default it's set to `rfc3339`.\njanitor.script | If specified, this script would be run periodically. This would be useful for running house-keeping tasks.\njanitor.interval | Interval in seconds between two invocations of the janitor script. By default it's set to `1` day.\njanitor.timeout | Time limit in seconds for the janitor script. By default it's set to `0` that means no time limit.\n\n*Note*\n- Removing a database from `databases.databases` list and deploying again does not trigger a physical deletion of the database in PostgreSQL.\n- Removing a role from `databases.roles` list and deploying again does not trigger a physical deletion of the role in PostgreSQL.\n\n### Enabling TLS on the PostgreSQL server\nPostgreSQL has native support for using TLS connections to encrypt client/server communications for increased security.\nYou can enable it by setting the `databases.tls.certificate` and the `databases.tls.private_key` properties.\n\nA script is provided that creates a CA, generates a key pair, and signs it with the CA:\n\n```\n./scripts/generate-postgres-certs -n HOSTNAME_OR_IP_ADDRESS\n```\n The common name for the server certificate must be set to the DNS hostname if any or to the ip address of the PostgreSQL server. This because in TLS mode `verify-full`, the hostname is matched against the common-name. Refer to [PostgreSQL documentation](https://www.postgresql.org/docs/9.6/static/libpq-ssl.html) for more details.\n\n You can also use [BOSH variables](https://bosh.io/docs/cli-int.html) to generate the certificates. See by way of [example](templates/operations/use_ssl.yml) the operation file used by the manifest generation script.\n\n```\n~/workspace/postgres-release/scripts/generate-deployment-manifest \\\n   -s -h HOSTNAME_OR_IP_ADDRESS \\\n   -o OPERATION-FILE-PATH \u003e OUTPUT_MANIFEST_PATH\n\n```\n### Enabling TLS certificate authentication\n\nIn order to perform authentication using TLS client certificates, you must not specify a user password and you must configure the following properties:\n\n- `databases.tls.certificate`\n- `databases.tls.private_key`\n- `databases.tls.ca`\n\nThe cn (Common Name) attribute of the certificate will be compared to the requested database user name, and if they match the login will be allowed.\n\nOptionally you can map the common_name to a different database user by specifying property `databases.roles[n].common_name`.\n\nA script is provided that creates a client certificates:\n\n```\n./scripts/generate-postgres-client-certs --ca-cert \u003cPATH-TO-CA-CERT\u003e --ca-key \u003cPATH-TO-CA-KEY\u003e --client-name \u003cUSER_NAME\u003e\n```\n\n### Hooks\nYou can run custom code before or after PostgreSQL starts or stops or periodically.\nFor details, see [hooks](docs/hooks.md) documentation.\n\n### Backup and Restore\nYou can enable backup and restore through bbr by adding the `bbr-postgres-db` job with the `postgres` job and by setting its `release_level_backup` option to `true`. If enabled, a backup is collected using `pg_dump` for each database specified in the `databases.databases` property.\n\nIf you don't colocate the `bbr-postgres-db` with `postgres` then you must specify in the `postgres.dbuser` property a database user with enough permissions to run backup and restore.\n\nIf your PostgreSQL is configured with TLS, by default backup and restore are run with `sslmode=verify-full`. You can change it to `sslmode=verify-ca` by setting `postgres.ssl_verify_hostname` to `false`.\n\nCaveats:\n\n- Restore does not drop the database, the extensions, or the schema; therefore the schema of the restored and existing databases must be the same.\n- If a backup is not present for one of the configured databases in the `databases.databases` property, the restore issues a message and continues.\n\n## Contributing\n\n### Contributor License Agreement\n\nContributors must sign the Contributor License Agreement before their contributions can be merged.\nFollow the directions [here](https://www.cloudfoundry.org/community/contribute/) to complete that process.\n\n### Developer Workflow\n\n1. [Fork](https://help.github.com/articles/fork-a-repo) the repository and make a local [clone](https://help.github.com/articles/fork-a-repo#step-2-create-a-local-clone-of-your-fork)\n1. Create a feature branch from the development branch\n\n   ```bash\n   cd postgres-release\n   git checkout develop\n   git checkout -b feature-branch\n   ```\n1. Make changes on your branch\n1. Test your changes by running [acceptance tests](docs/acceptance-tests.md)\n1. Push to your fork (`git push origin feature-branch`) and [submit a pull request](https://help.github.com/articles/creating-a-pull-request) selecting `develop` as the target branch.\n   PRs submitted against other branches will need to be resubmitted with the correct branch targeted.\n\n## Known Limitations\n\nThe postgres-release does not directly support high availability.\nEven if you deploy more instances, no replication is configured.\n\n## Upgrading\n\nRefer to [versions.yml](versions.yml) in order to assess if a postgres-release version upgrades the PostgreSQL version.\n\n### Upgrade Test Policy\n\nThe maintainers of the postgres-release test the following upgrade paths:\n\n* From the previous postgres-release\n* From the latest postgres-release that bumps the previous PostgreSQL version\n* From the latest cf-deployment that bumps the previous PostgreSQL version\n\n### Considerations before deploying\n\n1. A copy of the database is made for the upgrade, you may need to adjust the persistent disk capacity of the `postgres` job.\n    - For major upgrades the copy is always created\n    - For minor upgrades the copy is created unless the `databases.skip_data_copy_in_minor` is set to `true`.\n1. The upgrade happens as part of the pre-start and its duration may vary basing on your env.\n    - In case of a PostgreSQL minor upgrade a simple copy of the old data directory is made.\n    - In case of a PostgreSQL major upgrade the `pg_upgrade` utility is used.\n1. Postgres will be unavailable during this upgrade.\n\n### Considerations after a successful deployment\n\nPostgreSQL upgrade may require some post-upgrade processing. The administrator should check the `/var/vcap/store/postgres/pg_upgrade_tmp` directory for the generated script files and eventually run them. See [pg_upgrade post-upgrade processing](https://www.postgresql.org/docs/11/pgupgrade.html) for more details.\n\nIn case a copy of the old database is kept (see considerations above), the old database is moved to `/var/vcap/store/postgres/postgres-previous`. The postgres-previous directory will be kept until the next postgres upgrade is performed in the future. You are free to remove this if you have verified the new database works and you want to reclaim the space.\n\n### Recovering a failure during deployment\n\nIn case of a long upgrade, the deployment may time out; anyway, bosh would not stop the actual upgrade process. In this case you can just wait for the upgrade to complete and, only when postgres is up and running, rerun the bosh deploy.\n\nIf the upgrade fails:\n\n- The old data directory is still available at `/var/vcap/store/postgres/postgres-x.x.x` where `x.x.x` is the old PostgreSQL version\n- The new data directory is at `/var/vcap/store/postgres/postgres-y.y.y` where `y.y.y` is the new PostgreSQL version\n- If the upgrade is a PostgreSQL major upgrade:\n  - A marker file is kept at `/var/vcap/store/postgres/POSTGRES_UPGRADE_LOCK` to prevent the upgrade from happening again.\n  - `pg_upgrade` logs that may have details of why the migration failed can be found in `/var/vcap/sys/log/postgres/postgres_ctl.log`\n\nIf you want to attempt the upgrade again or to roll back to the previous release, you should remove the new data directory and, if present, the marker file.\n\n\n## CI\n\nThe [CI pipeline](https://bosh.ci.cloudfoundry.org/teams/main/pipelines/postgres-release/jobs/run-acceptance-tests)runs:\n\n- the postgres-release [acceptance tests](docs/acceptance-tests.md)\n- the supported [upgrade paths](#upgrade-test-policy)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudfoundry%2Fpostgres-release","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudfoundry%2Fpostgres-release","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudfoundry%2Fpostgres-release/lists"}