Metabase

Integrate Metabase into Coalesce Catalog so dashboard and metadata content stays available alongside your warehouse lineage.

Requirements

Warehouse Integration Required

A Warehouse type integration must already be configured to complete the first ingestion of this integration.

Catalog ingests Metabase metadata using one of two technical paths: the Metabase HTTP API, or read-only SQL against the PostgreSQL database Metabase uses as its application database. Metabase stores questions, dashboards, and collections there. That PostgreSQL instance is not your warehouse.

How you connect breaks down along two choices: the connector and whether extraction is Catalog managed or client managed. The connector is either the API or the PostgreSQL application database. Catalog managed means credentials live in the Coalesce App. Client managed means you run the extractor. Use this table to match your setup to the connector:

Setup	Connector	What you use
Catalog managed	Metabase API	JSON credentials in the Coalesce App. See Catalog Managed.
Client managed	Metabase API	castor-extract-metabase-api with API credentials. See Client Managed.
Client managed	PostgreSQL application database	castor-extract-metabase-db with read-only PostgreSQL credentials for Metabase application tables. See Client Managed.

Metabase API Prerequisites

For Catalog managed onboarding or the API extraction script, the Metabase account must meet Metabase privilege requirements for metadata access through the API. The castor-extractor documentation refers to this as the Metabase superuser role. That is a permission on the Metabase account, not a requirement tied to a person's job title. For API limitations such as popularity metrics, see Metabase package documentation.

PostgreSQL Application Database Path

Read-only access to the PostgreSQL instance Metabase uses for application metadata applies when you run client-managed extraction with castor-extract-metabase-db. Catalog managed onboarding does not collect PostgreSQL host or database credentials for Metabase. See Metabase configuration documentation for how Metabase configures its application database.

Allowlist Catalog IP

Here are our fixed IPs:

• For instances on app.us.castordoc.com: 34.42.92.72
• For instances on app.castordoc.com: 35.246.176.138

Catalog Managed

You can enter your credentials directly in the Coalesce App.

Using the API:

{
    "baseUrl": "http://company.cloud.metabase.com",
    "user": "catalog",
    "password": "abcdefgh"
}

For your first sync, it will take up to 48 hours and we will let you know when it is complete.

If you are not comfortable giving us access to your credentials, continue to Client Managed.

Client Managed

Doing a One-Shot Extract

For your trial, you can simply give us a one-shot view of your BI tool.

To get things working quickly, here is a Google Colab to run our package swiftly.

Running the Extraction Package

Install the PyPI Package

pip install castor-extractor[metabase]

For further details, see the castor-extractor installation instructions.

Run the Package

Once the package has been installed, you should be able to run the following command in your terminal:

castor-extract-metabase-db [arguments]

# or, if you use the API connector:
castor-extract-metabase-api [arguments]

The script will run and display logs as follows:

INFO - Getting session_id: {'id': '****'}
INFO - Fetching USER (15 results)
INFO - Wrote output file: /tmp/catalog/1649081473-user.json
INFO - Fetching COLLECTION (41 results)

...

INFO - Wrote output file: /tmp/catalog/1649081473-dashboard_cards.json
INFO - Wrote output file: /tmp/catalog/1649081473-summary.json

Credentials

You can sign in using one of the following methods:

• Postgres connector
  • -H, --host: Host name where the server is running
  • -P, --port: TCP/IP port number
  • -d, --database: Database name
  • -s, --schema: Schema name where the views or tables are located
  • -u, --user: User
  • -p, --password: Password
  • -o, --output: Directory to write to
  • --require_ssl: Flag to require SSL
• API connector
  • -b, --base-url: Metabase base URL, such as http://company.cloud.metabase.com
  • -u, --user: Metabase user
  • -p, --password: Metabase password

Other Arguments

• -o, --output: target folder to store the extracted files

Run any extractor command with --help to list all arguments.

Scheduling and Push to Catalog

When moving out of trial, you will want to refresh your Metabase content in Catalog. Here is how to do it:

• Your source id from Catalog. In the code examples, this value is called source_id.
• Your Catalog Token from the Catalog team

The Catalog team will provide you with:

1. Catalog Identifier: An id we use to match your Metabase files with your Catalog instance
2. Catalog Token: An API token

You can then use the castor-upload command:

castor-upload [arguments]

Arguments

• -k, --token: Token provided by Catalog
• -s, --source_id: account id provided by Catalog
• -t, --file_type: source type to upload. Currently supported are DBT, VIZ, or WAREHOUSE

Target Files

To specify the target files, provide one of the following:

• -f, --file_path: to push a single file

or

• -d, --directory_path: to push several files at once

Directory Contents

The tool will upload all files included in the given directory.

Make sure it contains only the extracted files before pushing.

Then you will have to schedule the script run and the push to Catalog. Use your preferred scheduler to create this job.

After you schedule the extractor runs and uploads, Metabase content stays current in Catalog.

Troubleshooting

These checks cover both Catalog-managed Metabase onboarding and client-managed extractors.

You Chose the API Path but Ingestion Stays Shallow on Dashboards

Metabase labels certain accounts as superuser for API access in extractor documentation. Without that privilege tier, popular metrics and some collections may not export.

Resolution:

1. Confirm the Metabase account tied to Catalog meets the API prerequisites in Metabase package documentation.
2. Retry ingestion after promoting the account or switching to an administrative service account permitted by your Metabase policy.

Confusion Between Metabase Application PostgreSQL and Your Warehouse PostgreSQL

Catalog never asks for your warehouse credentials when you pick Catalog managed onboarding for Metabase. Client-managed extraction with castor-extract-metabase-db connects to the PostgreSQL database Metabase itself uses for app metadata, not your analytical warehouse.

Resolution:

1. Point --host and --database at Metabase's application database host from Metabase admin settings.
2. Keep read-only accounts limited to Metabase metadata tables only.

Catalog-Managed Credentials Fail Immediately

Incorrect base URL format or blocked outbound traffic stops login before extraction begins.

Resolution:

1. Allowlist Catalog IPs from Allowlist Catalog IP on this page when Metabase sits behind a firewall.
2. Validate JSON keys such as baseUrl, user, and password against Metabase's HTTPS endpoint.

Extractor Logs Stop Mid-Collection

Large Metabase instances sometimes hit API rate limits or disk limits on the runner.

Resolution:

1. Re-run with a larger output directory (-o) on the extractor host.
2. Split collections by scheduling incremental pushes instead of one oversized upload directory.

Upload Succeeds but Dashboards Never Refresh

Schedulers often point to stale directories or wrong source_id.

Resolution:

1. Confirm castor-upload receives the current source_id from Catalog operations.
2. Verify cron jobs replace all JSON outputs between runs so partial uploads do not leave mixed timestamps.

---