# BigAl

> PostgreSQL-optimized TypeScript ORM

Built exclusively for Postgres. Type-safe fluent query builder, decorator-based models, and queries tuned for Postgres performance.

## Table of Contents

### Introduction

- [Getting Started](/bigal/getting-started.md): Install BigAl, define your first model with decorators, initialize a repository, and run type-safe PostgreSQL queries.

### Guide

- [Models](/bigal/guide/models.md): Define PostgreSQL tables as TypeScript classes with decorators for columns, primary keys, relationships, and automatic timestamps.
- [Querying](/bigal/guide/querying.md): Fluent query builder for find, findOne, and count with WHERE operators, JSONB querying, pagination, sorting, DISTINCT ON, and populate.
- [CRUD Operations](/bigal/guide/crud-operations.md): Create, update, and destroy records with RETURNING support, query projection, and ON CONFLICT upserts.
- [Relationships](/bigal/guide/relationships.md): Many-to-one, one-to-many, and many-to-many relationships with decorators, QueryResult type narrowing, and populate options.
- [Subqueries and Joins](/bigal/guide/subqueries-and-joins.md): Type-safe subqueries for WHERE IN, EXISTS, and scalar comparisons. Model joins, subquery joins, aggregates, GROUP BY, and HAVING.
- [Views and Readonly Repositories](/bigal/guide/views.md): Map PostgreSQL views to readonly models with ReadonlyRepository. Supports inheritance, schema options, and all query features.

### Reference

- [API Reference](/bigal/reference/api.md): Complete API reference for BigAl — initialize(), Repository, ReadonlyRepository, query builder methods, subquery(), decorators, and types.
- [Configuration](/bigal/reference/configuration.md): Configure connection pools (postgres-pool, pg, Neon), read replicas, multiple databases, and debug logging.

### Advanced

- [BigAl vs Raw SQL](/bigal/advanced/bigal-vs-raw-sql.md): When to use BigAl vs raw SQL, with a side-by-side translation table mapping common SQL queries to BigAl's fluent API.
- [Known Issues](/bigal/advanced/known-issues.md): Known issues and workarounds — optional collections, NotEntity for JSON objects with id fields, and DEBUG_BIGAL logging.