Class SpriteServer

When you close a database in ArcadeDB, it:

1. Frees up resources on the server: The database instance is released, and the associated resources, such as memory, threads, and file handles, are returned to the system. This helps to reduce the server's memory footprint and free up resources for other tasks.
2. Releases it from RAM: The database instance is removed from the server's RAM, which means that the database's metadata, schema, and cached data are no longer stored in memory. This helps to reduce memory usage.
3. Prevents further operations: Once the database is closed, users can no longer perform operations on the database, such as executing queries, creating new records, or modifying existing data. The database is effectively "offline" until it's reopened.

Example

const server = new SpriteServer({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
});

async function closeDatabaseExample(databaseName: string) {
  try {
    const closed = await server.closeDatabase(databaseName);
    console.log(closed);
    // true
  } catch (error) {
    // manage error conditions
    console.error(error);
  }
};

closeDatabaseExample('aDatabase');
Copy

Sends a command to the ArcadeDB server and returns the response.

This method provides a way to execute arbitrary commands on the server, such as creating databases, executing queries, or performing administrative tasks.

Throws

If the command fails to execute, an error will be thrown with a message describing the problem. The error object will contain a cause property with the underlying error.

Example

const server = new SpriteServer({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
});

async function commandExample(databaseName: string) {
  try {
    const response = await server.command(`CREATE DATABASE ${databaseName}`);
    console.log(response);
    // {
    //   user: 'aUser',
    //   version: '24.x.x',
    //   serverName: 'ArcadeDB_0',
    //   result: 'ok'
    // }
  } catch (error) {
    // Will throw an error for conditions such as:
    // Invalid credentials, Database Already Exists, etc.
    console.error(error);
    // {
    //   message: 'Encountered an error when sending a command to the server.',
    //   cause: Error: Invalid credentials
    // }
  }
}

commandExample('aDatabase');
Copy

Connects this server to a cluster with address.

Throws

Error if the cluster could not be connected.

Example

const server = new SpriteServer({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
});

async function connectClusterExample(address: string) {
  try {
    const connected = await server.connectCluster(address);
    console.log(connected);
    // true
  } catch (error) {
    console.log(error);
    // handle error conditions
  }
}

connectClusterExample('192.168.0.1');
Copy

Create a database

Example

const server = new SpriteServer({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
});

async function createDatabaseExample(databaseName: string) {
  try {
    const database = await server.createDatabase(databaseName);
    console.log(database.name);
    // 'aDatabase'
  } catch (error) {
    console.log(error);
    // handle error conditions
  }
}

createDatabaseExample('aDatabase');
Copy

Create a user. username, password, and access controls to multiple databases can be established using the databases property of the input parameters. The databases object uses 'groups' to grant access controls. Assigning a user to groups within a specific database grants them the permissions associated with those groups for a particular database.

Throws

Error if the user could not be created.

Example

const server = new SpriteServer({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
});

async function createUserExample(details: ISpriteCreateArcadeUser) {
  try {
    const created = await server.createUser(details);
    console.log(created);
    // true
  } catch (error) {
    console.error(error);
    // handle error conditions
  }
}

createUserExample({
  username: 'myUsername',
  password: 'myPassword',
  databases: {
    "FirstDatabase": "admin"
    "SecondDatabase": "user"
  }
});
Copy

Returns a SpriteDatabase instance for the supplied databaseName, using the authorization details of the SpriteServer instance.

Example

const server = new SpriteServer({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
});

async function databaseExample() {
  try {
    const database = await server.database('aDatabase');
    // returns an instance of SpriteDatabase
    console.log(database.name);
  } catch (error) {
    // handle errors
    console.error(error);
  }
};

databaseExample();
Copy

Disconnects the server from the cluster.

Throws

Error if the cluster could not be disconnected.

Example

const server = new SpriteServer({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
});

async function disconnectClusterExample() {
  try {
    const disconnected = await server.disconnectCluster();
    console.log(disconnected);
    // true
  } catch (error) {
    console.error(error);
    // handle error condition
  }
}

disconnectClusterExample();
Copy

Drop a database

Throws

Error if the database could not be dropped.

Example

const server = new SpriteServer({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
});

async function dropDatabaseExample(databaseName: string) {
  try {
    const dropped = await server.dropDatabase(databaseName);
    console.log(dropped);
    // true
  } catch (error) {
    console.error(error);
    // handle error condition
  }
}

dropDatabaseExample('aDatabase');
Copy

Drop a user from the ArcadeDB server.

Throws

Error if the user could not be dropped.

Example

