Database

Schema and Instance Management

This page covers the Schema, SchemaInstance, and related types that control database structure and lifecycle.

Schema

The Schema<T> class defines the structure of a database and manages its instances.

class Schema<T = any> extends StagedObject {
  static get(id: string): Schema | undefined;
  constructor(id: string, definition: SchemaDefinition);
  instance(id?: InstanceId): SchemaInstance<T>;
  createInstance(id?: string): Query<string>;
  destroyInstance(id?: string): Query<void>;
  listInstances(): Query<string[]>;
}

`SchemaDefinition`

interface SchemaDefinition {
  [tableName: string]: TableDefinition;
}

`InstanceId` and `CROSS_INSTANCE`

const CROSS_INSTANCE: unique symbol;
type InstanceId = string | typeof CROSS_INSTANCE;

schema.instance(CROSS_INSTANCE) returns a query stage that operates across every instance of the schema. Adapters skip the per-instance filter on read/update/delete and reject inserts.

Create and Manage Instances

import { Schema } from "@antelopejs/interface-database";

// Define a schema
const schema = new Schema("myapp", {
  users: {
    fields: { name: "string" },
    indexes: {},
  },
});

// Create the default instance
const instanceId = await schema.createInstance();

// Create a named instance
await schema.createInstance("tenant-1");

// Access instances
const defaultDb = schema.instance();
const tenantDb = schema.instance("tenant-1");

// Destroy an instance
await schema.destroyInstance("tenant-1");

// List named instances
const ids = await schema.listInstances();

Retrieve a Schema

Use Schema.get() to look up a previously defined schema anywhere in your application:

const schema = Schema.get("myapp");

if (schema) {
  const db = schema.instance();
  const users = db.table("users");
}

SchemaInstance

The SchemaInstance<T> class represents a single instance of a schema. Its primary method is table(), which returns a Table for the specified table name.

class SchemaInstance<T> extends StagedObject {
  table<TK extends keyof T>(id: TK): Table<T[TK]>;
}

const db = schema.instance();
const users = db.table("users");
const posts = db.table("posts");

For practical usage patterns, see Schema Management.

Table Definitions

In AQL, tables are defined as part of a schema. Each table definition specifies the fields and indexes for that table.

Change Events

The Changes<T> interface represents a change event emitted by change feeds. It includes the type of change and the document values before and after the change.