Docs

Migrating to Postgres 17

Migrate a FOSSA-managed Postgres 11.8 database to a standalone Postgres 17.x instance before the bundled-Postgres deprecation.

5 min readUpdated Jul 9, 2026

Overview

This guide walks through migrating a FOSSA-managed Postgres database (version 11.8) to a standalone Postgres 17.x instance. For customers running databases inside Kubernetes, the example steps use the fossa/postgres Helm chart, but any properly configured Postgres 17.x database is supported.

Warning

After June 16, 2025, FOSSA no longer bundles a Postgres database within the FOSSA Helm charts. If you currently rely on the built-in provisioned instances (postgres.provisionInstance, hubble.postgres.provisionInstance, or sparklePostgres.provisionInstance), you must migrate to an externally provisioned Postgres 17 database to keep receiving updates.

For Postgres running inside your cluster, we recommend the fossa/postgres 2.0.0+ Helm chart as a convenient, tested deployment method. Any properly configured Postgres 17.x database (Amazon RDS, Aurora Postgres, or self-managed Postgres 17) is also supported.

Prerequisites

  • psql client 17.x (Postgres 17.2)
  • helm 3.17+
  • kubectl 1.28+ with Kubernetes API access
  • FOSSA Helm charts, including the fossa/postgres chart version 2.0.0+ (see Set up Helm)
  • Quay pull secrets

Recommendations

  • The default resource values for database deployments match FOSSA Core's defaults. If your application has customized resource requirements, adjust the database configuration files accordingly.
  • If you use external Postgres services (e.g. RDS or self-hosted instances), ensure that:
    • Required extensions (pgcrypto, uuid-ossp) are available.
    • The database is reachable from the FOSSA application. (SSL is not currently supported.)
    • Authentication credentials and roles allow schema migrations.
  • If your vulns updater is disabled, ignore the associated configuration steps in this guide.

Assumptions

The example commands assume:

  • Your Helm release is named fossa.
  • Database credentials are fossa / fossa123 for Core, Sparkle, and Hubble, with services:
    • Core: old: fossa-core-postgres, new: postgres-core
    • Sparkle: old: fossa-sparkle-postgres, new: postgres-sparkle
    • Hubble: old: fossa-hubble-postgres, new: postgres-hubble
  • Resource settings align with Core's defaults unless otherwise specified.
  • The vulns updater is enabled.
  • Quay.io pull secrets are username fossa+customer, password HELLOWORLD1.

