### Initialize Project and Install TypeScript

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/api-docs/04.typescript.md

Basic setup for a Node.js project using TypeScript, including initialization and configuration.

```bash
mkdir my_agdb
cd my_agdb
npm init # follow the steps & prompts
```

```bash
npm install typescript --save-dev
```

```json
{
  "compilerOptions": {
    "module": "ESNext",
    "sourceMap": true,
    "lib": ["ES2015", "DOM"],
    "moduleResolution": "node",
    "allowJs": true,
    "esModuleInterop": true
  }
}
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/README.md

Run this command to install all necessary project dependencies.

```bash
pnpm install
```

--------------------------------

### Start Development Server with pnpm

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/README.md

Starts the development server, typically accessible at http://localhost:3000.

```bash
pnpm dev
```

--------------------------------

### Install Rust

Source: https://github.com/agnesoft/agdb/blob/main/AGENTS.md

Installs Rust using the official script. Assumes curl is available.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Start development server

Source: https://github.com/agnesoft/agdb/blob/main/agdb_studio/README.md

Compiles the project and enables hot-reload for development.

```sh
pnpm run dev
```

--------------------------------

### Install agdb_server with Cargo

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/01.guides/03.how-to-run-server/01.server-bare-metal.md

Installs the agdb_server using Cargo, with optional features for TLS and Studio. Ensure Rust is installed.

```shell
cargo install agdb_server --features "tls studio"
```

--------------------------------

### Install pnpm

Source: https://github.com/agnesoft/agdb/blob/main/AGENTS.md

Installs pnpm globally using npm. Assumes npm is installed and available.

```bash
npm i -g pnpm
```

--------------------------------

### Install project dependencies

Source: https://github.com/agnesoft/agdb/blob/main/agdb_studio/README.md

Installs all project dependencies using the frozen lockfile to ensure consistency.

```sh
pnpm install --frozen-lockfile
```

--------------------------------

### Run agdb_server

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/01.guides/03.how-to-run-server/01.server-bare-metal.md

Starts the agdb_server. The server will create configuration and data directories in its working directory upon startup.

```bash
agdb_server
```

--------------------------------

### Run PHP API Client Tests

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/README.md

Commands to install dependencies and execute the test suite.

```bash
composer install
vendor/bin/phpunit
```

--------------------------------

### dbConvert Usage Example

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/docs/Api/AgdbApi.md

Demonstrates how to configure the API client and invoke the dbConvert method with required parameters.

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer authorization: Token
$config = Agnesoft
AgdbApi\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Agnesoft\AgdbApi\Api\AgdbApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$owner = 'owner_example'; // string | user name
$db = 'db_example'; // string | db name
$db_type = new \Agnesoft\AgdbApi\Model\\Agnesoft\AgdbApi\Model\DbKind(); // \Agnesoft\AgdbApi\Model\DbKind

try {
    $apiInstance->dbConvert($owner, $db, $db_type);
} catch (Exception $e) {
    echo 'Exception when calling AgdbApi->dbConvert: ', $e->getMessage(), PHP_EOL;
}
```

--------------------------------

### Start agdb_server Node

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/01.guides/03.how-to-run-server/04.cluster-bare-metal.md

Command to start an agdb_server node from its respective directory. It is recommended to run each node in its own shell for log monitoring.

```bash
cd ~/agdb_cluster/node0/ #run each node in its respective directory
agdb_server
```

--------------------------------

### adminUserChangePassword Usage Example

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/docs/Api/AgdbApi.md

Example demonstrating how to configure the API client and call the adminUserChangePassword method.

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer authorization: Token
$config = Agnesoft\AgdbApi\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Agnesoft\AgdbApi\Api\AgdbApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$username = 'username_example'; // string | user name
$user_credentials = new \Agnesoft\AgdbApi\Model\UserCredentials(); // \Agnesoft\AgdbApi\Model\UserCredentials

try {
    $apiInstance->adminUserChangePassword($username, $user_credentials);
} catch (Exception $e) {
    echo 'Exception when calling AgdbApi->adminUserChangePassword: ', $e->getMessage(), PHP_EOL;
}
```

--------------------------------

### Install Playwright

Source: https://github.com/agnesoft/agdb/blob/main/AGENTS.md

Installs Playwright browsers. Only needed for TypeScript end-to-end tests.

```bash
pnpm exec playwright install
```

--------------------------------

### Example Usage of adminDbUserAdd

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/docs/Api/AgdbApi.md

Demonstrates how to configure the API client and call the adminDbUserAdd method.

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer authorization: Token
$config = Agnesoft
AgdbApi
Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Agnesoft
AgdbApi
Api
AgdbApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp
ClientInterface`.
    // This is optional, `GuzzleHttp
