Skip to main content
The PlanetScale Discovery Tool analyzes your existing PostgreSQL database and cloud infrastructure to help plan your migration to PlanetScale Postgres. It collects metadata about your database configuration, schema structure, performance characteristics, security settings, and cloud resources. It never reads or stores actual table data. The tool produces a structured JSON report that PlanetScale uses to provide migration guidance tailored to your environment.
The discovery tool is open source and available on GitHub. The documentation below covers the essentials. See the full documentation in the repository for advanced usage, troubleshooting, and detailed reference.

​
What it discovers

Database analysis:
  • PostgreSQL version, configuration, and installed extensions
  • Schema structure, including tables, columns, indexes, constraints, and sizes
  • Performance statistics such as cache hit ratios, table/index usage, and active locks
  • Security configuration: roles, permissions, and SSL settings
  • Feature usage: foreign data wrappers, partitioning, PostGIS, and more
Cloud infrastructure analysis:
  • Database instances, clusters, and their configurations
  • VPC networking, subnets, security groups, and firewall rules
  • Performance metrics from cloud monitoring services
  • High availability and replica configurations

​
Installation

The discovery tool requires Python 3.9 or later.
1

Download and extract

Download the latest release from GitHub and extract it:
tar -xzf ps-discovery-*.tar.gz
cd ps-discovery
2

Run setup

The setup script verifies your Python version, creates a virtual environment, and installs dependencies:
./setup.sh
3

Configure credentials

Copy the sample configuration file and edit it to include your database and cloud provider credentials:
cp sample-config.yaml config.yaml
At a minimum, you need to configure your database connection. See Configuration below for the full format.
Alternatively, you can install with pipx for a cleaner setup: 
# Install with support for a specific cloud provider
pipx install -e ".[aws]"

# Or install with all provider support
pipx install -e ".[all]"

​
Database user setup

Create a dedicated read-only user for the discovery tool. Connect to your database as a superuser or privileged role and run the following: 
-- Create a dedicated user for database discovery
CREATE USER planetscale_discovery WITH PASSWORD 'secure_password_here';

-- Grant basic connection and usage permissions
GRANT CONNECT ON DATABASE your_database TO planetscale_discovery;
GRANT USAGE ON SCHEMA public TO planetscale_discovery;
GRANT USAGE ON SCHEMA information_schema TO planetscale_discovery;

-- Grant read access to all tables and views
GRANT SELECT ON ALL TABLES IN SCHEMA public TO planetscale_discovery;
GRANT SELECT ON ALL TABLES IN SCHEMA information_schema TO planetscale_discovery;
GRANT SELECT ON ALL TABLES IN SCHEMA pg_catalog TO planetscale_discovery;

-- Grant permissions for system catalogs and statistics
GRANT SELECT ON pg_stat_database TO planetscale_discovery;
GRANT SELECT ON pg_stat_user_tables TO planetscale_discovery;
GRANT SELECT ON pg_stat_user_indexes TO planetscale_discovery;
GRANT SELECT ON pg_stat_activity TO planetscale_discovery;
GRANT SELECT ON pg_stat_replication TO planetscale_discovery;
GRANT SELECT ON pg_settings TO planetscale_discovery;
GRANT SELECT ON pg_database TO planetscale_discovery;
GRANT SELECT ON pg_user TO planetscale_discovery;
GRANT SELECT ON pg_roles TO planetscale_discovery;
GRANT SELECT ON pg_user_mappings TO planetscale_discovery;

-- For foreign data wrapper analysis
GRANT SELECT ON pg_foreign_server TO planetscale_discovery;
GRANT SELECT ON pg_foreign_data_wrapper TO planetscale_discovery;

-- For advanced performance analysis (if pg_stat_statements is enabled)
GRANT SELECT ON pg_stat_statements TO planetscale_discovery;

-- For replication analysis
GRANT SELECT ON pg_stat_wal_receiver TO planetscale_discovery;
GRANT SELECT ON pg_stat_subscription TO planetscale_discovery;

-- For PostgreSQL 10+ enhanced privileges (recommended)
GRANT pg_read_all_stats TO planetscale_discovery;
GRANT pg_read_all_settings TO planetscale_discovery;
If your database has additional schemas beyond public, repeat the GRANT USAGE ON SCHEMA and GRANT SELECT ON ALL TABLES IN SCHEMA statements for each schema you want analyzed.

​
Cleanup

