Skip to content

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.

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.py
index 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, request
from flask_jwt_extended import get_jwt_identity, jwt_required
from app.middleware.rbac import admin_required
+from app.services import database_engine_extension_service as extensions
from app.services import database_engine_service as engines
from app.services.deployment_job_service import DeploymentJobService
+from app.services.template_service import TemplateService
logger = 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), 201
diff --git a/backend/app/api/templates.py b/backend/app/api/templates.py
index 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), 200
diff --git a/backend/app/services/database_engine_extension_service.py b/backend/app/services/database_engine_extension_service.py
new file mode 100644
index 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.py
index 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)}
+
@staticmethod
def 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.py
index 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 logging
import re
import secrets
-import subprocess
from datetime import datetime
from app import db
@@ -60,24 +59,14 @@ class ManagedDbUserService:
@staticmethod
def _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 ──
@staticmethod
diff --git a/backend/app/services/template_service.py b/backend/app/services/template_service.py
index ef643d34..a6613b24 100644
--- a/backend/app/services/template_service.py
+++ b/backend/app/services/template_service.py
@@ -196,6 +196,8 @@ class TemplateService:
raise ValueError
except (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
+
@classmethod
def parse_template(cls, template_path: str) -> Dict:
"""Parse a template file."""
diff --git a/backend/templates/extensions/pgvector.yaml b/backend/templates/extensions/pgvector.yaml
new file mode 100644
index 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.yaml
new file mode 100644
index 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.json
index 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.yaml
new file mode 100644
index 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: 5GB
diff --git a/backend/tests/test_database_engine_extensions.py b/backend/tests/test_database_engine_extensions.py
new file mode 100644
index 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