Client` will be used as default.
    new GuzzleHttp
Client(),
    $config
);
$owner = 'owner_example'; // string | db owner user name
$db = 'db_example'; // string | db name
$username = 'username_example'; // string | user name
$db_role = new \Agnesoft
AgdbApi
Model\\Agnesoft
AgdbApi
Model
DbUserRole(); // \Agnesoft
AgdbApi
Model
DbUserRole

try {
    $apiInstance->adminDbUserAdd($owner, $db, $username, $db_role);
} catch (Exception $e) {
    echo 'Exception when calling AgdbApi->adminDbUserAdd: ', $e->getMessage(), PHP_EOL;
}
```

--------------------------------

### Setup agdb for Multithreaded Use

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/03.references/05.efficient-agdb.md

Initializes a new agdb database file, sets up root, users, and posts nodes, and connects them to the root. Designed for multithreaded access using Arc and RwLock.

```rust
fn create_db() -> Result<Arc<RwLock<Db>>, DbError> {
    let db = Arc::new(RwLock::new(Db::new("social.agdb")?));
    db.write()?.transaction_mut(|t| -> Result<(), DbError> {
        t.exec_mut(
            QueryBuilder::insert()
                .nodes()
                .aliases(["root", "users", "posts"])
                .query(),
        )?;
        t.exec_mut(
            QueryBuilder::insert()
                .edges()
                .from("root")
                .to(["users", "posts"])
                .query(),
        )?;
        Ok(())
    })?;

    Ok(db)
}
```

--------------------------------

### Install agdb_api Package

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/api-docs/04.typescript.md

Add the agdb_api package as a project dependency.

```bash
npm install @agnesoft/agdb_api
```

--------------------------------

### Install TypeScript Dependencies

Source: https://github.com/agnesoft/agdb/blob/main/AGENTS.md

Installs TypeScript dependencies using pnpm, ensuring the lockfile is frozen.

```bash
pnpm i --frozen-lockfile
```

--------------------------------

### Add Admin User PHP Example

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/docs/Api/AgdbApi.md

Demonstrates initializing the AgdbApi client with Bearer token authentication and calling the adminUserAdd method.

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer authorization: Token
$config = Agnesoft\\\AgdbApi\\\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Agnesoft\\\AgdbApi\\\Api\\\AgdbApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\\\ClientInterface`.
    // This is optional, `GuzzleHttp\\\Client` will be used as default.
    new GuzzleHttp\\\Client(),
    $config
);
$username = 'username_example'; // string | desired user name
$user_credentials = new \\Agnesoft\\\AgdbApi\\\Model\\\UserCredentials(); // \\Agnesoft\\\AgdbApi\\\Model\\\UserCredentials

try {
    $apiInstance->adminUserAdd($username, $user_credentials);
} catch (Exception $e) {
    echo 'Exception when calling AgdbApi->adminUserAdd: ', $e->getMessage(), PHP_EOL;
}
```

--------------------------------

### GET /api/v1

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/03.references/02.server.md

Serves the RapiDoc OpenAPI GUI for interactive API exploration.

```APIDOC
## GET /api/v1

### Description
Serves the RapiDoc OpenAPI GUI. This endpoint is intended to be accessed via a web browser.

### Method
GET

### Endpoint
/api/v1
```

--------------------------------

### Run PHP Client Program

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/api-docs/03.php.md

Executes the main PHP client script. Ensure the agdb server is running and dependencies are installed.

```bash
php src/index.php
```

--------------------------------

### Composer Configuration

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/README.md

Add this configuration to your composer.json file to install the library dependencies.

```json
{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/GIT_USER_ID/GIT_REPO_ID.git"
    }
  ],
  "require": {
    "GIT_USER_ID/GIT_REPO_ID": "*@dev"
  }
}
```

--------------------------------

### QueryBuilder Condition Examples

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/03.references/01.queries.md

Demonstrates various ways to apply conditions, modifiers, and logical operators using the QueryBuilder API.

```rust
//the where_() can be applied to any of the basic search queries after order_by/offset/limit
//not() and not_beyond() can be applied to all conditions including nested where_()
QueryBuilder::search().from(1).where_().distance(CountComparison::LessThan(3)).query();
QueryBuilder::search().from(1).where_().edge().query();
QueryBuilder::search().from(1).where_().edge_count(CountComparison::GreaterThan(2)).query();
QueryBuilder::search().from(1).where_().edge_count_from(1).query();
QueryBuilder::search().from(1).where_().edge_count_to(CountComparison::NotEqual(1)).query();
QueryBuilder::search().from(1).where_().node().query();
QueryBuilder::search().from(1).where_().key("k").value(1).query();
QueryBuilder::search().from(1).where_().keys(vec!["k1".into(), "k2".into()]).query();
QueryBuilder::search().from(1).where_().not().keys(vec!["k1".into(), "k2".into()]).query();
QueryBuilder::search().from(1).where_().ids([1, 2]).query();
QueryBuilder::search().from(1).where_().beyond().keys(vec!["k".into()]).query();
QueryBuilder::search().from(1).where_().not().ids([1, 2]).query();
QueryBuilder::search().from(1).where_().not_beyond().ids("a").query();
QueryBuilder::search().from(1).where_().node().or().edge().query();
QueryBuilder::search().from(1).where_().node().and().distance(CountComparison::GreaterThanOrEqual(3)).query();
QueryBuilder::search().from(1).where_().node().or().where_().edge().and().key("k").value(1).end_where().query();
QueryBuilder::search().from(1).where_().node().or().where_().edge().and().key("k").value(Comparison::Contains(1.into())).end_where().query();
QueryBuilder::search().from(1).where_().node().or().where_().edge().and().key("k").value(Comparison::Contains(vec![1, 2].into())).end_where().query();
```

