Module neug.database

The Neug database module.

Database Objects

class Database

The entrance of the Neug database. (Only AP mode is supported.)

This class is used to open a database connection and manage the database. User should use this class to open a database connection, and then use the connect method to get a Connection object to interact with the database.

By passing an empty string as the database path, the database will be opened in memory mode.

The database could be opened with different modes(read-only or read-write) and different buffer strategies.

When the database is opened in read-only mode, other databases could also open the same database directory in read-only mode, inside the same process or in different processes. When the database is opened in read-write mode, no other databases could open the same database directory in either read-only or read-write mode, inside the same process or in different processes.

Note that opening a database in read-only mode still requires a writable data directory: the lock file is created on demand if missing, and read-only processes create temporary working files in their own runtime/open-<epoch>/ directory. Read-only mode cannot be used on a read-only file system or mount.

When the database is closed, all the connections to the database will be closed automatically.

 
    const { Database } = require('neug');
    const db = new Database({ databasePath: '/tmp/test.db', mode: 'w' });
    const conn = db.connect();
 
    // Use the connection to interact with the database
    conn.execute('CREATE NODE TABLE Person(id INT64, name STRING, PRIMARY KEY(id));');
    conn.execute('CREATE REL TABLE KNOWS(FROM Person TO Person, weight DOUBLE);');
 
    // Import data from csv file.
    conn.execute('COPY Person FROM "person.csv"');
    conn.execute('COPY KNOWS FROM "knows.csv" (from="Person", to="Person");');
 
    const res = conn.execute('MATCH(n) RETURN n.id;');
    for (const row of res) {
        console.log(row);
    }
 

constructor

constructor(options = {}) {
  const {
    databasePath = null,
    mode = 'read-write',
    maxThreadNum = 0,
    checkpointOnClose = true,
    bufferStrategy = 'M_FULL',
  } = options;
}

Open a database.

• Parameters:

  • options (Object) Database configuration options.

  • options.databasePath (string | null) Path to the database file. Default is null. If it is set to empty string ('') or null, the database will be opened in memory mode. Note that in memory mode, the database will not be persisted to disk, and all data will be lost when the program exits. Note: null cannot be combined with read-only mode; '' (empty string) can.

  • options.mode (string) Mode to open the database. Supported values: ‘r’, ‘read’, ‘read-only’, ‘read_only’, ‘w’, ‘rw’, ‘write’, ‘readwrite’, ‘read-write’, ‘read_write’. Default is ‘read-write’.

  • options.maxThreadNum (number) Database query capacity; 0 selects hardware concurrency (fallback 1), while higher inputs warn and clamp to it.

    Embedded (AP) queries are currently single-threaded; using this setting for intra-query parallelism is future work.

    In TP mode, it sizes the slot pool and caps service threads. Queries run concurrently; each uses one slot/thread.

  • options.checkpointOnClose (boolean) Whether to automatically create a checkpoint when the database is closed. Default is true. If false, no checkpoint is created automatically when close the database.

  • options.bufferStrategy (string) Buffer strategy to use for the database, could be ‘InMemory’ (or ‘M_FULL’), ‘SyncToFile’ (or ‘M_LAZY’) or ‘HugePagePreferred’ (or ‘M_HUGE’). Default is ‘M_FULL’.

    • ‘InMemory’ / ‘M_FULL’: The database will be opened fully in memory, and the changes will not be persisted to disk until checkpoint is created.
    • ‘SyncToFile’ / ‘M_LAZY’: The database will be opened in memory on demand, suitable for large databases that cannot fit into memory. Also changes will not be persisted to disk until checkpoint is created.
    • ‘HugePagePreferred’ / ‘M_HUGE’: Similar to ‘InMemory’, but it will try to use huge pages for memory allocation, which may improve performance for large databases.

• Throws:

  • Error (ERR_INVALID_PATH) If the database path contains illegal characters.
  • Error (ERR_INVALID_ARGUMENT) If the mode is not one of the supported modes. If maxThreadNum exceeds the number of CPU cores. If in-memory mode is opened with read-only mode.
  • Error (ERR_CONFIG_INVALID) If maxThreadNum is negative.

version

get version() -> string

Get the version of the database.

mode

get mode() -> string

Get the mode of the database.

• Returns:
  • string The mode of the database, could be ‘r’, ‘read’, ‘w’, ‘rw’, ‘write’, ‘readwrite’, ‘read-write’, ‘read-only’.

connect

connect() -> Connection

Connect to the database.

• Returns:
  • Connection A Connection object to interact with the database.
• Throws:
  • Error If the database is closed.

asyncConnect

asyncConnect() -> AsyncConnection

Connect to the database asynchronously.

• Returns:
  • AsyncConnection An AsyncConnection object to interact with the database asynchronously.
• Throws:
  • Error If the database is closed.

close

close()

Close the database and release all resources. All open connections and async connections will be closed automatically.

For a read-write database with checkpointOnClose: true, this method creates a checkpoint before releasing the database resources. Automatic checkpoint creation is best effort: failures are logged and do not propagate to the caller.