refactor: deprecate common database manager

Signed-off-by: Camila Belo <camilaibs@gmail.com>

.changeset/early-donkeys-cheer.md

@@ -0,0 +1,5 @@
+---
+'@backstage/backend-common': patch
+---
+
+The `database` types, helpers and implementations were moved to the package `@backstage/backend-defaults` and deprecated from the package `@backstage/backend-commons`.

packages/backend-app-api/api-report.md

@@ -12,6 +12,7 @@ import { CacheService } from '@backstage/backend-plugin-api';
 import { Config } from '@backstage/config';
 import { ConfigSchema } from '@backstage/config-loader';
 import { CorsOptions } from 'cors';
+import { DatabaseService } from '@backstage/backend-plugin-api';
 import { DiscoveryService } from '@backstage/backend-plugin-api';
 import { ErrorRequestHandler } from 'express';
 import { Express as Express_2 } from 'express';
@@ -28,7 +29,6 @@ import { LifecycleService } from '@backstage/backend-plugin-api';
 import { LoadConfigOptionsRemote } from '@backstage/config-loader';
 import { LoggerService } from '@backstage/backend-plugin-api';
 import { PermissionsService } from '@backstage/backend-plugin-api';
-import { PluginDatabaseManager } from '@backstage/backend-common';
 import { RemoteConfigSourceOptions } from '@backstage/config-loader';
 import { RequestHandler } from 'express';
 import { RequestListener } from 'http';