--------------------------------

### Configure cluster nodes

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/03.references/02.server.md

Example configuration for three nodes in a cluster where the cluster array must be identical across all nodes.

```yaml
#node0 agdb_server.yaml
address: http://localhost:3000
cluster: ["http://localhost:3000", "http://localhost:3001", "http://localhost:3002"]

#node1 abdb_server.yaml
address: http://localhost:3001
cluster: ["http://localhost:3000", "http://localhost:3001", "http://localhost:3002"]

#node2 agdb_server.yaml
address: http://localhost:3002
cluster: ["http://localhost:3000", "http://localhost:3001", "http://localhost:3002"]
```

--------------------------------

### InsertEdgesQuery Builder Patterns

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/03.references/01.queries.md

Examples of using the QueryBuilder to insert edges with various configurations, including values and sub-queries.

```rust
QueryBuilder::insert().edges().from(1).to(2).query();
QueryBuilder::insert().edges().from("a").to("b").query();
QueryBuilder::insert().edges().from("a").to([1, 2]).query();
QueryBuilder::insert().edges().from([1, 2]).to([2, 3]).query();
QueryBuilder::insert().edges().from([1, 2]).to([2, 3]).each().query();
QueryBuilder::insert().edges().from("a").to([1, 2]).values([[("k", 1).into()], [("k", 2).into()]]).query();
QueryBuilder::insert().edges().from("a").to([1, 2]).values_uniform([("k", "v").into(), (1, 10).into()]).query();
QueryBuilder::insert().edges().from(QueryBuilder::search().from("a").where_().node().query()).to(QueryBuilder::search().from("b").where_().node().query()).query();
QueryBuilder::insert().edges().from(QueryBuilder::search().from("a").where_().node().query()).to(QueryBuilder::search().from("b").where_().node().query()).values([[("k", 1).into()], [("k", 2).into()]]).query();
QueryBuilder::insert().edges().from(QueryBuilder::search().from("a").where_().node().query()).to(QueryBuilder::search().from("b").where_().node().query()).values_uniform([("k", "v").into(), (1, 10).into()]).query();
QueryBuilder::insert().edges().ids(-3).from(1).to(2).query();
QueryBuilder::insert().edges().ids([-3, -4]).from(1).to(2).query();
QueryBuilder::insert().edges().ids(QueryBuilder::search().from(1).where_().edge().query()).from(1).to(2).query();
```

--------------------------------

### QueryBuilder Search Patterns

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/03.references/01.queries.md

Examples of using the QueryBuilder to construct various search queries, including path, index, and element-based searches.

```rust
QueryBuilder::search().from("a").query();
QueryBuilder::search().to(1).query(); //reverse search
QueryBuilder::search().from("a").to("b").query(); //path search using A* algorithm
QueryBuilder::search().breadth_first().from("a").query(); //breadth first is the default and can be omitted
QueryBuilder::search().depth_first().from("a").query();
QueryBuilder::search().elements().query();
QueryBuilder::search().index("age").value(20).query(); //index search
//limit, offset and order_by can be applied similarly to all the search variants except search index
QueryBuilder::search().from(1).order_by([DbKeyOrder::Desc("age".into()), DbKeyOrder::Asc("name".into())]).query()
QueryBuilder::search().from(1).offset(10).query();
QueryBuilder::search().from(1).limit(5).query();
QueryBuilder::search().from(1).order_by([DbKeyOrder::Desc("k".into())]).offset(10).query();
QueryBuilder::search().from(1).order_by([DbKeyOrder::Desc("k".into())]).limit(5).query();
QueryBuilder::search().from(1).order_by([DbKeyOrder::Desc("k".into())]).offset(10).limit(5).query();
QueryBuilder::search().from(1).offset(10).limit(5).query();
```

--------------------------------

### Run agdb_server Docker Container

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/01.guides/03.how-to-run-server/02.server-docker.md

Run the agdb_server in a Docker container, mounting a volume for data persistence and mapping the container port to the host. This command starts the server with default configuration (no TLS).

```bash
docker run -v agdb_data:/agdb/agdb_data --name agdb -p 3000:3000 agnesoft/agdb:dev
```

--------------------------------

### Run agdb_server Cluster with Docker Compose

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/01.guides/03.how-to-run-server/05.cluster-docker.md

Starts the agdb_server cluster using a Docker Compose file. This command ensures nodes are brought up and waited upon, with data persistence via volumes and nodes exposed on ports 3000, 3001, and 3002.

```bash
docker compose -f agdb_server/compose.yaml up --wait
```

--------------------------------

### Create and Login as a Database User in PHP

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/api-docs/03.php.md

