Realtime Database¶
The Realtime Database is one big JSON tree, synced live to every connected client. It answers in milliseconds and is billed by data downloaded, which suits presence, chat, live cursors and game state. For rich queries over many documents, Firestore is usually the better fit.
from pyios_firebase.database import DataEventType, Database, ServerValue
db = Database.database()
messages = db.reference("rooms/general/messages")
messages.child_by_auto_id().set_value({"text": "Hello", "sent_at": ServerValue.timestamp()})
def on_message(snapshot, previous_key):
print(snapshot.key, snapshot.value)
observer = messages.order_by_child("sent_at").limit_to_last(50).observe(
DataEventType.CHILD_ADDED, on_message
)
Installation¶
- Add the
FirebaseDatabaseSwift package product (Installation). - In the console, open Realtime Database and create the database. Pick
its location: the URL depends on it
(
https://<project>-default-rtdb.firebaseio.com, orhttps://<name>.<region>.firebasedatabase.app). - Download
GoogleService-Info.plistagain: it then has theDATABASE_URL.
App configuration¶
What the app's build needs for this product. To combine several products, list
them all in one products; see App configuration.
[[tool.kivy.ios.include_files]]
dest = "."
sources = ["GoogleService-Info.plist"]
[tool.kivy.ios.native.swift_packages.Firebase]
url = "https://github.com/firebase/firebase-ios-sdk.git"
requirement = { from = "13.1.1" }
products = ["FirebaseDatabase"]
[tool.kivy.ios.xcode.build_settings]
OTHER_LDFLAGS = "$(inherited) -ObjC"
- File > Add Package Dependencies...,
https://github.com/firebase/firebase-ios-sdk.git, and pickFirebaseDatabase. - Build Settings > Other Linker Flags: add
-ObjC. - Add
GoogleService-Info.plistto the app target.
Guides¶
- Reading and writing: values, updates, listeners, transactions.
- Lists and queries: child events, sorting, filtering, paging.
- Offline and presence: persistence,
on_disconnect, connection state.
The data model¶
Everything is one JSON tree; a DatabaseReference points to a location in it:
{
"users": {
"ada": { "name": "Ada Lovelace", "rooms": { "general": true } }
},
"rooms": {
"general": {
"messages": {
"-NqA1...": { "from": "ada", "text": "Hello", "sent_at": 1767225600000 }
}
}
}
}
db.reference() # the root
db.reference("users/ada") # a location
db.reference("users").child("ada") # the same
ref.parent, ref.root, ref.key, ref.path, ref.url
Structuring the data¶
- Keep it flat. Reading a location downloads everything below it: store messages apart from the room list, not inside it.
- Index relationships both ways (
users/ada/rooms/general: trueandrooms/general/members/ada: true), and write both at once with a multi-path update. - Use
child_by_auto_id()for lists: its keys sort by creation time and never collide between clients.
Values¶
| Python | Stored | Read back as |
|---|---|---|
str, int, float, bool |
the same | the same (bool stays bool) |
None |
deletes the value | (absent: None) |
dict (str keys) |
an object | dict |
list, tuple |
an object with keys "0", "1"... |
list (when the keys are mostly sequential), else dict |
ServerValue.timestamp() |
the server's time, in ms since 1970 | int |
ServerValue.increment(n) |
the stored number + n | int / float |
The database has no date type: store ServerValue.timestamp() or
milliseconds since 1970 (int(dt.timestamp() * 1000)), or an ISO string.
Mistakes raise in Python¶
The SDK raises an Objective-C exception, which aborts the whole app, for a bad path, value or query. pyios-firebase checks first and raises a Python exception instead:
| Mistake | Raises |
|---|---|
A key with . # $ [ ] or / (or an empty key) |
ValueError |
A path with . # $ [ ] |
ValueError |
nan, inf, a string over 10 MB |
ValueError |
A datetime, bytes, a set, a non-str key |
TypeError |
Writing under .info |
ValueError |
Update paths at or below each other ("a" and "a/b") |
ValueError |
| Ordering a query twice, two starts, two ends, two limits, a limit of 0 | ValueError |
order_by_key() with non-str start / end values, or a child key |
TypeError / ValueError |
name = user_input.strip()
try:
db.reference("usernames").child(name).set_value(uid)
except ValueError:
show("A name cannot contain . # $ [ ] or /")
Several databases¶
Use the local emulator¶
Call it before the first reference. See Emulator Suite.
Errors¶
Database errors are DatabaseErrors (name from DatabaseErrorCode):
DatabaseErrorCode |
Means |
|---|---|
PERMISSION_DENIED |
The security rules do not allow this read or write |
UNAVAILABLE |
The server is unavailable |
WRITE_CANCELED |
The write was dropped (purge_outstanding_writes) |
OTHER |
Another status, in description (for example "maxretry" for a transaction) |
get_data offline, with nothing cached, fails with an error from another
domain (name is "").
Turn on the SDK's logs while debugging: Database.set_logging_enabled(True).