datastore

package
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 5, 2025 License: Apache-2.0 Imports: 19 Imported by: 1

Documentation

Overview

Package datastore provides a zero-dependency Google Cloud Datastore client.

It uses only the Go standard library and makes direct REST API calls to the Datastore API. Authentication is handled via the GCP metadata server when running on GCP, or via Application Default Credentials.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalidEntityType is returned when functions like Get or Next are
	// passed a dst or src argument of invalid type.
	ErrInvalidEntityType = errors.New("datastore: invalid entity type")

	// ErrInvalidKey is returned when an invalid key is presented.
	ErrInvalidKey = errors.New("datastore: invalid key")

	// ErrNoSuchEntity is returned when no entity was found for a given key.
	ErrNoSuchEntity = errors.New("datastore: no such entity")

	// ErrConcurrentTransaction is returned when a transaction is used concurrently.
	ErrConcurrentTransaction = errors.New("datastore: concurrent transaction")

	// Done is returned by Iterator.Next when no more results are available.
	// This matches the official cloud.google.com/go/datastore API.
	//
	//nolint:revive,errname,staticcheck // Name must match official API (iterator.Done)
	Done = errors.New("datastore: no more items in iterator")
)

Functions

func TestConfig added in v0.6.0 

func TestConfig(ctx context.Context, metadataURL, apiURL string) context.Context

TestConfig creates a context with test configuration for the given URLs. This is a helper for tests to easily configure mock servers. Use this with context.Background() or any existing context.

Example: 

ctx := datastore.TestConfig(context.Background(), metadataURL, apiURL)
client, err := datastore.NewClient(ctx, "test-project")

func WithConfig added in v0.6.0 

func WithConfig(ctx context.Context, cfg *Config) context.Context

WithConfig returns a new context with the given datastore config. This also sets the auth config if provided.

Types

type Client 

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

Client is a Google Cloud Datastore client.

func NewClient 

func NewClient(ctx context.Context, projectID string) (*Client, error)

NewClient creates a new Datastore client. If projectID is empty, it will be fetched from the GCP metadata server. Configuration can be provided via WithConfig in the context.

func NewClientWithDatabase 

func NewClientWithDatabase(ctx context.Context, projID, dbID string) (*Client, error)

NewClientWithDatabase creates a new Datastore client with a specific database. Configuration can be provided via WithConfig in the context.

func NewMockClient 

func NewMockClient(t *testing.T) (client *Client, cleanup func())

NewMockClient creates a datastore client connected to mock servers with in-memory storage. This is a convenience wrapper for testing. Returns the client and a cleanup function that should be deferred.

func (*Client) AllKeys 

func (c *Client) AllKeys(ctx context.Context, q *Query) ([]*Key, error)

AllKeys returns all keys matching the query. This is a convenience method for KeysOnly queries.

func (*Client) AllocateIDs 

func (c *Client) AllocateIDs(ctx context.Context, keys []*Key) ([]*Key, error)

AllocateIDs allocates IDs for incomplete keys. Returns keys with IDs filled in. Complete keys are returned unchanged. API compatible with cloud.google.com/go/datastore.

func (*Client) Close 

func (*Client) Close() error

Close closes the client connection. This is a no-op for ds9 since it uses a shared HTTP client with connection pooling, but is provided for API compatibility with cloud.google.com/go/datastore.

func (*Client) Count 

func (c *Client) Count(ctx context.Context, q *Query) (int, error)

Count returns the number of entities matching the query. Deprecated: Use aggregation queries with RunAggregationQuery instead. API compatible with cloud.google.com/go/datastore.

func (*Client) Delete 

func (c *Client) Delete(ctx context.Context, key *Key) error

Delete deletes the entity with the given key.

func (*Client) DeleteAllByKind 

func (c *Client) DeleteAllByKind(ctx context.Context, kind string) error

DeleteAllByKind deletes all entities of a given kind. This method queries for all keys and then deletes them in batches.

func (*Client) DeleteMulti 

func (c *Client) DeleteMulti(ctx context.Context, keys []*Key) error