Demonstrates how to log in as the server admin, add a new database user, and then log in as that new user.

```php
// Login as server admin
$token = self::$client->userLogin(
    new UserLogin(["username" => "admin", "password" => "admin"])
);
$client->getConfig()->setAccessToken($token);

// Creat user "php_user1"
$client->adminUserAdd(
    "php_user1",
    new UserCredentials(["password" => "php_user1"])
);

// Login as "php_user1"
$token = self::$client->userLogin(
    new UserLogin([
        "username" => "php_user1",
        "password" => "php_user1",
    ])
);
$client->getConfig()->setAccessToken($token);
```

--------------------------------

### Initialize PHP Project with Composer

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/api-docs/03.php.md

Steps to create a new PHP project and add the agdb_api package as a dependency using Composer.

```bash
mkdir my_agdb
cd my_agdb
composer init # follow the steps & prompts
```

```bash
composer install agnesoft/agdb_api
```

--------------------------------

### API Initialization and Usage

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/README.md

Configure the API client with an access token and execute an administrative database addition request.

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');



// Configure Bearer authorization: Token
$config = Agnesoft\AgdbApi\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Agnesoft\AgdbApi\Api\AgdbApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$owner = 'owner_example'; // string | user name
$db = 'db_example'; // string | db name
$db_type = new \Agnesoft\AgdbApi\Model\\Agnesoft\AgdbApi\Model\DbKind(); // \Agnesoft\AgdbApi\Model\DbKind

try {
    $apiInstance->adminDbAdd($owner, $db, $db_type);
} catch (Exception $e) {
    echo 'Exception when calling AgdbApi->adminDbAdd: ', $e->getMessage(), PHP_EOL;
}
```

--------------------------------

### Preview Production Build with pnpm

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/README.md

Locally previews the production build of the application.

```bash
pnpm preview
```

--------------------------------

### GET /api/v1/status

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/README.md

Retrieves the system status.

```APIDOC
## GET /api/v1/status

### Description
Returns the current status of the system.

### Method
GET

### Endpoint
/api/v1/status
```

--------------------------------

### GET /api/v1/cluster/status

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/docs/Api/AgdbApi.md

Retrieves the current status of the cluster.

```APIDOC
## GET /api/v1/cluster/status

### Description
Retrieves the current status of the cluster.

### Method
GET

### Endpoint
/api/v1/cluster/status
```

--------------------------------

### Build Application for Production with pnpm

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/README.md

Compiles the application for production deployment.

```bash
pnpm build
```

--------------------------------

### GET /api/v1/status

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/03.references/02.server.md

Checks the operational status of the server.

```APIDOC
## GET /api/v1/status

### Description
Returns a 200 OK status if the server is ready and running.

### Method
GET

### Endpoint
/api/v1/status
```

--------------------------------

### Create Database User

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/01.guides/03.how-to-run-server/01.server-bare-metal.md

Demonstrates how to create a new database user using the server's API. It involves obtaining an admin token first, then using that token to add a new user with a specified password.

```bash
# produce an admin API token, e.g. "bb2fc207-90d1-45dd-8110-3247c4753cd5"
token=$(curl -X POST -H 'Content-Type: application/json' localhost:3000/api/v1/user/login -d '{"username":"admin","password":"admin"}')
# using admin token to create a user
curl -X POST -H "Authorization: Bearer ${token}" localhost:3000/api/v1/admin/user/my_db_user/add -d '{"password":"password123"}'
```

--------------------------------

### GET /api/v1/admin/db/list

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/docs/Api/AgdbApi.md

Retrieves a list of all databases available in the system.

```APIDOC
## GET /api/v1/admin/db/list

### Description
Retrieves a list of all databases available in the system.

### Method
GET

### Endpoint
/api/v1/admin/db/list
```

--------------------------------

### Copy a database using adminDbCopy

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/docs/Api/AgdbApi.md

Demonstrates how to initialize the AgdbApi client with Bearer token authentication and execute the adminDbCopy operation.

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer authorization: Token
$config = Agnesoft
AgdbApi\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Agnesoft\AgdbApi\Api\AgdbApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$owner = 'owner_example'; // string | db owner user name
$db = 'db_example'; // string | db name
$new_owner = 'new_owner_example'; // string
$new_db = 'new_db_example'; // string

try {
    $apiInstance->adminDbCopy($owner, $db, $new_owner, $new_db);
} catch (Exception $e) {
    echo 'Exception when calling AgdbApi->adminDbCopy: ', $e->getMessage(), PHP_EOL;
}
```

--------------------------------

### GET /api/v1/cluster/status

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/03.references/02.server.md

Retrieves the current status and topology of the cluster.

```APIDOC
## GET /api/v1/cluster/status

### Description
Returns the list of cluster nodes, indicating which nodes are reachable from the current node and identifying the current cluster leader.

### Method
GET

### Endpoint
/api/v1/cluster/status
```

--------------------------------

### Initialize Rust Application

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/api-docs/02.rust.md

Use cargo to initialize a new Rust project for the agdb client.