const server = new SpriteServer({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
});

async function dropUserExample(username: string) {
  try {
    const dropped = await server.dropUser(username);
    console.log(dropped);
    // true
  } catch (error) {
    console.error(error);
    // handle error condition
  }
}

dropUserExample('aUser');
Copy

Retrieves a list of server events, optionally a filename of the form server-event-log-yyyymmdd-HHMMSS.INDEX.jsonl (where INDEX is a integer, i.e. 0) can be given to retrieve older event logs.

Throws

Error if there was a problem fetching the event logs.

Example

const server = new SpriteServer({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
});

async function getServerEventsExample() {
  try {
    const events = await server.getServerEvents();
    console.log(events);
    // {
    //    events: [
    //      {
    //        "time":"2024-01-30 06:37:20.325",
    //        "type":"INFO","component":"Server",
    //        "message":"ArcadeDB Server started in \\u0027development\\u0027 mode (CPUs\\u003d8 MAXRAM\\u003d3.84GB)"}]
    //      }
    //    ],
    //    files: [
    //      "server-event-log-20240205-060106.13.jsonl",
    //      "server-event-log-20240204-185020.12.jsonl",
    //      "server-event-log-20240204-063235.11.jsonl",
    //      "server-event-log-20240131-205254.10.jsonl",
    //      "server-event-log-20240130-133802.9.jsonl"
    //    ]
    // }
  } catch (error) {
    console.error(error);
    // handle error condition
  }
}

getServerEventsExample();
Copy

Returns the current configuration.

Throws

Error if the information could not be retrieved.

Example

const server = new SpriteServer({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
});

async function getInformationExample(mode: ArcadeServerInformationLevel) {
  try {
    const information = await sprite.getInformation(mode);
    console.log(information);
    // {
    //   user: 'aUser',
    //   version: '24.x.x',
    //   serverName: 'ArcadeDB_0'
    // }
  } catch (error) {
    console.error(error);
    // handle error condition
  }
}

getInformationExample('basic');
Copy

Returns a list of database names that are present on the server.

Throws

Error if the database list could not be retrieved.

Example

const server = new SpriteServer({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
});

async function listDatabasesExample() {
  try {
    const list = await sprite.listDatabases();
    console.log(list);
    // [ 'databaseName' ]
  } catch (error) {
    console.error(error);
    // handle error condition
  }
}

listDatabasesExample();
Copy

When you "open" a database in ArcadeDB, it means you're creating an instance of the database in memory, allocating resources, and making the database available for operations. Here's what happens when you open a database:

1. Create a new database instance: A new database instance is created in memory, which includes the database's metadata, schema, and cached data. This instance is used to manage the database's resources and provide access to the data.
2. Allocate resources: The database instance allocates the necessary resources, such as memory, threads, and file handles, to support the database's operations. This ensures that the database has the necessary resources to handle incoming requests.
3. Load database metadata and schema: The database's metadata and schema are loaded into memory, which includes information about the database's structure, indexes, and relationships.
4. Connect to the underlying storage: The database instance establishes a connection to the underlying storage, such as disk storage, to access the database files.
5. Make the database available for operations: The database is now available for users to perform operations, such as executing queries, creating new records, or modifying existing data.

Example

const server = new SpriteServer({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
});

async function openDatabaseExample(databaseName: string) {
  try {
    const open = await server.openDatabase(databaseName);
    console.log(open);
    // true
  } catch (error) {
    // handle errors
    console.error(error);
  }
};

openDatabaseExample('aDatabase');
Copy

Returns a boolean value indicating if the ArcadeDB server is ready.
Useful for remote monitoring of server readiness.

Example

const client = new SpriteServer({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
});

async function serverReadyExample() {
  try {
    const ready = await client.serverReady();
    if (ready) {
      console.log(ready);
      // true;
    }
  } catch (error) {
    throw new Error(
      'An error occurred while running example.',
      { cause: error }
    );
  }
}

serverReadyExample();
Copy

Gracefully shutdown the server.
TODO: This works, in that it does shutdown the server, but the fetch throws before it resolves, guessing because the server is shutting down. A CURL, however, returns an empty 204 response as the documentation indicates.

Throws

Error if there is a problem attempting the shutdown.

Example

const server = new SpriteServer({
  username: 'aUser',
  password: 'aPassword',
  address: 'http://localhost:2480',
});

async function shutdownExample() {
  try {
    const shutdown = await server.shutdown();
    console.log(shutdown);
  } catch (error) {
    console.error(error);
    // handle error condition
  }
}

shutdownExample();
Copy