ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
feat(databases): engine extensions, without the silent failure
Juan Denis679082bf16ce
diff --git a/backend/app/api/database_engines.py b/backend/app/api/database_engines.pyindex 8568fecf..4b62e219 100644--- a/backend/app/api/database_engines.py+++ b/backend/app/api/database_engines.py@@ -8,6 +8,11 @@ install uses -- so the UI can navigate straight to the deploy console.Lifecycle (start / stop / uninstall) is app lifecycle. Use``POST /api/v1/apps/<id>/start``, ``/stop`` and ``DELETE /api/v1/apps/<id>``(which preserves an engine's data volumes unless ``?remove_data=true``).++Extensions live under the same prefix but are a different shape: they get no+container, so installing one executes a statement against an engine that is+already running rather than creating a deployment job. See+``app/services/database_engine_extension_service.py``."""import logging@@ -15,8 +20,10 @@ from flask import Blueprint, jsonify, requestfrom flask_jwt_extended import get_jwt_identity, jwt_requiredfrom app.middleware.rbac import admin_required+from app.services import database_engine_extension_service as extensionsfrom app.services import database_engine_service as enginesfrom app.services.deployment_job_service import DeploymentJobService+from app.services.template_service import TemplateServicelogger = logging.getLogger(__name__)@@ -35,9 +42,15 @@ def list_database_engines():"""live = request.args.get('live', 'true').lower() != 'false'catalog = engines.engine_catalog()+ extension_catalog = extensions.extension_catalog()return jsonify({'catalog': catalog,'installed': engines.installed_engines(live_status=live),+ # The drawer renders engines and extensions together; one round trip.+ # Every entry carries family 'Extension' -- deliberately NOT merged into+ # `families`, which stays the engine-family filter it has always been.+ 'extensions': extension_catalog,+ 'extension_family': TemplateService.EXTENSION_FAMILY if extension_catalog else None,# Derived from the catalog so the UI never carries its own family list.'families': engines.catalog_families(catalog),}), 200@@ -86,3 +99,64 @@ def install_database_engine():status = (result.get('job') or {}).get('status')return jsonify(result), 201 if status == 'succeeded' else 202+++# ── extensions ───────────────────────────────────────────────────────────────+# An extension has no container: it is a statement run against an engine that+# is already up. These routes sit under the engines prefix because that is where+# the catalog is entered from, but nothing here creates a deployment job.++@database_engines_bp.route('/extensions', methods=['GET'])+@jwt_required()+def list_engine_extensions():+ """Every declared extension, with who can host it.++ Composed from ``<templates>/extensions/*.yaml``: dropping one in is enough+ to make it appear, exactly as for an engine. Each entry carries ``hosts``+ (engine templates that speak its protocol), ``provided_by`` (those whose+ image actually ships it) and the installed instance ids split into+ ``compatible_instances`` / ``incompatible_instances``.+ """+ return jsonify({'extensions': extensions.extension_catalog(),+ 'family': TemplateService.EXTENSION_FAMILY}), 200+++@database_engines_bp.route('/<int:app_id>/extensions', methods=['GET'])+@jwt_required()+def list_instance_extensions(app_id):+ """Every extension judged against ONE installed engine.++ ``?probe=true`` asks the engine itself what it can load instead of+ inferring it from the image name -- slower (a docker exec per extension),+ authoritative, and the only way to see what is already installed.+ """+ probe = request.args.get('probe', 'false').lower() == 'true'+ result = extensions.instance_extensions(app_id, probe=probe)+ if 'error' in result:+ # Popped BEFORE serializing: the transport code is not part of the body.+ status = result.pop('status_code', 400)+ return jsonify(result), status+ return jsonify(result), 200+++@database_engines_bp.route('/<int:app_id>/extensions', methods=['POST'])+@jwt_required()+@admin_required+def install_engine_extension(app_id):+ """Install an extension into a database on this engine.++ Answers 409 with a ``remedy`` when the engine's image cannot ship the+ extension -- the statement is never attempted in that case, so the operator+ gets "your image does not carry this, install X instead" rather than a raw+ ``could not open extension control file``.+ """+ data = request.get_json(silent=True) or {}+ result = extensions.install_extension(+ app_id,+ extension_id=data.get('extension_id') or data.get('id'),+ database=data.get('database'),+ )+ if 'error' in result:+ status = result.pop('status_code', 400)+ return jsonify(result), status+ return jsonify(result), 201diff --git a/backend/app/api/templates.py b/backend/app/api/templates.pyindex c6ee1769..7fe1faa4 100644--- a/backend/app/api/templates.py+++ b/backend/app/api/templates.py@@ -245,16 +245,63 @@ def catalog_schema():'description': 'CLI client hint shown in the UI.'},{'field': 'data_path', 'required': False,'description': 'Container-side data directory the named volume mounts onto.'},+ {'field': 'extensions', 'required': False, 'default': False,+ 'description': 'true when the engine can load database extensions (see '+ 'extension_block). Opt-in, because speaking a protocol is '+ 'not the same as supporting its extensions.'},{'field': 'versions', 'required': False,'description': 'Selectable image versions. Defaults to the template version.'},],},+ # An extension is NOT an app template: it has no container, so it is not+ # in this directory at all. Documented here because this endpoint is+ # where an author looks for "what can I drop into the catalog".+ 'extension_block': {+ 'optional': True,+ 'location': f'<templates>/{TemplateService.EXTENSIONS_SUBDIR}/<id>.yaml',+ 'family': TemplateService.EXTENSION_FAMILY,+ 'description': 'An extension installs INTO a running engine by executing one '+ 'statement against it. It declares no compose/dockerfile and '+ 'creates no application; it lives in its own directory so it '+ 'never appears in the app catalog.',+ 'protocols': [p for p in TemplateService.ENGINE_PROTOCOLS if p != 'none'],+ 'fields': [+ {'field': 'protocol', 'required': True,+ 'description': "Engines that can host it, matched against each engine "+ "template's own engine.protocol. Never names an engine."},+ {'field': 'statement', 'required': True,+ 'description': 'The statement executed on install, e.g. '+ 'CREATE EXTENSION IF NOT EXISTS vector;'},+ {'field': 'available_query', 'required': False,+ 'description': 'Asked before installing and authoritative: an empty result '+ 'means the running image cannot load the extension, and the '+ 'install is refused with a remedy instead of failing with '+ '"could not open extension control file".'},+ {'field': 'installed_query', 'required': False,+ 'description': 'Returns the installed version, or nothing when absent.'},+ {'field': 'images', 'required': False,+ 'description': 'Image repositories that SHIP the extension. Stock postgres '+ 'does not ship pgvector, so this is what lets the catalog '+ 'mark an instance incompatible before it is clicked.'},+ {'field': 'image_hint', 'required': False,+ 'description': 'Image reference to suggest; {version} is replaced with the '+ "installed engine's version."},+ {'field': 'templates', 'required': False,+ 'description': 'Optional narrowing to specific engine template ids. Omit to '+ 'offer it on every engine speaking `protocol`.'},+ {'field': 'versions', 'required': False,+ 'description': 'Selectable extension versions. Defaults to the file version.'},+ ],+ },'notes': ['Magic tokens need no variables: entry; they are resolved at install ''and persisted to .env / surfaced post-install.','<NAME> groups related tokens: the same <NAME> resolves to a consistent value.','Unknown top-level keys are tolerated by the validator; `engine` is now a ''known block and is carried through the catalog listing and repo index.',+ f'Database extensions are separate files under '+ f'{TemplateService.EXTENSIONS_SUBDIR}/ and are listed by '+ 'GET /api/v1/databases/engines/extensions.',],}return jsonify(schema), 200diff --git a/backend/app/services/database_engine_extension_service.py b/backend/app/services/database_engine_extension_service.pynew file mode 100644index 00000000..f3df5180--- /dev/null+++ b/backend/app/services/database_engine_extension_service.py@@ -0,0 +1,524 @@+"""Database engine extensions — installed INTO a running engine, not beside it.++An engine is an app template because an engine gets a container. An extension+gets nothing: installing pgvector is executing ``CREATE EXTENSION IF NOT EXISTS+vector;`` against a database on a PostgreSQL that is already up. So an extension+is a small YAML in ``<templates>/extensions/`` and everything below is composed+from those files -- dropping one in makes the extension appear, with no Python+change, exactly as dropping an engine YAML does.++Three things this module is responsible for:++1. **Discovery.** :func:`extension_catalog` — what exists, which engine+ templates can host each one, and which installed instances can.+2. **Compatibility.** Matching is on the engine template's *own*+ ``engine.protocol``, so a new PostgreSQL-speaking engine template becomes a+ host automatically and neither side names the other.+3. **The image problem, which is the whole difficulty.**++ ``CREATE EXTENSION vector`` is a correct statement that fails on stock+ ``postgres:16``::++ ERROR: could not open extension control file+ "/usr/share/postgresql/16/extension/vector.control"++ The image simply does not carry the shared library, and no statement can+ conjure it. ServerKit never recreates a container behind the operator's back,+ so instead:++ * the extension declares ``images:`` — the repositories that ship it — and a+ listing marks an instance ``image_unsupported`` **before** anything is+ clicked, naming the image that would work;+ * an install *always* asks the engine first (``available_query`` against+ ``pg_available_extensions``) and refuses with that same remedy if the+ answer is empty. The probe is authoritative: an operator who built their+ own capable image is allowed even though its name is unknown to us, and an+ image whose name matches but whose library is missing is still refused.++ The remedy points at real, installable engine templates, found by matching+ the extension's ``images`` against each engine template's own compose image+ — so shipping a capable engine is, again, adding a YAML file.+"""+import logging+import os+import re+from typing import Dict, List, Optional++import yaml++from app.services import database_engine_service as engines+from app.services.database_service import DatabaseService+from app.services.template_service import TemplateService++logger = logging.getLogger(__name__)++# Per-instance compatibility verdicts. The UI renders these; it does not+# recompute them.+STATUS_INSTALLED = 'installed' # already present in the database+STATUS_READY = 'ready' # can be installed right now+STATUS_IMAGE_UNSUPPORTED = 'image_unsupported' # engine image does not ship it+STATUS_INCOMPATIBLE = 'incompatible' # wrong engine entirely+STATUS_UNKNOWN = 'unknown' # not probed / engine unreachable++# Which client can execute a statement against which engine protocol. This is a+# property of ServerKit's clients, not of any extension: adding an EXTENSION+# needs no entry here, only adding a whole new engine PROTOCOL would -- and the+# protocol list is already a closed enum in TemplateService.+_DATABASE_NAME_RE = re.compile(r'^[A-Za-z0-9_][A-Za-z0-9_\-]{0,62}$')+++def _postgres_exec(context: Dict, sql: str, database: Optional[str]) -> Dict:+ return DatabaseService.docker_pg_execute(+ context['container'], sql,+ database=database or context.get('default_database') or 'postgres',+ user=context.get('admin_user') or 'postgres',+ password=context.get('password'))+++def _mysql_exec(context: Dict, sql: str, database: Optional[str]) -> Dict:+ return DatabaseService.docker_mysql_execute(+ context['container'], sql,+ database=database or context.get('default_database'),+ user=context.get('admin_user') or 'root',+ password=context.get('password'))+++EXECUTORS = {+ 'postgresql': _postgres_exec,+ 'mysql': _mysql_exec,+}+++def _err(message: str, status_code: int = 400, **extra) -> Dict:+ payload = {'error': message, 'status_code': status_code}+ payload.update(extra)+ return payload+++# ── image identity ───────────────────────────────────────────────────────────+def _repository(image: str) -> str:+ """``pgvector/pgvector:pg16`` -> ``pgvector/pgvector``.++ Strips a digest and a tag (a colon in the last path segment), then a+ registry host, then Docker Hub's implicit ``library/`` namespace, so the+ same image written five ways compares equal.+ """+ ref = str(image or '').strip().split('@')[0]+ head, sep, tail = ref.rpartition(':')+ if sep and '/' not in tail:+ ref = head+ parts = ref.split('/')+ if len(parts) > 1 and ('.' in parts[0] or ':' in parts[0] or parts[0] == 'localhost'):+ parts = parts[1:]+ if len(parts) == 2 and parts[0] == 'library':+ parts = parts[1:]+ return '/'.join(parts)+++def _image_provides(image: Optional[str], declared: List[str]) -> Optional[bool]:+ """Does ``image`` look like one of the repositories that ship the extension?++ ``None`` when there is nothing to decide from (no image resolved), so a+ caller can tell "no" apart from "don't know".+ """+ if not declared:+ return True # the extension makes no image claim+ if not image:+ return None+ repository = _repository(image)+ return any(repository == _repository(want) for want in declared)+++def _compose_images(template: Dict) -> List[str]:+ """Image references a template's compose declares."""+ services = ((template or {}).get('compose') or {}).get('services') or {}+ return [str(svc['image']) for svc in services.values()+ if isinstance(svc, dict) and svc.get('image')]+++def instance_image(app) -> Optional[str]:+ """The image an installed engine actually runs.++ Read from the rendered compose in the app directory first -- it is on disk,+ it is what was installed, and it needs no Docker. Falls back to inspecting+ the live container.+ """+ root = getattr(app, 'root_path', None)+ if root:+ for filename in ('docker-compose.yml', 'docker-compose.yaml'):+ path = os.path.join(root, filename)+ if not os.path.exists(path):+ continue+ try:+ with open(path, 'r', encoding='utf-8') as fh:+ compose = yaml.safe_load(fh) or {}+ except Exception:+ continue+ services = compose.get('services') or {}+ service = services.get('app') or next(iter(services.values()), None)+ if isinstance(service, dict) and service.get('image'):+ return str(service['image'])+ try:+ from app.services.docker_service import DockerService+ info = DockerService.get_container(getattr(app, 'container_id', None) or app.name)+ except Exception:+ return None+ return ((info or {}).get('Config') or {}).get('Image')+++# ── catalog ──────────────────────────────────────────────────────────────────+def get_extension(extension_id: str) -> Optional[Dict]:+ """One extension by id, straight off the YAML."""+ return TemplateService.get_extension_template(extension_id)+++def _hosts_for(extension: Dict, engine_templates: List[Dict]) -> List[Dict]:+ """Engine templates that can host ``extension``, and whether each ships it.++ ``provides`` is what makes the remedy actionable: an operator told their+ PostgreSQL cannot host pgvector is also told which engine template can.+ """+ hosts = []+ for entry in engine_templates:+ engine = entry.get('engine') or {}+ # Both halves matter. Speaking the protocol is not enough -- CockroachDB+ # answers on the PostgreSQL wire and cannot load a single extension --+ # so the engine has to have declared `engine.extensions: true`.+ if not engine.get('supports_extensions'):+ continue+ if engine.get('protocol') != extension['protocol']:+ continue+ if extension['templates'] and entry['id'] not in extension['templates']:+ continue+ fetched = TemplateService.get_template(entry['id'])+ images = _compose_images(fetched['template']) if fetched.get('success') else []+ provides = any(_image_provides(image, extension['images']) for image in images)+ hosts.append({+ 'template_id': entry['id'],+ 'name': entry.get('name'),+ # The repository, not the compose string: a template's image still+ # carries an unresolved ${IMAGE_TAG} at this point.+ 'image': _repository(images[0]) if images else None,+ 'provides': bool(provides),+ })+ return hosts+++def extension_catalog() -> List[Dict]:+ """Every declared extension, with who can host it and where it is installed.++ One round trip is enough for the drawer: which engine templates host it,+ which of those actually ship it, and the id of every installed instance+ that is compatible today.+ """+ engine_templates = TemplateService.list_engine_templates()+ instances = engine_instances()++ catalog = []+ for extension in TemplateService.list_extension_templates():+ hosts = _hosts_for(extension, engine_templates)+ host_ids = {h['template_id'] for h in hosts}++ # "Compatible" means *not known to be incompatible*: an instance whose+ # image could not be read stays offered, because the install itself+ # still asks the engine before it writes anything.+ compatible, needs_image = [], []+ for instance in instances:+ if instance['template_id'] not in host_ids:+ continue+ (needs_image+ if _instance_verdict(instance, extension)[0] == STATUS_IMAGE_UNSUPPORTED+ else compatible).append(instance['app_id'])++ item = dict(extension)+ item['hosts'] = hosts+ item['provided_by'] = [h['template_id'] for h in hosts if h['provides']]+ item['compatible_instances'] = compatible+ item['incompatible_instances'] = needs_image+ catalog.append(item)+ return catalog+++# ── per-instance compatibility ───────────────────────────────────────────────+def _instance_verdict(instance: Dict, extension: Dict) -> tuple:+ """Static verdict for one instance/extension pair: ``(status, reason)``.++ Static because it costs nothing -- no Docker, no exec. It is enough to grey+ a card out in the catalog; :func:`install_extension` still asks the engine+ itself before it writes anything.+ """+ engine = instance.get('engine') or {}+ protocol = engine.get('protocol')+ if protocol != extension['protocol']:+ return STATUS_INCOMPATIBLE, (+ f"{instance['name']} speaks {protocol or 'no known protocol'}; "+ f"{extension['name']} needs {extension['protocol']}")+ if not engine.get('supports_extensions'):+ return STATUS_INCOMPATIBLE, (+ f"{instance['template_name'] or instance['name']} does not support "+ 'database extensions, even though it speaks the same protocol')+ if extension['templates'] and instance['template_id'] not in extension['templates']:+ return STATUS_INCOMPATIBLE, (+ f"{extension['name']} is only offered for "+ f"{', '.join(extension['templates'])}")+ provides = _image_provides(instance.get('image'), extension['images'])+ if provides is False:+ return STATUS_IMAGE_UNSUPPORTED, (+ f"{instance['name']} runs {instance.get('image')}, which does not ship "+ f"{extension['name']}. Enabling it there would fail with "+ '"could not open extension control file".')+ if provides is None:+ return STATUS_UNKNOWN, 'Could not determine which image this engine runs'+ return STATUS_READY, None+++def _remedy(extension: Dict, instance: Dict, engine_templates=None) -> Dict:+ """What the operator can actually do about an image that cannot host it."""+ version = instance.get('engine_version')+ hint = extension.get('image_hint')+ suggested = None+ if hint:+ suggested = hint.replace('{version}', str(version)) if version else hint+ elif extension['images']:+ suggested = extension['images'][0]+ hosts = _hosts_for(extension, engine_templates+ if engine_templates is not None+ else TemplateService.list_engine_templates())+ return {+ 'kind': 'image',+ 'current_image': instance.get('image'),+ 'required_images': extension['images'],+ 'suggested_image': suggested,+ # Engine templates whose own image ships it -- installable today.+ 'install_instead': [h for h in hosts if h['provides']],+ 'action': (+ 'This engine runs an image without the extension, and no statement can '+ 'add it. Install an engine whose image ships it and point the app at '+ f"that instance{', for example ' + suggested if suggested else ''}. "+ 'ServerKit will not silently recreate this container: doing so would '+ 'restart every connection to it.'),+ }+++def instance_extensions(app_id: int, probe: bool = False) -> Dict:+ """Every extension, judged against ONE installed engine.++ ``probe=True`` replaces the static image verdict with the engine's own+ answer, which is slower (a docker exec per extension) but authoritative.+ """+ instance = _find_instance(app_id)+ if instance is None:+ return _err(f'No installed database engine with id {app_id}', 404)++ engine_templates = TemplateService.list_engine_templates()+ results = []+ for extension in TemplateService.list_extension_templates():+ status, reason = _instance_verdict(instance, extension)+ item = dict(extension)+ item['installed_version'] = None++ if probe and status in (STATUS_READY, STATUS_IMAGE_UNSUPPORTED, STATUS_UNKNOWN):+ status, reason, item['installed_version'] = _probe(instance, extension,+ status, reason)++ item['status'] = status+ item['reason'] = reason+ item['remedy'] = (_remedy(extension, instance, engine_templates)+ if status == STATUS_IMAGE_UNSUPPORTED else None)+ results.append(item)++ return {'instance': _public_instance(instance), 'extensions': results,+ 'probed': bool(probe)}+++def _probe(instance: Dict, extension: Dict, status: str, reason: Optional[str]) -> tuple:+ """Ask the running engine what it can load, and what it already has."""+ executor = EXECUTORS.get(extension['protocol'])+ if executor is None or not extension.get('available_query'):+ return status, reason, None++ context = _execution_context(instance)+ result = executor(context, extension['available_query'], None)+ if not result.get('success'):+ # Falling back to the static verdict is deliberate: a stopped container+ # must not turn "your image cannot host this" into "maybe".+ if status == STATUS_IMAGE_UNSUPPORTED:+ return status, reason, None+ return STATUS_UNKNOWN, (result.get('error') or '').strip() or \+ 'Could not reach the engine', None+ if not (result.get('output') or '').strip():+ return STATUS_IMAGE_UNSUPPORTED, (+ f"{instance['name']} cannot load {extension['name']}: the running image "+ 'does not ship it.'), None++ version = None+ if extension.get('installed_query'):+ installed = executor(context, extension['installed_query'], None)+ version = (installed.get('output') or '').strip() or None+ return (STATUS_INSTALLED if version else STATUS_READY), None, version+++# ── install ──────────────────────────────────────────────────────────────────+def install_extension(app_id: int, extension_id: str, database: str = None) -> Dict:+ """Run an extension's statement against one database on one instance.++ Never executes the statement without first confirming the engine can load+ it, so the failure mode is a 409 naming the image to use, not a raw+ ``could not open extension control file`` surfaced as a generic error.+ """+ extension = get_extension(extension_id)+ if extension is None:+ return _err(f"Unknown extension '{extension_id}'", 404,+ available=[e['id'] for e in TemplateService.list_extension_templates()])++ instance = _find_instance(app_id)+ if instance is None:+ return _err(f'No installed database engine with id {app_id}', 404)++ status, reason = _instance_verdict(instance, extension)+ if status == STATUS_INCOMPATIBLE:+ return _err(reason, 400,+ hosts=[h['template_id']+ for h in _hosts_for(extension, TemplateService.list_engine_templates())])++ executor = EXECUTORS.get(extension['protocol'])+ if executor is None:+ return _err(f"ServerKit has no client for {extension['protocol']}, so it "+ 'cannot install extensions into it', 400)++ database = (database or instance.get('default_database') or '').strip() or None+ if database and not _DATABASE_NAME_RE.match(database):+ return _err(f"'{database}' is not a valid database name", 400)++ context = _execution_context(instance)++ # 1. Ask the engine itself. This is the check that matters: it is the only+ # one that knows whether the running image carries the control file.+ if extension.get('available_query'):+ probe = executor(context, extension['available_query'], database)+ if not probe.get('success'):+ if status == STATUS_IMAGE_UNSUPPORTED:+ return _err(reason, 409, status=STATUS_IMAGE_UNSUPPORTED,+ remedy=_remedy(extension, instance))+ return _err(+ f"Could not reach {instance['name']} to check whether it can load "+ f"{extension['name']}: {(probe.get('error') or '').strip() or 'no answer'}",+ 502, status=STATUS_UNKNOWN)+ if not (probe.get('output') or '').strip():+ return _err(+ f"{instance['name']} cannot load {extension['name']}: its image "+ f"({instance.get('image') or 'unknown'}) does not ship the extension. "+ 'Installing it would fail with "could not open extension control file".',+ 409, status=STATUS_IMAGE_UNSUPPORTED,+ remedy=_remedy(extension, instance))+ elif status == STATUS_IMAGE_UNSUPPORTED:+ # No probe to fall back on -- the declared image requirement is all we+ # have, and it says no.+ return _err(reason, 409, status=STATUS_IMAGE_UNSUPPORTED,+ remedy=_remedy(extension, instance))++ # 2. The statement comes from the extension's YAML, never from the request.+ result = executor(context, extension['statement'], database)+ if not result.get('success'):+ return _err(+ f"{extension['name']} could not be installed into "+ f"{database or instance['name']}: "+ f"{(result.get('error') or '').strip() or 'the engine rejected the statement'}",+ 400, status=STATUS_UNKNOWN)++ version = None+ if extension.get('installed_query'):+ installed = executor(context, extension['installed_query'], database)+ version = (installed.get('output') or '').strip() or None++ return {+ 'success': True,+ 'status': STATUS_INSTALLED,+ 'extension': {'id': extension['id'], 'name': extension['name'],+ 'version': version or extension['version']},+ 'instance': _public_instance(instance),+ 'database': database,+ 'statement': extension['statement'],+ }+++# ── instance plumbing ────────────────────────────────────────────────────────+def engine_instances() -> List[Dict]:+ """Every installed engine, described for extension purposes."""+ from app.models import Application++ described = []+ for app in Application.query.order_by(Application.created_at.asc()).all():+ record = _describe(app)+ if record:+ described.append(record)+ return described+++def _find_instance(app_id: int) -> Optional[Dict]:+ """One installed engine by app id, or ``None`` when it is not an engine."""+ from app.models import Application++ app = Application.query.get(app_id)+ return _describe(app) if app is not None else None+++def _describe(app) -> Optional[Dict]:+ """An installed engine, enriched with the bits extensions need.++ Engine-ness is decided by ``database_engine_service`` (a template carrying+ an ``engine:`` block), so "what counts as an installed engine" is still+ answered in exactly one place.+ """+ template_id = engines.app_template_id(app)+ if not template_id:+ return None+ fetched = TemplateService.get_template(template_id)+ if not fetched.get('success'):+ return None+ template = fetched['template']+ # No `engine:` block, no engine -- an ordinary app cannot host an extension.+ engine = TemplateService.engine_metadata(template)+ if not engine:+ return None+ variables = ((engines._install_info(app) or {}).get('variables') or {})+ version_var = (template.get('engine') or {}).get('version_var') or 'IMAGE_TAG'++ return {+ 'app_id': app.id,+ 'name': app.name,+ 'status': app.status,+ 'container': getattr(app, 'container_id', None) or app.name,+ 'template_id': template_id,+ 'template_name': template.get('name'),+ 'engine': engine,+ 'engine_version': variables.get(version_var) or template.get('version'),+ 'image': instance_image(app),+ 'default_database': variables.get(engine.get('database_var') or ''),+ 'admin_user': engine.get('admin_user'),+ 'password': variables.get(engine.get('admin_password_var') or ''),+ }+++def _execution_context(instance: Dict) -> Dict:+ return {+ 'container': instance['container'],+ 'admin_user': instance.get('admin_user'),+ 'password': instance.get('password'),+ 'default_database': instance.get('default_database'),+ }+++def _public_instance(instance: Dict) -> Dict:+ """The instance as the API may describe it — never the admin secret."""+ return {+ 'app_id': instance['app_id'],+ 'name': instance['name'],+ 'status': instance['status'],+ 'template_id': instance['template_id'],+ 'template_name': instance['template_name'],+ 'protocol': (instance.get('engine') or {}).get('protocol'),+ 'engine_version': instance.get('engine_version'),+ 'image': instance.get('image'),+ 'default_database': instance.get('default_database'),+ }diff --git a/backend/app/services/database_service.py b/backend/app/services/database_service.pyindex 0a218e1d..136e0d2f 100644--- a/backend/app/services/database_service.py+++ b/backend/app/services/database_service.py@@ -1251,6 +1251,40 @@ class DatabaseService:except Exception as e:return {'success': False, 'error': str(e)}+ @staticmethod+ def docker_pg_execute(container_name, query, database='postgres', user='postgres',+ password=None, timeout=30):+ """Execute a PostgreSQL statement inside a Docker container.++ The psql twin of :meth:`docker_mysql_execute`, so anything that has to+ talk to a containerised engine has one place to do it.++ ``ON_ERROR_STOP=1`` is not optional: without it psql happily reports+ success for a statement the server rejected, which turns a real failure+ (``could not open extension control file``) into a silent no-op.++ Output is ``-t -A``: no header, no padding, ``|``-separated columns.+ """+ try:+ cmd = ['docker', 'exec']+ # PGPASSWORD via the exec environment, never on the command line.+ if password:+ cmd.extend(['-e', f'PGPASSWORD={password}'])+ cmd.extend([container_name, 'psql', '-U', user,+ '-d', database or 'postgres',+ '-v', 'ON_ERROR_STOP=1',+ '-c', query, '-t', '-A'])+ result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)+ return {+ 'success': result.returncode == 0,+ 'output': result.stdout,+ 'error': result.stderr if result.returncode != 0 else None,+ }+ except subprocess.TimeoutExpired:+ return {'success': False, 'error': 'Query timed out'}+ except Exception as e:+ return {'success': False, 'error': str(e)}+@staticmethoddef docker_mysql_list_databases(container_name, user='root', password=None):"""List databases in a Docker MySQL container."""diff --git a/backend/app/services/managed_db_user_service.py b/backend/app/services/managed_db_user_service.pyindex 6d4f6768..437eaf9c 100644--- a/backend/app/services/managed_db_user_service.py+++ b/backend/app/services/managed_db_user_service.py@@ -13,7 +13,6 @@ the single choke-point ``_exec_sql`` so tests can stub it.import loggingimport reimport secrets-import subprocessfrom datetime import datetimefrom app import db@@ -60,24 +59,14 @@ class ManagedDbUserService:@staticmethoddef _docker_pg_execute(container_name, sql, user='postgres', password=None):- """psql inside a Docker container (database_service has no pg twin of- docker_mysql_execute, so this fills that gap here)."""- try:- cmd = ['docker', 'exec']- if password:- cmd.extend(['-e', f'PGPASSWORD={password}'])- cmd.extend([container_name, 'psql', '-U', user, '-d', 'postgres',- '-c', sql, '-t', '-A'])- result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)- return {- 'success': result.returncode == 0,- 'output': result.stdout,- 'error': result.stderr if result.returncode != 0 else None,- }- except subprocess.TimeoutExpired:- return {'success': False, 'error': 'Query timed out'}- except Exception as e:- return {'success': False, 'error': str(e)}+ """psql inside a Docker container.++ ``database_service`` grew the pg twin of ``docker_mysql_execute``; this+ stays as the named seam these callers use, with one implementation+ underneath.+ """+ return DatabaseService.docker_pg_execute(+ container_name, sql, database='postgres', user=user, password=password)# ── validation / quoting helpers ──@staticmethoddiff --git a/backend/app/services/template_service.py b/backend/app/services/template_service.pyindex ef643d34..a6613b24 100644--- a/backend/app/services/template_service.py+++ b/backend/app/services/template_service.py@@ -196,6 +196,8 @@ class TemplateService:raise ValueErrorexcept (TypeError, ValueError):errors.append('engine.default_port must be a port number (1-65535)')+ if 'extensions' in engine and not isinstance(engine['extensions'], bool):+ errors.append('engine.extensions must be true or false')return errors@classmethod@@ -230,9 +232,197 @@ class TemplateService:'unit': engine.get('unit'),'client': engine.get('client'),'data_path': engine.get('data_path'),+ # Opt-in, because speaking a protocol is not the same as supporting+ # its extensions: CockroachDB answers on the PostgreSQL wire and has+ # no `CREATE EXTENSION` to speak of. An engine that can load them+ # says so, so nothing has to special-case the ones that cannot.+ 'supports_extensions': engine.get('extensions') is True,'versions': [str(v) for v in versions],}+ # ==================================================================+ # The `extension:` block — an add-on that installs INTO a running engine+ # ------------------------------------------------------------------+ # An engine is a template because an engine gets a container. An+ # extension does NOT: installing pgvector means executing one statement+ # against a PostgreSQL that is already running. It therefore has no+ # compose, no port, no volume and no app row -- so it is not an app+ # template and is deliberately kept out of the app catalog. It lives in+ # its own namespace, ``<templates>/extensions/*.yaml``:+ #+ # id: pgvector # == the filename stem+ # name: pgvector+ # version: "0.8.0"+ # description: ...+ # extension:+ # protocol: postgresql # which engines can host it+ # statement: CREATE EXTENSION IF NOT EXISTS vector;+ # available_query: SELECT 1 FROM pg_available_extensions WHERE ...+ # installed_query: SELECT extversion FROM pg_extension WHERE ...+ # images: [pgvector/pgvector] # images that SHIP it (see below)+ # image_hint: "pgvector/pgvector:pg{version}"+ # templates: [postgresql] # optional: narrow beyond protocol+ #+ # ``images:`` is the load-bearing field. `CREATE EXTENSION vector`+ # against stock ``postgres:16`` fails with "could not open extension+ # control file" -- the statement is right, the image simply does not+ # carry the shared library. Declaring which images provide the extension+ # lets the catalog say so BEFORE the operator clicks, and lets the+ # installer refuse with a remedy instead of a cryptic engine error.+ # ==================================================================+ EXTENSIONS_SUBDIR = 'extensions'+ # Extensions are one family by definition, so it is not a YAML field --+ # nothing can declare it wrong.+ EXTENSION_FAMILY = 'Extension'++ @classmethod+ def extension_dirs(cls) -> List[str]:+ """Where extension YAMLs are looked for, highest precedence first.++ The synced/operator directory shadows the bundled one, exactly like+ :meth:`list_local_templates` does for app templates.+ """+ return [os.path.join(cls.TEMPLATES_DIR, cls.EXTENSIONS_SUBDIR),+ os.path.join(cls.LOCAL_TEMPLATES_DIR, cls.EXTENSIONS_SUBDIR)]++ @classmethod+ def validate_extension(cls, document: Dict) -> Dict:+ """Validate an extension document (the whole file, not just the block)."""+ errors = []+ if not isinstance(document, dict):+ return {'valid': False, 'errors': ['extension file must be a mapping']}+ for field in ('name', 'version', 'description'):+ if not document.get(field):+ errors.append(f'Missing required field: {field}')+ if 'extension' not in document:+ errors.append("Missing required 'extension' block")+ else:+ errors.extend(cls._extension_block_errors(document['extension']))+ if 'compose' in document or 'dockerfile' in document:+ errors.append('An extension installs into a running engine and must '+ 'not declare a compose/dockerfile of its own')+ if errors:+ return {'valid': False, 'errors': errors}+ return {'valid': True, 'errors': []}++ @classmethod+ def _extension_block_errors(cls, extension: Any) -> List[str]:+ """Hard errors in an ``extension:`` block (shape only, never opinions)."""+ if not isinstance(extension, dict):+ return ["'extension' must be a mapping"]+ errors = []+ protocol = extension.get('protocol')+ if not protocol:+ errors.append('extension.protocol is required (which engines can host it)')+ elif protocol not in cls.ENGINE_PROTOCOLS:+ errors.append(+ f"extension.protocol '{protocol}' is not one of: "+ f"{', '.join(cls.ENGINE_PROTOCOLS)}")+ elif protocol == 'none':+ errors.append("extension.protocol 'none' cannot host an extension: "+ 'there is no client to execute the statement with')+ statement = extension.get('statement')+ if not statement or not isinstance(statement, str) or not statement.strip():+ errors.append('extension.statement is required and must be a non-empty string')+ for key in ('available_query', 'installed_query', 'image_hint', 'size', 'unit'):+ value = extension.get(key)+ if value is not None and not isinstance(value, str):+ errors.append(f'extension.{key} must be a string')+ for key in ('images', 'templates', 'versions'):+ value = extension.get(key)+ if value is None:+ continue+ if not isinstance(value, list) or not all(isinstance(v, str) for v in value):+ errors.append(f'extension.{key} must be a list of strings')+ return errors++ @classmethod+ def extension_metadata(cls, document: Dict, extension_id: str = None) -> Optional[Dict]:+ """Normalized extension record, or ``None`` when the document is not one.++ Everything a consumer needs is read off the YAML; nothing about any+ particular extension is hardcoded here.+ """+ if not isinstance(document, dict) or not isinstance(document.get('extension'), dict):+ return None+ block = document['extension']+ versions = block.get('versions')+ if not isinstance(versions, list) or not versions:+ versions = [document.get('version')] if document.get('version') else []+ images = [i for i in (block.get('images') or []) if isinstance(i, str)]+ return {+ 'id': extension_id or document.get('id'),+ 'name': document.get('name'),+ 'version': document.get('version'),+ 'description': document.get('description'),+ 'icon': document.get('icon'),+ 'website': document.get('website'),+ 'documentation': document.get('documentation'),+ 'family': cls.EXTENSION_FAMILY,+ 'protocol': block.get('protocol'),+ 'statement': block.get('statement'),+ 'available_query': block.get('available_query'),+ 'installed_query': block.get('installed_query'),+ # [] means "any engine template speaking `protocol`".+ 'templates': [t for t in (block.get('templates') or []) if isinstance(t, str)],+ 'images': images,+ 'image_hint': block.get('image_hint'),+ # An extension with no declared images makes no image claim, so it+ # is never blocked on one.+ 'requires_image': bool(images),+ 'size': block.get('size'),+ 'unit': block.get('unit'),+ 'versions': [str(v) for v in versions],+ }++ @classmethod+ def list_extension_templates(cls) -> List[Dict]:+ """Every extension declared under a ``templates/extensions/`` directory.++ Derived from the files, like the engine catalog: dropping a YAML in+ makes the extension appear, with no code change anywhere.+ """+ found: List[Dict] = []+ seen = set()+ for directory in cls.extension_dirs():+ if not os.path.isdir(directory):+ continue+ for filename in sorted(os.listdir(directory)):+ if not filename.endswith(('.yaml', '.yml')):+ continue+ extension_id = filename.rsplit('.', 1)[0]+ if extension_id in seen:+ continue+ record = cls._load_extension_file(os.path.join(directory, filename),+ extension_id)+ if record:+ seen.add(extension_id)+ found.append(record)+ return found++ @classmethod+ def _load_extension_file(cls, path: str, extension_id: str) -> Optional[Dict]:+ """Parse + validate one extension file, or ``None`` (logged) if broken."""+ try:+ with open(path, 'r', encoding='utf-8') as fh:+ document = yaml.safe_load(fh)+ except Exception:+ return None+ validation = cls.validate_extension(document if isinstance(document, dict) else {})+ if not validation['valid']:+ return None+ return cls.extension_metadata(document, extension_id=extension_id)++ @classmethod+ def get_extension_template(cls, extension_id: str) -> Optional[Dict]:+ """One normalized extension by id, or ``None``."""+ if not extension_id:+ return None+ for record in cls.list_extension_templates():+ if record['id'] == extension_id:+ return record+ return None+@classmethoddef parse_template(cls, template_path: str) -> Dict:"""Parse a template file."""diff --git a/backend/templates/extensions/pgvector.yaml b/backend/templates/extensions/pgvector.yamlnew file mode 100644index 00000000..f4c4f919--- /dev/null+++ b/backend/templates/extensions/pgvector.yaml@@ -0,0 +1,32 @@+id: pgvector+name: pgvector+version: "0.8.0"+description: Vector similarity search inside PostgreSQL — embeddings, ANN indexes and cosine distance next to your relational data+icon: https://serverkit.ai/imgs/template-icons/postgresql.svg+website: https://github.com/pgvector/pgvector+documentation: https://github.com/pgvector/pgvector#readme++# An extension gets no container of its own: installing it runs `statement`+# against a database on an engine that is ALREADY running.+extension:+ protocol: postgresql+ statement: CREATE EXTENSION IF NOT EXISTS vector;++ # Asked first, every time, and authoritative. `pg_available_extensions` lists+ # what the running image can actually load -- an empty answer is the whole+ # reason this file declares `images` below, and is what stops the install+ # from hitting "ERROR: could not open extension control file".+ available_query: SELECT 1 FROM pg_available_extensions WHERE name = 'vector';+ installed_query: SELECT extversion FROM pg_extension WHERE extname = 'vector';++ # Stock `postgres:16` does NOT ship the vector shared library, so no+ # statement can conjure it. These are the image repositories that do.+ images:+ - pgvector/pgvector+ image_hint: pgvector/pgvector:pg{version}++ size: 2.4 MB+ unit: indexes+ versions:+ - "0.8.0"+ - "0.7.4"diff --git a/backend/templates/extensions/timescaledb.yaml b/backend/templates/extensions/timescaledb.yamlnew file mode 100644index 00000000..6288261c--- /dev/null+++ b/backend/templates/extensions/timescaledb.yaml@@ -0,0 +1,29 @@+id: timescaledb+name: TimescaleDB+version: "2.17.2"+description: Turns PostgreSQL into a time-series database with hypertables, compression and continuous aggregates+icon: https://serverkit.ai/imgs/template-icons/postgresql.svg+website: https://www.timescale.com+documentation: https://docs.timescale.com++extension:+ protocol: postgresql+ statement: CREATE EXTENSION IF NOT EXISTS timescaledb;++ available_query: SELECT 1 FROM pg_available_extensions WHERE name = 'timescaledb';+ installed_query: SELECT extversion FROM pg_extension WHERE extname = 'timescaledb';++ # TimescaleDB needs its library preloaded (shared_preload_libraries), which no+ # stock PostgreSQL image does -- the timescale images are built for it. No+ # bundled engine template ships one, so out of the box this extension reports+ # honestly that nothing installed can host it, and names what would.+ images:+ - timescale/timescaledb+ - timescale/timescaledb-ha+ image_hint: timescale/timescaledb:latest-pg{version}++ size: 18 MB+ unit: hypertables+ versions:+ - "2.17.2"+ - "2.16.1"diff --git a/backend/templates/index.json b/backend/templates/index.jsonindex 3401279f..c5a2e76f 100644--- a/backend/templates/index.json+++ b/backend/templates/index.json@@ -2,7 +2,7 @@"name": "serverkit-official","schema_version": "1.0","generated_at": "2026-07-25T20:06:08.123735",- "count": 117,+ "count": 118,"templates": [{"id": "actualbudget",@@ -167,6 +167,7 @@"unit": "tables","client": "clickhouse-client","data_path": "/var/lib/clickhouse",+ "supports_extensions": false,"versions": ["24.3","23.8"@@ -196,6 +197,7 @@"unit": "tables","client": "cockroach sql","data_path": "/cockroach/cockroach-data",+ "supports_extensions": false,"versions": ["24.1","23.2"@@ -236,6 +238,7 @@"unit": "documents","client": "curl","data_path": "/opt/couchdb/data",+ "supports_extensions": false,"versions": ["3.3","3.2"@@ -493,6 +496,7 @@"unit": "buckets","client": "influx","data_path": "/var/lib/influxdb2",+ "supports_extensions": false,"versions": ["2.7","2.6"@@ -663,6 +667,7 @@"unit": "tables","client": "mariadb","data_path": "/var/lib/mysql",+ "supports_extensions": false,"versions": ["11.4","10.11"@@ -715,6 +720,7 @@"unit": "indexes","client": "curl","data_path": "/meili_data",+ "supports_extensions": false,"versions": ["1.12"]@@ -800,6 +806,7 @@"unit": "collections","client": "mongosh","data_path": "/data/db",+ "supports_extensions": false,"versions": ["7.0","6.0"@@ -840,6 +847,7 @@"unit": "tables","client": "mysql","data_path": "/var/lib/mysql",+ "supports_extensions": false,"versions": ["8.4","8.0"@@ -892,6 +900,7 @@"unit": "nodes","client": "cypher-shell","data_path": "/data",+ "supports_extensions": false,"versions": ["5.20","4.4"@@ -1157,6 +1166,38 @@"unit": "tables","client": "psql","data_path": "/var/lib/postgresql/data",+ "supports_extensions": true,+ "versions": [+ "16",+ "15",+ "14"+ ]+ }+ },+ {+ "id": "postgresql-pgvector",+ "name": "PostgreSQL + pgvector",+ "version": "16",+ "description": "PostgreSQL on an image that ships the pgvector shared library, so vector search can be enabled without rebuilding the container",+ "icon": "https://serverkit.ai/imgs/template-icons/postgresql.svg",+ "categories": [+ "database",+ "sql",+ "ai"+ ],+ "engine": {+ "family": "Relational",+ "protocol": "postgresql",+ "default_port": 5434,+ "admin_user": "postgres",+ "admin_password_var": "DB_PASSWORD",+ "database_var": "DB_NAME",+ "port_var": "PORT",+ "bind_var": "BIND_ADDRESS",+ "unit": "tables",+ "client": "psql",+ "data_path": "/var/lib/postgresql/data",+ "supports_extensions": true,"versions": ["16","15",@@ -1291,6 +1332,7 @@"unit": "keys","client": "redis-cli","data_path": "/data",+ "supports_extensions": false,"versions": ["7.2","7.0"@@ -1483,6 +1525,7 @@"unit": "keys","client": "valkey-cli","data_path": "/data",+ "supports_extensions": false,"versions": ["8","7.2"diff --git a/backend/templates/postgresql-pgvector.yaml b/backend/templates/postgresql-pgvector.yamlnew file mode 100644index 00000000..127ae8a3--- /dev/null+++ b/backend/templates/postgresql-pgvector.yaml@@ -0,0 +1,88 @@+id: postgresql-pgvector+name: PostgreSQL + pgvector+version: "16"+description: PostgreSQL on an image that ships the pgvector shared library, so vector search can be enabled without rebuilding the container+icon: https://serverkit.ai/imgs/template-icons/postgresql.svg+categories:+ - database+ - sql+ - ai+website: https://github.com/pgvector/pgvector+documentation: https://github.com/pgvector/pgvector#readme++# A normal engine template. The only thing that distinguishes it from+# `postgresql.yaml` is the image: `pgvector/pgvector` carries the extension's+# control file, so `CREATE EXTENSION vector` succeeds here and cannot on stock+# `postgres:16`. Nothing in Python knows that -- the extension declares which+# image repositories provide it, and this template is discovered by matching.+engine:+ family: Relational+ protocol: postgresql+ default_port: 5434+ admin_user: postgres+ admin_password_var: DB_PASSWORD+ database_var: DB_NAME+ port_var: PORT+ bind_var: BIND_ADDRESS+ unit: tables+ client: psql+ data_path: /var/lib/postgresql/data+ extensions: true+ version_var: IMAGE_TAG+ versions:+ - "16"+ - "15"+ - "14"++variables:+ - name: IMAGE_TAG+ type: string+ default: "16"+ hidden: true+ description: PostgreSQL major version; constrained to engine.versions by the installer+ - name: PORT+ type: port+ # 5432 is usually the host's own PostgreSQL and 5433 the plain engine template.+ default: "5434"+ hidden: false+ description: Host port to publish PostgreSQL on+ - name: BIND_ADDRESS+ type: string+ default: 127.0.0.1+ hidden: true+ description: Address the port binds to. 127.0.0.1 keeps the engine private.+ - name: DB_PASSWORD+ type: password+ length: 28+ description: Password for the postgres superuser+ - name: DB_NAME+ type: string+ default: postgres+ description: Initial database to create++compose:+ services:+ app:+ image: pgvector/pgvector:pg${IMAGE_TAG}+ container_name: ${APP_NAME}+ restart: unless-stopped+ ports:+ - "${BIND_ADDRESS}:${PORT}:5432"+ environment:+ POSTGRES_PASSWORD: "${DB_PASSWORD}"+ POSTGRES_USER: postgres+ POSTGRES_DB: "${DB_NAME}"+ volumes:+ - postgresql-pgvector-data:/var/lib/postgresql/data++ volumes:+ postgresql-pgvector-data:++ports:+ - port: "${PORT}"+ protocol: postgresql+ description: PostgreSQL wire protocol++requirements:+ memory: 512MB+ storage: 5GBdiff --git a/backend/tests/test_database_engine_extensions.py b/backend/tests/test_database_engine_extensions.pynew file mode 100644index 00000000..6499b861--- /dev/null+++ b/backend/tests/test_database_engine_extensions.py@@ -0,0 +1,763 @@+"""Database engine extensions — installed INTO a running engine, not beside it.++Sibling of ``test_database_engines.py``: engines are app templates, extensions+are not (they get no container), so they get their own file rather than a+section of that one.++Two tests carry the design:++* ``test_dropping_a_new_extension_yaml_lists_it`` — the same zero-code-change+ property the engine catalog has, for extensions.+* ``TestTheImageProblem`` — ``CREATE EXTENSION vector`` is a *correct*+ statement that fails on stock ``postgres:16``. Nothing here may reach the+ engine without first establishing that the image can load the extension.++No Docker: every executor is stubbed, and the stubs record exactly which+statements would have been run so "it never executed the statement" is a real+assertion rather than a hope.+"""+import json+import os++import pytest+import yaml++from app import db+from app.models import Application, User+from app.services import database_engine_extension_service as ext+from app.services.template_service import TemplateService++EXTENSIONS_DIR = os.path.join(TemplateService.LOCAL_TEMPLATES_DIR,+ TemplateService.EXTENSIONS_SUBDIR)+TEMPLATES_DIR = TemplateService.LOCAL_TEMPLATES_DIR++# A complete extension, written into backend/templates/extensions/ by a fixture.+NEW_EXTENSION_YAML = """\+id: probe_ext+name: ProbeExt+version: "3.1"+description: An extension that exists only for this test+extension:+ protocol: postgresql+ statement: CREATE EXTENSION IF NOT EXISTS probe_ext;+ available_query: SELECT 1 FROM pg_available_extensions WHERE name = 'probe_ext';+ installed_query: SELECT extversion FROM pg_extension WHERE extname = 'probe_ext';+ images:+ - probe/postgres-probe+ image_hint: probe/postgres-probe:pg{version}+ size: 1 MB+ unit: probes+ versions:+ - "3.1"+ - "3.0"+"""++# An engine template whose image ships the extension above — proving the+# "install this instead" remedy is discovered, not hardcoded.+CAPABLE_ENGINE_YAML = """\+id: probe-capable-pg+name: Probe-capable PostgreSQL+version: "16"+description: PostgreSQL on an image that ships ProbeExt+icon: https://serverkit.ai/imgs/template-icons/postgresql.svg+categories:+ - database+engine:+ family: Relational+ protocol: postgresql+ default_port: 55432+ admin_user: postgres+ admin_password_var: DB_PASSWORD+ port_var: PORT+ bind_var: BIND_ADDRESS+ unit: tables+ client: psql+ data_path: /var/lib/postgresql/data+ extensions: true+ version_var: IMAGE_TAG+ versions:+ - "16"+variables:+ - name: IMAGE_TAG+ type: string+ default: "16"+ hidden: true+ - name: PORT+ type: port+ default: "55432"+ - name: BIND_ADDRESS+ type: string+ default: 127.0.0.1+ hidden: true+ - name: DB_PASSWORD+ type: password+ length: 28+compose:+ services:+ app:+ image: probe/postgres-probe:pg${IMAGE_TAG}+ container_name: ${APP_NAME}+ restart: unless-stopped+ ports:+ - "${BIND_ADDRESS}:${PORT}:5432"+ environment:+ POSTGRES_PASSWORD: "${DB_PASSWORD}"+ POSTGRES_USER: postgres+ volumes:+ - probe-capable-data:/var/lib/postgresql/data+ volumes:+ probe-capable-data:+"""+++# ── fixtures ─────────────────────────────────────────────────────────────────[email protected](autouse=True)+def offline_templates(monkeypatch):+ """Hermetic: no remote repos, no `docker ps`, no `docker inspect`."""+ monkeypatch.setattr(TemplateService, 'get_config',+ classmethod(lambda cls: {'repos': [], 'installed': {}}))+ monkeypatch.setattr(TemplateService, '_get_docker_used_ports',+ classmethod(lambda cls: set()))+ monkeypatch.setattr(TemplateService, '_managed_app_base_port',+ classmethod(lambda cls: 0))+++def new_extension_yaml():+ """Drop a brand-new extension into the extensions directory, then remove it.++ No registration, no import, no code change — the whole design.+ """+ path = os.path.join(EXTENSIONS_DIR, 'probe_ext.yaml')+ with open(path, 'w', encoding='utf-8') as fh:+ fh.write(NEW_EXTENSION_YAML)+ try:+ yield 'probe_ext'+ finally:+ if os.path.exists(path):+ os.remove(path)+++def capable_engine_yaml():+ """An engine template whose image ships ProbeExt."""+ path = os.path.join(TEMPLATES_DIR, 'probe-capable-pg.yaml')+ with open(path, 'w', encoding='utf-8') as fh:+ fh.write(CAPABLE_ENGINE_YAML)+ try:+ yield 'probe-capable-pg'+ finally:+ if os.path.exists(path):+ os.remove(path)+++def viewer_headers(app):+ """A logged-in NON-admin, for the admin-only checks."""+ from flask_jwt_extended import create_access_token+ from werkzeug.security import generate_password_hash++ user = User(email='[email protected]', username='extviewer',+ password_hash=generate_password_hash('x'),+ role=User.ROLE_DEVELOPER, is_active=True)+ db.session.add(user)+ db.session.commit()+ return {'Authorization': f'Bearer {create_access_token(identity=user.id)}'}+++def _install_engine(tmp_path, monkeypatch, *, template_id='postgresql',+ name='pg-main', image='postgres:16-alpine', variables=None):+ """An Application that looks exactly like a finished engine install.++ The rendered compose is written for real, because that file is where the+ image an instance runs is read from.+ """+ root = tmp_path / name+ root.mkdir()+ (root / '.serverkit-template.json').write_text(json.dumps({+ 'template_id': template_id,+ 'template_version': '16',+ 'variables': variables or {'PORT': '5433', 'BIND_ADDRESS': '127.0.0.1',+ 'IMAGE_TAG': '16', 'DB_NAME': 'shop',+ 'DB_PASSWORD': 'sup3rs3cret-do-not-leak'},+ }), encoding='utf-8')+ if image:+ (root / 'docker-compose.yml').write_text(yaml.safe_dump({+ 'services': {'app': {'image': image, 'container_name': name}},+ }), encoding='utf-8')++ application = Application(name=name, app_type='docker', status='running',+ user_id=1, port=5433, root_path=str(root))+ db.session.add(application)+ db.session.commit()+ monkeypatch.setattr(TemplateService, 'get_config', classmethod(+ lambda cls: {'repos': [], 'installed': {+ str(application.id): {'template_id': template_id}}}))+ return application+++class FakeEngine:+ """Records every statement, answers the ones a test declares.++ Defaults to "the extension is not available", which is what a stock+ postgres image really says.+ """++ def __init__(self, *, available=False, installed_version='', fail=None):+ self.available = available+ self.installed_version = installed_version+ self.fail = fail+ self.statements = []++ def __call__(self, context, sql, database):+ self.statements.append((sql, database))+ if self.fail is not None:+ return {'success': False, 'error': self.fail}+ if 'pg_available_extensions' in sql:+ return {'success': True, 'output': '1\n' if self.available else '\n'}+ if 'pg_extension' in sql:+ return {'success': True, 'output': self.installed_version}+ return {'success': True, 'output': ''}++ @property+ def ran_create(self):+ return any(s.upper().startswith('CREATE EXTENSION') for s, _ in self.statements)+++def engine_client(monkeypatch):+ """Install a FakeEngine as the postgresql executor and hand it back."""+ def _install(**kwargs):+ fake = FakeEngine(**kwargs)+ monkeypatch.setitem(ext.EXECUTORS, 'postgresql', fake)+ return fake+ return _install+++def _post(client, headers, app_id, **body):+ return client.post(f'/api/v1/databases/engines/{app_id}/extensions',+ json=body, headers=headers)+++# ── the design proof ─────────────────────────────────────────────────────────+class TestZeroCodeChangeCatalog:++ def test_dropping_a_new_extension_yaml_lists_it(self, client, auth_headers,+ new_extension_yaml):+ """A new extension YAML appears in the catalog with NO code change."""+ response = client.get('/api/v1/databases/engines/extensions',+ headers=auth_headers)+ assert response.status_code == 200++ entry = next((e for e in response.get_json()['extensions']+ if e['id'] == 'probe_ext'), None)+ assert entry is not None, 'a new extension file must appear with no code change'+ assert entry['name'] == 'ProbeExt'+ assert entry['statement'] == 'CREATE EXTENSION IF NOT EXISTS probe_ext;'+ assert entry['protocol'] == 'postgresql'+ assert entry['images'] == ['probe/postgres-probe']+ assert entry['versions'] == ['3.1', '3.0']+ assert entry['family'] == 'Extension'++ def test_extension_removed_when_yaml_is_removed(self, client, auth_headers):+ """The catalog is derived, not cached: no YAML, no entry."""+ data = client.get('/api/v1/databases/engines/extensions',+ headers=auth_headers).get_json()+ assert 'probe_ext' not in {e['id'] for e in data['extensions']}++ def test_a_new_extension_is_immediately_installable(+ self, client, auth_headers, tmp_path, monkeypatch,+ new_extension_yaml, engine_client):+ """...and installing it needs no code either."""+ fake = engine_client(available=True, installed_version='3.1')+ application = _install_engine(tmp_path, monkeypatch,+ image='probe/postgres-probe:pg16')+ response = _post(client, auth_headers, application.id,+ extension_id='probe_ext', database='shop')+ assert response.status_code == 201, response.get_json()+ assert fake.ran_create+ assert response.get_json()['extension']['version'] == '3.1'++ def test_a_new_engine_yaml_becomes_a_host_with_no_code_change(+ self, client, auth_headers, new_extension_yaml, capable_engine_yaml):+ """Compatibility is matched on the engine's OWN protocol.++ Neither file names the other, so an engine template dropped in later is+ offered as a host — and as the remedy, because its image ships it.+ """+ data = client.get('/api/v1/databases/engines/extensions',+ headers=auth_headers).get_json()+ entry = next(e for e in data['extensions'] if e['id'] == 'probe_ext')+ hosts = {h['template_id'] for h in entry['hosts']}+ assert 'postgresql' in hosts # protocol match, image does not ship it+ assert 'probe-capable-pg' in hosts+ assert entry['provided_by'] == ['probe-capable-pg']++ def test_bundled_extensions_are_the_ones_shipped(self, client, auth_headers):+ data = client.get('/api/v1/databases/engines/extensions',+ headers=auth_headers).get_json()+ assert {'pgvector', 'timescaledb'} <= {e['id'] for e in data['extensions']}++ def test_extensions_are_not_app_templates(self, app):+ """They have no container, so they must never reach the app catalog."""+ ids = {t['id'] for t in TemplateService.list_all_templates()}+ assert 'pgvector' not in ids+ assert 'timescaledb' not in ids+++# ── the extension block: loader + validator ──────────────────────────────────+class TestExtensionBlockPlumbing:++ def test_shipped_extensions_all_validate(self, app):+ for filename in os.listdir(EXTENSIONS_DIR):+ if not filename.endswith(('.yaml', '.yml')):+ continue+ with open(os.path.join(EXTENSIONS_DIR, filename), encoding='utf-8') as fh:+ document = yaml.safe_load(fh)+ result = TemplateService.validate_extension(document)+ assert result['valid'], (filename, result['errors'])+ assert document['id'] == filename.rsplit('.', 1)[0], filename++ def test_statement_is_required(self, app):+ result = TemplateService.validate_extension({+ 'name': 'x', 'version': '1', 'description': 'd',+ 'extension': {'protocol': 'postgresql'}})+ assert not result['valid']+ assert any('statement' in e for e in result['errors'])++ def test_protocol_must_be_a_known_one(self, app):+ result = TemplateService.validate_extension({+ 'name': 'x', 'version': '1', 'description': 'd',+ 'extension': {'protocol': 'telepathy', 'statement': 'SELECT 1;'}})+ assert not result['valid']+ assert any('telepathy' in e for e in result['errors'])++ def test_protocol_none_cannot_host_an_extension(self, app):+ """`protocol: none` is legitimate for an ENGINE and meaningless here."""+ result = TemplateService.validate_extension({+ 'name': 'x', 'version': '1', 'description': 'd',+ 'extension': {'protocol': 'none', 'statement': 'SELECT 1;'}})+ assert not result['valid']++ def test_an_extension_may_not_declare_a_container(self, app):+ """The distinction from an engine, enforced rather than documented."""+ result = TemplateService.validate_extension({+ 'name': 'x', 'version': '1', 'description': 'd',+ 'extension': {'protocol': 'postgresql', 'statement': 'SELECT 1;'},+ 'compose': {'services': {'app': {'image': 'x'}}}})+ assert not result['valid']+ assert any('compose' in e for e in result['errors'])++ def test_a_broken_file_is_skipped_not_fatal(self, app):+ """One malformed extension must not take the catalog down with it."""+ path = os.path.join(EXTENSIONS_DIR, 'broken_ext.yaml')+ with open(path, 'w', encoding='utf-8') as fh:+ fh.write('name: Broken\nextension: not-a-mapping\n')+ try:+ ids = {e['id'] for e in TemplateService.list_extension_templates()}+ assert 'broken_ext' not in ids+ assert 'pgvector' in ids+ finally:+ os.remove(path)++ def test_catalog_schema_documents_the_extension_block(self, client, auth_headers):+ schema = client.get('/api/v1/templates/catalog/schema',+ headers=auth_headers).get_json()+ block = schema['extension_block']+ assert block['family'] == 'Extension'+ assert 'none' not in block['protocols']+ fields = {f['field'] for f in block['fields']}+ assert {'protocol', 'statement', 'images', 'available_query'} <= fields+++# ── compatibility ────────────────────────────────────────────────────────────+class TestCompatibility:++ def test_extension_is_only_offered_for_engines_that_can_host_it(+ self, client, auth_headers):+ """pgvector is a PostgreSQL extension; MongoDB may not be offered it."""+ data = client.get('/api/v1/databases/engines/extensions',+ headers=auth_headers).get_json()+ entry = next(e for e in data['extensions'] if e['id'] == 'pgvector')+ hosts = {h['template_id'] for h in entry['hosts']}+ assert 'postgresql' in hosts+ assert 'postgresql-pgvector' in hosts+ assert 'mongodb' not in hosts+ assert 'mysql' not in hosts+ assert 'redis' not in hosts++ def test_speaking_the_protocol_is_not_enough(self, client, auth_headers):+ """CockroachDB answers on the PostgreSQL wire and has no extensions.++ Offering pgvector for it would send an operator to an image that cannot+ exist, so an engine has to declare `engine.extensions: true` -- which+ keeps CockroachDB out without anything in Python naming it.+ """+ data = client.get('/api/v1/databases/engines', headers=auth_headers).get_json()+ cockroach = next(e for e in data['catalog'] if e['id'] == 'cockroachdb')+ assert cockroach['engine']['protocol'] == 'postgresql'+ assert cockroach['engine']['supports_extensions'] is False++ entry = next(e for e in data['extensions'] if e['id'] == 'pgvector')+ assert 'cockroachdb' not in {h['template_id'] for h in entry['hosts']}++ def test_installing_into_an_engine_without_extension_support_is_refused(+ self, client, auth_headers, tmp_path, monkeypatch, engine_client):+ fake = engine_client(available=True)+ application = _install_engine(tmp_path, monkeypatch, template_id='cockroachdb',+ name='crdb', image='cockroachdb/cockroach:latest-v24.1')+ response = _post(client, auth_headers, application.id, extension_id='pgvector')+ assert response.status_code == 400+ assert 'does not support database extensions' in response.get_json()['error']+ assert not fake.statements++ def test_installing_into_the_wrong_engine_is_refused(+ self, client, auth_headers, tmp_path, monkeypatch, engine_client):+ fake = engine_client(available=True)+ application = _install_engine(tmp_path, monkeypatch, template_id='mongodb',+ name='mongo-main', image='mongo:7.0')+ response = _post(client, auth_headers, application.id, extension_id='pgvector')+ assert response.status_code == 400+ body = response.get_json()+ assert 'postgresql' in body['error']+ assert 'postgresql' in body['hosts']+ assert not fake.statements, 'a wrong-engine install must not reach any engine'++ def test_a_compatible_instance_is_listed_as_such(+ self, client, auth_headers, tmp_path, monkeypatch):+ _install_engine(tmp_path, monkeypatch, template_id='postgresql-pgvector',+ name='pgv', image='pgvector/pgvector:pg16')+ data = client.get('/api/v1/databases/engines/extensions',+ headers=auth_headers).get_json()+ entry = next(e for e in data['extensions'] if e['id'] == 'pgvector')+ assert entry['compatible_instances']+ assert not entry['incompatible_instances']++ def test_instance_listing_judges_every_extension(+ self, client, auth_headers, tmp_path, monkeypatch):+ application = _install_engine(tmp_path, monkeypatch)+ data = client.get(f'/api/v1/databases/engines/{application.id}/extensions',+ headers=auth_headers).get_json()+ by_id = {e['id']: e for e in data['extensions']}+ assert by_id['pgvector']['status'] == ext.STATUS_IMAGE_UNSUPPORTED+ assert data['instance']['protocol'] == 'postgresql'+ assert data['probed'] is False+ # The secret never leaves the install record.+ assert 'sup3rs3cret-do-not-leak' not in json.dumps(data)++ def test_instance_listing_404s_for_a_non_engine_app(+ self, client, auth_headers, tmp_path, monkeypatch):+ application = _install_engine(tmp_path, monkeypatch, template_id='gitea',+ name='git', image='gitea/gitea:1')+ response = client.get(f'/api/v1/databases/engines/{application.id}/extensions',+ headers=auth_headers)+ assert response.status_code == 404++ def test_unknown_instance_is_404(self, client, auth_headers):+ assert client.get('/api/v1/databases/engines/9999/extensions',+ headers=auth_headers).status_code == 404+++# ── THE image problem ────────────────────────────────────────────────────────+class TestTheImageProblem:+ """`CREATE EXTENSION vector` is correct SQL that fails on stock postgres.++ Every test here exists so that failure can never be silent:++ ERROR: could not open extension control file+ "/usr/share/postgresql/16/extension/vector.control"+ """++ def test_stock_postgres_is_marked_incompatible_before_anything_is_clicked(+ self, client, auth_headers, tmp_path, monkeypatch):+ application = _install_engine(tmp_path, monkeypatch, image='postgres:16-alpine')+ data = client.get(f'/api/v1/databases/engines/{application.id}/extensions',+ headers=auth_headers).get_json()+ entry = next(e for e in data['extensions'] if e['id'] == 'pgvector')+ assert entry['status'] == ext.STATUS_IMAGE_UNSUPPORTED+ assert 'postgres:16-alpine' in entry['reason']+ assert entry['remedy']['suggested_image'] == 'pgvector/pgvector:pg16'+ assert entry['remedy']['required_images'] == ['pgvector/pgvector']++ def test_the_remedy_names_an_engine_template_that_can_host_it(+ self, client, auth_headers, tmp_path, monkeypatch):+ """Discovered by matching images, not by naming a template in Python."""+ application = _install_engine(tmp_path, monkeypatch, image='postgres:16-alpine')+ data = client.get(f'/api/v1/databases/engines/{application.id}/extensions',+ headers=auth_headers).get_json()+ remedy = next(e for e in data['extensions'] if e['id'] == 'pgvector')['remedy']+ assert 'postgresql-pgvector' in {h['template_id'] for h in remedy['install_instead']}++ def test_install_refuses_and_never_runs_the_statement(+ self, client, auth_headers, tmp_path, monkeypatch, engine_client):+ """The engine says it cannot load it, so CREATE EXTENSION is not sent."""+ fake = engine_client(available=False)+ application = _install_engine(tmp_path, monkeypatch, image='postgres:16-alpine')+ response = _post(client, auth_headers, application.id,+ extension_id='pgvector', database='shop')+ assert response.status_code == 409+ body = response.get_json()+ assert 'does not ship the extension' in body['error']+ assert body['remedy']['suggested_image'] == 'pgvector/pgvector:pg16'+ assert body['remedy']['install_instead'][0]['image'] == 'pgvector/pgvector'+ # The transport code is the status, not part of the body.+ assert 'status_code' not in body+ assert not fake.ran_create, 'refused installs must not execute the statement'++ def test_a_capable_image_installs(self, client, auth_headers, tmp_path,+ monkeypatch, engine_client):+ fake = engine_client(available=True, installed_version='0.8.0')+ application = _install_engine(tmp_path, monkeypatch,+ template_id='postgresql-pgvector', name='pgv',+ image='pgvector/pgvector:pg16')+ response = _post(client, auth_headers, application.id,+ extension_id='pgvector', database='shop')+ assert response.status_code == 201, response.get_json()+ body = response.get_json()+ assert body['status'] == ext.STATUS_INSTALLED+ assert body['statement'] == 'CREATE EXTENSION IF NOT EXISTS vector;'+ assert body['database'] == 'shop'+ assert body['extension']['version'] == '0.8.0'+ assert fake.ran_create++ def test_the_engine_overrules_the_image_name_when_it_says_yes(+ self, client, auth_headers, tmp_path, monkeypatch, engine_client):+ """An operator's own build is not punished for an unfamiliar name.++ The probe is authoritative in both directions; this is the direction+ that keeps the image list from becoming a false blocker.+ """+ fake = engine_client(available=True, installed_version='0.8.0')+ application = _install_engine(tmp_path, monkeypatch,+ image='registry.internal/ops/pg-with-vector:16')+ response = _post(client, auth_headers, application.id, extension_id='pgvector')+ assert response.status_code == 201, response.get_json()+ assert fake.ran_create++ def test_the_engine_overrules_the_image_name_when_it_says_no(+ self, client, auth_headers, tmp_path, monkeypatch, engine_client):+ """...and a matching name is not a licence to skip the check.++ A ``pgvector/pgvector`` tag that predates the extension, or a mangled+ image, must still be refused rather than trusted by its name.+ """+ fake = engine_client(available=False)+ application = _install_engine(tmp_path, monkeypatch,+ template_id='postgresql-pgvector', name='pgv',+ image='pgvector/pgvector:pg16')+ response = _post(client, auth_headers, application.id, extension_id='pgvector')+ assert response.status_code == 409+ assert not fake.ran_create++ def test_an_unreachable_engine_does_not_downgrade_a_known_no(+ self, client, auth_headers, tmp_path, monkeypatch, engine_client):+ """A stopped container must not turn "cannot" into "maybe"."""+ engine_client(fail='Error: No such container: pg-main')+ application = _install_engine(tmp_path, monkeypatch, image='postgres:16-alpine')+ response = _post(client, auth_headers, application.id, extension_id='pgvector')+ assert response.status_code == 409+ assert response.get_json()['status'] == ext.STATUS_IMAGE_UNSUPPORTED++ def test_an_unreachable_capable_engine_is_reported_as_unreachable(+ self, client, auth_headers, tmp_path, monkeypatch, engine_client):+ """Not a 409 with a remedy: the image is fine, the engine is down."""+ fake = engine_client(fail='Error: No such container: pgv')+ application = _install_engine(tmp_path, monkeypatch,+ template_id='postgresql-pgvector', name='pgv',+ image='pgvector/pgvector:pg16')+ response = _post(client, auth_headers, application.id, extension_id='pgvector')+ assert response.status_code == 502+ assert 'Could not reach' in response.get_json()['error']+ assert not fake.ran_create++ def test_a_rejected_statement_surfaces_the_engines_own_error(+ self, client, auth_headers, tmp_path, monkeypatch, monkeypatch_free=None):+ """If it fails anyway, the operator sees why — not a generic failure."""+ control_file_error = ('ERROR: could not open extension control file '+ '"/usr/share/postgresql/16/extension/vector.control"')++ def executor(context, sql, database):+ if 'pg_available_extensions' in sql:+ return {'success': True, 'output': '1\n'}+ return {'success': False, 'error': control_file_error}++ monkeypatch.setitem(ext.EXECUTORS, 'postgresql', executor)+ application = _install_engine(tmp_path, monkeypatch,+ template_id='postgresql-pgvector', name='pgv',+ image='pgvector/pgvector:pg16')+ response = _post(client, auth_headers, application.id, extension_id='pgvector')+ assert response.status_code == 400+ assert 'control file' in response.get_json()['error']++ def test_timescaledb_has_no_bundled_host_and_says_so(self, client, auth_headers,+ tmp_path, monkeypatch):+ """We ship no timescale image, and the catalog is honest about it."""+ _install_engine(tmp_path, monkeypatch, image='postgres:16-alpine')+ data = client.get('/api/v1/databases/engines/extensions',+ headers=auth_headers).get_json()+ entry = next(e for e in data['extensions'] if e['id'] == 'timescaledb')+ assert entry['hosts'], 'postgres engines can still host it in principle'+ assert entry['provided_by'] == [], 'no bundled engine ships timescaledb'+ assert entry['compatible_instances'] == []+++class TestImageReferenceMatching:+ """The image comparison itself — five spellings of the same image."""++ @pytest.mark.parametrize('image', [+ 'pgvector/pgvector:pg16',+ 'pgvector/pgvector',+ 'docker.io/pgvector/pgvector:pg16',+ 'pgvector/pgvector@sha256:' + 'a' * 64,+ 'registry.example.com:5000/pgvector/pgvector:pg16',+ ])+ def test_equivalent_references_match(self, image):+ assert ext._image_provides(image, ['pgvector/pgvector']) is True++ @pytest.mark.parametrize('image', ['postgres:16-alpine', 'postgres', 'mysql:8'])+ def test_unrelated_images_do_not_match(self, image):+ assert ext._image_provides(image, ['pgvector/pgvector']) is False++ def test_an_unresolvable_image_is_not_a_no(self):+ """Unknown is a third answer, so we never claim an image cannot host it."""+ assert ext._image_provides(None, ['pgvector/pgvector']) is None++ def test_no_declared_images_means_no_image_claim(self):+ assert ext._image_provides('anything:1', []) is True++ def test_image_is_read_from_the_rendered_compose(self, app, tmp_path, monkeypatch):+ application = _install_engine(tmp_path, monkeypatch, image='postgres:15-alpine')+ assert ext.instance_image(application) == 'postgres:15-alpine'+++# ── rejection paths ──────────────────────────────────────────────────────────+class TestRejections:++ def test_unknown_extension_is_404(self, client, auth_headers, tmp_path,+ monkeypatch, engine_client):+ fake = engine_client(available=True)+ application = _install_engine(tmp_path, monkeypatch)+ response = _post(client, auth_headers, application.id,+ extension_id='definitely-not-an-extension')+ assert response.status_code == 404+ body = response.get_json()+ assert 'Unknown extension' in body['error']+ assert 'pgvector' in body['available']+ assert not fake.statements++ def test_extension_id_is_required(self, client, auth_headers, tmp_path, monkeypatch):+ application = _install_engine(tmp_path, monkeypatch)+ assert _post(client, auth_headers, application.id).status_code == 404++ def test_unknown_instance_is_404(self, client, auth_headers):+ assert _post(client, auth_headers, 4242, extension_id='pgvector').status_code == 404++ def test_a_bad_database_name_is_refused(self, client, auth_headers, tmp_path,+ monkeypatch, engine_client):+ fake = engine_client(available=True)+ application = _install_engine(tmp_path, monkeypatch,+ template_id='postgresql-pgvector', name='pgv',+ image='pgvector/pgvector:pg16')+ response = _post(client, auth_headers, application.id,+ extension_id='pgvector', database='shop; DROP DATABASE x')+ assert response.status_code == 400+ assert not fake.statements++ def test_the_statement_comes_from_the_yaml_not_the_request(+ self, client, auth_headers, tmp_path, monkeypatch, engine_client):+ """A caller cannot smuggle SQL through this route."""+ fake = engine_client(available=True, installed_version='0.8.0')+ application = _install_engine(tmp_path, monkeypatch,+ template_id='postgresql-pgvector', name='pgv',+ image='pgvector/pgvector:pg16')+ response = client.post(+ f'/api/v1/databases/engines/{application.id}/extensions',+ json={'extension_id': 'pgvector', 'statement': 'DROP DATABASE shop;'},+ headers=auth_headers)+ assert response.status_code == 201+ assert not any('DROP DATABASE' in sql for sql, _ in fake.statements)+++class TestAdminOnly:+ """Mutations are admin-only, matching the engine install route."""++ def test_install_rejects_a_non_admin(self, client, viewer_headers, tmp_path,+ monkeypatch, engine_client):+ fake = engine_client(available=True)+ application = _install_engine(tmp_path, monkeypatch,+ template_id='postgresql-pgvector', name='pgv',+ image='pgvector/pgvector:pg16')+ response = _post(client, viewer_headers, application.id, extension_id='pgvector')+ assert response.status_code == 403+ assert not fake.statements++ def test_install_rejects_anonymous(self, client, tmp_path, monkeypatch):+ application = _install_engine(tmp_path, monkeypatch)+ assert _post(client, {}, application.id, extension_id='pgvector').status_code == 401++ def test_reading_the_catalog_requires_auth(self, client):+ assert client.get('/api/v1/databases/engines/extensions').status_code == 401++ def test_reading_the_catalog_does_not_require_admin(self, client, viewer_headers):+ assert client.get('/api/v1/databases/engines/extensions',+ headers=viewer_headers).status_code == 200+++# ── the engine listing carries them too ──────────────────────────────────────+class TestEngineListingIncludesExtensions:++ def test_the_engine_catalog_response_carries_extensions(self, client, auth_headers):+ """One round trip for the drawer, which renders both."""+ data = client.get('/api/v1/databases/engines', headers=auth_headers).get_json()+ assert {'pgvector', 'timescaledb'} <= {e['id'] for e in data['extensions']}+ assert data['extension_family'] == 'Extension'++ def test_extensions_do_not_pollute_the_engine_family_filter(self, client, auth_headers):+ """`families` stays what it was: the families engines actually have."""+ data = client.get('/api/v1/databases/engines', headers=auth_headers).get_json()+ assert 'Extension' not in data['families']++ def test_extensions_are_not_in_the_engine_catalog(self, client, auth_headers):+ data = client.get('/api/v1/databases/engines', headers=auth_headers).get_json()+ assert 'pgvector' not in {e['id'] for e in data['catalog']}+++# ── probing ──────────────────────────────────────────────────────────────────+class TestProbing:++ def test_probe_reports_what_is_already_installed(+ self, client, auth_headers, tmp_path, monkeypatch, engine_client):+ engine_client(available=True, installed_version='0.8.0')+ application = _install_engine(tmp_path, monkeypatch,+ template_id='postgresql-pgvector', name='pgv',+ image='pgvector/pgvector:pg16')+ data = client.get(+ f'/api/v1/databases/engines/{application.id}/extensions?probe=true',+ headers=auth_headers).get_json()+ entry = next(e for e in data['extensions'] if e['id'] == 'pgvector')+ assert data['probed'] is True+ assert entry['status'] == ext.STATUS_INSTALLED+ assert entry['installed_version'] == '0.8.0'++ def test_probe_reports_ready_when_available_but_absent(+ self, client, auth_headers, tmp_path, monkeypatch, engine_client):+ engine_client(available=True, installed_version='')+ application = _install_engine(tmp_path, monkeypatch,+ template_id='postgresql-pgvector', name='pgv',+ image='pgvector/pgvector:pg16')+ data = client.get(+ f'/api/v1/databases/engines/{application.id}/extensions?probe=true',+ headers=auth_headers).get_json()+ entry = next(e for e in data['extensions'] if e['id'] == 'pgvector')+ assert entry['status'] == ext.STATUS_READY+ assert entry['installed_version'] is None++ def test_not_probing_costs_no_engine_calls(+ self, client, auth_headers, tmp_path, monkeypatch, engine_client):+ fake = engine_client(available=True)+ application = _install_engine(tmp_path, monkeypatch,+ template_id='postgresql-pgvector', name='pgv',+ image='pgvector/pgvector:pg16')+ client.get(f'/api/v1/databases/engines/{application.id}/extensions',+ headers=auth_headers)+ assert not fake.statements