ageSchemaClient

A TypeScript library for Apache AGE graph databases with schema validation and efficient data loading.

📚 Full Documentation | 🚀 Getting Started | 📖 API Reference

Features

• Schema-aware graph database operations
• Type-safe query building
• SQL generation for batch operations
• Efficient data loading with single-function approach
• Extensible connection pool system - Support for multiple PostgreSQL extensions
• Transaction management
• Progress tracking for large operations
• Comprehensive error handling
• Support for both Node.js and browser environments

Installation

# Using pnpm
pnpm add age-schema-client

# Using npm
npm install age-schema-client

# Using yarn
yarn add age-schema-client

Quick Start

import { AgeSchemaClient } from 'age-schema-client';

// 1. Create client instance
const client = new AgeSchemaClient({
  host: 'localhost',
  port: 5432,
  database: 'my_database',
  user: 'postgres',
  password: 'postgres',
  graph: 'my_graph'
});

// 2. Connect to the database
await client.connect();

// 3. Define a schema
const schema = {
  version: '1.0.0',
  vertices: {
    Person: {
      properties: {
        name: { type: 'string', required: true },
        age: { type: 'number' }
      }
    },
    Movie: {
      properties: {
        title: { type: 'string', required: true },
        year: { type: 'number' }
      }
    }
  },
  edges: {
    ACTED_IN: {
      properties: {
        role: { type: 'string' }
      },
      from: ['Person'],
      to: ['Movie']
    }
  }
};

// 4. Set the schema
await client.setSchema(schema);

// 5. Get a query builder and execute queries
const queryBuilder = client.queryBuilder();

const result = await queryBuilder
  .match('Person', 'p')
  .where('p.name = $actorName')
  .withParam('actorName', 'Tom Hanks')
  .outgoing('ACTED_IN', 'r', 'Movie', 'm')
  .return('p.name', 'm.title', 'r.role')
  .execute();

// 6. Clean up
await client.disconnect();

Documentation

📚 Full documentation is available at https://standardbeagle.github.io/ageSchemaClient/

Quick Links

• 🚀 Getting Started Guide
• 📖 API Reference
• 🏗️ Architecture Overview
• 💡 How-to Guides
• 🔧 Examples - Example code for common use cases

Key Topics

• Extension System - NEW: Pluggable extension system for PostgreSQL extensions
• Schema Loader - Documentation for the SchemaLoader class
• Batch Operations - Efficient bulk data loading
• Query Builder - Type-safe query construction

API Reference

A comprehensive API reference is available in the online documentation. This includes detailed information about:

• Connection Management
• Query Execution
• SQL Generation
• Vertex Operations
• Edge Operations
• Batch Operations
• Schema Migration
• Error Handling
• SchemaLoader Operations

Examples

Basic Usage

See basic-usage.ts for a simple example of using the client.

Transactions

See schema-loader-transaction.ts for an example of using transactions.

Progress Tracking

See schema-loader-progress.ts for an example of tracking progress during data loading.

Error Handling

See schema-loader-error-handling.ts for examples of handling various error scenarios.

Connection Options

For detailed information about connection options, including PostgreSQL-specific options like search_path, see the Connection Configuration guide in our documentation.

Apache AGE Integration

This library is designed to work with Apache AGE, a PostgreSQL extension for graph database functionality. It handles the complexities of working with AGE, including:

• Proper parameter passing using temporary tables
• Handling AGE-specific data types (agtype)
• Optimizing queries for performance
• Managing graph data loading efficiently
• Ensuring ag_catalog is in the search path

Important AGE-Specific Considerations

1. Search Path: Always include ag_catalog in the search path:

   searchPath: 'ag_catalog, "$user", public'

2. Loading AGE Extension: The library automatically loads the AGE extension with LOAD 'age'; for each new connection.

3. Parameter Passing: Due to AGE limitations with dynamic parameters, the library uses temporary tables for parameter passing.

4. AGE Data Types: The library properly handles the ag_catalog.agtype data type, including proper string formatting.

5. Query Structure: For optimal performance with AGE, the library structures queries to minimize the number of database roundtrips.

Development

Prerequisites

• Node.js 16+
• pnpm 10+

Setup

# Clone the repository
git clone https://github.com/beagle/age-schema-client.git
cd age-schema-client

# Install dependencies
pnpm install

# Build the library
pnpm build

# Run tests
pnpm test

License

MIT