Goal

This tutorial shows how to migrate sqleton repository discovery config from the old top-level repositories: key to the current app.repositories block.

Use this guide if sqleton fails with an error like:

legacy top-level repositories is no longer supported in /path/to/config.yaml; move entries to app.repositories

What changed

Sqleton now treats repository discovery as app-owned config.

The supported shape is:

app:
  repositories:
    - /path/to/repo-a
    - /path/to/repo-b

The old shape is no longer accepted:

repositories:
  - /path/to/repo-a
  - /path/to/repo-b

Why this changed

This makes sqleton's config model clearer:

• app.repositories is for repository discovery
• --config-file is for explicit command config such as sql-connection or dbt

That separation matters because repository discovery is layered automatically, while database settings remain explicit.

Supported repository-discovery locations

Sqleton discovers repository config from these locations, in layer order:

• /etc/sqleton/config.yaml
• ~/.sqleton/config.yaml
• $XDG_CONFIG_HOME/sqleton/config.yaml
• .sqleton.yml at the git repository root
• .sqleton.override.yml at the git repository root
• .sqleton.yml in the current working directory
• .sqleton.override.yml in the current working directory

Then sqleton appends:

• SQLETON_REPOSITORIES
• the default $HOME/.sqleton/queries directory when it exists

Migration examples

Example 1: global user config

Before:

repositories:
  - ~/code/sql/shared
  - ~/.sqleton/queries-extra

After:

app:
  repositories:
    - ~/code/sql/shared
    - ~/.sqleton/queries-extra

Example 2: project-local config

Before .sqleton.yml:

repositories:
  - ./queries
  - ../team-queries

After .sqleton.yml:

app:
  repositories:
    - ./queries
    - ../team-queries

Example 3: project repositories plus explicit DB config

Project-local .sqleton.yml:

app:
  repositories:
    - ./queries
    - ../team-queries

Explicit DB config file:

sql-connection:
  db-type: postgresql
  host: 127.0.0.1
  port: 5432
  database: app
  user: app

Run with:

sqleton run-command ./queries/list-users.sql -- --config-file ./db-config.yaml

Can one file contain both app and command config?

Yes.

A .sqleton.yml file can contain both:

• app.repositories
• command sections like sql-connection

Example:

app:
  repositories:
    - ./queries

sql-connection:
  db-type: sqlite
  database: ./local.db

Sqleton will:

• use app.repositories automatically for repository discovery
• only use sql-connection when you explicitly point --config-file at that file

For example:

sqleton query --config-file ./.sqleton.yml "SELECT COUNT(*) FROM users"

Troubleshooting

I updated my config but sqleton still does not find my query repository

Check:

• the file is in one of the supported locations
• the key is app.repositories, not repositories
• the paths are valid on your machine
• you did not accidentally put repository config only into a command config file that sqleton never auto-discovers

I want project-local repositories and project-local DB settings

Use:

• .sqleton.yml for app.repositories
• either the same file or a second file for sql-connection
• --config-file when you want sqleton to read the command settings

Summary

The migration rule is simple:

• move repositories: to app.repositories
• keep repository discovery in layered app config
• keep DB and dbt settings in explicit command config