```bash
cargo init agdb_client
```

--------------------------------

### GET /api/v1/user/status

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/README.md

Retrieves the current user's status.

```APIDOC
## GET /api/v1/user/status

### Description
Returns the status of the currently authenticated user.

### Method
GET

### Endpoint
/api/v1/user/status
```

--------------------------------

### GET /api/v1/openapi.json

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/03.references/02.server.md

Retrieves the server's OpenAPI specification in JSON format.

```APIDOC
## GET /api/v1/openapi.json

### Description
Returns the server's OpenAPI specification as a JSON object.

### Method
GET

### Endpoint
/api/v1/openapi.json
```

--------------------------------

### Basic AGDB Usage: Create, Insert, and Query

Source: https://github.com/agnesoft/agdb/blob/main/README.md

Demonstrates creating a database, inserting graph elements with data, and querying them back. The function using this code must handle `agdb::DbError` for the `?` operator.

```rust
use agdb::{Db, DbId, QueryBuilder, DbType};

let mut db = Db::new("db_file.agdb")?;

db.exec_mut(QueryBuilder::insert().nodes().aliases("users").query())?;

#[derive(Debug, DbType)]
struct User {
    db_id: Option<DbId>,
    name: String,
}
let users = vec![User { db_id: None, name: "Alice".into() },
                 User { db_id: None, name: "Bob".into() },
                 User { db_id: None, name: "John".into() }];

let users_ids = db.exec_mut(QueryBuilder::insert().nodes().values(&users).query())?;

db.exec_mut(
    QueryBuilder::insert()
        .edges()
        .from("users")
        .to(&users_ids)
        .query(),
)?;
```

--------------------------------

### Initialize Rust Application

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/01.guides/02.quickstart.md

Initialize a new Rust application using cargo. This sets up the basic project structure.

```bash
mkdir agdb_app
cd agdb_app
cargo init
```

--------------------------------

### GET /api/v1/db/{owner}/{db}/user/list

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/README.md

Lists users associated with a database.

```APIDOC
## GET /api/v1/db/{owner}/{db}/user/list

### Description
Lists all users for the specified database.

### Method
GET

### Endpoint
/api/v1/db/{owner}/{db}/user/list

### Parameters
#### Path Parameters
- **owner** (string) - Required - The owner of the database
- **db** (string) - Required - The name of the database
```

--------------------------------

### Add a database using adminDbAdd

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/docs/Api/AgdbApi.md

Demonstrates how to configure the API client and call the adminDbAdd method to create a new database.

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer authorization: Token
$config = Agnesoft
AgdbApi\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Agnesoft\AgdbApi\Api\AgdbApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$owner = 'owner_example'; // string | user name
$db = 'db_example'; // string | db name
$db_type = new \Agnesoft\AgdbApi\Model\\Agnesoft\AgdbApi\Model\DbKind(); // \Agnesoft\AgdbApi\Model\DbKind

try {
    $apiInstance->adminDbAdd($owner, $db, $db_type);
} catch (Exception $e) {
    echo 'Exception when calling AgdbApi->adminDbAdd: ', $e->getMessage(), PHP_EOL;
}
```

--------------------------------

### InsertAliasesQuery Builder Patterns

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/03.references/01.queries.md

Examples of using the QueryBuilder to insert or update node aliases.

```rust
QueryBuilder::insert().aliases("a").ids(1).query();
QueryBuilder::insert().aliases("a").ids("b").query(); // alias "b" is replaced  with "a"
QueryBuilder::insert().aliases(["a", "b"]).ids([1, 2]).query();
```

--------------------------------

### Login and Generate User Token

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/01.guides/03.how-to-run-server/01.server-bare-metal.md

Use this command to log in as a new user and obtain an authentication token for subsequent API requests.

```bash
token=$(curl -X POST -H 'Content-Type: application/json' localhost:3000/api/v1/user/login -d '{"username":"my_db_user","password":"password123"}')
```

--------------------------------

### Convert Database Type

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/docs/Api/AgdbApi.md

Demonstrates how to initialize the AgdbApi client and call the adminDbConvert method.

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer authorization: Token
$config = Agnesoft
AgdbApi
Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Agnesoft
AgdbApi
Api
AgdbApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp
ClientInterface`.
    // This is optional, `GuzzleHttp
Client` will be used as default.
    new GuzzleHttp
Client(),
    $config
);
$owner = 'owner_example'; // string | user name
$db = 'db_example'; // string | db name
$db_type = new \Agnesoft
AgdbApi
Model\\Agnesoft
AgdbApi
Model
DbKind(); // \Agnesoft
AgdbApi
Model
DbKind

try {
    $apiInstance->adminDbConvert($owner, $db, $db_type);
} catch (Exception $e) {
    echo 'Exception when calling AgdbApi->adminDbConvert: ', $e->getMessage(), PHP_EOL;
}
```

--------------------------------

### GET /api/v1/db/{owner}/{db}/audit

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/03.references/02.server.md

Returns the log of all mutable queries that ran against the database.

