firestore

README

---

id: firestore title: Firestore

A Firestore storage driver using cloud.google.com/go/firestore.

Note: If no credentials are provided, the driver uses Application Default Credentials (ADC) or the GOOGLE_APPLICATION_CREDENTIALS environment variable. If credentials are provided via config (Credentials or CredentialsPath), those take precedence. See: Google Cloud Authentication Guide

Table of Contents

• Signatures
• Installation
• Examples
• Config
• Default Config

Signatures

func New(config ...Config) *Storage
func NewFromConnection(client *firestore.Client, collection string) *Storage
func (s *Storage) Get(key string) ([]byte, error)
func (s *Storage) GetWithContext(ctx context.Context, key string) ([]byte, error)
func (s *Storage) Set(key string, val []byte, exp time.Duration) error
func (s *Storage) SetWithContext(ctx context.Context, key string, val []byte, exp time.Duration) error
func (s *Storage) Delete(key string) error
func (s *Storage) DeleteWithContext(ctx context.Context, key string) error
func (s *Storage) Reset() error
func (s *Storage) ResetWithContext(ctx context.Context) error
func (s *Storage) Close() error
func (s *Storage) Conn() *firestore.Client

Installation

Firestore is tested on the last Go versions with support for modules. So make sure to initialize one first if you didn't do that yet:

go mod init github.com/<user>/<repo>

And then install the firestore implementation:

go get github.com/gofiber/storage/firestore

Examples

Import the storage package.

import firestorage "github.com/gofiber/storage/firestore"

You can use the following possibilities to create a storage:

// Initialize with Application Default Credentials
store := firestorage.New(firestorage.Config{
	ProjectID: "my-gcp-project",
})

// Initialize with service account JSON file
store := firestorage.New(firestorage.Config{
	ProjectID:       "my-gcp-project",
	CredentialsPath: "/path/to/service-account-key.json",
	Collection:      "sessions",
})

// Initialize with embedded credentials JSON
store := firestorage.New(firestorage.Config{
	ProjectID:   "my-gcp-project",
	Credentials: `{"type": "service_account", ...}`,
})

// Initialize with custom timeout
store := firestorage.New(firestorage.Config{
	ProjectID:      "my-gcp-project",
	Collection:     "fiber_storage",
	RequestTimeout: 10 * time.Second,
	Reset:          false,
})

Using an Existing Firestore Client

If you already have a Firestore client configured in your application, you can create a Storage instance directly from that client:

import (
	"cloud.google.com/go/firestore"
	"context"
	firestorage "github.com/gofiber/storage/firestore"
)

ctx := context.Background()
client, err := firestore.NewClient(ctx, "my-gcp-project")
if err != nil {
	panic(err)
}

store := firestorage.NewFromConnection(client, "my_collection")

Config

type Config struct {
	// ProjectID is the Google Cloud project ID
	// Required. Will panic if empty
	ProjectID string

	// Collection name where data will be stored
	//
	// Optional. Default is "fiber_storage"
	Collection string

	// CredentialsPath is the path to the service account JSON key file
	// If not provided, Application Default Credentials (ADC) will be used
	//
	// Optional. Default is ""
	CredentialsPath string

	// Credentials is a JSON string with service account credentials
	// Takes precedence over CredentialsPath if both are provided
	//
	// Optional. Default is ""
	Credentials string

	// RequestTimeout is the timeout for Firestore requests
	//
	// Optional. Default is 10 seconds
	RequestTimeout time.Duration

	// Reset clears all documents in the collection on initialization
	//
	// Optional. Default is false
	Reset bool
}

Default Config

var ConfigDefault = Config{
	Collection:     "fiber_storage",
	RequestTimeout: 10 * time.Second,
	Reset:          false,
}

Additional Resources

• Firestore Go SDK Documentation
• Firebase Console
• Google Cloud Firestore Documentation
• Google Cloud Authentication Guide
• Firestore Quotas and Limits

Documentation

Overview

Package firestore provides a Firestore storage driver for Fiber. It uses cloud.google.com/go/firestore v1.14.0 for Google Cloud Firestore operations.

Key dependencies:

• cloud.google.com/go/firestore: Official Firestore Go SDK
• google.golang.org/api/option: Authentication options (ADC, service account)
• google.golang.org/grpc: gRPC communication and status codes

