@wearesage/schema/examples/multi-db/README.md

A flexible schema definition and validation system for TypeScript with multi-database support

# Multi-Database Example

This example demonstrates how to use the SAGE schema system with multiple databases simultaneously. It showcases:

1. Defining your schema once with TypeScript decorators
2. Using different database adapters for different entity types
3. Managing relationships across databases

## Prerequisites

- Node.js v14+ and npm/yarn
- MongoDB running on localhost:27017
- Neo4j running on localhost:7687
- PostgreSQL running on localhost:5432

## Database Setup

### MongoDB

No specific setup needed for this example. The system will create the collections as needed.

### Neo4j

Run the following Cypher queries to prepare Neo4j:

```cypher
// Create constraints
CREATE CONSTRAINT post_id IF NOT EXISTS FOR (p:Post) REQUIRE p.id IS UNIQUE;
CREATE CONSTRAINT tag_id IF NOT EXISTS FOR (t:Tag) REQUIRE t.id IS UNIQUE;
CREATE CONSTRAINT user_id IF NOT EXISTS FOR (u:User) REQUIRE u.id IS UNIQUE;
```

### PostgreSQL

Run the following SQL to prepare PostgreSQL:

```sql
-- Create tables
CREATE TABLE IF NOT EXISTS users (
  id VARCHAR(255) PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  email VARCHAR(255) UNIQUE NOT NULL
);

CREATE TABLE IF NOT EXISTS posts (
  id VARCHAR(255) PRIMARY KEY,
  title VARCHAR(255) NOT NULL,
  content TEXT NOT NULL,
  created_at TIMESTAMP,
  author_id VARCHAR(255) REFERENCES users(id)
);

CREATE TABLE IF NOT EXISTS tags (
  id VARCHAR(255) PRIMARY KEY,
  name VARCHAR(255) UNIQUE NOT NULL
);

CREATE TABLE IF NOT EXISTS post_tags (
  post_id VARCHAR(255) REFERENCES posts(id),
  tag_id VARCHAR(255) REFERENCES tags(id),
  PRIMARY KEY (post_id, tag_id)
);
```

## Running the Example

```bash
# From the project root
npm install
npm run build
node dist/examples/multi-db/index.js
```

## How It Works

This example demonstrates a blog system where:

- Users are stored in MongoDB
- Posts are stored in Neo4j
- Tags are stored in PostgreSQL

The entities have relationships with each other (e.g., a Post has an Author who is a User), but these entities live in different databases. The SAGE schema system manages these cross-database relationships seamlessly.

### Key Features

1. **One Schema Definition**: Define your entities once using TypeScript decorators.
   
2. **Multiple Database Adapters**: Use different databases for different entity types.
   
3. **Cross-Database Relationships**: Maintain relationships between entities in different databases.
   
4. **Type Safety**: Full TypeScript support with proper types throughout.

### Code Structure

- `User`, `Post`, and `Tag` entities are defined in the blog example.
- We create separate adapters for MongoDB, Neo4j, and PostgreSQL.
- We create repositories for each entity, using the appropriate adapter.
- We demonstrate CRUD operations with cross-database relationships.

## Customizing

- Change the connection strings in the adapters to match your database setup.
- Modify the entity definitions to match your use case.
- Add specific database optimizations using the adapter-specific decorators:
  - MongoDB: `@Collection`, `@Index`
  - Neo4j: `@Labels`, `@RelationshipType`
  - PostgreSQL: `@Table`, `@Column`, `@Index`, `@JoinTable`