```APIDOC
## GET /api/v1/db/{owner}/{db}/audit

### Description
Returns the log of all mutable queries that ran against the database, including the user who performed the action.

### Method
GET

### Endpoint
/api/v1/db/{owner}/{db}/audit
```

--------------------------------

### Run agdb_benchmark

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/03.references/06.performance.md

Execute the agdb_benchmark project in release mode to simulate database traffic and measure performance.

```bash
cargo run --release -p agdb_benchmark
```

--------------------------------

### Select Keys Query Builder

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/03.references/01.queries.md

Demonstrates various ways to construct a select keys query using the QueryBuilder.

```rs
QueryBuilder::select().keys().ids("a").query();
QueryBuilder::select().keys().ids([1, 2]).query();
QueryBuilder::select().keys().ids(QueryBuilder::search().from(1).query()).query();
QueryBuilder::select().keys().search().from(1).query(); // Equivalent to the previous query
```

--------------------------------

### Select Key Count Query Builder

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/03.references/01.queries.md

Demonstrates various ways to construct a select key count query using the QueryBuilder.

```rs
QueryBuilder::select().key_count().ids("a").query();
QueryBuilder::select().key_count().ids([1, 2]).query();
QueryBuilder::select().key_count().ids(QueryBuilder::search().from(1).query()).query();
QueryBuilder::select().key_count().search().from(1).query(); // Equivalent to the previous query
```

--------------------------------

### Add a user to a database using PHP

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/docs/Api/AgdbApi.md

Demonstrates how to configure the API client and call the dbUserAdd method to assign a role to a user in a specific database.

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer authorization: Token
$config = Agnesoft\AgdbApi\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Agnesoft\AgdbApi\Api\AgdbApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$owner = 'owner_example'; // string | db owner user name
$db = 'db_example'; // string | db name
$username = 'username_example'; // string | user name
$db_role = new \Agnesoft\AgdbApi\Model\\Agnesoft\AgdbApi\Model\DbUserRole(); // \Agnesoft\AgdbApi\Model\DbUserRole

try {
    $apiInstance->dbUserAdd($owner, $db, $username, $db_role);
} catch (Exception $e) {
    echo 'Exception when calling AgdbApi->dbUserAdd: ', $e->getMessage(), PHP_EOL;
}
```

--------------------------------

### Create a Database in PHP

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/api-docs/03.php.md

Associates a new database with a user, specifying its name and type (e.g., MAPPED, MEMORY, FILE).

```php
// Creates memory mapped database "db1" for user "php_user1"
$client->dbAdd("php_user1", "db1", DbType::MAPPED);
```

--------------------------------

### Fetch Comments for a Post in Rust

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/03.references/05.efficient-agdb.md

Fetches all comments associated with a given post ID using a depth-first search. The query filters out the starting post node by requiring a distance greater than 1.

```rust
fn comments(db: &Db, id: DbId) -> Result<Vec<Comment>, DbError> {
    db
        .exec(
            QueryBuilder::select()
                .elements::<Comment>()
                .search()
                .depth_first()
                .from(id)
                .where_()
                .node()
                .and()
                .distance(CountComparison::GreaterThan(1))
                .query(),
        )?
        .try_into()
}
```

--------------------------------

### Build for production

Source: https://github.com/agnesoft/agdb/blob/main/agdb_studio/README.md

Performs type-checking, compilation, and minification for production deployment.

```sh
pnpm run build
```

--------------------------------

### Create a Database via API

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/03.references/02.server.md

Use this curl command to create a new database under the authenticated user's namespace.

```bash
curl -X POST -H "Authorization: Bearer ${token}" localhost:3000/api/v1/db/my_db_owner/my_db/add?db_type=mapped
```

--------------------------------

### Retrieve all outputs at a specific distance

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/blog/01.distance.md

Use the `distance` condition to fetch all elements exactly 4 steps away from the starting 'projects' node. This is useful for retrieving related data without explicit joins.

```rust
QueryBuilder::search()
    .from("projects")
    .where_()
        .distance(4)
    .query();
```

--------------------------------

### Insert Nodes and Edges in Rust

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/api-docs/02.rust.md

Insert multiple nodes with associated data and connect them using edges. This example demonstrates inserting a 'users' node, three user nodes, and an edge connecting 'users' to the first user node.

```rust
// We derive from agdb::DbType
// so we can use the type in the db.
#[derive(Debug, DbType)]
struct User {
    db_id: Option<DbId>, // The db_id member is optional but
                         // it allows querying your user type
                         // from the database.
    username: String
    age: u64,
}

let users = vec![User { db_id: None, username: "Alice".to_string(), age: 40 },
                 User { db_id: None, username: "Bob".to_string(), age: 30 },
                 User { db_id: None, username: "John".to_string(), age: 20 }];

// We can pass users directly as
// query parameter thanks to the
// implementation of the agdb::DbType
// trait via #[derive(DbType)].
let queries: Vec<QueryType> = vec![QueryBuilder::insert().nodes().aliases("users").query().into(),
                                   QueryBuilder::insert().nodes().values(&users).query().into(),
                                   QueryBuilder::insert().edges().from("users").to(":1").query().into(),
                            ];