Index

• Variables
• func LoadCredentialsFromFile(filepath string) (string, error)
• type Config
• type Storage
  • func New(config ...Config) *Storage
  • func NewFromConnection(client *firestore.Client, collection string) *Storage
  • func (s *Storage) Close() error
  • func (s *Storage) Conn() *firestore.Client
  • func (s *Storage) Delete(key string) error
  • func (s *Storage) DeleteWithContext(ctx context.Context, key string) error
  • func (s *Storage) Get(key string) ([]byte, error)
  • func (s *Storage) GetWithContext(ctx context.Context, key string) ([]byte, error)
  • func (s *Storage) Reset() error
  • func (s *Storage) ResetWithContext(ctx context.Context) error
  • func (s *Storage) Set(key string, val []byte, exp time.Duration) error
  • func (s *Storage) SetWithContext(ctx context.Context, key string, val []byte, exp time.Duration) error

Variables

var ConfigDefault = Config{
	Collection:     "fiber_storage",
	RequestTimeout: 10 * time.Second,
	Reset:          false,
}

ConfigDefault is the default config

Functions

func LoadCredentialsFromFile

func LoadCredentialsFromFile(filepath string) (string, error)

LoadCredentialsFromFile loads credentials from a file and returns as JSON string. This is a utility function for consumers of this package who need to load credentials from a file path and pass them to the Config.Credentials field.

Example:

credentials, err := firestore.LoadCredentialsFromFile("/path/to/service-account-key.json")
if err != nil {
	log.Fatal(err)
}
store := firestore.New(firestore.Config{
	ProjectID:   "my-gcp-project",
	Credentials: credentials,
})

Types

type Config

type Config struct {
	// ProjectID is the Google Cloud project ID
	// Required. Will panic if empty
	ProjectID string

	// Collection name where data will be stored
	//
	// Optional. Default is "fiber_storage"
	Collection string

	// CredentialsPath is the path to the service account JSON key file
	// If not provided, Application Default Credentials (ADC) will be used
	// Download from: Firebase Console -> Project Settings -> Service Accounts -> Generate New Private Key
	// See: https://cloud.google.com/docs/authentication/application-default-credentials
	//
	// Optional. Default is ""
	CredentialsPath string

	// Credentials is a JSON string with service account credentials
	// Takes precedence over CredentialsPath if both are provided
	// Useful for embedding credentials or loading from environment variables
	//
	// Optional. Default is ""
	Credentials string

	// RequestTimeout is the timeout for Firestore requests
	//
	// Optional. Default is 10 seconds
	RequestTimeout time.Duration

	// Reset clears all documents in the collection on initialization
	//
	// Optional. Default is false
	Reset bool
}

Config defines the config for Firestore storage.

type Storage

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

Storage interface that is implemented by storage providers

func New

func New(config ...Config) *Storage

New creates a new Firestore storage instance

func NewFromConnection

func NewFromConnection(client *firestore.Client, collection string) *Storage

NewFromConnection creates a new Storage instance from an existing Firestore client

func (*Storage) Close

func (s *Storage) Close() error

Close the database

func (*Storage) Conn

func (s *Storage) Conn() *firestore.Client

Return database client

func (*Storage) Delete

func (s *Storage) Delete(key string) error

Delete entry by key

func (*Storage) DeleteWithContext

func (s *Storage) DeleteWithContext(ctx context.Context, key string) error

DeleteWithContext deletes entry by key with context

func (*Storage) Get

func (s *Storage) Get(key string) ([]byte, error)

Get value by key

func (*Storage) GetWithContext

func (s *Storage) GetWithContext(ctx context.Context, key string) ([]byte, error)

GetWithContext gets value by key with context

func (*Storage) Reset

func (s *Storage) Reset() error

Reset all keys

func (*Storage) ResetWithContext

func (s *Storage) ResetWithContext(ctx context.Context) error

ResetWithContext reset all keys with context

func (*Storage) Set

func (s *Storage) Set(key string, val []byte, exp time.Duration) error

Set key with value and expiration

func (*Storage) SetWithContext

func (s *Storage) SetWithContext(ctx context.Context, key string, val []byte, exp time.Duration) error

SetWithContext key with value and expiration with context