After discovery is complete, remove the planetscale_discovery user from your database. This user has read access to your schema and system catalogs and should not be left in place.
DROP USER IF EXISTS planetscale_discovery;
If the user owns any objects, reassign ownership first: 
REASSIGN OWNED BY planetscale_discovery TO postgres;
DROP OWNED BY planetscale_discovery;
DROP USER planetscale_discovery;

​
Configuration

The discovery tool uses a YAML configuration file. Here is an example with the most common options: 
modules:
  - database # Run database analysis
  - cloud    # Run cloud infrastructure analysis (optional)

database:
  host: your-db-host.example.com
  port: 5432
  database: your_database
  username: planetscale_discovery
  password: secure_password_here
  sslmode: require

providers:
  aws:
    enabled: true
    regions:
      - us-east-1
  gcp:
    enabled: false
  supabase:
    enabled: false
  heroku:
    enabled: false

output:
  output_dir: ./discovery_output

​
Running discovery

Run database-only analysis: 
./ps-discovery database --config config.yaml
Run both database and cloud analysis: 
./ps-discovery both --config config.yaml
The tool produces a planetscale_discovery_results.json file in your configured output directory. Share this report with PlanetScale for migration planning assistance.
Once the discovery is complete, remember to clean up the planetscale_discovery user you created on your source database.

​
Cloud provider setup

Each cloud provider requires specific credentials and permissions. Below is a summary of what you need for each. For detailed instructions including IAM policies and API enablement steps, see the provider documentation.

​
AWS (RDS / Aurora)

The tool discovers RDS instances, Aurora clusters, VPC networking, security groups, and CloudWatch metrics. Authentication (choose one):
  • IAM instance profile (recommended when running on EC2)
  • Access key and secret key
  • IAM role assumption (for cross-account access)
Required permissions:
  • RDS: DescribeDBInstances, DescribeDBClusters, DescribeDBSubnetGroups
  • EC2: DescribeVpcs, DescribeSubnets, DescribeSecurityGroups, DescribeRouteTables
  • CloudWatch: GetMetricStatistics, ListMetrics
Configuration: 
providers:
  aws:
    enabled: true
    regions:
      - us-east-1
      - us-west-2
    # Authentication - choose one approach:
    # Option 1: Use instance profile or environment variables (recommended)
    # Option 2: Explicit credentials
    access_key_id: AKIA...
    secret_access_key: ...

​
Google Cloud (Cloud SQL / AlloyDB)

The tool discovers Cloud SQL instances, AlloyDB clusters, VPC networks, firewall rules, and Cloud Monitoring metrics. Authentication (choose one):
  • Application Default Credentials (recommended)
  • Service account key file
Required APIs (must be enabled in your project):
  • Cloud SQL Admin API
  • Compute Engine API
  • Cloud Monitoring API
  • AlloyDB API (if using AlloyDB)
Configuration: 
providers:
  gcp:
    enabled: true
    project_id: your-project-id
    # Optional: path to service account key
    credentials_file: /path/to/service-account-key.json

​
Supabase

The tool discovers project metadata, database configuration, PgBouncer settings, and connection details. Authentication: Configuration: 
providers:
  supabase:
    enabled: true
    access_token: sbp_...

​
Heroku

The tool discovers Heroku Postgres add-ons across all your apps, including plan details, database sizes, replica configurations, and connection pooling. Authentication: Configuration: 
providers:
  heroku:
    enabled: true
    api_key: your-heroku-api-key

​
Performance and safety

The default database analyzers are safe to run against production databases. They use read-only queries against system catalogs and statistics views, with very low performance impact.
The optional data size analyzer performs sampling queries against actual tables and can have a significant performance impact on large databases. If you need this analysis, consider running it against a read replica and starting with a low sampling percentage. This analyzer is disabled by default and must be explicitly opted into via configuration.

​
Privacy and security

The discovery tool runs entirely on your infrastructure. No data is sent to external services during analysis. Collected: Schema metadata, database configuration, usage statistics, infrastructure topology, and role names. Not collected: Table contents, row data, application queries, passwords, or secrets. Passwords are used only to establish the database connection and are never included in the output.

​
Next steps

Once you have your discovery report, share it with us if you want tailored migration guidance. You can also follow one of our migration guides on your own:

Migrate using pgdump/restore

Migrate using WAL streaming

Migrate using Amazon DMS

Migrate from Heroku

​
Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.