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): track managed databases as first-class resources

Juan Denis58e80b2e18e6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ce3ffd38..581d47e5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,13 @@ awaiting a stable release:
### Added
+- **Managed databases** — the databases ServerKit provisions are now tracked as
+ first-class resources (beside the existing live explorer): durable rows for
+ backups and connection strings. A managed database backs a `BackupPolicy` by a
+ real foreign key (not an untethered descriptor), one-click "Protect" creates
+ that policy, and a real connection URI can be revealed/copied (audited, secret
+ Fernet-encrypted at rest). Adopt an existing database to start tracking it. API
+ under `/api/v1/databases/managed`. Not a DBaaS — no pooling/replicas/scaling.
- **Per-app managed volumes** — first-class, tracked persistent storage for a
service. Attach a named Docker volume at a chosen container path under
Settings → Storage; it survives redeploys and is visible with live
diff --git a/backend/app/api/databases.py b/backend/app/api/databases.py
index fe081821..9249acf3 100644
--- a/backend/app/api/databases.py
+++ b/backend/app/api/databases.py
@@ -1,13 +1,37 @@
+import logging
+
from flask import Blueprint, request, jsonify
from flask_jwt_extended import jwt_required, get_jwt_identity
from app.models import User, Application
from app.services.database_service import DatabaseService
+from app.services.managed_database_service import ManagedDatabaseService
from app.middleware.rbac import admin_required
from app.services.resource_grant_service import ResourceGrantService
+logger = logging.getLogger(__name__)
+
databases_bp = Blueprint('databases', __name__)
+def _persist_provisioned(engine, name, result, data):
+ """Track a just-provisioned database as a managed resource. Best-effort and
+ additive — a persistence failure never fails the provisioning that succeeded."""
+ try:
+ from app.services.workspace_service import WorkspaceService
+ user = User.query.get(get_jwt_identity())
+ ws_id = WorkspaceService.resolve_workspace_id(
+ user, request.headers.get('X-Workspace-Id') or request.args.get('workspace_id'))
+ ManagedDatabaseService.record_provisioned(
+ engine, name,
+ admin_username=result.get('user'),
+ admin_secret=result.get('password'),
+ owner_application_id=(data or {}).get('application_id'),
+ workspace_id=ws_id,
+ )
+ except Exception as exc: # pragma: no cover - defensive
+ logger.warning('Failed to track provisioned database %s/%s: %s', engine, name, exc)
+
+
# ==================== STATUS ====================
@databases_bp.route('/status', methods=['GET'])
@@ -70,6 +94,8 @@ def create_mysql_database():
result['user'] = data['name']
result['password'] = password
+ _persist_provisioned('mysql', data['name'], result, data)
+
return jsonify(result), 201 if result['success'] else 400
@@ -271,6 +297,8 @@ def create_pg_database():
result['user'] = data['name']
result['password'] = password
+ _persist_provisioned('postgresql', data['name'], result, data)
+
return jsonify(result), 201 if result['success'] else 400
@@ -746,6 +774,151 @@ def execute_docker_query(container, database):
return jsonify(result), 200 if result['success'] else 400
+# ==================== MANAGED DATABASES ====================
+# Durable tracking beside the live introspection above. Listing is available to
+# any authenticated user; mutations + credential reveal are admin-only.
+
+def _workspace_id():
+ from app.services.workspace_service import WorkspaceService
+ user = User.query.get(get_jwt_identity())
+ return WorkspaceService.resolve_workspace_id(
+ user, request.headers.get('X-Workspace-Id') or request.args.get('workspace_id'))
+
+
+@databases_bp.route('/managed', methods=['GET'])
+@jwt_required()
+def list_managed_databases():
+ """List tracked databases (credentials masked)."""
+ rows = ManagedDatabaseService.list(workspace_id=_workspace_id())
+ return jsonify({'databases': [r.to_dict() for r in rows]}), 200
+
+
+@databases_bp.route('/managed', methods=['POST'])
+@jwt_required()
+@admin_required
+def create_managed_database():
+ """Provision a new database (mysql|postgresql) AND track it as managed."""
+ data = request.get_json() or {}
+ engine = (data.get('engine') or '').strip().lower()
+ name = data.get('name')
+ if not name:
+ return jsonify({'error': 'name is required'}), 400
+ if engine not in ('mysql', 'postgresql'):
+ return jsonify({'error': 'engine must be mysql or postgresql'}), 400
+
+ if engine == 'mysql':
+ result = DatabaseService.mysql_create_database(
+ name, data.get('charset', 'utf8mb4'),
+ data.get('collation', 'utf8mb4_unicode_ci'), data.get('root_password'))
+ if result.get('success') and data.get('create_user'):
+ password = data.get('user_password') or DatabaseService.generate_password()
+ DatabaseService.mysql_create_user(name, password, data.get('host', 'localhost'), data.get('root_password'))
+ DatabaseService.mysql_grant_privileges(name, name, 'ALL', data.get('host', 'localhost'), data.get('root_password'))
+ result['user'] = name
+ result['password'] = password
+ else:
+ result = DatabaseService.pg_create_database(name, data.get('owner'), data.get('encoding', 'UTF8'))
+ if result.get('success') and data.get('create_user'):
+ password = data.get('user_password') or DatabaseService.generate_password()
+ DatabaseService.pg_create_user(name, password)
+ DatabaseService.pg_grant_privileges(name, name, 'ALL')
+ result['user'] = name
+ result['password'] = password
+
+ if not result.get('success'):
+ return jsonify(result), 400
+
+ managed = ManagedDatabaseService.record_provisioned(
+ engine, name,
+ admin_username=result.get('user'),
+ admin_secret=result.get('password'),
+ owner_application_id=data.get('application_id'),
+ workspace_id=_workspace_id(),
+ )
+ return jsonify({'database': managed.to_dict()}), 201
+
+
+@databases_bp.route('/managed/adopt', methods=['POST'])
+@jwt_required()
+@admin_required
+def adopt_managed_database():
+ """Track a live-discovered database that isn't tracked yet."""
+ data = request.get_json() or {}
+ engine = (data.get('engine') or '').strip().lower()
+ name = data.get('name')
+ if not name or engine not in ('mysql', 'postgresql', 'mongodb'):
+ return jsonify({'error': 'engine (mysql|postgresql|mongodb) and name are required'}), 400
+ managed = ManagedDatabaseService.adopt(
+ engine, data.get('host', 'localhost'), name,
+ port=data.get('port'),
+ host_kind=data.get('host_kind', 'host'),
+ container_ref=data.get('container_ref'),
+ admin_username=data.get('admin_username'),
+ admin_secret=data.get('admin_secret'),
+ owner_application_id=data.get('application_id'),
+ workspace_id=_workspace_id(),
+ )
+ return jsonify({'database': managed.to_dict()}), 201
+
+
+@databases_bp.route('/managed/<int:managed_id>', methods=['GET'])
+@jwt_required()
+def get_managed_database(managed_id):
+ """Detail + a best-effort live-sync state (does the DB still exist?)."""
+ managed = ManagedDatabaseService.get(managed_id)
+ if not managed:
+ return jsonify({'error': 'Managed database not found'}), 404
+ data = managed.to_dict()
+ data['sync'] = ManagedDatabaseService.sync_state(managed)
+ return jsonify({'database': data}), 200
+
+
+@databases_bp.route('/managed/<int:managed_id>', methods=['DELETE'])
+@jwt_required()
+@admin_required
+def delete_managed_database(managed_id):
+ """Untrack a managed database (optional ``?drop=true`` to also DROP it)."""
+ managed = ManagedDatabaseService.get(managed_id)
+ if not managed:
+ return jsonify({'error': 'Managed database not found'}), 404
+ drop = str(request.args.get('drop', '')).lower() in ('1', 'true', 'yes')
+ ManagedDatabaseService.delete(managed, drop=drop)
+ return jsonify({'success': True, 'dropped': drop}), 200
+
+
+@databases_bp.route('/managed/<int:managed_id>/connection-uri', methods=['POST'])
+@jwt_required()
+@admin_required
+def reveal_managed_connection_uri(managed_id):
+ """Reveal the real connection string (audited)."""
+ from app.models.audit_log import AuditLog
+ from app.services.audit_service import AuditService
+ managed = ManagedDatabaseService.get(managed_id)
+ if not managed:
+ return jsonify({'error': 'Managed database not found'}), 404
+ uri = ManagedDatabaseService.build_connection_uri(managed, reveal=True)
+ AuditService.log(
+ action=getattr(AuditLog, 'ACTION_SECRET_REVEALED', 'secret.revealed'),
+ user_id=get_jwt_identity(),
+ target_type='managed_database', target_id=managed.id,
+ details={'engine': managed.engine, 'name': managed.name},
+ )
+ return jsonify({'connection_uri': uri}), 200
+
+
+@databases_bp.route('/managed/<int:managed_id>/protect', methods=['POST'])
+@jwt_required()
+@admin_required
+def protect_managed_database(managed_id):
+ """Create/refresh a BackupPolicy for a managed database (real FK target)."""
+ managed = ManagedDatabaseService.get(managed_id)
+ if not managed:
+ return jsonify({'error': 'Managed database not found'}), 404
+ data = request.get_json() or {}
+ policy = ManagedDatabaseService.protect(managed, fields=data.get('policy'))
+ return jsonify({'policy': policy.to_dict()}), 201
+
+
# ==================== UTILITY ====================
@databases_bp.route('/generate-password', methods=['GET'])
diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py
index 160637cd..59a7a7b3 100644
--- a/backend/app/models/__init__.py
+++ b/backend/app/models/__init__.py
@@ -31,6 +31,7 @@ from app.models.source_connection import SourceConnection
from app.models.registrar_connection import RegistrarConnection
from app.models.container_registry import ContainerRegistry
from app.models.app_volume import AppVolume
+from app.models.managed_database import ManagedDatabase
from app.models.api_key import ApiKey
from app.models.api_usage import ApiUsageLog, ApiUsageSummary
from app.models.event_subscription import EventSubscription, EventDelivery
@@ -74,7 +75,7 @@ __all__ = [
'WordPressCustomPlugin', 'WordPressSitePlugin',
'EnvironmentActivity', 'PromotionJob', 'SanitizationProfile',
'EmailDomain', 'EmailAccount', 'EmailAlias', 'EmailForwardingRule', 'DNSProviderConfig', 'EmailRelayConfig',
- 'OAuthIdentity', 'SourceConnection', 'RegistrarConnection', 'ContainerRegistry', 'AppVolume', 'ApiKey', 'ApiUsageLog', 'ApiUsageSummary',
+ 'OAuthIdentity', 'SourceConnection', 'RegistrarConnection', 'ContainerRegistry', 'AppVolume', 'ManagedDatabase', 'ApiKey', 'ApiUsageLog', 'ApiUsageSummary',
'EventSubscription', 'EventDelivery', 'Invitation',
'ServerAlertThreshold', 'MetricAlert',
'AgentPlugin', 'AgentPluginInstall',
diff --git a/backend/app/models/managed_database.py b/backend/app/models/managed_database.py
new file mode 100644
index 00000000..63c79f42
--- /dev/null
+++ b/backend/app/models/managed_database.py
@@ -0,0 +1,79 @@
+from datetime import datetime
+
+from app import db
+
+# Engines whose lifecycle ServerKit actually drives (Mongo stays read-first).
+VALID_DB_ENGINES = ('mysql', 'postgresql', 'mongodb')
+
+
+class ManagedDatabase(db.Model):
+ """A database ServerKit tracks as a first-class resource.
+
+ Adds durable state (backups, connection strings, ownership) **beside** the
+ live introspection in ``database_service`` — it does NOT replace that
+ discovery/browse surface. ``origin`` records whether ServerKit provisioned it
+ (``provisioned``) or adopted a live-discovered one (``adopted``).
+
+ The admin secret is Fernet-encrypted at rest (same helper as
+ ``SourceConnection``); it is masked in API responses and revealed only through
+ an explicit, audited action.
+ """
+
+ __tablename__ = 'managed_databases'
+
+ # Default listening ports per engine, used when a row doesn't pin one.
+ DEFAULT_PORTS = {'mysql': 3306, 'postgresql': 5432, 'mongodb': 27017}
+ # URI scheme per engine for build_connection_uri.
+ URI_SCHEMES = {'mysql': 'mysql', 'postgresql': 'postgresql', 'mongodb': 'mongodb'}
+
+ id = db.Column(db.Integer, primary_key=True)
+ engine = db.Column(db.String(20), nullable=False, index=True) # mysql|postgresql|mongodb
+ name = db.Column(db.String(200), nullable=False) # database name on the server
+ host_kind = db.Column(db.String(20), nullable=False, default='host') # host|docker
+ container_ref = db.Column(db.String(200), nullable=True) # container name/id when docker
+ host = db.Column(db.String(255), nullable=False, default='localhost')
+ port = db.Column(db.Integer, nullable=True)
+ # The app this DB backs, if any. SET NULL on app delete so the tracked DB
+ # survives its app being removed.
+ owner_application_id = db.Column(
+ db.Integer, db.ForeignKey('applications.id', ondelete='SET NULL'),
+ nullable=True, index=True,
+ )
+ origin = db.Column(db.String(20), nullable=False, default='provisioned') # provisioned|adopted
+ admin_username = db.Column(db.String(180), nullable=True)
+ admin_secret_encrypted = db.Column(db.Text, nullable=True)
+ workspace_id = db.Column(db.Integer, db.ForeignKey('workspaces.id'), nullable=True, index=True)
+ created_at = db.Column(db.DateTime, default=datetime.utcnow, index=True)
+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+ __table_args__ = (
+ db.UniqueConstraint('engine', 'host', 'name', name='uq_managed_database'),
+ )
+
+ def effective_port(self):
+ return self.port or self.DEFAULT_PORTS.get(self.engine)
+
+ def to_dict(self, connection_uri=None):
+ data = {
+ 'id': self.id,
+ 'engine': self.engine,
+ 'name': self.name,
+ 'host_kind': self.host_kind,
+ 'container_ref': self.container_ref,
+ 'host': self.host,
+ 'port': self.effective_port(),
+ 'owner_application_id': self.owner_application_id,
+ 'origin': self.origin,
+ 'admin_username': self.admin_username,
+ # Never serialize the secret — expose only whether one is stored.
+ 'has_secret': bool(self.admin_secret_encrypted),
+ 'workspace_id': self.workspace_id,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,
+ }
+ if connection_uri is not None:
+ data['connection_uri'] = connection_uri
+ return data
+
+ def __repr__(self):
+ return f'<ManagedDatabase {self.engine}:{self.name}@{self.host}>'
diff --git a/backend/app/services/backup_policy_service.py b/backend/app/services/backup_policy_service.py
index def9fe79..59ad8d49 100644
--- a/backend/app/services/backup_policy_service.py
+++ b/backend/app/services/backup_policy_service.py
@@ -220,6 +220,21 @@ class BackupPolicyService:
if policy.target_type == 'database':
meta = policy.get_target_meta()
+ # Managed database: target_id is a real FK into managed_databases and
+ # the descriptor (incl. the encrypted admin secret) lives on the row.
+ # Legacy policies have no 'managed' marker and keep the JSON path below.
+ if meta.get('managed'):
+ from app.models.managed_database import ManagedDatabase
+ from app.services.managed_database_service import ManagedDatabaseService
+ managed = ManagedDatabase.query.get(policy.target_id)
+ if managed is None:
+ raise BackupPolicyError('Managed database is no longer tracked')
+ return {
+ 'name': managed.name, 'root_path': None,
+ 'target_type': 'database', 'site': None, 'app': None,
+ 'managed_db': managed,
+ 'db_config': ManagedDatabaseService.backup_descriptor(managed),
+ }
db_name = meta.get('db_name')
if not db_name:
raise BackupPolicyError('Database target is missing db_name')
diff --git a/backend/app/services/managed_database_service.py b/backend/app/services/managed_database_service.py
new file mode 100644
index 00000000..0444a88b
--- /dev/null
+++ b/backend/app/services/managed_database_service.py
@@ -0,0 +1,186 @@
+"""Managed-database persistence — the thin, durable layer under the databases
+ServerKit provisions.
+
+The Databases feature is otherwise 100% live introspection (``database_service``
+runs ``SHOW DATABASES`` / ``SELECT datname …``). This service **adds** a tracked
+``managed_databases`` row beside that introspection (it does not replace it) so
+backups, connection strings, and the UI have durable state to hang off. It is
+NOT a DBaaS: no pooling, replicas, scaling, or failover.
+
+Headline payoff: a ``BackupPolicy`` targeting a managed database gets a **real
+FK** (``target_id = managed_databases.id`` + a ``managed`` marker in
+``target_meta_json``) instead of an arbitrary int, while legacy JSON-descriptor
+policies keep working unchanged.
+"""
+import logging
+
+from app import db
+from app.models.managed_database import ManagedDatabase
+from app.services.database_service import DatabaseService
+from app.utils.crypto import encrypt_secret, decrypt_secret_safe
+
+logger = logging.getLogger(__name__)
+
+# db_type strings understood by the backup executor / database_service.
+_ENGINE_TO_DBTYPE = {'mysql': 'mysql', 'postgresql': 'postgresql', 'mongodb': 'mongodb'}
+
+
+class ManagedDatabaseService:
+ """CRUD + connection-string + backup-wiring for tracked databases."""
+
+ # ── persistence ──
+ @classmethod
+ def _upsert(cls, engine, name, host='localhost', *, origin, port=None,
+ host_kind='host', container_ref=None, owner_application_id=None,
+ admin_username=None, admin_secret=None, workspace_id=None):
+ """Find-or-create a row keyed by (engine, host, name), refreshing the
+ mutable descriptors. ``origin`` is only set on creation — adopting a row
+ ServerKit already provisioned never downgrades its origin."""
+ engine = (engine or '').strip().lower()
+ host = (host or 'localhost').strip() or 'localhost'
+ managed = ManagedDatabase.query.filter_by(engine=engine, host=host, name=name).first()
+ created = managed is None
+ if created:
+ managed = ManagedDatabase(engine=engine, name=name, host=host, origin=origin)
+ db.session.add(managed)
+
+ if port is not None:
+ managed.port = port
+ if host_kind:
+ managed.host_kind = host_kind
+ if container_ref is not None:
+ managed.container_ref = container_ref
+ if owner_application_id is not None:
+ managed.owner_application_id = owner_application_id
+ if admin_username is not None:
+ managed.admin_username = admin_username
+ if admin_secret:
+ managed.admin_secret_encrypted = encrypt_secret(admin_secret)
+ if workspace_id is not None:
+ managed.workspace_id = workspace_id
+
+ db.session.commit()
+ return managed
+
+ @classmethod
+ def record_provisioned(cls, engine, name, **kwargs):
+ """Persist a DB ServerKit just created (``origin='provisioned'``).
+ Additive: called after the SQL provisioning succeeds, never blocks it."""
+ return cls._upsert(engine, name, origin='provisioned', **kwargs)
+
+ @classmethod
+ def adopt(cls, engine, host, name, **kwargs):
+ """Track a live-discovered database (``origin='adopted'``). Idempotent —
+ adopting an already-tracked DB just refreshes its descriptors."""
+ return cls._upsert(engine, name, host=host, origin='adopted', **kwargs)
+
+ @classmethod
+ def list(cls, workspace_id=None):
+ q = ManagedDatabase.query
+ if workspace_id is not None:
+ q = q.filter(db.or_(
+ ManagedDatabase.workspace_id == workspace_id,
+ ManagedDatabase.workspace_id.is_(None),
+ ))
+ return q.order_by(ManagedDatabase.created_at.desc()).all()
+
+ @classmethod
+ def get(cls, managed_id):
+ if not managed_id:
+ return None
+ return ManagedDatabase.query.get(managed_id)
+
+ @classmethod
+ def delete(cls, managed, drop=False):
+ """Untrack a managed database. With ``drop=True`` also DROP it on the
+ server (host engines only). Any managed BackupPolicy pointing at it is
+ removed so no policy is left dangling."""
+ if drop and managed.host_kind == 'host':
+ if managed.engine == 'mysql':
+ DatabaseService.mysql_drop_database(managed.name)
+ elif managed.engine == 'postgresql':
+ DatabaseService.pg_drop_database(managed.name)
+ # mongodb drop is out of scope (read-first); untrack only.
+
+ cls._delete_managed_policy(managed)
+ db.session.delete(managed)
+ db.session.commit()
+
+ # ── connection string ──
+ @classmethod
+ def build_connection_uri(cls, managed, user=None, reveal=False):
+ """The real DB connection URI the codebase otherwise lacks:
+ ``mysql://user:***@host:port/name`` (password masked unless ``reveal``)."""
+ scheme = ManagedDatabase.URI_SCHEMES.get(managed.engine, managed.engine)
+ username = user or managed.admin_username
+ password = None
+ if managed.admin_secret_encrypted:
+ password = decrypt_secret_safe(managed.admin_secret_encrypted) if reveal else '***'
+
+ userinfo = ''
+ if username:
+ userinfo = username
+ if password is not None:
+ userinfo += f':{password}'
+ userinfo += '@'
+
+ port = managed.effective_port()
+ hostport = managed.host + (f':{port}' if port else '')
+ return f'{scheme}://{userinfo}{hostport}/{managed.name}'
+
+ # ── live reconciliation ──
+ @classmethod
+ def sync_state(cls, managed):
+ """Best-effort reconcile against live state. Returns
+ ``{'exists': bool|None, 'drifted': bool}``. ``exists=None`` means we
+ couldn't determine it (docker/mongo) — not treated as drift."""
+ exists = None
+ try:
+ if managed.host_kind == 'host' and managed.engine == 'mysql':
+ names = [d.get('name') for d in DatabaseService.mysql_list_databases()]
+ exists = managed.name in names
+ elif managed.host_kind == 'host' and managed.engine == 'postgresql':
+ names = [d.get('name') for d in DatabaseService.pg_list_databases()]
+ exists = managed.name in names
+ except Exception as e: # pragma: no cover - defensive
+ logger.debug('sync_state failed for %s: %s', managed.name, e)
+ exists = None
+ return {'exists': exists, 'drifted': exists is False}
+
+ # ── backup wiring (the headline) ──
+ @classmethod
+ def backup_descriptor(cls, managed):
+ """The ``db_config`` the backup executor expects, resolved from the row."""
+ return {
+ 'db_type': _ENGINE_TO_DBTYPE.get(managed.engine, managed.engine),
+ 'db_name': managed.name,
+ 'user': managed.admin_username,
+ 'password': decrypt_secret_safe(managed.admin_secret_encrypted or '') or None,
+ 'host': managed.host,
+ }
+
+ @classmethod
+ def protect(cls, managed, fields=None):
+ """Create/refresh a BackupPolicy for this managed DB with a **real FK**
+ (``target_id = managed.id``) plus a ``managed`` marker so the executor
+ resolves the descriptor from the row (not a free-floating JSON blob)."""
+ from app.services.backup_policy_service import BackupPolicyService
+ policy = BackupPolicyService.get_or_create_policy(
+ target_type='database',
+ target_id=managed.id,
+ target_subtype=managed.engine,
+ target_meta={'managed': True, 'db_name': managed.name,
+ 'db_type': _ENGINE_TO_DBTYPE.get(managed.engine, managed.engine),
+ 'host': managed.host},
+ )
+ if fields:
+ policy = BackupPolicyService.update_policy(policy, fields)
+ return policy
+
+ @staticmethod
+ def _delete_managed_policy(managed):
+ """Remove the managed BackupPolicy for a DB being untracked, if any."""
+ from app.models.backup_policy import BackupPolicy
+ policy = BackupPolicy.query.filter_by(target_type='database', target_id=managed.id).first()
+ if policy is not None and policy.get_target_meta().get('managed'):
+ db.session.delete(policy)
diff --git a/backend/migrations/versions/044_managed_databases.py b/backend/migrations/versions/044_managed_databases.py
new file mode 100644
index 00000000..1d3de02c
--- /dev/null
+++ b/backend/migrations/versions/044_managed_databases.py
@@ -0,0 +1,62 @@
+"""Managed databases.
+
+Adds:
+- managed_databases (durable tracking of provisioned/adopted databases so
+ BackupPolicy target_id='database' has a real FK and connection strings have a
+ home; live introspection is unchanged)
+
+Idempotent: MigrationService runs _fix_missing_columns() + db.create_all() on boot
+before Alembic, so guard on the live schema.
+
+Revision ID: 044_managed_databases
+Revises: 043_app_volumes
+Create Date: 2026-07-01
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = '044_managed_databases'
+down_revision = '043_app_volumes'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ existing = set(inspector.get_table_names())
+
+ if 'managed_databases' not in existing:
+ op.create_table(
+ 'managed_databases',
+ sa.Column('id', sa.Integer, nullable=False),
+ sa.Column('engine', sa.String(20), nullable=False),
+ sa.Column('name', sa.String(200), nullable=False),
+ sa.Column('host_kind', sa.String(20), nullable=False, server_default='host'),
+ sa.Column('container_ref', sa.String(200), nullable=True),
+ sa.Column('host', sa.String(255), nullable=False, server_default='localhost'),
+ sa.Column('port', sa.Integer, nullable=True),
+ sa.Column('owner_application_id', sa.Integer, nullable=True),
+ sa.Column('origin', sa.String(20), nullable=False, server_default='provisioned'),
+ sa.Column('admin_username', sa.String(180), nullable=True),
+ sa.Column('admin_secret_encrypted', sa.Text, nullable=True),
+ sa.Column('workspace_id', sa.Integer, nullable=True),
+ sa.Column('created_at', sa.DateTime, nullable=True),
+ sa.Column('updated_at', sa.DateTime, nullable=True),
+ sa.PrimaryKeyConstraint('id'),
+ sa.ForeignKeyConstraint(['owner_application_id'], ['applications.id'], ondelete='SET NULL'),
+ sa.ForeignKeyConstraint(['workspace_id'], ['workspaces.id']),
+ sa.UniqueConstraint('engine', 'host', 'name', name='uq_managed_database'),
+ )
+ op.create_index('ix_managed_databases_engine', 'managed_databases', ['engine'])
+ op.create_index('ix_managed_databases_owner_application_id', 'managed_databases', ['owner_application_id'])
+ op.create_index('ix_managed_databases_workspace_id', 'managed_databases', ['workspace_id'])
+ op.create_index('ix_managed_databases_created_at', 'managed_databases', ['created_at'])
+
+
+def downgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ existing = set(inspector.get_table_names())
+ if 'managed_databases' in existing:
+ op.drop_table('managed_databases')
diff --git a/backend/tests/test_managed_database.py b/backend/tests/test_managed_database.py
new file mode 100644
index 00000000..ac4b095b
--- /dev/null
+++ b/backend/tests/test_managed_database.py
@@ -0,0 +1,168 @@
+"""Managed database resource — service, backup FK wiring, and API.
+
+Covers the proving points from docs/plans/MANAGED_DATABASE_RESOURCE.md:
+- provisioning persists a row; adopt is idempotent
+- build_connection_uri is correct per engine and masks the secret by default
+- sync_state flags a dropped-but-tracked DB as drifted
+- a BackupPolicy for a managed DB resolves its descriptor from the row (real FK),
+ while a legacy JSON-descriptor policy still resolves unchanged
+- API masking, admin-gating, and an audited connection-uri reveal
+"""
+import pytest
+
+from app import db
+from app.models import ManagedDatabase, User
+from app.services.managed_database_service import ManagedDatabaseService
+from app.services.database_service import DatabaseService
+
+
+def managed(app):
+ return ManagedDatabaseService.record_provisioned(
+ 'mysql', 'shop', host='localhost', port=3306,
+ admin_username='shop_user', admin_secret='s3cr3t',
+ )
+
+
+# ── persistence ──────────────────────────────────────────────────────────────
+
+def test_record_provisioned_persists_row(app, managed):
+ assert managed.id is not None
+ assert managed.origin == 'provisioned'
+ assert managed.engine == 'mysql' and managed.name == 'shop'
+ assert managed.admin_secret_encrypted and managed.admin_secret_encrypted != 's3cr3t'
+
+
+def test_adopt_is_idempotent(app):
+ a = ManagedDatabaseService.adopt('postgresql', 'localhost', 'analytics')
+ b = ManagedDatabaseService.adopt('postgresql', 'localhost', 'analytics', admin_username='pg')
+ assert a.id == b.id # same row
+ assert ManagedDatabase.query.filter_by(name='analytics').count() == 1
+ assert b.admin_username == 'pg' # refreshed descriptor
+ assert b.origin == 'adopted'
+
+
+def test_provisioned_then_adopt_keeps_origin(app, managed):
+ again = ManagedDatabaseService.adopt('mysql', 'localhost', 'shop')
+ assert again.id == managed.id
+ assert again.origin == 'provisioned' # not downgraded to adopted
+
+
+# ── connection URI ───────────────────────────────────────────────────────────
+
+def test_connection_uri_masks_secret_by_default(app, managed):
+ uri = ManagedDatabaseService.build_connection_uri(managed)
+ assert uri == 'mysql://shop_user:***@localhost:3306/shop'
+ assert 's3cr3t' not in uri
+
+
+def test_connection_uri_reveal_includes_secret(app, managed):
+ uri = ManagedDatabaseService.build_connection_uri(managed, reveal=True)
+ assert uri == 'mysql://shop_user:s3cr3t@localhost:3306/shop'
+
+
+def test_connection_uri_postgres_scheme_and_default_port(app):
+ m = ManagedDatabaseService.record_provisioned('postgresql', 'reports',
+ admin_username='u', admin_secret='pw')
+ uri = ManagedDatabaseService.build_connection_uri(m)
+ assert uri == 'postgresql://u:***@localhost:5432/reports' # default port filled, secret masked
+
+
+# ── sync_state ───────────────────────────────────────────────────────────────
+
+def test_sync_state_flags_dropped_db_as_drifted(app, managed, monkeypatch):
+ monkeypatch.setattr(DatabaseService, 'mysql_list_databases',
+ staticmethod(lambda *a, **k: [{'name': 'other'}]))
+ state = ManagedDatabaseService.sync_state(managed)
+ assert state['exists'] is False and state['drifted'] is True
+
+
+def test_sync_state_present_db_not_drifted(app, managed, monkeypatch):
+ monkeypatch.setattr(DatabaseService, 'mysql_list_databases',
+ staticmethod(lambda *a, **k: [{'name': 'shop'}]))
+ state = ManagedDatabaseService.sync_state(managed)
+ assert state['exists'] is True and state['drifted'] is False
+
+
+# ── backup FK wiring (the headline) ──────────────────────────────────────────
+
+def test_protect_creates_policy_with_real_fk(app, managed):
+ from app.services.backup_policy_service import BackupPolicyService
+ policy = ManagedDatabaseService.protect(managed)
+ assert policy.target_type == 'database'
+ assert policy.target_id == managed.id # real FK, not an arbitrary int
+ assert policy.get_target_meta().get('managed') is True
+
+ # The executor resolves the descriptor from the ROW (incl. decrypted secret).
+ target = BackupPolicyService._resolve_target(policy)
+ assert target['managed_db'].id == managed.id
+ cfg = target['db_config']
+ assert cfg['db_type'] == 'mysql' and cfg['db_name'] == 'shop'
+ assert cfg['user'] == 'shop_user' and cfg['password'] == 's3cr3t'
+
+
+def test_legacy_json_descriptor_policy_still_resolves(app):
+ """A pre-existing database policy (no managed marker) resolves from
+ target_meta_json exactly as before — the change is backward compatible."""
+ from app.models.backup_policy import BackupPolicy
+ from app.services.backup_policy_service import BackupPolicyService
+ policy = BackupPolicy(target_type='database', target_id=98765, target_subtype='mysql')
+ policy.set_target_meta({'db_name': 'legacy_db', 'db_type': 'mysql',
+ 'user': 'legacy', 'password': 'pw', 'host': 'localhost'})
+ db.session.add(policy)
+ db.session.commit()
+
+ target = BackupPolicyService._resolve_target(policy)
+ assert 'managed_db' not in target
+ assert target['db_config']['db_name'] == 'legacy_db'
+ assert target['db_config']['user'] == 'legacy'
+
+
+def test_untrack_removes_managed_policy(app, managed):
+ from app.models.backup_policy import BackupPolicy
+ ManagedDatabaseService.protect(managed)
+ assert BackupPolicy.query.filter_by(target_type='database', target_id=managed.id).count() == 1
+ ManagedDatabaseService.delete(managed, drop=False)
+ assert BackupPolicy.query.filter_by(target_type='database', target_id=managed.id).count() == 0
+ assert ManagedDatabase.query.get(managed.id) is None
+
+
+# ── API ──────────────────────────────────────────────────────────────────────
+
+def test_api_list_masks_secret(client, auth_headers, app, managed):
+ resp = client.get('/api/v1/databases/managed', headers=auth_headers)
+ assert resp.status_code == 200
+ rows = resp.get_json()['databases']
+ assert any(r['name'] == 'shop' for r in rows)
+ for r in rows:
+ assert 'admin_secret_encrypted' not in r and 'secret' not in r
+ assert 'has_secret' in r
+
+
+def test_api_connection_uri_reveal_is_audited(client, auth_headers, app, managed):
+ from app.models.audit_log import AuditLog
+ before = AuditLog.query.count()
+ resp = client.post(f'/api/v1/databases/managed/{managed.id}/connection-uri', headers=auth_headers)
+ assert resp.status_code == 200
+ assert resp.get_json()['connection_uri'] == 'mysql://shop_user:s3cr3t@localhost:3306/shop'
+ assert AuditLog.query.count() == before + 1 # reveal emitted an audit row
+
+
+def test_api_adopt_requires_admin(client, app):
+ from flask_jwt_extended import create_access_token
+ from werkzeug.security import generate_password_hash
+ dev = User(email='[email protected]', username='dbdev',
+ password_hash=generate_password_hash('x'),
+ role=User.ROLE_DEVELOPER, is_active=True)
+ db.session.add(dev)
+ db.session.commit()
+ headers = {'Authorization': f'Bearer {create_access_token(identity=dev.id)}'}
+ resp = client.post('/api/v1/databases/managed/adopt', headers=headers,
+ json={'engine': 'mysql', 'name': 'x'})
+ assert resp.status_code == 403
+
+
+def test_api_untrack(client, auth_headers, app, managed):
+ resp = client.delete(f'/api/v1/databases/managed/{managed.id}', headers=auth_headers)
+ assert resp.status_code == 200
+ assert ManagedDatabase.query.get(managed.id) is None
diff --git a/frontend/src/components/databases/ManagedDatabasesPanel.jsx b/frontend/src/components/databases/ManagedDatabasesPanel.jsx
new file mode 100644
index 00000000..1c2d0717
--- /dev/null
+++ b/frontend/src/components/databases/ManagedDatabasesPanel.jsx
@@ -0,0 +1,138 @@
+import { useState, useEffect, useCallback } from 'react';
+import { Copy, ShieldCheck, Trash2, RefreshCw, Link2 } from 'lucide-react';
+import api from '../../services/api';
+import { useToast } from '../../contexts/ToastContext';
+import { useConfirm } from '../../hooks/useConfirm';
+import { Button } from '@/components/ui/button';
+import { Pill } from '../ds';
+
+// Durable list of the databases ServerKit tracks (provisioned or adopted),
+// beside the live explorer. Reveal/copy a real connection string (audited),
+// protect it with a backup policy (real FK), or untrack/drop it.
+export default function ManagedDatabasesPanel() {
+ const toast = useToast();
+ const { confirm } = useConfirm();
+ const [rows, setRows] = useState([]);
+ const [loading, setLoading] = useState(true);
+ const [busyId, setBusyId] = useState(null);
+
+ const load = useCallback(async () => {
+ setLoading(true);
+ try {
+ const data = await api.getManagedDatabases();
+ setRows(data?.databases || []);
+ } catch (err) {
+ toast.error(err.message || 'Failed to load managed databases');
+ } finally {
+ setLoading(false);
+ }
+ }, [toast]);
+
+ useEffect(() => { load(); }, [load]);
+
+ async function copyConnectionUri(row) {
+ setBusyId(row.id);
+ try {
+ const data = await api.revealManagedConnectionUri(row.id);
+ const uri = data?.connection_uri;
+ if (uri && navigator.clipboard) {
+ await navigator.clipboard.writeText(uri);
+ toast.success('Connection string copied (reveal was audited)');
+ } else if (uri) {
+ toast.info(uri);
+ }
+ } catch (err) {
+ toast.error(err.message || 'Failed to reveal connection string');
+ } finally {
+ setBusyId(null);
+ }
+ }
+
+ async function protect(row) {
+ setBusyId(row.id);
+ try {
+ await api.protectManagedDatabase(row.id);
+ toast.success('Backup policy created. Tune it under Backups.');
+ } catch (err) {
+ toast.error(err.message || 'Failed to protect database');
+ } finally {
+ setBusyId(null);
+ }
+ }
+
+ async function untrack(row, drop) {
+ const ok = await confirm({
+ title: drop ? `Drop “${row.name}”?` : `Untrack “${row.name}”?`,
+ message: drop
+ ? 'This DROPs the database on the server and removes tracking. This cannot be undone.'
+ : 'This stops tracking the database. The database itself is left untouched.',
+ confirmText: drop ? 'Drop database' : 'Untrack',
+ danger: drop,
+ });
+ if (!ok) return;
+ setBusyId(row.id);
+ try {
+ await api.deleteManagedDatabase(row.id, { drop });
+ toast.success(drop ? 'Database dropped and untracked' : 'Database untracked');
+ await load();
+ } catch (err) {
+ toast.error(err.message || 'Failed to remove database');
+ } finally {
+ setBusyId(null);
+ }
+ }
+
+ if (loading) {
+ return <p className="managed-db__hint">Loading managed databases…</p>;
+ }
+
+ return (
+ <div className="managed-db">
+ <div className="managed-db__head">
+ <p className="managed-db__hint">
+ Databases ServerKit tracks for backups and connection strings. The live
+ explorer still shows everything on the server.
+ </p>
+ <Button type="button" size="sm" variant="ghost" onClick={load} aria-label="Refresh">
+ <RefreshCw size={14} /> Refresh
+ </Button>
+ </div>
+
+ {rows.length === 0 ? (
+ <p className="managed-db__empty">
+ <Link2 size={15} /> No tracked databases yet. Provisioning a database tracks it
+ automatically; you can also adopt an existing one.
+ </p>
+ ) : (
+ <div className="managed-db__list">
+ {rows.map((row) => (
+ <div key={row.id} className="managed-db__row">
+ <div className="managed-db__info">
+ <strong>{row.name}</strong>
+ <span className="managed-db__meta">
+ {row.engine} · {row.host}:{row.port}
+ {row.admin_username ? ` · ${row.admin_username}` : ''}
+ </span>
+ </div>
+ <Pill kind={row.origin === 'provisioned' ? 'green' : 'gray'}>{row.origin}</Pill>
+ <div className="managed-db__actions">
+ <Button type="button" size="sm" variant="outline" disabled={busyId === row.id}
+ onClick={() => copyConnectionUri(row)}>
+ <Copy size={14} /> Connection string
+ </Button>
+ <Button type="button" size="sm" variant="outline" disabled={busyId === row.id}
+ onClick={() => protect(row)}>
+ <ShieldCheck size={14} /> Protect
+ </Button>
+ <Button type="button" size="sm" variant="ghost" disabled={busyId === row.id}
+ onClick={() => untrack(row, false)} aria-label={`Untrack ${row.name}`}>
+ <Trash2 size={14} /> Untrack
+ </Button>
+ </div>
+ </div>
+ ))}
+ </div>
+ )}
+ </div>
+ );
+}
diff --git a/frontend/src/pages/Databases.jsx b/frontend/src/pages/Databases.jsx
index 4f7cde52..21a7b533 100644
--- a/frontend/src/pages/Databases.jsx
+++ b/frontend/src/pages/Databases.jsx
@@ -2,9 +2,11 @@ import { useState, useEffect, useMemo, useCallback, useRef } from 'react';
import {
PanelLeftClose, PanelLeftOpen, Search, X, RefreshCw, Plus, Terminal,
Archive, Database, Table2, Server, ChevronDown,
- Trash2, DatabaseBackup, Copy, FileCode2, Lock,
+ Trash2, DatabaseBackup, Copy, FileCode2, Lock, BookMarked,
} from 'lucide-react';
import api from '../services/api';
+import Modal from '@/components/Modal';
+import ManagedDatabasesPanel from '../components/databases/ManagedDatabasesPanel';
import { formatBytes } from '@/utils/formatBytes';
import { useToast } from '../contexts/ToastContext';
import { useConfirm } from '../hooks/useConfirm';
@@ -80,6 +82,7 @@ export default function Databases() {
const [filter, setFilter] = useState('');
const [ctxMenu, setCtxMenu] = useState(null);
const [showNewMenu, setShowNewMenu] = useState(false);
+ const [showManaged, setShowManaged] = useState(false);
const [modal, setModal] = useState(null); // { type, databases }
const newMenuRef = useRef(null);
const didAutoExpand = useRef(false);
@@ -443,6 +446,9 @@ export default function Databases() {
</div>
)}
</div>
+ <button type="button" className="dbx-chip" onClick={() => setShowManaged(true)}>
+ <BookMarked size={14} aria-hidden="true" /> Managed
+ </button>
<button type="button" className="dbx-chip" onClick={openBackups}>
<Archive size={14} aria-hidden="true" /> Backups
</button>
@@ -616,6 +622,10 @@ export default function Databases() {
{modal?.type === 'mysql-user' && <CreateMySQLUserModal databases={modal.databases} onClose={() => setModal(null)} onCreated={onModalCreated} />}
{modal?.type === 'pg-user' && <CreatePostgreSQLUserModal databases={modal.databases} onClose={() => setModal(null)} onCreated={onModalCreated} />}
+ <Modal open={showManaged} onClose={() => setShowManaged(false)} title="Managed databases" size="lg">
+ <ManagedDatabasesPanel />
+ </Modal>
+
</div>
);
}
diff --git a/frontend/src/services/api/databases.js b/frontend/src/services/api/databases.js
index b9f2c312..895feae1 100644
--- a/frontend/src/services/api/databases.js
+++ b/frontend/src/services/api/databases.js
@@ -230,3 +230,35 @@ export async function applyMigrations() {
export async function getMigrationHistory() {
return this.request('/migrations/history');
}
+
+// Managed databases — durable tracking beside the live introspection. Secrets
+// are never returned (has_secret); the connection URI is revealed only via an
+// explicit, audited action.
+export async function getManagedDatabases() {
+ return this.request('/databases/managed');
+}
+
+export async function getManagedDatabase(id) {
+ return this.request(`/databases/managed/${id}`);
+}
+
+export async function createManagedDatabase(data) {
+ return this.request('/databases/managed', { method: 'POST', body: data });
+}
+
+export async function adoptManagedDatabase(data) {
+ return this.request('/databases/managed/adopt', { method: 'POST', body: data });
+}
+
+export async function deleteManagedDatabase(id, { drop = false } = {}) {
+ const q = drop ? '?drop=true' : '';
+ return this.request(`/databases/managed/${id}${q}`, { method: 'DELETE' });
+}
+
+export async function revealManagedConnectionUri(id) {
+ return this.request(`/databases/managed/${id}/connection-uri`, { method: 'POST' });
+}
+
+export async function protectManagedDatabase(id, policy = null) {
+ return this.request(`/databases/managed/${id}/protect`, { method: 'POST', body: { policy } });
+}
diff --git a/frontend/src/styles/pages/_databases.scss b/frontend/src/styles/pages/_databases.scss
index e5851ac3..9b584a61 100644
--- a/frontend/src/styles/pages/_databases.scss
+++ b/frontend/src/styles/pages/_databases.scss
@@ -1001,3 +1001,72 @@ $dbx-sqlite: #3d8fd1;
.dbx-spin { animation: none; }
}
}
+
+// ============================================
+// MANAGED DATABASES (modal panel)
+// ============================================
+.managed-db {
+ display: flex;
+ flex-direction: column;
+ gap: $spacing-md;
+
+ &__head {
+ display: flex;
+ align-items: flex-start;
+ justify-content: space-between;
+ gap: $spacing-md;
+ }
+
+ &__hint {
+ font-size: 13px;
+ color: var(--text-dim);
+ line-height: 1.5;
+ margin: 0;
+ }
+
+ &__empty {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ font-size: 13px;
+ color: var(--text-faint);
+ padding: $spacing-lg 0;
+ }
+
+ &__list {
+ display: flex;
+ flex-direction: column;
+ }
+
+ &__row {
+ display: flex;
+ align-items: center;
+ gap: $spacing-md;
+ padding: $space-3 0;
+ border-top: 1px solid var(--border-soft);
+
+ &:first-child { border-top: none; }
+ }
+
+ &__info {
+ display: flex;
+ flex-direction: column;
+ gap: 2px;
+ min-width: 0;
+ flex: 1;
+ }
+
+ &__meta {
+ font-family: $font-mono, monospace;
+ font-size: 12px;
+ color: var(--text-faint);
+ word-break: break-all;
+ }
+
+ &__actions {
+ display: flex;
+ gap: 6px;
+ flex-wrap: wrap;
+ justify-content: flex-end;
+ }
+}