Migration steps

  1. 1

    Add the FOSSA chart repository

    Shell
    helm repo add fossa https://charts.fossa.comhelm repo update
  2. 2

    Set the namespace

    Shell
    kubectl config set-context --current --namespace=fossa
  3. 3

    Create a values file for each database

    Create a values file for the Core, Sparkle, and Hubble databases with the appropriate credentials and resources for the Postgres chart.

    Core: core-psql-values.yml

    YAML
    database: fossausername: fossapassword: fossa123image.registry: quay.ioimage.repository: fossa/postgresimage.tag: 17.2-1 imageCredentials:  username: fossa+customer  password: HELLOWORLD1 resources:  limits:    cpu: 4000m    memory: 4Gi  requests:    cpu: 2000m    memory: 4Gi

    Sparkle: sparkle-psql-values.yml

    YAML
    database: sparkleusername: fossapassword: fossa123image.registry: quay.ioimage.repository: fossa/postgresimage.tag: 17.2-1 imageCredentials:  username: fossa+customer  password: HELLOWORLD1 resources:  limits:    cpu: 4000m    memory: 4Gi  requests:    cpu: 2000m    memory: 4Gi

    Hubble: hubble-psql-values.yml

    YAML
    database: hubbleusername: fossapassword: fossa123image.registry: quay.ioimage.repository: fossa/postgresimage.tag: 17.2-1 imageCredentials:  username: fossa+customer  password: HELLOWORLD1 resources:  limits:    cpu: 4000m    memory: 4Gi  requests:    cpu: 2000m    memory: 4Gi
  4. 4

    Install the Postgres chart for each database

    Shell
    helm upgrade -i postgres-core fossa/postgres --values core-psql-values.ymlhelm upgrade -i postgres-sparkle fossa/postgres --values sparkle-psql-values.ymlhelm upgrade -i postgres-hubble fossa/postgres --values hubble-psql-values.yml
  5. 5

    Set the application to maintenance mode

    Shell
    helm upgrade -i fossa fossa/fossa-core --set global.maintenanceMode.enabled=true --set vulns.updater.enabled=false --reuse-values

    If your vulns updater is disabled, omit the vulns parameters:

    Shell
    helm upgrade -i fossa fossa/fossa-core --set global.maintenanceMode.enabled=true --reuse-values
  6. 6

    Back up the databases

    Back up the Core, Hubble, and Sparkle databases, terminating each port-forward when the dump completes.

    Core

    Shell
    kubectl port-forward service/fossa-core-postgres 5432:5432 &pg_dumpall -h localhost -U fossa -f fossa-core-backup.bkp# Terminate the port-forward using `fg` and `Ctrl+C`fg

    Sparkle

    Shell
    kubectl port-forward service/fossa-sparkle-postgres 5432:5432 &pg_dumpall -h localhost -U fossa -f fossa-sparkle-backup.bkp# Terminate the port-forward using `fg` and `Ctrl+C`fg

    Hubble

    Shell
    kubectl port-forward service/fossa-hubble-postgres 5432:5432 &pg_dumpall -h localhost -U fossa -f fossa-hubble-backup.bkp# Terminate the port-forward using `fg` and `Ctrl+C`fg
  7. 7

    Restore the databases

    Restore each database from its backup into the new instance.

    Core

    Shell
    kubectl port-forward service/postgres-core 5432:5432 &psql -h localhost -U fossa -d fossa -f fossa-core-backup.bkp# Terminate the port-forward using `fg` and `Ctrl+C`fg

    Sparkle

    Shell
    kubectl port-forward service/postgres-sparkle 5432:5432 &psql -h localhost -U fossa -d sparkle -f fossa-sparkle-backup.bkp# Terminate the port-forward using `fg` and `Ctrl+C`fg

    Hubble

    Shell
    kubectl port-forward service/postgres-hubble 5432:5432 &psql -h localhost -U fossa -d hubble -f fossa-hubble-backup.bkp# Terminate the port-forward using `fg` and `Ctrl+C`fg
  8. 8

    Check database health

    Shell
    kubectl logs sts/postgres-core -fkubectl logs sts/postgres-sparkle -fkubectl logs sts/postgres-hubble -f
  9. 9

    Point the applications at the new databases

    Core

    Shell
    helm upgrade -i fossa fossa/fossa-core --set postgres.host=postgres-core --reuse-values

    Sparkle

    Shell
    helm upgrade -i fossa fossa/fossa-sparkle --set sparklePostgres.externalHost=postgres-sparkle --reuse-values

    Hubble

    Shell
    helm upgrade -i fossa fossa/fossa-hubble --set hubble.postgres.host=postgres-hubble --reuse-values
  10. 10

    Set the application to production mode

    Shell
    helm upgrade -i fossa fossa/fossa-core --set global.maintenanceMode.enabled=false --set vulns.updater.enabled=true --reuse-values

    If your vulns updater is disabled, omit the vulns parameters:

    Shell
    helm upgrade -i fossa fossa/fossa-core --set global.maintenanceMode.enabled=false --reuse-values
  11. 11

    Confirm the application is healthy

    Shell
    kubectl logs deployment/fossa-fossa-core-api -fkubectl logs deployment/fossa-fossa-core-workers-primary -fkubectl logs deployment/fossa-fossa-hubble-api -fkubectl logs deployment/fossa-fossa-core-sparkle-api -f
  12. 12

    Update your main values file

    After confirming the applications are healthy, update your values file to use the new databases.

    YAML
    postgres:  host: postgres-core sparklePostgres:  externalHost: postgres-sparkle hubble:  postgres:    host: postgres-hubble

Connecting to an external database

If you're connecting FOSSA Core to an external Postgres 17.x service such as Amazon RDS, Aurora, or self-hosted Postgres:

  • You don't need to deploy the Postgres Helm charts.
  • Update your FOSSA Helm values to point at the external database hostnames.
  • Ensure firewall/endpoint access between FOSSA pods and your database.
  • Ensure required extensions (pgcrypto, uuid-ossp) are enabled.
  • Review resource sizing and connection-pool settings for performance.

Example for an external RDS database:

YAML
postgres:  host: your-rds-endpoint.amazonaws.com  username: fossa  password: your-fossa-password  database: fossa

Repeat similar configuration for Sparkle and Hubble if those services are deployed.

Final verification

Once all updates are complete:

  • Ensure all FOSSA pods are healthy.
  • Verify schema migrations completed successfully.
  • Confirm FOSSA Core, Sparkle, and Hubble are operating normally.
  • Confirm the data from before the upgrade is still available in the web interface.
PreviousGlobal License CorrectionsNextMigrating to SeaweedFS
© 2026 FOSSA, Inc.support@fossa.com