Skip to content
PolarisPolaris

Synchronization

pda sync fills the project folder from your sources. It connects to each configured source, writes Markdown and files into the right folder, and then renders any templates. Run it after you change pda_config.yaml, and on a schedule so the docs stay current.

What it syncs

Section titled “What it syncs”
Provider Source Writes to
databases Each database in databases databases/type=<type>/database=<db>/schema=<schema>/table=<table>/
repositories Each Git repository in repos repos/<name>/
notion Notion pages docs/notion/
confluence Confluence pages and spaces docs/
obsidian An Obsidian vault docs/obsidian/
semantics The MetricFlow manifest semantics/

Providers run in the order above, and databases come before the semantic layer.

Common runs

Section titled “Common runs”

Sync everything:

Terminal window
pda sync

Sync only databases, with four threads:

Terminal window
pda sync -p databases -t 4

Sync one database connection:

Terminal window
pda sync -p databases:epigenomics

Refresh only a few tables, without removing the docs of other tables:

Terminal window
pda sync -p databases -s "main.tcga_*"

See the CLI reference for every flag and alias.

Templates

Section titled “Templates”

After syncing, pda sync renders every *.j2 file in the project with Jinja. Use templates to generate context from synced data. Add templates/ and *.j2 to .pdaignore so the agent reads only the rendered output. Turn rendering off with --no-render-templates.

What happens on errors

Section titled “What happens on errors”

If a provider or template fails, pda sync finishes the others and exits with code 1. If an optional config section is invalid, for example a missing secret for Notion, it is skipped with a warning.

GitHub Actions

Section titled “GitHub Actions”

Run pda sync on a schedule and commit the result, so your project in Git always has fresh table docs. Store database credentials as GitHub secrets and reference them from pda_config.yaml with {{ env('...') }}.

.github/workflows/pda-sync.yml
name: pda sync


on:
    schedule:
        - cron: '0 6 * * 1' # Mondays at 06:00 UTC
    workflow_dispatch:


permissions:
    contents: write


jobs:
    sync:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4


            - uses: actions/checkout@v4
              with:
                  repository: <org>/<polaris-repository>
                  path: polaris-src


            - uses: astral-sh/setup-uv@v6


            - name: Install the Polaris CLI from source
              run: |
                  uv venv .venv
                  uv pip install --python .venv './polaris-src/cli[snowflake]'


            - name: pda sync
              env:
                  SNOWFLAKE_PAT: ${{ secrets.SNOWFLAKE_PAT }}
              run: .venv/bin/pda sync


            - name: Commit changes
              run: |
                  git config user.name "pda-sync"
                  git config user.email "pda-sync@users.noreply.github.com"
                  git add databases repos docs semantics
                  git diff --cached --quiet || git commit -m "pda sync"
                  git push

Adjust the extras (snowflake above) to match your databases. If your project deploys on every push to main (see Deploy context), the sync commit triggers a deploy, so the team always gets the new docs.