db

Documentation

Overview

Package db contains functions for accessing the Firebase Realtime Database.

Index

• type Client
  • func NewClient(ctx context.Context, c *internal.DatabaseConfig) (*Client, error)
  • func (c *Client) NewRef(path string) *Ref
• type Event
  • func (e *Event) Snapshot() string
  • func (e *Event) Unmarshal(v interface{}) error
• type EventType
• type Query
  • func (q *Query) EndAt(v interface{}) *Query
  • func (q *Query) EqualTo(v interface{}) *Query
  • func (q *Query) Get(ctx context.Context, v interface{}) error
  • func (q *Query) GetOrdered(ctx context.Context) ([]QueryNode, error)
  • func (q *Query) LimitToFirst(n int) *Query
  • func (q *Query) LimitToLast(n int) *Query
  • func (q *Query) StartAt(v interface{}) *Query
• type QueryNode
• type Ref
  • func (r *Ref) Child(path string) *Ref
  • func (r *Ref) Delete(ctx context.Context) error
  • func (r *Ref) Get(ctx context.Context, v interface{}) error
  • func (r *Ref) GetIfChanged(ctx context.Context, etag string, v interface{}) (bool, string, error)
  • func (r *Ref) GetShallow(ctx context.Context, v interface{}) error
  • func (r *Ref) GetWithETag(ctx context.Context, v interface{}) (string, error)
  • func (r *Ref) Listen(ctx context.Context) (*SnapshotIterator, error)
  • func (r *Ref) OrderByChild(child string) *Query
  • func (r *Ref) OrderByKey() *Query
  • func (r *Ref) OrderByValue() *Query
  • func (r *Ref) Parent() *Ref
  • func (r *Ref) Push(ctx context.Context, v interface{}) (*Ref, error)
  • func (r *Ref) Set(ctx context.Context, v interface{}) error
  • func (r *Ref) SetIfUnchanged(ctx context.Context, etag string, v interface{}) (bool, error)
  • func (r *Ref) Transaction(ctx context.Context, fn UpdateFn) error
  • func (r *Ref) Update(ctx context.Context, v map[string]interface{}) error
• type SnapshotIterator
  • func (it *SnapshotIterator) Done() bool
  • func (it *SnapshotIterator) Next() (*Event, error)
  • func (it *SnapshotIterator) Stop()
• type TransactionNode
• type UpdateFn

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the interface for the Firebase Realtime Database service.

func NewClient

func NewClient(ctx context.Context, c *internal.DatabaseConfig) (*Client, error)

NewClient creates a new instance of the Firebase Database Client.

This function can only be invoked from within the SDK. Client applications should access the Database service through firebase.App.

func (*Client) NewRef

func (c *Client) NewRef(path string) *Ref

NewRef returns a new database reference representing the node at the specified path.

type Event

type Event struct {
	EventType EventType // ChildChanged, ValueChanged, ChildAdded, ChildRemoved

	Data string // JSON-encoded snapshot
	Path string // snapshot path
}

Event Sever-Sent Event object

func (*Event) Snapshot

func (e *Event) Snapshot() string

Snapshot ssevent data, data part

func (*Event) Unmarshal

func (e *Event) Unmarshal(v interface{}) error

Unmarshal current snapshot Event.Data

type EventType

type EventType uint

EventType specific event type changes

const (
	ChildChanged EventType = iota
	ChildAdded             // to be implemented
	ChildRemoved           // to be implemented
	ValueChanged           // to be implemented
)

EventType ...

type Query

type Query struct {
	// contains filtered or unexported fields
}

Query represents a complex query that can be executed on a Ref.

Complex queries can consist of up to 2 components: a required ordering constraint, and an optional filtering constraint. At the server, data is first sorted according to the given ordering constraint (e.g. order by child). Then the filtering constraint (e.g. limit, range) is applied on the sorted data to produce the final result. Despite the ordering constraint, the final result is returned by the server as an unordered collection. Therefore the values read from a Query instance are not ordered.

func (*Query) EndAt

func (q *Query) EndAt(v interface{}) *Query

EndAt returns a shallow copy of the Query with v set as a upper bound of a range query.

The resulting Query will only return child nodes with a value less than or equal to v.

func (*Query) EqualTo

func (q *Query) EqualTo(v interface{}) *Query

EqualTo returns a shallow copy of the Query with v set as an equals constraint.

The resulting Query will only return child nodes whose values equal to v.

func (*Query) Get

func (q *Query) Get(ctx context.Context, v interface{}) error

Get executes the Query and populates v with the results.

Data deserialization is performed using https://golang.org/pkg/encoding/json/#Unmarshal, and therefore v has the same requirements as the json package. Specifically, it must be a pointer, and must not be nil.

Despite the ordering constraint of the Query, results are not stored in any particular order in v. Use GetOrdered() to obtain ordered results.

func (*Query) GetOrdered

func (q *Query) GetOrdered(ctx context.Context) ([]QueryNode, error)

GetOrdered executes the Query and returns the results as an ordered slice.

func (*Query) LimitToFirst

func (q *Query) LimitToFirst(n int) *Query

LimitToFirst returns a shallow copy of the Query, which is anchored to the first n elements of the window.

func (*Query) LimitToLast

func (q *Query) LimitToLast(n int) *Query

LimitToLast returns a shallow copy of the Query, which is anchored to the last n elements of the window.

func (*Query) StartAt

func (q *Query) StartAt(v interface{}) *Query

StartAt returns a shallow copy of the Query with v set as a lower bound of a range query.

The resulting Query will only return child nodes with a value greater than or equal to v.

type QueryNode

