queryapigate 0.26.0__tar.gz → 0.27.0__tar.gz

{queryapigate-0.26.0/queryapigate.egg-info → queryapigate-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: queryapigate
-Version: 0.26.0
+Version: 0.27.0
 Summary: Turn SQL into governed REST APIs over MySQL, PostgreSQL, ClickHouse, SQLite, DuckDB, H2, MongoDB, and Parquet/CSV/JSON files - JSON, CSV, Parquet or Excel out, with scoped keys, an admin Console and MCP for AI agents.
 Author-email: Anantha Raju C <arcswdev@gmail.com>
 License-Expression: FSL-1.1-MIT

{queryapigate-0.26.0 → queryapigate-0.27.0}/queryapigate/__init__.py

@@ -1,5 +1,5 @@
 """QueryAPIGate - expose SQL databases as a REST API."""
-__version__ = "0.26.0"
+__version__ = "0.27.0"
 
 from .app import create_app  # noqa: E402  (app imports __version__)
 

{queryapigate-0.26.0 → queryapigate-0.27.0}/queryapigate/adminroles.py

@@ -33,12 +33,13 @@ CAPABILITIES = {
     'exports.write': 'create, change and delete exports',
     'exports.run': 'run an export',
     'destinations.write': 'create, change, test and delete destinations',
+    'config.apply': 'see what a configuration file would change, and apply it - any of the above (ADR 0014)',
 }
 
 _EVERYONE = {'queries.read', 'connections.read', 'observe', 'self'}
 ROLES = {
     'owner': set(CAPABILITIES),
-    'admin': set(CAPABILITIES) - {'admins.read', 'admins.write', 'secrets.rotate'},
+    'admin': set(CAPABILITIES) - {'admins.read', 'admins.write', 'secrets.rotate', 'config.apply'},
     'developer': _EVERYONE | {'queries.write', 'exports.read', 'exports.run'},
     'auditor': _EVERYONE | {'access.read', 'settings.read', 'exports.read'},
 }
@@ -90,6 +91,7 @@ OPERATIONS = {
     'v1.list_exports': 'exports.read', 'v1.get_export': 'exports.read', 'v1.list_export_runs': 'exports.read',
     'v1.create_export': 'exports.write', 'v1.update_export': 'exports.write', 'v1.delete_export': 'exports.write',
     'v1.run_export': 'exports.run',
+    'v1.config_diff': 'config.apply', 'v1.config_apply': 'config.apply', 'v1.config_managed': 'observe',
 }
 
 

{queryapigate-0.26.0 → queryapigate-0.27.0}/queryapigate/apikeys.py

@@ -417,6 +417,29 @@ def _validate_allowed_tables(allowed_tables):
     return sorted({v.lower() for v in allowed_tables})
 
 
+def normalize_grants(connections=None, allow_writes=False, queries=None, collections=None, rate_limit=None,
+                     allowed_ips=None, allowed_write_ops=None, allowed_tables=None, mask=None, max_concurrent=None,
+                     query_timeout=None, max_rows=None, quota=None):
+    """A key's or role's grants, checked and normalised as they're stored - without writing anything, or checking that
+    the collections named exist (_require_existing_collections() does, where they're saved). The one place a grant's
+    rules are applied: creating a key or role, and reading one from a configuration file (configcode.py)."""
+    return {
+        'connections': _normalize_connections(connections),
+        'allow_writes': bool(allow_writes),
+        'queries': _normalize_queries(queries),
+        'collections': _normalize_collections(collections),
+        'rate_limit': _validate_rate_limit(rate_limit),
+        'allowed_ips': _validate_allowed_ips(allowed_ips),
+        'allowed_write_ops': _validate_allowed_write_ops(allowed_write_ops),
+        'allowed_tables': _validate_allowed_tables(allowed_tables),
+        'mask': masking.validate_rules(mask),
+        'max_concurrent': _validate_limit('max_concurrent', max_concurrent),
+        'query_timeout': _validate_limit('query_timeout', query_timeout),
+        'max_rows': _validate_limit('max_rows', max_rows),
+        'quota': quotas.validate(quota),
+    }
+
+
 def is_expired(entry):
     """Whether a stored key entry's expires_at date has passed - checked live on every authenticate() call,
     not swept by a background job: an expired key simply stops matching, the same way flipping `active` to
@@ -476,6 +499,13 @@ def list_keys():
             for name, entry in _read().items()}
 
 
+def secret_hashes():
+    """{name: SHA-256 of the key's secret} - for a configuration file only (ADR 0014), which declares a key by its
+    hash. Not a secret: a generated secret is 32 random bytes, so its hash can't be reversed. The API never shows it
+    anyway, like the rest of what authenticates a key."""
+    return {name: entry['hash'] for name, entry in _read().items()}
+
+
 def create_key(name, connections=None, allow_writes=None, queries=None, expires_at=None, rate_limit=None,
                allowed_ips=None, allowed_write_ops=None, role=None, collections=None, allowed_tables=None,
                example=False, mask=None, max_concurrent=None, query_timeout=None, max_rows=None, quota=None):
@@ -517,20 +547,10 @@ def create_key(name, connections=None, allow_writes=None, queries=None, expires_
             raise ApiError(f"An API key named '{name}' already exists", 409, code='key_exists')
         entry = {
             'hash': _hash(secret),
-            'connections': _normalize_connections(connections),
-            'allow_writes': bool(allow_writes),
-            'queries': _normalize_queries(queries),
-            'collections': collections,
+            **normalize_grants(connections, allow_writes, queries, collections, rate_limit, allowed_ips,
+                               allowed_write_ops, allowed_tables, mask, max_concurrent, query_timeout, max_rows,
+                               quota),
             'expires_at': _validate_expiry(expires_at),
-            'rate_limit': _validate_rate_limit(rate_limit),
-            'allowed_ips': _validate_allowed_ips(allowed_ips),
-            'allowed_write_ops': _validate_allowed_write_ops(allowed_write_ops),
-            'allowed_tables': _validate_allowed_tables(allowed_tables),
-            'mask': masking.validate_rules(mask),
-            'max_concurrent': _validate_limit('max_concurrent', max_concurrent),
-            'query_timeout': _validate_limit('query_timeout', query_timeout),
-            'max_rows': _validate_limit('max_rows', max_rows),
-            'quota': quotas.validate(quota),
             'created_from_role': role,
             'active': True,
             'created_at': store.now(),
@@ -610,15 +630,45 @@ def rotate_key(name, grace_minutes=None):
                            '- end that first (DELETE .../previous), or wait for it', 409,
                            code='key_rotation_pending', previous_expires_at=row['previous_expires_at'])
         secret = 'sk_' + secrets.token_urlsafe(32)
-        until = (datetime.now() + timedelta(minutes=grace)).strftime('%Y-%m-%d %H:%M:%S') if grace else None
-        details = json.loads(row['details_json'])
-        details.pop('previous_last_used_at', None)
-        conn.execute('UPDATE api_keys SET hash = ?, previous_hash = ?, previous_expires_at = ?, details_json = ? '
-                     'WHERE name = ?', (_hash(secret), row['hash'] if until else None, until, json.dumps(details),
-                                        name))
+        until = _replace_hash(conn, name, row, _hash(secret), grace)
     return secret, until
 
 
+def _replace_hash(conn, name, row, new_hash, grace):
+    """The key's secret becomes the one `new_hash` is the hash of; the old one keeps working `grace` minutes."""
+    until = (datetime.now() + timedelta(minutes=grace)).strftime('%Y-%m-%d %H:%M:%S') if grace else None
+    details = json.loads(row['details_json'])
+    details.pop('previous_last_used_at', None)
+    conn.execute('UPDATE api_keys SET hash = ?, previous_hash = ?, previous_expires_at = ?, details_json = ? '
+                 'WHERE name = ?', (new_hash, row['hash'] if until else None, until, json.dumps(details), name))
+    return until
+
+
+def set_secret_hash(name, secret_hash, grace_minutes=None):
+    """A key's secret set to the one `secret_hash` is the SHA-256 of - a configuration file's `secret_sha256`
+    (ADR 0014) - with the old secret kept working for `grace_minutes`, as rotate_key() does. The secret itself is
+    never seen here. Refused when another key already has it: one secret must name one key. Returns when the old
+    secret stops working."""
+    grace = _validate_grace(grace_minutes)
+    with db.transaction() as conn:
+        row = conn.execute('SELECT hash, details_json, previous_hash, previous_expires_at FROM api_keys WHERE name = ?',
+                           (name,)).fetchone()
+        if row is None:
+            raise ApiError(f"API key '{name}' not found", 404, code='key_not_found')
+        taken = conn.execute('SELECT name FROM api_keys WHERE (hash = ? OR previous_hash = ?) AND name <> ?',
+                             (secret_hash, secret_hash, name)).fetchone()
+        if taken is not None:
+            raise ApiError("Another key already has this secret_sha256 - each key needs its own secret",
+                           409, code='key_secret_taken')
+        if row['hash'] == secret_hash:
+            return None
+        if grace and row['previous_hash'] and row['previous_expires_at'] and row['previous_expires_at'] > store.now():
+            raise ApiError(f"The secret this key had before its last change works until {row['previous_expires_at']} "
+                           '- end that first (DELETE .../previous), or wait for it', 409,
+                           code='key_rotation_pending', previous_expires_at=row['previous_expires_at'])
+        return _replace_hash(conn, name, row, secret_hash, grace)
+
+
 def end_previous(name):
     """Stop the old secret now, before its grace period ends. Returns when it would have stopped."""
     with db.transaction() as conn:
@@ -685,19 +735,9 @@ def create_role(name, connections=None, allow_writes=False, queries=None, rate_l
         if conn.execute('SELECT 1 FROM roles WHERE name = ?', (name,)).fetchone() is not None:
             raise ApiError(f"A role named '{name}' already exists", 409, code='role_exists')
         entry = {
-            'connections': _normalize_connections(connections),
-            'allow_writes': bool(allow_writes),
-            'queries': _normalize_queries(queries),
-            'collections': collections,
-            'rate_limit': _validate_rate_limit(rate_limit),
-            'allowed_ips': _validate_allowed_ips(allowed_ips),
-            'allowed_write_ops': _validate_allowed_write_ops(allowed_write_ops),
-            'allowed_tables': _validate_allowed_tables(allowed_tables),
-            'mask': masking.validate_rules(mask),
-            'max_concurrent': _validate_limit('max_concurrent', max_concurrent),
-            'query_timeout': _validate_limit('query_timeout', query_timeout),
-            'max_rows': _validate_limit('max_rows', max_rows),
-            'quota': quotas.validate(quota),
+            **normalize_grants(connections, allow_writes, queries, collections, rate_limit, allowed_ips,
+                               allowed_write_ops, allowed_tables, mask, max_concurrent, query_timeout, max_rows,
+                               quota),
             'created_at': store.now(),
             **({'example': True} if example else {}),  # installed by `examples load` - see examples.py
         }

{queryapigate-0.26.0 → queryapigate-0.27.0}/queryapigate/app.py

@@ -91,6 +91,32 @@ class JSONProvider(DefaultJSONProvider):
     sort_keys = False  # keep result columns in the order the query returned them
 
 
+def apply_config_at_startup():
+    """QUERYAPIGATE_CONFIG_FILE (ADR 0014): apply it before serving - once per file, so with several instances the first
+    to start applies it and the others find it done. A file that can't be applied stops startup, changing nothing:
+    in a rolling update the new pods don't come up, and the ones still serving keep the configuration they have."""
+    from . import configcode
+    path = config.config_file()
+    if path is None:
+        return
+    try:
+        doc = configcode.load(path.read_text())
+        result = configcode.apply(doc, prune=config.config_prune(), actor='startup', once=True)
+    except OSError as error:
+        log.error('QUERYAPIGATE_CONFIG_FILE %s could not be read: %s', path, error)
+        raise ValueError(f'QUERYAPIGATE_CONFIG_FILE {path} could not be read: {error}') from None
+    except configcode.ConfigInvalid as error:
+        message = f'QUERYAPIGATE_CONFIG_FILE {path} was not applied - nothing in it was. ' + '; '.join(error.problems)
+        log.error('%s', message)  # one line in the log, whatever prints the exception after (gunicorn: a traceback)
+        raise ValueError(message) from None
+    if result.get('already_applied'):
+        log.info('QUERYAPIGATE_CONFIG_FILE %s (sha256 %s) is already applied', path, result['file_sha256'][:12])
+    else:
+        counts = {a: sum(1 for c in result['changes'] if c['action'] == a) for a in ('create', 'update', 'delete')}
+        log.info('Applied QUERYAPIGATE_CONFIG_FILE %s (sha256 %s): %d created, %d changed, %d deleted', path,
+                 result['file_sha256'][:12], counts['create'], counts['update'], counts['delete'])
+
+
 def load_examples_at_startup():
     """QUERYAPIGATE_LOAD_EXAMPLES=yes: make sure the example APIs are installed. A problem (something of yours
     holds an example's name, the home is read-only) is a warning, not a startup failure - the examples are a
@@ -190,6 +216,7 @@ def create_app():
     _note_audit_key_rotation()
     from . import auditstream
     auditstream.start()  # the audit log to a SIEM, when an output is set (ADR 0012)
+    apply_config_at_startup()
     if config.load_examples():
         load_examples_at_startup()
     app.json = JSONProvider(app)

{queryapigate-0.26.0 → queryapigate-0.27.0}/queryapigate/cli.py

@@ -2,9 +2,11 @@
 ``collection export|import``."""
 import argparse
 import contextlib
+import hashlib
 import json
 import logging
 import os
+import secrets
 import sys
 import time
 from datetime import datetime, timedelta
@@ -15,6 +17,7 @@ from . import (
     admins,
     bundle,
     config,
+    configcode,
     db,
     examples,
     experimental,
@@ -333,6 +336,130 @@ def _collection_import(args):
     return 0
 
 
+def _config_command(action):
+    """Shared shell for the config subcommands (ADR 0014). Every failure exits 1, settings included: `config diff`
+    exits 2 for "there are changes", so a script can tell the two apart."""
+    def run(args):
+        try:
+            config.check_settings()
+            return action(args)
+        except configcode.ConfigInvalid as error:
+            print(f'queryapigate config {args.action}: {len(error.problems)} problem(s) in the file:', file=sys.stderr)
+            for problem in error.problems:
+                print(f'  {problem}', file=sys.stderr)
+            return 1
+        except ApiError as error:
+            print(f'queryapigate config {args.action}: {error.message}', file=sys.stderr)
+            return 1
+        except (OSError, ValueError) as error:
+            print(f'queryapigate config {args.action}: {error}', file=sys.stderr)
+            return 1
+    return run
+
+
+def _read_config_file(path):
+    if path == '-':
+        return configcode.load(sys.stdin.read())
+    with open(path) as f:
+        return configcode.load(f.read())
+
+
+@_config_command
+def _config_export(args):
+    kinds = tuple(k.strip() for k in args.kinds.split(',')) if args.kinds else configcode.KINDS
+    doc, variables, skipped = configcode.export(kinds, examples=args.examples)
+    text = configcode.dump(doc, variables)
+    if args.out is None:
+        sys.stdout.write(text)
+    else:
+        out_dir = os.path.dirname(args.out) or '.'
+        tmp_path = os.path.join(out_dir, f'.{os.path.basename(args.out)}.part')
+        try:
+            with open(tmp_path, 'w') as f:
+                f.write(text)
+            os.replace(tmp_path, args.out)  # a failed run never leaves a partial file at the destination
+        finally:
+            if os.path.exists(tmp_path):
+                os.remove(tmp_path)
+        print(f'Wrote the configuration to {args.out}', file=sys.stderr)
+    for variable in variables:
+        print(f"Set {variable['name']} where the server runs: {variable['for']}'s password, stored "
+              f"{variable['stored']} here", file=sys.stderr)
+    for name in skipped:
+        print(f'Left out saved query {name}: it has no published version', file=sys.stderr)
+    return 0
+
+
+def _remote(args, operation, **flags):
+    """POST the file to a running server's /api/v1/config/<operation> (`--server`), with the key in QAG_API_KEY - an
+    environment variable, so it never shows in a CI log or a process list."""
+    import urllib.error
+    import urllib.request
+    key = os.environ.get('QAG_API_KEY', '').strip()
+    if not key:
+        raise ApiError('--server needs the API key in the QAG_API_KEY environment variable')
+    doc = _read_config_file(args.file)
+    query = '&'.join(f'{k}=true' for k, v in flags.items() if v)
+    url = args.server.rstrip('/') + f'/api/v1/config/{operation}' + (f'?{query}' if query else '')
+    request = urllib.request.Request(url, data=json.dumps(doc).encode(), method='POST',
+                                     headers={'X-API-Key': key, 'Content-Type': 'application/json'})
+    try:
+        with urllib.request.urlopen(request, timeout=120) as response:
+            return json.load(response)
+    except urllib.error.HTTPError as error:
+        try:
+            body = json.load(error)
+        except ValueError:
+            raise ApiError(f'{url} answered {error.code}') from None
+        if body.get('code') == 'invalid_config':
+            raise configcode.ConfigInvalid(body.get('problems') or [body.get('error')]) from None
+        raise ApiError(f"{url} answered {error.code}: {body.get('error')}") from None
+    except urllib.error.URLError as error:
+        raise ApiError(f'{url}: {error.reason}') from None
+
+
+@_config_command
+def _config_diff(args):
+    if args.server:
+        result = _remote(args, 'diff', prune=args.prune)
+    else:
+        result = configcode.diff(_read_config_file(args.file), prune=args.prune)
+    if args.json:
+        print(json.dumps(result, indent=2, default=str))
+    else:
+        print(configcode.render(result))
+    return 2 if result['changes'] else 0
+
+
+@_config_command
+def _config_apply(args):
+    if args.server:
+        result = _remote(args, 'apply', prune=args.prune, dry_run=args.dry_run)
+    elif args.dry_run:
+        result = {**configcode.diff(_read_config_file(args.file), prune=args.prune), 'applied': False}
+    else:
+        result = configcode.apply(_read_config_file(args.file), prune=args.prune, actor='cli')
+    if args.json:
+        print(json.dumps(result, indent=2, default=str))
+        return 0
+    print(configcode.render(result))
+    if args.dry_run:
+        print('Dry run: nothing was changed.')
+    elif result['applied']:
+        print(f"Applied: the server matches the file (sha256 {result['file_sha256'][:12]}).")
+    return 0
+
+
+def _config_new_key(args):
+    """A fresh API key secret and its SHA-256, for a key declared in a configuration file. Nothing is stored."""
+    secret = 'sk_' + secrets.token_urlsafe(32)
+    print(f'secret:        {secret}')
+    print(f'secret_sha256: {hashlib.sha256(secret.encode()).hexdigest()}')
+    print('Give the secret to whoever uses the key, keep it in your secrets manager, and put only secret_sha256 in '
+          'the file.', file=sys.stderr)
+    return 0
+
+
 def _examples_command(action):
     """Shared shell for the examples subcommands - the same settings check and clean-error handling as the
     collection ones."""
@@ -686,6 +813,42 @@ def build_parser():
     collection_import.add_argument('--dry-run', action='store_true', help='report what would happen; write nothing')
     collection_import.set_defaults(func=_collection_import)
 
+    config_parser = commands.add_parser('config', help="the server's configuration as a file (ADR 0014, experimental): "
+                                                       'export it, see what applying one would change, apply it')
+    config_parser.set_defaults(func=lambda a: config_parser.print_help() or 2)
+    config_actions = config_parser.add_subparsers(dest='action')
+    config_export = config_actions.add_parser(
+        'export', help='write connections, destinations, roles, saved queries, API keys, descriptions and exports as '
+                       'one YAML file - passwords as ${VAR} references, keys as their hashes, never a secret')
+    config_export.add_argument('--kinds', help=f"only these, comma-separated (of: {', '.join(configcode.KINDS)})")
+    config_export.add_argument('--examples', action='store_true', help='include the bundled examples too')
+    config_export.add_argument('--out', help='write to this file instead of stdout')
+    config_export.set_defaults(func=_config_export)
+    config_diff = config_actions.add_parser(
+        'diff', help='what applying FILE would create and change, field by field - writes nothing. Exit 0: no '
+                     'changes; 2: changes; 1: the file has problems')
+    config_diff.add_argument('file', help='a configuration file (YAML or JSON), or - for stdin')
+    config_diff.add_argument('--json', action='store_true', help='the changes as JSON, for a script')
+    config_diff.add_argument('--prune', action='store_true', help='also show what --prune would delete')
+    config_diff.add_argument('--server', metavar='URL', help="a running server's base URL, instead of this home's "
+                                                             'store - the key in QAG_API_KEY (CI against prod)')
+    config_diff.set_defaults(func=_config_diff)
+    config_apply = config_actions.add_parser(
+        'apply', help='make the server match FILE, all or nothing - every change through the same rules as the API, '
+                      'audited; what the file does not name is left alone')
+    config_apply.add_argument('file', help='a configuration file (YAML or JSON), or - for stdin')
+    config_apply.add_argument('--prune', action='store_true',
+                              help='also delete what a file manages (created, changed or named before) and this one '
+                                   'no longer has - never what was made in the Console or the API')
+    config_apply.add_argument('--dry-run', action='store_true', help='say what would change; change nothing')
+    config_apply.add_argument('--json', action='store_true', help='the result as JSON, for a script')
+    config_apply.add_argument('--server', metavar='URL', help="a running server's base URL, instead of this home's "
+                                                              'store - the key in QAG_API_KEY (an owner\'s)')
+    config_apply.set_defaults(func=_config_apply)
+    config_new_key = config_actions.add_parser(
+        'new-key', help="a fresh API key secret and its secret_sha256, for a key declared in a file - nothing stored")
+    config_new_key.set_defaults(func=_config_new_key)
+
     example_parser = commands.add_parser('examples', help='load, remove or check the bundled example APIs '
                                                           '(reporting, dashboard, export, partner)')
     example_parser.set_defaults(func=lambda a: example_parser.print_help() or 2)
@@ -759,6 +922,8 @@ def main(argv=None):
         args = parser.parse_args(['serve', *(argv or [])])
     if getattr(args, 'home', None):
         os.environ['QUERYAPIGATE_HOME'] = args.home
+    if getattr(args, 'server', None) or getattr(args, 'func', None) is _config_new_key:
+        return args.func(args)  # nothing of this home's: no store opened, so none made in a CI checkout
     try:
         config.check_database_url()
         db.init_schema()

{queryapigate-0.26.0 → queryapigate-0.27.0}/queryapigate/config.py

@@ -64,6 +64,25 @@ def load_examples():
     return env_flag('QUERYAPIGATE_LOAD_EXAMPLES')
 
 
+def config_file():
+    """QUERYAPIGATE_CONFIG_FILE: a configuration file (ADR 0014) applied at startup, before the server serves - once per
+    file: an instance that finds it already applied leaves the store alone. None when unset."""
+    raw = os.environ.get('QUERYAPIGATE_CONFIG_FILE', '').strip()
+    return Path(raw) if raw else None
+
+
+def config_prune():
+    """QUERYAPIGATE_CONFIG_PRUNE: applying QUERYAPIGATE_CONFIG_FILE at startup also deletes what a file manages and this
+    one no longer has (`config apply --prune`)."""
+    return env_flag('QUERYAPIGATE_CONFIG_PRUNE')
+
+
+def config_locked():
+    """QUERYAPIGATE_CONFIG_LOCKED: what a configuration file manages can be changed only through a file - the API and
+    the Console answer 409 config_managed (ADR 0014)."""
+    return env_flag('QUERYAPIGATE_CONFIG_LOCKED')
+
+
 def home():
     """Folder holding queryapigate.db (QUERYAPIGATE_HOME, default: current directory)."""
     return _resolved_home(os.environ.get('QUERYAPIGATE_HOME') or '', os.getcwd())
@@ -335,6 +354,13 @@ def check_settings():
     raw = os.environ.get('QUERYAPIGATE_LOAD_EXAMPLES', '').strip().lower()
     if raw not in _FLAG_WORDS:
         raise ValueError(f"QUERYAPIGATE_LOAD_EXAMPLES must be yes or no (or 1/0, true/false, on/off), not '{raw}'")
+    for name in ('QUERYAPIGATE_CONFIG_PRUNE', 'QUERYAPIGATE_CONFIG_LOCKED'):
+        raw = os.environ.get(name, '').strip().lower()
+        if raw not in _FLAG_WORDS:
+            raise ValueError(f"{name} must be yes or no (or 1/0, true/false, on/off), not '{raw}'")
+    if config_prune() and config_file() is None:
+        raise ValueError('QUERYAPIGATE_CONFIG_PRUNE is set but QUERYAPIGATE_CONFIG_FILE is not - prune what, against '
+                         'which file?')
     raw = os.environ.get('QUERYAPIGATE_RATE_LIMIT', '').strip()
     if raw:
         parse_rate_limit(raw)
@@ -1004,6 +1030,13 @@ def describe_settings():
                 else f'PostgreSQL ({redact_url(database_url())})', secret=True),
             row('Load examples', 'Load the example APIs at startup. Idempotent.',
                 'QUERYAPIGATE_LOAD_EXAMPLES', on_off(load_examples())),
+            row('Configuration file', 'A configuration file applied at startup, once per file - connections, '
+                'queries, roles, keys and the rest as code (ADR 0014).', 'QUERYAPIGATE_CONFIG_FILE',
+                str(config_file()) if config_file() else 'none'),
+            row('Prune at startup', 'Applying it also deletes what a file manages and this one no longer has.',
+                'QUERYAPIGATE_CONFIG_PRUNE', on_off(config_prune())),
+            row('Locked to the file', 'What a file manages can be changed only through a file, not here or the API.',
+                'QUERYAPIGATE_CONFIG_LOCKED', on_off(config_locked())),
             row('H2 driver', 'JAR used for h2 connections.', 'QUERYAPIGATE_H2_JAR',
                 Path(h2_jar()).name + ('' if os.environ.get('QUERYAPIGATE_H2_JAR') else ' (bundled)'))]},
         {'id': 'security', 'title': 'Security',