DeleteMulti deletes multiple entities with their keys. Returns MultiError if any keys are invalid. This matches the API of cloud.google.com/go/datastore.

func (*Client) Get 

func (c *Client) Get(ctx context.Context, key *Key, dst any) error

Get retrieves an entity by key and stores it in dst. dst must be a pointer to a struct. Returns ErrNoSuchEntity if the key is not found.

func (*Client) GetAll 

func (c *Client) GetAll(ctx context.Context, query *Query, dst any) ([]*Key, error)

GetAll retrieves all entities matching the query and stores them in dst. dst must be a pointer to a slice of structs, or nil for KeysOnly queries. Returns the keys of the retrieved entities and any error. This matches the API of cloud.google.com/go/datastore.

func (*Client) GetMulti 

func (c *Client) GetMulti(ctx context.Context, keys []*Key, dst any) error

GetMulti retrieves multiple entities by their keys. dst must be a pointer to a slice of structs. Returns MultiError with ErrNoSuchEntity for missing keys, or other errors for specific items. This matches the API of cloud.google.com/go/datastore.

func (*Client) Mutate 

func (c *Client) Mutate(ctx context.Context, muts ...*Mutation) ([]*Key, error)

Mutate applies one or more mutations atomically. API compatible with cloud.google.com/go/datastore.

func (*Client) NewTransaction 

func (c *Client) NewTransaction(ctx context.Context, opts ...TransactionOption) (*Transaction, error)

NewTransaction creates a new transaction. The caller must call Commit or Rollback when done. API compatible with cloud.google.com/go/datastore.

func (*Client) Put 

func (c *Client) Put(ctx context.Context, key *Key, src any) (*Key, error)

Put stores an entity with the given key. src must be a struct or pointer to struct. Returns the key (useful for auto-generated IDs in the future).

func (*Client) PutMulti 

func (c *Client) PutMulti(ctx context.Context, keys []*Key, src any) ([]*Key, error)

PutMulti stores multiple entities with their keys. keys and src must have the same length. Returns the keys (same as input) and MultiError if any operations failed. This matches the API of cloud.google.com/go/datastore.

func (*Client) Run 

func (c *Client) Run(ctx context.Context, q *Query) *Iterator

Run executes the query and returns an iterator for the results. API compatible with cloud.google.com/go/datastore.

func (*Client) RunInTransaction 

func (c *Client) RunInTransaction(ctx context.Context, f func(*Transaction) error, opts ...TransactionOption) (*Commit, error)

RunInTransaction runs a function in a transaction. The function should use the transaction's Get and Put methods. API compatible with cloud.google.com/go/datastore.

type Commit 

type Commit struct{}

Commit represents the result of a committed transaction. This is provided for API compatibility with cloud.google.com/go/datastore.

type Config added in v0.6.0 

type Config struct {
	// AuthConfig is passed to the auth package for authentication.
	// Can be nil to use defaults.
	AuthConfig *auth.Config

	// APIURL is the base URL for the Datastore API.
	// Defaults to production if empty.
	APIURL string
}

Config holds datastore client configuration.

type Cursor 

type Cursor string

Cursor represents a query cursor for pagination. API compatible with cloud.google.com/go/datastore.

func DecodeCursor 

func DecodeCursor(s string) (Cursor, error)

DecodeCursor decodes a cursor string. API compatible with cloud.google.com/go/datastore.

func (Cursor) String 

func (c Cursor) String() string

String returns the cursor as a string.

type Iterator 

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

Iterator is an iterator for query results. API compatible with cloud.google.com/go/datastore.

func (*Iterator) Cursor 

func (it *Iterator) Cursor() (Cursor, error)

Cursor returns the cursor for the iterator's current position. API compatible with cloud.google.com/go/datastore.

func (*Iterator) Next 

func (it *Iterator) Next(dst any) (*Key, error)

Next advances the iterator and returns the next key and destination. It returns Done when no more results are available. API compatible with cloud.google.com/go/datastore.

type Key 

type Key struct {
	Namespace string
	Parent    *Key // Parent key for hierarchical keys
	Kind      string
	Name      string // For string keys
	ID        int64  // For numeric keys
}

