# Ledger Migrations

> SQL schema migrations for the governance ledger database

## Overview

This directory contains SQL migration files that define and evolve the SQLite database schema for the agent governance system. Migrations are numbered sequentially and should be applied in order.

## Migration Files

| File | Phase | Description |
|------|-------|-------------|
| `001_multi_tenant.sql` | Phase 10 | Multi-tenant support tables |
| `002_marketplace.sql` | Phase 11 | Agent marketplace tables |

## Migration 001: Multi-Tenant Support

Adds tables for multi-tenant architecture:

| Table | Purpose |
|-------|---------|
| `tenants` | Organization/customer records |
| `projects` | Workspaces within tenants |
| `tenant_quotas` | Resource limits per tenant |
| `tenant_usage` | Usage tracking for billing |
| `api_keys` | API authentication keys |
| `user_roles` | RBAC role assignments |
| `audit_log_tenant` | Tenant-scoped audit trail |

## Migration 002: Marketplace

Adds tables for the agent template marketplace:

| Table | Purpose |
|-------|---------|
| `agent_templates` | Core template registry |
| `template_versions` | Version history with semver |
| `template_installations` | Installation tracking |
| `template_ratings` | User ratings and reviews |
| `template_downloads` | Download metrics |
| `templates_fts` | FTS5 full-text search index |

## Applying Migrations

Migrations are applied automatically when the ledger API starts, or can be applied manually:

```bash
# Apply all migrations
sqlite3 /opt/agent-governance/ledger/governance.db < 001_multi_tenant.sql
sqlite3 /opt/agent-governance/ledger/governance.db < 002_marketplace.sql

# Verify tables
sqlite3 /opt/agent-governance/ledger/governance.db ".tables"
```

## Schema Conventions

- Primary keys: `{entity}_id TEXT PRIMARY KEY`
- Timestamps: `TEXT DEFAULT CURRENT_TIMESTAMP` (ISO 8601)
- Foreign keys: `REFERENCES {table}({column}) ON DELETE CASCADE`
- JSON storage: `TEXT` columns with JSON content
- Boolean: `INTEGER` (0/1)
- Indices: Created for frequently queried columns

## Adding New Migrations

1. Create file: `00N_description.sql`
2. Use `CREATE TABLE IF NOT EXISTS` for idempotency
3. Add indices for query performance
4. Document in this README
5. Test with fresh database

## Status

**Complete**

See [STATUS.md](./STATUS.md) for detailed progress tracking.

## Architecture Reference

Part of the [Ledger System](/opt/agent-governance/ledger/README.md).

---
*Last updated: 2026-01-24 UTC*