client.db_exec_mut("my_user", "my_db", &queries).await?;
```

--------------------------------

### Create agdb API Client in PHP

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/api-docs/03.php.md

Initializes the agdb API client in PHP, configuring it to connect to a local server and performing a status check.

```php
<?php
// Needed to load the libraries installed by composer
require 'vendor/autoload.php';

use Agnesoft\AgdbApi\Api\AgdbApi;
use Agnesoft\AgdbApi\Model\DbType;
use Agnesoft\AgdbApi\Model\UserLogin;
use Agnesoft\AgdbApi\Model\UserCredentials;
use Agnesoft\AgdbApi\QueryBuilder;
use Agnesoft\AgdbApi\ComparisonBuilder;

// Default config will look for the server at http://localhost:3000
$config = Agnesoft\AgdbApi\Configuration::getDefaultConfiguration();

// Using GuzzleHttp client. You can use any other like Symfony. 
$client = new AgdbApi(new GuzzleHttp\Client(), $config);

// Runs the status query against the database
// and throws if the server is not accessible.
$client->status(false);
```

--------------------------------

### Build agdb_server Docker Image

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/01.guides/03.how-to-run-server/02.server-docker.md

Build the Docker image for agdb_server from the source repository. This command should be run from the root of the checked-out agdb repository.

```bash
docker build --pull -t agnesoft/agdb:dev -f agdb_server/containerfile .
```

--------------------------------

### Kubernetes ConfigMap for agdb Server Configuration

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/01.guides/03.how-to-run-server/06.cluster-k8s.md

Provides the agdb_server configuration, including a custom start script that assigns the replica index and a server configuration file. The configuration specifies network bindings, addresses, TLS settings, and cluster peer information. Ensure the certificate is valid for all cluster node DNS names.

```yaml
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: agdb-config
  labels:
    app: agdb
