class LMDB::Environment

Overview

Class for an LMDB database environment. An environment may contain multiple databases, all residing in the same shared-memory map and underlying disk file. A database is a key-value table.

An environment, and its databases, is usually stored in a directory which contains two files:

To write to the environment a Transaction must be created. One simultaneous write transaction is allowed, however there is no limit on the number of read transactions even when a write transaction exists.

Example:

env = LMDB.new "mydbdir"
db = env.database "mydb"
# ...
env.close

Included Modules

Defined in:

lmdb/environment.cr

Constructors

Instance Method Summary

Instance methods inherited from module LMDB::Disposable

close close, closed? closed?

Constructor Detail

def self.new(path : String, flags : Flag = Flag::NoTls, mode : FileMode = FileMode.new(420), max_dbs : Int = 0, map_size : Int = 0) #

Create and opens a new Environment under path with given options.

  • max_dbs: sets the maximum number of named databases in the environment.
  • mode: the POSIX permissions to set on created files.
  • map_size: sets the size of the memory map to be allocated for this environment, in bytes. The size should be a multiple of the OS page size. The default is 10485760 bytes. The size of the memory map is also the maximum size of the database.

[View source]

Instance Method Detail

def clear_flags(flags : Flag) #

Clears environment flags.


[View source]
def database(flags : Database::Flag = LMDB.db_flags(None)) : Database #

Opens and returns the main Database associated with self. Each environment has an unnamed database.

A database needs to be opened (or created) within a transaction. If a pending transaction for this environment exists, it will be used for this purpose. Otherwise, a new ReadOnlyTransaction is created.

If a transaction is created specifically, it will be commited before the Database is returned. Otherwise, no particular action on the existing pending transaction is performed.


[View source]
def database(flags : Database::Flag = LMDB.db_flags(None), &) #

Opens and yields the main Database associated with self. Each environment has an unnamed database.

A database needs to be opened (or created) within a transaction. If a pending transaction for this environment exists, it will be used for this purpose. Otherwise, a new ReadOnlyTransaction is created.

If a transaction is created specifically, it will be commited when the block goes out of scope. Otherwise, no particular action on the existing pending transaction is performed.


[View source]
def database(name : String, flags : Database::Flag = LMDB.db_flags(None)) : Database #

Opens and returns the a named Database associated with self. If the database is newly created, it will not be available in other transactions until the transaction that is creating the database commits. If the transaction creating the database aborts, the database is not created.

A database needs to be opened (or created) within a transaction. If a pending transaction for this environment exists, it will be used for this purpose. Otherwise, a new Transaction is created.

If a transaction is created specifically, it will be commited before the Database is returned. Otherwise, no particular action on the existing pending transaction is performed.


[View source]
def database(name : String, flags : Database::Flag = LMDB.db_flags(None), &) #

Opens and yields the a named Database associated with self. If the database is newly created, it will not be available in other transactions until the transaction that is creating the database commits. If the transaction creating the database aborts, the database is not created.

A database needs to be opened (or created) within a transaction. If a pending transaction for this environment exists, it will be used for this purpose. Otherwise, a new Transaction is created.

If a transaction is created specifically, it will be commited before the Database is returned. Otherwise, no particular action on the existing pending transaction is performed.


[View source]
def database?(name : String, flags : Database::Flag = LMDB.db_flags(Create)) #

Opens and returns a named Database associated with self. Create the database if it does not exist.


[View source]
def database?(name : String, flags : Database::Flag = LMDB.db_flags(Create), &) #

Opens and yields the a named Database associated with self. Create the database if it does not exist.


[View source]
def do_close #

Close the environment and release the memory map when self is disposed (see #close).


[View source]
def drop(db : Database) #

Remove the given Database.


[View source]
def dump(to path : String, compact : Bool = false) #

Copy the database to another database, at the given path. This may be used to backup an existing environment.

If compact flag is set to true, compaction is performed while copying: free pages are omitted and all pages are sequentially renumbered in output. This option consumes more CPU and runs more slowly than the default.


[View source]
def finalize #

[View source]
def flags : Flag #

Get environment flags.


[View source]
def flags=(flags : Flag) #

Set environment flags.


[View source]
def info : LibLMDB::Envinfo #

Returns raw information about self.


[View source]
def map_size=(size) #

Set the memory map size to use for self.

The size should be a multiple of the OS page size. This method may be called if no transactions are active.


[View source]
def max_key_size #

Returns the maximum size of keys that can be written.


[View source]
def path : String #

Returns the path to the database environment files.


[View source]
def stat : LibLMDB::Stat #

Returns raw statistics about self.


[View source]
def sync(force : Bool) #

Flush the data buffers to disk.


[View source]
def to_unsafe : Pointer(Void) #

[View source]
def transaction(on db : Database | Nil = nil, readonly : Bool = false, &) #

Create and yields a transaction for use with the environment.

The transaction commits when the block goes out of scope. It is aborted if an exception is raised or if an explicit call to Transaction#abort is made.


[View source]
def transaction(on db : Database | Nil = nil, readonly : Bool = false) #

Create a transaction for use with the environment.


[View source]