Key represents a Datastore key.

func DecodeKey 

func DecodeKey(encoded string) (*Key, error)

DecodeKey decodes a key from its opaque representation. API compatible with cloud.google.com/go/datastore.

func IDKey 

func IDKey(kind string, id int64, parent *Key) *Key

IDKey creates a new key with a numeric ID. The parent parameter can be nil for top-level keys. This matches the API of cloud.google.com/go/datastore.

func IncompleteKey 

func IncompleteKey(kind string, parent *Key) *Key

IncompleteKey creates a new incomplete key. The key will be completed (assigned an ID) when the entity is saved. API compatible with cloud.google.com/go/datastore.

func NameKey 

func NameKey(kind, name string, parent *Key) *Key

NameKey creates a new key with a string name. The parent parameter can be nil for top-level keys. This matches the API of cloud.google.com/go/datastore.

func (*Key) Encode 

func (k *Key) Encode() string

Encode returns an opaque representation of the key. API compatible with cloud.google.com/go/datastore.

func (*Key) Equal 

func (k *Key) Equal(other *Key) bool

Equal returns true if this key is equal to the other key. API compatible with cloud.google.com/go/datastore.

func (*Key) Incomplete 

func (k *Key) Incomplete() bool

Incomplete returns true if the key does not have an ID or Name. API compatible with cloud.google.com/go/datastore.

func (*Key) String 

func (k *Key) String() string

String returns a human-readable string representation of the key. API compatible with cloud.google.com/go/datastore.

type MultiError added in v0.7.0 

type MultiError []error

MultiError is returned by batch operations when there are errors with particular elements. Errors will be in a one-to-one correspondence with the input elements; successful elements will have a nil entry.

func (MultiError) Error added in v0.7.0 

func (m MultiError) Error() string

type Mutation 

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

Mutation represents a pending datastore mutation.

func NewDelete 

func NewDelete(k *Key) *Mutation

NewDelete creates a delete mutation. API compatible with cloud.google.com/go/datastore.

func NewInsert 

func NewInsert(k *Key, src any) *Mutation

NewInsert creates an insert mutation. API compatible with cloud.google.com/go/datastore.

func NewUpdate 

func NewUpdate(k *Key, src any) *Mutation

NewUpdate creates an update mutation. API compatible with cloud.google.com/go/datastore.

func NewUpsert 

func NewUpsert(k *Key, src any) *Mutation

NewUpsert creates an upsert mutation. API compatible with cloud.google.com/go/datastore.

type MutationOp 

type MutationOp string

MutationOp represents the type of mutation operation. 

const (
	// MutationInsert represents an insert operation.
	MutationInsert MutationOp = "insert"
	// MutationUpdate represents an update operation.
	MutationUpdate MutationOp = "update"
	// MutationUpsert represents an upsert operation.
	MutationUpsert MutationOp = "upsert"
	// MutationDelete represents a delete operation.
	MutationDelete MutationOp = "delete"
)

type PendingKey 

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

PendingKey represents a key that will be resolved after a transaction commit. API compatible with cloud.google.com/go/datastore.

type Query 

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

Query represents a Datastore query.

func NewQuery 

func NewQuery(kind string) *Query

NewQuery creates a new query for the given kind.

func (*Query) Ancestor 

func (q *Query) Ancestor(ancestor *Key) *Query

Ancestor sets an ancestor filter for the query. Only entities with the given ancestor will be returned. API compatible with cloud.google.com/go/datastore.

func (*Query) Distinct 

func (q *Query) Distinct() *Query

Distinct marks the query to return only distinct results. This is equivalent to DistinctOn with all projected fields. API compatible with cloud.google.com/go/datastore.

func (*Query) DistinctOn 

func (q *Query) DistinctOn(fieldNames ...string) *Query

DistinctOn returns a query that removes duplicates based on the given field names. API compatible with cloud.google.com/go/datastore.

func (*Query) End 

func (q *Query) End(c Cursor) *Query

End sets the ending cursor for the query results. API compatible with cloud.google.com/go/datastore.

