fix(firestore): deprecate databaseURL in favor of databaseId (#12593)

Author: russellwheatley

packages/cloud_firestore/cloud_firestore/example/integration_test/second_database.dart

@@ -37,7 +37,7 @@ void runSecondDatabaseTests() {
       setUpAll(() async {
         firestore = FirebaseFirestore.instanceFor(
           app: Firebase.app(),
-          databaseURL: 'flutterfire-2',
+          databaseId: 'flutterfire-2',
         );
       });
 

packages/cloud_firestore/cloud_firestore/lib/src/firestore.dart

@@ -16,12 +16,14 @@ part of cloud_firestore;
 /// FirebaseFirestore firestore = FirebaseFirestore.instanceFor(app: secondaryApp);
 /// ```
 class FirebaseFirestore extends FirebasePluginPlatform {
-  FirebaseFirestore._({required this.app, required this.databaseURL})
-      : super(app.name, 'plugins.flutter.io/firebase_firestore') {
-    if (databaseURL.endsWith('/')) {
-      databaseURL = databaseURL.substring(0, databaseURL.length - 1);
-    }
-  }
+  FirebaseFirestore._({
+    required this.app,
+    @Deprecated(
+      '`databaseURL` has been deprecated. Please use `databaseId` instead.',
+    )
+    required this.databaseURL,
+    required this.databaseId,
+  }) : super(app.name, 'plugins.flutter.io/firebase_firestore');
 
   static final Map<String, FirebaseFirestore> _cachedInstances = {};
 
@@ -35,16 +37,25 @@ class FirebaseFirestore extends FirebasePluginPlatform {
   /// Returns an instance using a specified [FirebaseApp].
   static FirebaseFirestore instanceFor({
     required FirebaseApp app,
+    @Deprecated(
+      '`databaseURL` has been deprecated. Please use `databaseId` instead.',
+    )
     String? databaseURL,
+    String? databaseId,
   }) {
-    String url = databaseURL ?? '(default)';
-    String cacheKey = '${app.name}|$url';
+    String firestoreDatabaseId = databaseId ?? databaseURL ?? '(default)';
+    String cacheKey = '${app.name}|$firestoreDatabaseId';
     if (_cachedInstances.containsKey(cacheKey)) {
       return _cachedInstances[cacheKey]!;
     }
 
     FirebaseFirestore newInstance =
-        FirebaseFirestore._(app: app, databaseURL: url);
+        // Both databaseURL and databaseId are required so we have to pass both for now. We can remove databaseURL in a future release.
+        FirebaseFirestore._(
+      app: app,
+      databaseURL: firestoreDatabaseId,
+      databaseId: firestoreDatabaseId,
+    );
     _cachedInstances[cacheKey] = newInstance;
 
     return newInstance;
@@ -58,16 +69,23 @@ class FirebaseFirestore extends FirebasePluginPlatform {
   FirebaseFirestorePlatform get _delegate {
     return _delegatePackingProperty ??= FirebaseFirestorePlatform.instanceFor(
       app: app,
-      databaseURL: databaseURL,
+      databaseId: databaseId,
     );
   }
 
   /// The [FirebaseApp] for this current [FirebaseFirestore] instance.
   FirebaseApp app;
 
-  /// Firestore Database URL for this instance. Falls back to default database: "(default)"
+  /// Firestore Database ID for this instance. Falls back to default database: "(default)"
+  /// This is deprecated in favor of [databaseId].
+  @Deprecated(
+    '`databaseURL` has been deprecated. Please use `databaseId` instead.',
+  )
   String databaseURL;
 
+  /// Firestore Database ID for this instance. Falls back to default database: "(default)"
+  String databaseId;
+
   /// Gets a [CollectionReference] for the specified Firestore path.
   CollectionReference<Map<String, dynamic>> collection(String collectionPath) {
     assert(

packages/cloud_firestore/cloud_firestore/test/cloud_firestore_test.dart

@@ -40,6 +40,36 @@ void main() {
       );
     });
 
+    test('databaseId and databaseURL', () {
+      final firestore = FirebaseFirestore.instanceFor(
+        // ignore: deprecated_member_use_from_same_package
+        app: Firebase.app(), databaseURL: 'foo',
+      );
+
+      // ignore: deprecated_member_use_from_same_package
+      expect(firestore.databaseURL, equals('foo'));
+
+      expect(firestore.databaseId, equals('foo'));
+
+      final firestore2 =
+          FirebaseFirestore.instanceFor(app: Firebase.app(), databaseId: 'bar');
+
+      // ignore: deprecated_member_use_from_same_package
+      expect(firestore2.databaseURL, equals('bar'));
+
+      expect(firestore2.databaseId, equals('bar'));
+
+      final firestore3 = FirebaseFirestore.instanceFor(
+        // ignore: deprecated_member_use_from_same_package
+        app: Firebase.app(), databaseId: 'fire', databaseURL: 'not-this',
+      );
+
+      // databaseId should take precedence
+      expect(firestore3.databaseId, equals('fire'));
+      // ignore: deprecated_member_use_from_same_package
+      expect(firestore3.databaseURL, equals('fire'));
+    });
+
     test('returns the correct $FirebaseApp', () {
       expect(firestore!.app, equals(Firebase.app()));
       expect(firestoreSecondary!.app, equals(Firebase.app('foo')));

packages/cloud_firestore/cloud_firestore/test/test_firestore_message_codec.dart

@@ -60,20 +60,20 @@ class TestFirestoreMessageCodec extends FirestoreMessageCodec {
         );
       case _kFirestoreInstance:
         String appName = readValue(buffer)! as String;
-        String databaseURL = readValue(buffer)! as String;
+        String databaseId = readValue(buffer)! as String;
         readValue(buffer);
         final FirebaseApp app = Firebase.app(appName);
         return MethodChannelFirebaseFirestore(
           app: app,
-          databaseURL: databaseURL,
+          databaseId: databaseId,
         );
       case _kFirestoreQuery:
         String appName = readValue(buffer)! as String;
         Map<dynamic, dynamic> values =
             readValue(buffer)! as Map<dynamic, dynamic>;
         final FirebaseApp app = Firebase.app(appName);
         return MethodChannelQuery(
-          MethodChannelFirebaseFirestore(app: app, databaseURL: '(default)'),
+          MethodChannelFirebaseFirestore(app: app, databaseId: '(default)'),
           values['path'],
           FirestorePigeonFirebaseApp(
             appName: "['DEFAULT']",

packages/cloud_firestore/cloud_firestore_platform_interface/lib/src/method_channel/method_channel_firestore.dart

@@ -25,8 +25,8 @@ import 'utils/firestore_message_codec.dart';
 /// You can get an instance by calling [FirebaseFirestore.instance].
 class MethodChannelFirebaseFirestore extends FirebaseFirestorePlatform {
   /// Create an instance of [MethodChannelFirebaseFirestore] with optional [FirebaseApp]
-  MethodChannelFirebaseFirestore({FirebaseApp? app, String? databaseURL})
-      : super(appInstance: app, databaseChoice: databaseURL);
+  MethodChannelFirebaseFirestore({FirebaseApp? app, String? databaseId})
+      : super(appInstance: app, databaseChoice: databaseId);
 
   /// The [FirebaseApp] instance to which this [FirebaseDatabase] belongs.
   ///
@@ -68,7 +68,7 @@ class MethodChannelFirebaseFirestore extends FirebaseFirestorePlatform {
 
   late final FirestorePigeonFirebaseApp pigeonApp = FirestorePigeonFirebaseApp(
     appName: appInstance!.name,
-    databaseURL: databaseURL,
+    databaseURL: databaseId,
     settings: PigeonFirebaseSettings(
       persistenceEnabled: settings.persistenceEnabled,
       host: settings.host,
@@ -83,9 +83,9 @@ class MethodChannelFirebaseFirestore extends FirebaseFirestorePlatform {
   @override
   FirebaseFirestorePlatform delegateFor({
     required FirebaseApp app,
-    required String databaseURL,
+    required String databaseId,
   }) {
-    return MethodChannelFirebaseFirestore(app: app, databaseURL: databaseURL);
+    return MethodChannelFirebaseFirestore(app: app, databaseId: databaseId);
   }
 
   @override
@@ -268,7 +268,7 @@ class MethodChannelFirebaseFirestore extends FirebaseFirestorePlatform {
           transactionId,
           event['appName'],
           pigeonApp,
-          databaseURL,
+          databaseId,
         );
 
         // If the transaction fails on Dart side, then forward the error

packages/cloud_firestore/cloud_firestore_platform_interface/lib/src/method_channel/method_channel_transaction.dart

@@ -17,18 +17,18 @@ import 'method_channel_firestore.dart';
 class MethodChannelTransaction extends TransactionPlatform {
   /// [FirebaseApp] name used for this [MethodChannelTransaction]
   final String appName;
-  final String databaseURL;
+  final String databaseId;
   late String _transactionId;
   late FirebaseFirestorePlatform _firestore;
   FirestorePigeonFirebaseApp pigeonApp;
 
   /// Constructor.
   MethodChannelTransaction(
-      String transactionId, this.appName, this.pigeonApp, this.databaseURL)
+      String transactionId, this.appName, this.pigeonApp, this.databaseId)
       : _transactionId = transactionId,
         super() {
     _firestore = FirebaseFirestorePlatform.instanceFor(
-        app: Firebase.app(appName), databaseURL: databaseURL);
+        app: Firebase.app(appName), databaseId: databaseId);
   }
 
   List<PigeonTransactionCommand> _commands = [];

packages/cloud_firestore/cloud_firestore_platform_interface/lib/src/method_channel/utils/firestore_message_codec.dart

@@ -103,7 +103,7 @@ class FirestoreMessageCodec extends StandardMessageCodec {
     } else if (value is MethodChannelFirebaseFirestore) {
       buffer.putUint8(_kFirestoreInstance);
       writeValue(buffer, value.app.name);
-      writeValue(buffer, value.databaseURL);
+      writeValue(buffer, value.databaseId);
       writeValue(buffer, value.settings);
     } else if (value is MethodChannelQuery) {
       buffer.putUint8(_kFirestoreQuery);
@@ -141,12 +141,12 @@ class FirestoreMessageCodec extends StandardMessageCodec {
       case _kDocumentReference:
         final String appName = readValue(buffer)! as String;
         final String path = readValue(buffer)! as String;
-        final String databaseURL = readValue(buffer)! as String;
+        final String databaseId = readValue(buffer)! as String;
 
         final FirebaseApp app = Firebase.app(appName);
         final FirebaseFirestorePlatform firestore =
             FirebaseFirestorePlatform.instanceFor(
-                app: app, databaseURL: databaseURL);
+                app: app, databaseId: databaseId);
         return firestore.doc(path);
       case _kBlob:
         final int length = readSize(buffer);

packages/cloud_firestore/cloud_firestore_platform_interface/lib/src/platform_interface/platform_interface_firestore.dart

@@ -30,7 +30,7 @@ abstract class FirebaseFirestorePlatform extends PlatformInterface {
   final String? databaseChoice;
 
   /// Firestore Database URL for this instance. Falls back to default database: "(default)"
-  String get databaseURL {
+  String get databaseId {
     return databaseChoice ?? '(default)';
   }
 
@@ -39,10 +39,10 @@ abstract class FirebaseFirestorePlatform extends PlatformInterface {
   /// Create an instance using [app] using the existing implementation
   factory FirebaseFirestorePlatform.instanceFor({
     required FirebaseApp app,
-    required String databaseURL,
+    required String databaseId,
   }) {
     return FirebaseFirestorePlatform.instance
-        .delegateFor(app: app, databaseURL: databaseURL);
+        .delegateFor(app: app, databaseId: databaseId);
   }
 
   /// The current default [FirebaseFirestorePlatform] instance.
@@ -51,7 +51,7 @@ abstract class FirebaseFirestorePlatform extends PlatformInterface {
   /// if no other implementation was provided.
   static FirebaseFirestorePlatform get instance {
     return _instance ??= MethodChannelFirebaseFirestore(
-        app: Firebase.app(), databaseURL: '(default)');
+        app: Firebase.app(), databaseId: '(default)');
   }
 
   static FirebaseFirestorePlatform? _instance;
@@ -66,7 +66,7 @@ abstract class FirebaseFirestorePlatform extends PlatformInterface {
   /// [FirebaseApp] instance is required by the user.
   @protected
   FirebaseFirestorePlatform delegateFor(
-      {required FirebaseApp app, required String databaseURL}) {
+      {required FirebaseApp app, required String databaseId}) {
     throw UnimplementedError('delegateFor() is not implemented');
   }
 

packages/cloud_firestore/cloud_firestore_platform_interface/test/utils/test_firestore_message_codec.dart

@@ -62,7 +62,7 @@ class TestFirestoreMessageCodec extends FirestoreMessageCodec {
         readValue(buffer);
         final FirebaseApp app = Firebase.app(appName);
         return MethodChannelFirebaseFirestore(
-            app: app, databaseURL: databaseURL);
+            app: app, databaseId: databaseURL);
       case _kFirestoreQuery:
         Map<dynamic, dynamic> values =
             readValue(buffer)! as Map<dynamic, dynamic>;

packages/cloud_firestore/cloud_firestore_web/lib/cloud_firestore_web.dart

@@ -35,7 +35,7 @@ class FirebaseFirestoreWeb extends FirebaseFirestorePlatform {
   /// Lazily initialize [_webFirestore] on first method call
   firestore_interop.Firestore get _delegate {
     return _webFirestore ??= firestore_interop.getFirestoreInstance(
-        core_interop.app(app.name), _settings, databaseURL);
+        core_interop.app(app.name), _settings, databaseId);
   }
 
   /// Called by PluginRegistry to register this plugin for Flutter Web
@@ -46,15 +46,15 @@ class FirebaseFirestoreWeb extends FirebaseFirestorePlatform {
 
   /// Builds an instance of [FirebaseFirestoreWeb] with an optional [FirebaseApp] instance
   /// If [app] is null then the created instance will use the default [FirebaseApp]
-  FirebaseFirestoreWeb({FirebaseApp? app, String? databaseURL})
-      : super(appInstance: app, databaseChoice: databaseURL) {
+  FirebaseFirestoreWeb({FirebaseApp? app, String? databaseId})
+      : super(appInstance: app, databaseChoice: databaseId) {
     FieldValueFactoryPlatform.instance = FieldValueFactoryWeb();
   }
 
   @override
   FirebaseFirestorePlatform delegateFor(
-      {required FirebaseApp app, required String databaseURL}) {
-    return FirebaseFirestoreWeb(app: app, databaseURL: databaseURL);
+      {required FirebaseApp app, required String databaseId}) {
+    return FirebaseFirestoreWeb(app: app, databaseId: databaseId);
   }
 
   @override