Skip to main content
Illustration by Annie Ruygt of a balloon doing a lot of tasks

​
Creating a Managed Postgres Cluster from the Dashboard

To create a new Managed Postgres (MPG) cluster, visit your Fly.io dashboard, select the “Managed Postgres” tab on the left, and click the “Create new cluster” button. You’ll be prompted to set your clusters:
  • Cluster name (must be unique within your organization)
  • Region (see available MPG regions)
  • A plan with predefined hardware resources:
    • Basic: 2 shared vCPUs, 1GB RAM
    • Starter: 2 shared vCPUs, 2GB RAM
    • Launch: 2 Performance vCPUs, 8GB RAM
    • Scale: 4 Performance vCPUs, 32GB RAM
    • Performance: 8 Performance vCPUs, 64GB RAM
  • Initial storage size: Up to 500 GB at creation
  • Optional Third Party Extensions to install (Currently only PGVector is supported)
A screenshot of the Managed Postgres creation page.
After configuring your cluster, select “Create Cluster” and wait a few moments for it to initialize. Once that’s complete, you can now connect to your cluster

​
Creating a Managed Postgres Cluster from Flyctl

Illustration by Annie Ruygt of a balloon holding a box of honey clusters cereal You can also create an MPG cluster using the flyctl command line tool. To begin, run:
Follow the prompts to configure your cluster name, plan, and region. By default your cluster will be created with a 10GB volume, but you can specify larger using the --volume-size flag:
After all options are set the cluster will begin initializing. Once that’s complete, you can now connect to your cluster.

​
Attach an application to your Managed Postgres Database

To connect your application running on Fly.io to your Managed Postgres instance, you’ll need to add the DB connection details as a secret on your app. This can be done from the Dashboard or via flyctl.

​
Attaching an app from your MPG dashboard

From the “Connect” tab of your MPG Cluster page you can attach a specific app in your organization to your database.
  1. Select the app to attach in the dropdown
  2. If needed, customize the variable name to use for the database connection URL. The default is DATABASE_URL. If your chosen app already has a secret named DATABASE_URL, you will need to choose a new variable name before you can deploy.
  3. Select “Set secret and deploy”. This will trigger a deploy of your chosen app to add the new secret.
  4. Your app can now use the DATABASE_URL environment variable to connect to your database

​
Attaching an app using flyctl

To attach an application to your database using flyctl run:
This will also trigger a restart of the selected app in order to add the secret. You can find the cluster ID in your MPG dashboard or by using the fly mpg list command. Both of the attachment options will use the pooled connection URL, which uses PGBouncer to help manage database connections efficiently. This is recommended for most apps.

​
Manually connect an application using a connection string

After your database is created, the “Connection” tab will display connection strings for both the pooled connection URL, and the direct database connection address. You can use these to manually connect an app to the database by setting it as a secret in your Fly.io application:

​
Connecting from a local machine using flyctl

Because your MPG Cluster runs within your Fly.io private network, it’s not accessible over the public internet. You can use flyctl to securely connect to your database from your local machine for development, manual DB work, or to connect to a local tool. All connections using flyctl are securely routed through your organizations private wireguard network

​
Connecting with psql

To connect directly to your Managed Postgres database using psql:
This command will create a direct connection to your database and open a psql session. You’ll need a compatible psql version installed locally.

​
Setting up a Proxy Connection

You can create a proxy connection to your Managed Postgres database using the ‘mpg proxy’ command:
This will open a connection on one of your local ports that forwards to your database.
This command is useful when you want to connect to your database from your local machine using tools other than psql, such as database management tools or your application in development. To use the local proxy connection you can modify the direct connection string from your dashboard, replacing the “flympg.net” domain with “localhost”:

​
Alternative: Connect via WireGuard

As an alternative to using flyctl proxy commands, you can connect to your MPG cluster directly through your organization’s private network using WireGuard. First, set up a WireGuard connection to your private network. Once connected, you can use the direct connection string from your MPG dashboard:
This connection method is particularly useful for database management tools that need persistent connections or development environments where you want direct database access.