Database#

A database stores entities and their transactions. Documents and expression programs can operate without a database. The example opens a database, lists its included plugins, and closes it. The plugins option selects the plugins that the database enables. The reactors plugin runs live mutations.

Example#

Open a database and retain an independent native document#

opened, err := stardust.Open(databasePath, stardust.Options{})
if err != nil {
	return err
}

// Closing the database leaves the plugin document valid.
result, err := stardust.Plugins()
opened.Close()
if err != nil {
	return err
}
defer result.Close()

[{name            reactors
  description     Live mutations: stored mutations with live: true react to commits
  version         '1'
  requires        []
  definitionTypes []
  hooks           []
  indexProviders  []
  databaseHooks   true}]

Locking#

Opening a database requires the file lock that protects its recorded changes. The lock_timeout option sets how the call waits for that lock:

When the wait ends without the lock, the call fails with the locked status. The options table gives the default and the type in your language.

Operations#

Open#

open(path, options) opens a database.

• The create option defaults to true.
• A false value refuses a missing file.
• A missing parent directory reports not_found.

The lock_timeout option is a duration.

• Zero fails at once.
• A representable negative value waits without limit.

An absent plugin selection enables all included plugins.

• An empty selection enables none.

func Open(path string, options Options) (*Database, error)

• Concurrency: Other calls can overlap this call, except the release of a handle that this call uses.
• Ownership: The caller owns the returned handle and releases it.

Parameters#

Errors#

Examples#

Open a database and retain an independent native document#

opened, err := stardust.Open(databasePath, stardust.Options{})
if err != nil {
	return err
}

// Closing the database leaves the plugin document valid.
result, err := stardust.Plugins()
opened.Close()
if err != nil {
	return err
}
defer result.Close()

[{name            reactors
  description     Live mutations: stored mutations with live: true react to commits
  version         '1'
  requires        []
  definitionTypes []
  hooks           []
  indexProviders  []
  databaseHooks   true}]

Open with explicit native options#

create := true
result := stardust.Options{Create: &create, PageSize: 0}
database, err := stardust.Open(databasePath, result)
if err != nil {
	return err
}
defer database.Close()

{create            true
 clear             false
 pin_memory        false
 page_size         0
 lock_timeout      0
 initial_map_bytes 0
 commit_batch      0
 plugins           null}

Wait for the database lock without a limit#

create := true
result := stardust.Options{Create: &create, PageSize: 0, LockTimeout: -time.Nanosecond}
database, err := stardust.Open(databasePath, result)
if err != nil {
	return err
}
defer database.Close()

{create            true
 clear             false
 pin_memory        false
 page_size         0
 lock_timeout      null
 initial_map_bytes 0
 commit_batch      0
 plugins           null}

C exports: stardust_db_open

Database.Close#

Release the database handle.

close(handle) releases the handle.

• Do not use it after closure.
• Result documents remain usable after the handle that produces them closes.

func (d *Database) Close()

• Concurrency: This call is the last use of the receiver and ends its ownership.

Examples#

Open a database and retain an independent native document#

opened, err := stardust.Open(databasePath, stardust.Options{})
if err != nil {
	return err
}

// Closing the database leaves the plugin document valid.
result, err := stardust.Plugins()
opened.Close()
if err != nil {
	return err
}
defer result.Close()

[{name            reactors
  description     Live mutations: stored mutations with live: true react to commits
  version         '1'
  requires        []
  definitionTypes []
  hooks           []
  indexProviders  []
  databaseHooks   true}]

C exports: stardust_db_close

options#

This record supplies options for open. The zero value selects every default.