data:
  start.sh: |
    cp /agdb/config/agdb_server.yaml /agdb/agdb_server.yaml
    sed -i "s/{id}/$AGDB_REPLICA_INDEX/g" /agdb/agdb_server.yaml
    /usr/local/bin/agdb_server
  agdb_server.yaml: |
    bind: :::3000
    address: http://agdb-{id}.agdb.default.svc.cluster.local:3000
    basepath: ""
    static_roots: []
    admin: admin
    log_level: INFO
    data_dir: /agdb/data
    pepper_path: /agdb/pepper/pepper
    tls_certificate: /agdb/certs/cert.pem
    tls_key: /agdb/certs/key.pem
    tls_root: /agdb/certs/root_ca.pem
    cluster_token: cluster
    cluster_heartbeat_timeout_ms: 1000
    cluster_term_timeout_ms: 3000
    cluster: [http://agdb-0.agdb.default.svc.cluster.local:3000, http://agdb-1.agdb.default.svc.cluster.local:3000, http://agdb-2.agdb.default.svc.cluster.local:3000]
```

--------------------------------

### Connect and Query Agdb Database with TypeScript

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/typescript/README.md

Demonstrates connecting to a remote Agdb server, logging in, adding a user, creating a database, and executing a series of insert and select queries using the QueryBuilder. Ensure the server is running before execution.

```typescript
import { QueryBuilder, AgdbApi } from "@agnesfot/agdb_api";

async function main() {
    // Requires the server to be running...
    // Creates a client connecting to the remote server.
    let client = await AgdbApi.client("http://localhost", 3000);
    let admin_token = await client.user_login(null, {
        username: "admin",
        password: "admin",
    });
    AgdbApi.setToken(admin_token.data);
    await client.admin_user_add("user1", { password: "password123" });
    let token = await client.user_login(null, {
        username: "user1",
        password: "password123",
    });
    AgdbApi.setToken(token.data); //replaces the admin token

    // To create a database:
    await client.db_add({
        owner: "user1",
        db: "db1",
        db_type: "mapped", //memory mapped type, other options are "memory" and "file"
    });

    // Prepare and run queries:
    let queries = [
        // :0: Inserts a root node aliase "users"
        QueryBuilder.insert().nodes().aliases(["users"]).query(),
        // :1: Inserts more nodes with some data
        QueryBuilder.insert()
            .nodes()
            .values([
                [
                    { key: { String: "username" }, value: { String: "user1" } },
                    {
                        key: { String: "password" },
                        value: { String: "password123" },
                    },
                ],
                [
                    { key: { String: "username" }, value: { String: "user1" } },
                    {
                        key: { String: "password" },
                        value: { String: "password456" },
                    },
                ],
            ])
            .query(),
        // :2: Connect the root to the inserted nodes with edges referencing both from previous queries
        QueryBuilder.insert().edges().from(":0").to(":1").query(),

        // :3: Find a node starting at the "users" node (could also be ":0" in this instance) with specific username
        QueryBuilder.select()
            .ids(
                QueryBuilder.search()
                    .from("users")
                    .where()
                    .key({ String: "username" })
                    .value({ Equal: { String: "user1" } })
                    .query(),
            )
            .query(),
    ];
    // Execute queries.
    let results = (await client.db_exec({ owner: "user1", db: "db1" }, queries))
        .data;
    console.log(`User (id: ${results[3].elements[0].id})`);
    for (let { key, value } of results[3].elements[0].values) {
        console.log(`${key["String"]}: ${value["String"]}`);
    }
}

```

--------------------------------

### Run ESLint

Source: https://github.com/agnesoft/agdb/blob/main/agdb_studio/README.md

Executes linting across the project using ESLint.

```sh
pnpm run lint
```

--------------------------------

### Build All Rust Packages

Source: https://github.com/agnesoft/agdb/blob/main/AGENTS.md

Builds all Rust packages with all features enabled in release mode.

```bash
cargo build -r --all-features
```

--------------------------------

### Execute database query using dbExec

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/docs/Api/AgdbApi.md

Demonstrates how to configure the API client with a Bearer token and execute a query using the dbExec method.

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer authorization: Token
$config = Agnesoft	gdbApi\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Agnesoft\AgdbApi\Api\AgdbApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$owner = 'owner_example'; // string | db owner user name
$db = 'db_example'; // string | db name
$query_type = array(new \Agnesoft\AgdbApi\Model\QueryType()); // \Agnesoft\AgdbApi\Model\QueryType[]

try {
    $result = $apiInstance->dbExec($owner, $db, $query_type);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling AgdbApi->dbExec: ', $e->getMessage(), PHP_EOL;
}
```

--------------------------------

### POST /api/v1/db/{owner}/{db}/backup

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/03.references/02.server.md

Creates a backup of the specified database.

```APIDOC
## POST /api/v1/db/{owner}/{db}/backup

### Description
Backs up the database under the same name to the 'backups' subfolder in the owner's data.

### Method
POST

### Endpoint
/api/v1/db/{owner}/{db}/backup

### Parameters
#### Path Parameters
- **owner** (string) - Required - The owner of the database.
- **db** (string) - Required - The name of the database.
```

--------------------------------

### Execute Database Mutation via adminDbExecMut

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/docs/Api/AgdbApi.md

Demonstrates how to configure the API client with a bearer token and execute a database mutation request.

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer authorization: Token
$config = Agnesoft"));


$apiInstance = new Agnesoft\AgdbApi\Api\AgdbApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$owner = 'owner_example'; // string | db owner user name
$db = 'db_example'; // string | db name
$query_type = array(new \Agnesoft\AgdbApi\Model\QueryType()); // \Agnesoft\AgdbApi\Model\QueryType[]

try {
    $result = $apiInstance->adminDbExecMut($owner, $db, $query_type);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling AgdbApi->adminDbExecMut: ', $e->getMessage(), PHP_EOL;
}
```

--------------------------------

### Create a new user via admin API

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/docs/03.references/02.server.md

Uses the admin account to authenticate and create a new user with a specified password.

```bash
# produce an admin API token, e.g. "bb2fc207-90d1-45dd-8110-3247c4753cd5"
token=$(curl -X POST -H 'Content-Type: application/json' localhost:3000/api/v1/user/login -d '{"username":"admin","password":"admin"}')
# using admin token to create a user
curl -X POST -H "Authorization: Bearer ${token}" localhost:3000/api/v1/admin/user/my_db_user/add -d '{"password":"password123"}'
# login as the new user and producing their token
token=$(curl -X POST -H 'Content-Type: application/json' localhost:3000/api/v1/user/login -d '{"username":"my_db_user","password":"password123"}')
```

--------------------------------

### Backup database with PHP

Source: https://github.com/agnesoft/agdb/blob/main/agdb_api/php/docs/Api/AgdbApi.md

Triggers a backup for a specified database. This method returns void and requires Bearer token authentication.

```php
<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer authorization: Token
$config = Agnesoft\\\AgdbApi\\\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new Agnesoft\\\AgdbApi\\\Api\\\AgdbApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\\\ClientInterface`.
    // This is optional, `GuzzleHttp\\\Client` will be used as default.
    new GuzzleHttp\\\Client(),
    $config
);
$owner = 'owner_example'; // string | user name
$db = 'db_example'; // string | db name

try {
    $apiInstance->dbBackup($owner, $db);
} catch (Exception $e) {
    echo 'Exception when calling AgdbApi->dbBackup: ', $e->getMessage(), PHP_EOL;
}
```

--------------------------------

### Create Rust agdb API Client

Source: https://github.com/agnesoft/agdb/blob/main/agdb_web/content/api-docs/02.rust.md

Instantiate the async agdb API client using ReqwestClient and specify the server address. Ensure the server is running locally.

```rust
use agdb_api::AgdbApi;
use agdb_api::ReqwestClient;

#[tokio:main]
async fn main() -> anyhow::Result<()> {
    let mut client = AgdbApi::new(ReqwestClient::new(), "localhost:3000");

    Ok(())
}
```