Realtime Database · Flutter Compatibility
This page tracks an integration contract: unchanged Firebase code run through a Pyric runtime seam, so there is no separate Firebase public API to measure. The rows below are its signed behavior inventory.
Integration compatibility ledger for the Pure-Dart Flutter Realtime Database client (packages/flutter-client), conforming to firebase_database via Pyric WebSocket bridge transport.
Database Instance & Connection
PyricDatabase.instanceReturns the default Realtime Database instance bound to the active bridge connection.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)PyricDatabase.instanceFor(databaseURL)Returns a distinct Realtime Database handle for each database URL; production isolates the data and rules of each URL's database.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart, which asserts the handle carries its URL; bridge operations carry no instance field. (Structured evidence:
rtdb_conformance_test.dart)each URL yields a distinct handle, but data and rules are not isolated: the bridge does not carry the instance, so every handle reaches the default database
PyricDatabase.ref()Returns a DatabaseReference pointing to the root of the Realtime Database.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)PyricDatabase.ref(path)Returns a DatabaseReference pointing to the specified slash-delimited path.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)PyricDatabase.goOffline() / goOnline()Suspends and resumes the Realtime Database connection to the Pyric worker; .info/connected reports false after goOffline() and true again after goOnline() once the bridge is attached.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)ref('.info/connected').onValueServed by the client from its bridge connection. It reports false until the client attaches and false whenever the connection is interrupted, closed or taken offline with goOffline(), and true once the client re-attaches. An onDisconnect registered when it turns true reaches the host on the new connection, after the restore.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart, which follows goOffline() and goOnline(), and packages/flutter-client/test/rtdb_info_connected_reconnect_test.dart, which drives a drop, a re-attach and a replaced host over a fake bridge and asserts that no
.info frame reaches the host. (Structured evidence: rtdb_conformance_test.dart, rtdb_info_connected_reconnect_test.dart)ref('.info') / ref('.info/serverTimeOffset')Served by the client: .info is { connected, serverTimeOffset: 0 }, .info/serverTimeOffset is 0, and any other path under .info is null.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)the offset is always 0: the bridge handshake carries no server timestamp, and production delivers no offset until its first handshake
DatabaseReference Navigation & Properties
DatabaseReference.child(path)Returns a child DatabaseReference relative to the current path.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)DatabaseReference.parentReturns the parent DatabaseReference, or null when called on the root reference.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)DatabaseReference.rootReturns the root DatabaseReference from any descendant reference.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)DatabaseReference.keyReturns the last path segment token of the reference, or null for the root reference.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)DatabaseReference.pathReturns the normalized slash-delimited full path of the reference.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)DatabaseReference.push()Generates a new child DatabaseReference with a chronologically ordered unique push ID.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)DatabaseReference.push().keyMonotonically orders generated push keys lexicographically by creation timestamp.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)Write Operations
DatabaseReference.set(value)Overwrites data at the reference path with the provided JSON-serializable value.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)DatabaseReference.set(null)Deletes data at the reference path when set is called with null.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)DatabaseReference.setPriority(priority)Updates the ordering priority metadata of the node without altering its value.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)DatabaseReference.setWithPriority(value, priority)Atomically writes the node value alongside its ordering priority metadata.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)DatabaseReference.update(values)Performs a multi-path atomic update of specified child keys without overwriting omitted siblings.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)DatabaseReference.remove()Removes the node and all descendant data at the reference path.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)ServerValue Sentinels
ServerValue.timestampResolves server-side timestamp sentinel into current epoch milliseconds upon write.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)ServerValue.increment(delta)Atomically increments the numeric value at the target path by delta on the server.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)One-Shot Reads & DataSnapshot Inspection
DatabaseReference.get()Fetches a one-shot DataSnapshot of the current data at the reference path.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)DataSnapshot.existsReturns true if the DataSnapshot contains non-null data.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)DataSnapshot.keyReturns the key name of the location that generated the DataSnapshot.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)DataSnapshot.valueReturns the deserialized Dart value (Map, List, String, num, bool, or null) of the snapshot.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)DataSnapshot.childrenReturns an iterable of child DataSnapshots ordered according to the active query.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)DataSnapshot.child(path)Returns a DataSnapshot for the relative descendant path within the snapshot.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)DataSnapshot.priorityReturns the priority value (String, num, or null) associated with the snapshot node.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)Realtime Listeners & Streams
Query.onValueEmits DatabaseEvent with full DataSnapshot initially and upon any data change at the path.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)Query.onChildAddedEmits DatabaseEvent for each existing child and whenever a new child is added.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)Query.onChildChangedEmits DatabaseEvent whenever an existing child node is modified.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)Query.onChildRemovedEmits DatabaseEvent whenever a child node is removed from the watched location.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)StreamSubscription.cancel()Cancels the active stream subscription and unsubscribes the worker listener.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)Query Ordering, Filtering & Limits
Query.orderByChild(path)Orders query results by the value of the specified nested child key.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)Query.orderByKey()Orders query results lexicographically by child key name.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)Query.orderByValue()Orders query results by direct scalar node values.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)Query.equalTo(value, {key})Filters query results to nodes matching the exact sort value and optional key.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)Query.startAt(value) / endAt(value)Restricts query results to the inclusive lower and upper boundary values.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)Query.limitToFirst(limit) / limitToLast(limit)Caps query results to the first N or last N ordered child nodes.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)Transactions & OnDisconnect
DatabaseReference.runTransaction(handler)Executes optimistic concurrency transaction handler and commits new value upon success.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)Transaction.abort()Aborts an in-progress transaction without writing changes to the database.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)OnDisconnect.set(value) / remove()Registers server-side write or removal operations to execute upon client disconnect.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. The Node host runs the operations when the client socket closes, by a close frame or after the host closes a socket that pinged and went silent, and keeps the session signed in for re-attach (ADR-0019):
packages/cli/test/serve/fixtures/hosted-sqlite-relay-ondisconnect.ts. The app scenario test/apps/host-closes-silent-consumer sends the same rtdb.onDisconnectSet from a paused node --import @pyric/cli/register process on a real dev server, and the host runs it once the liveness window passes. (Structured evidence: rtdb_conformance_test.dart)OnDisconnect.cancel()Cancels previously queued OnDisconnect operations at the reference path.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)Current gaps
Documented divergences
Known differences between Pyric and production Firebase. Each remains tracked as a non-conforming row.
PyricDatabase.instanceFor(databaseURL)Returns a distinct Realtime Database handle for each database URL; production isolates the data and rules of each URL's database.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart, which asserts the handle carries its URL; bridge operations carry no instance field. (Structured evidence:
rtdb_conformance_test.dart)ref('.info') / ref('.info/serverTimeOffset')Served by the client: .info is { connected, serverTimeOffset: 0 }, .info/serverTimeOffset is 0, and any other path under .info is null.
Verified by packages/flutter-client/test/rtdb_conformance_test.dart. (Structured evidence:
rtdb_conformance_test.dart)