func (*Query) Filter 

func (q *Query) Filter(filterStr string, value any) *Query

Filter adds a property filter to the query. The filterStr should be in the format "Property Operator" (e.g., "Count >", "Name ="). Deprecated: Use FilterField instead. API compatible with cloud.google.com/go/datastore.

func (*Query) FilterField 

func (q *Query) FilterField(fieldName, operator string, value any) *Query

FilterField adds a property filter to the query with explicit operator. API compatible with cloud.google.com/go/datastore.

func (*Query) KeysOnly 

func (q *Query) KeysOnly() *Query

KeysOnly configures the query to return only keys, not full entities.

func (*Query) Limit 

func (q *Query) Limit(limit int) *Query

Limit sets the maximum number of results to return.

func (*Query) Namespace 

func (q *Query) Namespace(ns string) *Query

Namespace sets the namespace for the query. API compatible with cloud.google.com/go/datastore.

func (*Query) Offset 

func (q *Query) Offset(offset int) *Query

Offset sets the number of results to skip before returning. API compatible with cloud.google.com/go/datastore.

func (*Query) Order 

func (q *Query) Order(fieldName string) *Query

Order sets the order in which results are returned. Prefix the property name with "-" for descending order (e.g., "-Created"). API compatible with cloud.google.com/go/datastore.

func (*Query) Project 

func (q *Query) Project(fieldNames ...string) *Query

Project sets the fields to be projected (returned) in the query results. API compatible with cloud.google.com/go/datastore.

func (*Query) Start 

func (q *Query) Start(c Cursor) *Query

Start sets the starting cursor for the query results. API compatible with cloud.google.com/go/datastore.

type Transaction 

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

Transaction represents a Datastore transaction. Note: This struct stores context for API compatibility with Google's official cloud.google.com/go/datastore library, which uses the same pattern.

func (*Transaction) Commit 

func (tx *Transaction) Commit() (*Commit, error)

Commit applies the transaction's mutations. API compatible with cloud.google.com/go/datastore.

func (*Transaction) Delete 

func (tx *Transaction) Delete(key *Key) error

Delete deletes an entity within the transaction. API compatible with cloud.google.com/go/datastore.

func (*Transaction) DeleteMulti 

func (tx *Transaction) DeleteMulti(keys []*Key) error

DeleteMulti deletes multiple entities within the transaction. API compatible with cloud.google.com/go/datastore.

func (*Transaction) Get 

func (tx *Transaction) Get(key *Key, dst any) error

Get retrieves an entity within the transaction. API compatible with cloud.google.com/go/datastore.

func (*Transaction) GetMulti 

func (tx *Transaction) GetMulti(keys []*Key, dst any) error

GetMulti retrieves multiple entities within the transaction. API compatible with cloud.google.com/go/datastore.

func (*Transaction) Mutate 

func (tx *Transaction) Mutate(muts ...*Mutation) ([]*PendingKey, error)

Mutate adds one or more mutations to the transaction. API compatible with cloud.google.com/go/datastore.

func (*Transaction) Put 

func (tx *Transaction) Put(key *Key, src any) (*Key, error)

Put stores an entity within the transaction.

func (*Transaction) PutMulti 

func (tx *Transaction) PutMulti(keys []*Key, src any) ([]*Key, error)

PutMulti stores multiple entities within the transaction. API compatible with cloud.google.com/go/datastore.

func (*Transaction) Rollback 

func (tx *Transaction) Rollback() error

Rollback abandons the transaction. API compatible with cloud.google.com/go/datastore.

type TransactionOption 

type TransactionOption interface {
	// contains filtered or unexported methods
}

TransactionOption configures transaction behavior.

func MaxAttempts 

func MaxAttempts(n int) TransactionOption

MaxAttempts returns a TransactionOption that specifies the maximum number of times a transaction should be attempted before giving up.

func WithReadTime 

func WithReadTime(t time.Time) TransactionOption

WithReadTime returns a TransactionOption that sets a specific timestamp at which to read data, enabling reading from a particular snapshot in time.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.