docs: add virtual-schemas specification

[dimitri-yatsenko]

Summary

This PR adds comprehensive documentation for DataJoint's virtual schema infrastructure and CLI.

Virtual Schema Specification

reference/specs/virtual-schemas.md - Complete specification covering:

Core Concepts:

• Schema-module convention: DataJoint's 1:1 mapping where modules represent schemas and classes represent tables
• Table tier prefixes (#, _, __) and automatic detection

Schema Introspection API:

• Schema.get_table(name) - Direct table access
• Schema.__getitem__ - Bracket notation: schema['TableName']
• Schema.__iter__ - Iterate tables in dependency order
• Schema.__contains__ - Check table existence

Entry Points:

• dj.virtual_schema(schema_name) - Access existing database schemas
• dj.VirtualModule(alias, schema_name) - Create virtual modules with custom names
• Schema.spawn_missing_classes() - Generate table classes dynamically

Use Cases:

• Data exploration and ad-hoc queries
• Cross-schema queries and joins
• Schema migration and comparison
• Garbage collection infrastructure

CLI How-To Guide

how-to/use-cli.md - Practical guide for the dj command:

Getting Started:

• Starting the REPL with dj command
• Specifying database credentials (--host, --user, --password)

Schema Loading:

• Loading schemas as virtual modules (-s schema_name:alias)
• Multiple schema loading for cross-schema exploration

Common Workflows:

• Exploring existing schemas
• Quick data checks
• Testing database connections
• Viewing schema diagrams

Reference:

• All command-line options
• Programmatic usage from Python
• Entry points (dj and datajoint commands)

Related

• Companion to datajoint-python PR #1313

🤖 Generated with Claude Code