@@ -102,7 +102,7 @@ export interface CreateSpecializedBackendOptions {
 
 // @public @deprecated (undocumented)
 export const databaseServiceFactory: () => ServiceFactory<
-  PluginDatabaseManager,
+  DatabaseService,
   'plugin'
 >;
 

packages/backend-common/api-report.md

@@ -22,6 +22,7 @@ import { CacheServiceOptions } from '@backstage/backend-plugin-api';
 import { CacheServiceSetOptions } from '@backstage/backend-plugin-api';
 import { Config } from '@backstage/config';
 import cors from 'cors';
+import { DatabaseService } from '@backstage/backend-plugin-api';
 import { DiscoveryService } from '@backstage/backend-plugin-api';
 import Docker from 'dockerode';
 import { ErrorRequestHandler } from 'express';
@@ -43,7 +44,6 @@ import { Logger } from 'winston';
 import { LoggerService } from '@backstage/backend-plugin-api';
 import { MergeResult } from 'isomorphic-git';
 import { PermissionsService } from '@backstage/backend-plugin-api';
-import { DatabaseService as PluginDatabaseManager } from '@backstage/backend-plugin-api';
 import { PluginMetadataService } from '@backstage/backend-plugin-api';
 import { PushResult } from 'isomorphic-git';
 import { Readable } from 'stream';
@@ -191,26 +191,29 @@ export function createStatusCheckRouter(options: {
   statusCheck?: StatusCheck;
 }): Promise<express.Router>;
 
-// @public
+// @public @deprecated (undocumented)
 export class DatabaseManager implements LegacyRootDatabaseService {
+  // (undocumented)
   forPlugin(
     pluginId: string,
-    deps?: {
-      lifecycle: LifecycleService;
-      pluginMetadata: PluginMetadataService;
-    },
+    deps?:
+      | {
+          lifecycle: LifecycleService;
+          pluginMetadata: PluginMetadataService;
+        }
+      | undefined,
   ): PluginDatabaseManager;
+  // (undocumented)
   static fromConfig(
     config: Config,
     options?: DatabaseManagerOptions,
   ): DatabaseManager;
 }
 
-// @public
-export type DatabaseManagerOptions = {
-  migrations?: PluginDatabaseManager['migrations'];
-  logger?: LoggerService;
-};
+// Warning: (ae-forgotten-export) The symbol "DatabaseManagerOptions_2" needs to be exported by the entry point index.d.ts
+//
+// @public @deprecated (undocumented)
+export type DatabaseManagerOptions = DatabaseManagerOptions_2;
 
 // @public
 export class DockerContainerRunner implements ContainerRunner {
@@ -219,11 +222,10 @@ export class DockerContainerRunner implements ContainerRunner {
   runContainer(options: RunContainerOptions): Promise<void>;
 }
 
-// @public @deprecated
-export function dropDatabase(
-  dbConfig: Config,
-  ...databaseNames: string[]
-): Promise<void>;
+// Warning: (ae-forgotten-export) The symbol "dropDatabase_2" needs to be exported by the entry point index.d.ts
+//
+// @public @deprecated (undocumented)
+export const dropDatabase: typeof dropDatabase_2;
 
 // @public @deprecated
 export function errorHandler(
@@ -400,7 +402,7 @@ export const legacyPlugin: (
         {
           cache: CacheService;
           config: RootConfigService;
-          database: PluginDatabaseManager;
+          database: DatabaseService;
           discovery: DiscoveryService;
           logger: LoggerService;
           permissions: PermissionsService;
@@ -420,10 +422,10 @@ export const legacyPlugin: (
   }>,
 ) => BackendFeatureCompat;
 
-// @public
-export type LegacyRootDatabaseService = {
-  forPlugin(pluginId: string): PluginDatabaseManager;
-};
+// Warning: (ae-forgotten-export) The symbol "LegacyRootDatabaseService_2" needs to be exported by the entry point index.d.ts
+//
+// @public @deprecated (undocumented)
+export type LegacyRootDatabaseService = LegacyRootDatabaseService_2;
 
 // @public @deprecated
 export function loadBackendConfig(options: {
@@ -466,7 +468,8 @@ export function notFoundHandler(): RequestHandler;
 // @public @deprecated (undocumented)
 export type PluginCacheManager = PluginCacheManager_2;
 
-export { PluginDatabaseManager };
+// @public @deprecated (undocumented)
+export type PluginDatabaseManager = DatabaseService;
 
 // @public @deprecated (undocumented)
 export type PluginEndpointDiscovery = DiscoveryService;

packages/backend-common/src/database/index.ts

@@ -1,18 +0,0 @@
-/*
- * Copyright 2020 The Backstage Authors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-export * from './reexport';
-export type { PluginDatabaseManager } from './types';

packages/backend-common/src/database/reexport.ts

@@ -1,37 +0,0 @@
-/*
- * Copyright 2024 The Backstage Authors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-/*
- * NOTE(freben): This is a temporary hack. We use cross-package imports so that
- * we do not have to maintain double implementations for the time being, until
- * backend-common is properly removed. When it is, the impleemntation should be
- * moved into this part of the repo instead.
- */
-
-// eslint-disable-next-line @backstage/no-relative-monorepo-imports
-import {
-  DatabaseManager,
-  dropDatabase,
-  type DatabaseManagerOptions,
-  type LegacyRootDatabaseService,
-} from '../../../backend-defaults/src/entrypoints/database/DatabaseManager';
-
-export {
-  DatabaseManager,
-  dropDatabase,
-  type DatabaseManagerOptions,
-  type LegacyRootDatabaseService,
-};

packages/backend-common/src/database/types.ts

@@ -1,100 +0,0 @@
-/*
- * Copyright 2020 The Backstage Authors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import {
-  LifecycleService,
-  PluginMetadataService,
-} from '@backstage/backend-plugin-api';
-import { Config } from '@backstage/config';
-import { Knex } from 'knex';
-
-export type { DatabaseService as PluginDatabaseManager } from '@backstage/backend-plugin-api';
-
-/**
- * Manages an underlying Knex database driver.
- */
-export interface DatabaseConnector {
-  /**
-   * Provides an instance of a knex database connector.
-   */
-  createClient(
-    dbConfig: Config,
-    overrides?: Partial<Knex.Config>,
-    deps?: {
-      lifecycle: LifecycleService;
-      pluginMetadata: PluginMetadataService;
-    },
-  ): Knex;
-
-  /**
-   * Provides a partial knex config sufficient to override a database name.
-   */
-  createNameOverride(name: string): Partial<Knex.Config>;
-
-  /**
-   * Provides a partial knex config sufficient to override a PostgreSQL schema
-   * name within utilizing the `searchPath` knex configuration.
-   */
-  createSchemaOverride?(name: string): Partial<Knex.Config>;
-
-  /**
-   * Produces a knex connection config object representing a database connection
-   * string.
-   */
-  parseConnectionString(
-    connectionString: string,
-    client?: string,
-  ): Knex.StaticConnectionConfig;
-
-  /**
-   * Performs a side-effect to ensure database names passed in are present.
-   *
-   * Calling this function on databases which already exist should do nothing.
-   * Missing databases should be created if needed.
-   */
-  ensureDatabaseExists?(
-    dbConfig: Config,
-    ...databases: Array<string>
-  ): Promise<void>;
-
-  /**
-   * Performs a side-effect to ensure schema names passed in are present.
-   *
-   * Calling this function on schemas which already exist should do nothing.
-   * Missing schemas should be created if needed.
-   */
-  ensureSchemaExists?(
-    dbConfig: Config,
-    ...schemas: Array<string>
-  ): Promise<void>;
-
-  /**
-   * Deletes databases.
-   */
-  dropDatabase?(dbConfig: Config, ...databases: Array<string>): Promise<void>;
-}
-
-export interface Connector {
-  getClient(
-    pluginId: string,
-    deps?: {
-      lifecycle: LifecycleService;
-      pluginMetadata: PluginMetadataService;
-    },
-  ): Promise<Knex>;
-
-  dropDatabase(...databaseNames: string[]): Promise<void>;
-}

packages/backend-common/src/deprecated/index.ts

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+import { Config } from '@backstage/config';
+
 // eslint-disable-next-line @backstage/no-relative-monorepo-imports
 import { HostDiscovery as _HostDiscovery } from '../../../backend-defaults/src/entrypoints/discovery/HostDiscovery';
 
@@ -26,6 +28,14 @@ import {
   type CacheManagerOptions as _CacheManagerOptions,
 } from '../../../backend-defaults/src/entrypoints/cache/types';
 
+// eslint-disable-next-line @backstage/no-relative-monorepo-imports
+import {
+  dropDatabase as _dropDatabase,
+  DatabaseManager as _DatabaseManager,
+  type DatabaseManagerOptions as _DatabaseManagerOptions,
+  type LegacyRootDatabaseService as _LegacyRootDatabaseService,
+} from '../../../backend-defaults/src/entrypoints/database/DatabaseManager';
+
 // eslint-disable-next-line @backstage/no-relative-monorepo-imports
 import { AzureUrlReader as _AzureUrlReader } from '../../../backend-defaults/src/entrypoints/urlReader/lib/AzureUrlReader';
 // eslint-disable-next-line @backstage/no-relative-monorepo-imports
@@ -67,9 +77,12 @@ import type {
 
 import {
   DiscoveryService,
+  LifecycleService,
+  PluginMetadataService,
   CacheService,
   CacheServiceOptions,
   CacheServiceSetOptions,
+  DatabaseService as _PluginDatabaseManager,
   isDatabaseConflictError as _isDatabaseConflictError,
   resolvePackagePath as _resolvePackagePath,
   resolveSafeChildPath as _resolveSafeChildPath,
@@ -160,6 +173,55 @@ export type CacheClientSetOptions = CacheServiceSetOptions;
  */
 export type CacheClientOptions = CacheServiceOptions;
 
+/**
+ * @public
+ * @deprecated Use `DatabaseManager` from the `@backstage/backend-defaults` package instead
+ */
+export class DatabaseManager implements LegacyRootDatabaseService {
+  private constructor(private readonly _databaseManager: _DatabaseManager) {}
+
+  static fromConfig(
+    config: Config,
+    options?: DatabaseManagerOptions,
+  ): DatabaseManager {
+    const _databaseManager = _DatabaseManager.fromConfig(config, options);
+    return new DatabaseManager(_databaseManager);
+  }
+
+  forPlugin(
+    pluginId: string,
+    deps?:
+      | { lifecycle: LifecycleService; pluginMetadata: PluginMetadataService }
+      | undefined,
+  ): PluginDatabaseManager {
+    return this._databaseManager.forPlugin(pluginId, deps);
+  }
+}
+
+/**
+ * @public
+ * @deprecated Use `DatabaseManagerOptions` from the `@backstage/backend-defaults` package instead
+ */
+export type DatabaseManagerOptions = _DatabaseManagerOptions;
+
+/**
+ * @public
+ * @deprecated Use `DatabaseService` from the `@backstage/backend-plugin-api` package instead
+ */
+export type PluginDatabaseManager = _PluginDatabaseManager;
+
+/**
+ * @public
+ * @deprecated Use `LegacyRootDatabaseService` from the `@backstage/backend-defaults` package instead
+ */
+export type LegacyRootDatabaseService = _LegacyRootDatabaseService;
+
+/**
+ * @public
+ * @deprecated Use `dropDatabase` from the `@backstage/backend-defaults` package instead
+ */
+export const dropDatabase = _dropDatabase;
+
 /**
  * @public
  * @deprecated This function is deprecated and will be removed in a future release, see https://github.com/backstage/backstage/issues/24493.

packages/backend-common/src/index.ts

@@ -26,7 +26,6 @@ export { loadBackendConfig } from './config';
 export * from './deprecated';
 export * from './auth';
 export * from './cache';
-export * from './database';
 export * from './hot';
 export * from './logging';
 export * from './middleware';