type QueryNode interface {
	Key() string
	Unmarshal(v interface{}) error
}

QueryNode represents a data node retrieved from an ordered query.

type Ref

type Ref struct {
	Key  string
	Path string
	// contains filtered or unexported fields
}

Ref represents a node in the Firebase Realtime Database.

func (*Ref) Child

func (r *Ref) Child(path string) *Ref

Child returns a reference to the specified child node.

func (*Ref) Delete

func (r *Ref) Delete(ctx context.Context) error

Delete removes this node from the database.

func (*Ref) Get

func (r *Ref) Get(ctx context.Context, v interface{}) error

Get retrieves the value at the current database location, and stores it in the value pointed to by v.

Data deserialization is performed using https://golang.org/pkg/encoding/json/#Unmarshal, and therefore v has the same requirements as the json package. Specifically, it must be a pointer, and must not be nil.

func (*Ref) GetIfChanged

func (r *Ref) GetIfChanged(ctx context.Context, etag string, v interface{}) (bool, string, error)

GetIfChanged retrieves the value and ETag of the current database location only if the specified ETag does not match.

If the specified ETag does not match, returns true along with the latest ETag of the database location. The value of the database location will be stored in v just like a regular Get() call. If the etag matches, returns false along with the same ETag passed into the function. No data will be stored in v in this case.

func (*Ref) GetShallow

func (r *Ref) GetShallow(ctx context.Context, v interface{}) error

GetShallow performs a shallow read on the current database location.

Shallow reads do not retrieve the child nodes of the current reference.

func (*Ref) GetWithETag

func (r *Ref) GetWithETag(ctx context.Context, v interface{}) (string, error)

GetWithETag retrieves the value at the current database location, along with its ETag.

func (*Ref) Listen

func (r *Ref) Listen(ctx context.Context) (*SnapshotIterator, error)

Listen returns an iterator that listens to realtime events

func (*Ref) OrderByChild

func (r *Ref) OrderByChild(child string) *Query

OrderByChild returns a Query that orders data by child values before applying filters.

Returned Query can be used to set additional parameters, and execute complex database queries (e.g. limit queries, range queries). If r has a context associated with it, the resulting Query will inherit it.

func (*Ref) OrderByKey

func (r *Ref) OrderByKey() *Query

OrderByKey returns a Query that orders data by key before applying filters.

Returned Query can be used to set additional parameters, and execute complex database queries (e.g. limit queries, range queries). If r has a context associated with it, the resulting Query will inherit it.

func (*Ref) OrderByValue

func (r *Ref) OrderByValue() *Query

OrderByValue returns a Query that orders data by value before applying filters.

Returned Query can be used to set additional parameters, and execute complex database queries (e.g. limit queries, range queries). If r has a context associated with it, the resulting Query will inherit it.

func (*Ref) Parent

func (r *Ref) Parent() *Ref

Parent returns a reference to the parent of the current node.

If the current reference points to the root of the database, Parent returns nil.

func (*Ref) Push

func (r *Ref) Push(ctx context.Context, v interface{}) (*Ref, error)

Push creates a new child node at the current location, and returns a reference to it.

If v is not nil, it will be set as the initial value of the new child node. If v is nil, the new child node will be created with empty string as the value.

func (*Ref) Set

func (r *Ref) Set(ctx context.Context, v interface{}) error

Set stores the value v in the current database node.

Set uses https://golang.org/pkg/encoding/json/#Marshal to serialize values into JSON. Therefore v has the same requirements as the json package. Values like functions and channels cannot be saved into Realtime Database.

func (*Ref) SetIfUnchanged

func (r *Ref) SetIfUnchanged(ctx context.Context, etag string, v interface{}) (bool, error)

SetIfUnchanged conditionally sets the data at this location to the given value.

Sets the data at this location to v only if the specified ETag matches. Returns true if the value is written. Returns false if no changes are made to the database.

func (*Ref) Transaction

func (r *Ref) Transaction(ctx context.Context, fn UpdateFn) error

Transaction atomically modifies the data at this location.

Unlike a normal Set(), which just overwrites the data regardless of its previous state, Transaction() is used to modify the existing value to a new value, ensuring there are no conflicts with other clients simultaneously writing to the same location.

This is accomplished by passing an update function which is used to transform the current value of this reference into a new value. If another client writes to this location before the new value is successfully saved, the update function is called again with the new current value, and the write will be retried. In case of repeated failures, this method will retry the transaction up to 25 times before giving up and returning an error.

The update function may also force an early abort by returning an error instead of returning a value.

func (*Ref) Update

func (r *Ref) Update(ctx context.Context, v map[string]interface{}) error

Update modifies the specified child keys of the current location to the provided values.

type SnapshotIterator

type SnapshotIterator struct {
	Snapshot    string        // initial snapshot, JSON-encoded, returned from http Respoonse, server sent event, data part
	SSEDataChan <-chan string // continuous event snapshot, channel receive only, directional channel
	// contains filtered or unexported fields
}

SnapshotIterator iterator for continuous events

func (*SnapshotIterator) Done

func (it *SnapshotIterator) Done() bool

Done can be used to check if Stop() have been called

func (*SnapshotIterator) Next

func (it *SnapshotIterator) Next() (*Event, error)

Next realtime event

func (*SnapshotIterator) Stop

func (it *SnapshotIterator) Stop()

Stop listening for realtime events close http connection

type TransactionNode

type TransactionNode interface {
	Unmarshal(v interface{}) error
}

TransactionNode represents the value of a node within the scope of a transaction.

type UpdateFn

type UpdateFn func(TransactionNode) (interface{}, error)

UpdateFn represents a function type that can be passed into Transaction().