lungo

Lungo is a MongoDB-compatible embeddable database for Go. It is composed of several specialized packages:

• lungo: The main package implementing the embeddable database and the mongo compatible driver. It manages access to collections via an engine and transaction types.
• mongokit: Provides MongoDB data handling algorithms, including querying, updating, sorting, and a B-tree based index for documents. It provides the core mongokit.Collection CRUD interface.
• bsonkit: Extends the official bson package with utilities to inspect, compare, convert, transform, clone, and manipulate BSON data in memory.
• dbkit: Provides database-centric utilities, such as atomic file writes.

Most users should interact with the generic driver interface provided by the lungo package to achieve drop-in compatibility with applications written for official MongoDB deployments.

Lungo supports multi-document transactions using a copy-on-write mechanism:

1. Every transaction creates a copy of the catalog and clones namespaces before applying changes.
2. Once the new catalog is written to disk, the transaction is considered successful and the catalog is replaced.
3. Concurrency: Read-only transactions run in parallel as snapshots. Write transactions run sequentially using pessimistic concurrency control to prevent abortions due to conflicts.

To install the lungo package, use the standard Go toolchain:

go get -u github.com/256dpi/lungo

$ go get -u github.com/256dpi/lungo

A Transaction buffers multiple changes to a Catalog. It provides a thread-safe way to perform CRUD operations, index management, and namespace management. Operations within a transaction are applied to a cloned version of the catalog, and the transaction is marked as dirty if changes occur. Use NewTransaction(catalog *Catalog) to initialize a new transaction.

import "github.com/256dpi/lungo"

tx := lungo.NewTransaction(myCatalog)
// Perform operations...
if tx.Dirty() {
    // Apply changes to the main catalog
}

Lungo provides two ways to manage sessions:

1. Manual Session Management: Use StartSession to get an ISession. You can then manually call CommitTransaction, AbortTransaction, or EndSession.
2. Session Callback: Use UseSession or UseSessionWithOptions to execute a function within a session context. This is useful for ensuring sessions are properly managed.
3. Transactions: Use WithTransaction on an ISession to execute a function within a managed transaction. If the function returns an error, the transaction is aborted; otherwise, it is committed.

// Example: Using a transaction
session, _ := client.StartSession()
result, err := session.WithTransaction(ctx, func(sc ISessionContext) (interface{}, error) {
    // Perform database operations using sc
    return nil, nil
})

Lungo's Index implements multikey indexing to mirror MongoDB's behavior. When a document contains an array at an indexed path, the index expands that document into multiple entries—one for each element in the array.

If multiple columns in a compound index point to arrays, the index generates the Cartesian product of all array elements to ensure all combinations are indexed.

Example: If an index is on tags and categories, and a document has tags: ["a", "b"] and categories: ["x", "y"], the index will store entries for (a, x), (a, y), (b, x), and (b, y).

The Store interface defines the contract for storage adapters in Lungo. Any type implementing this interface can be used to persist and retrieve the Catalog. It requires two methods:

• Load() (*Catalog, error): Retrieves the current catalog.
• Store(*Catalog) error: Persists the provided catalog.

Lungo provides two built-in implementations: MemoryStore for in-memory operations and FileStore for disk-based persistence.

The lungo.Store interface allows for different storage backends:

• MemoryStore: Keeps all data in memory (volatile).
• FileStore: Writes all data atomically to a single BSON file (persistent).

Developers can implement custom adapters by satisfying the lungo.Store interface.

The Cursor struct implements the ICursor interface, ensuring compatibility with MongoDB-style driver patterns in Lungo.

Note the following behaviors:

• Thread Safety: The Cursor uses a sync.Mutex to ensure that methods like Next, Decode, and All are safe for concurrent use.
• Closing Behavior: Once All or Close is called, the cursor is marked as closed. Subsequent calls to Next or All will return errors or false.
• No-op Methods: For compatibility with the ICursor interface, the following methods are implemented as no-ops:
  • SetBatchSize(int32)
  • SetComment(interface{})
  • SetMaxTime(time.Duration)
  • ID() int64 (always returns 0)
  • Err() error (always returns nil)
  • TryNext(ctx context.Context) (alias for Next)

The Index type is not thread-safe and does not support automatic rollbacks on errors. To safely perform mutations, it is recommended to use the Clone() method to create a copy of the index before making changes.

newIndex := index.Clone()
// Perform mutations on newIndex safely