constella 0.1.0

package/skills/stacks/orm/diesel/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: diesel
+description: Safe, extensible compile-time-checked ORM and query builder for Rust; consult for type-safe SQL against PostgreSQL, MySQL, or SQLite in Rust.
+domain: stack
+category: orm
+tags: [orm, rust, query-builder, postgresql, sqlite, mysql]
+official_sources:
+  - https://diesel.rs/guides/
+  - https://github.com/diesel-rs/diesel
+verified: 2026-06-16
+---
+
+# Diesel
+
+## Overview
+Diesel is a safe, extensible ORM and query builder for Rust that uses Rust's type system to catch query errors at compile time and eliminate boilerplate. It supports PostgreSQL, MySQL, and SQLite with a zero-cost, Rust-like query DSL. Read this when building Rust applications that need type-safe, performant database access.
+
+## Official sources
+- Docs / guides: https://diesel.rs/guides/
+- Repo: https://github.com/diesel-rs/diesel
+- Install / getting started: https://diesel.rs/guides/getting-started
+
+## Install / setup
+```bash
+cargo install diesel_cli --no-default-features --features postgres
+```
+Add to `Cargo.toml`:
+```toml
+diesel = { version = "2.2.0", features = ["postgres"] }
+dotenvy = "0.15"
+```
+
+## Core concepts
+- **diesel_cli**: command-line tool that creates the database, manages migrations, and generates schema (`diesel setup`, `diesel migration`).
+- **schema.rs**: generated `table!` definitions describing tables and columns, used for compile-time query checking.
+- **Migrations**: pairs of `up.sql`/`down.sql` files applied and reverted by the CLI.
+- **Connection**: a typed connection (e.g. `PgConnection`) established with a database URL.
+- **Query DSL**: methods like `filter`, `select`, `load`, `insert_into` compile to checked SQL.
+- **Derive macros**: `Queryable`, `Insertable`, `Selectable` map Rust structs to rows.
+
+## Best practices
+- Install `diesel_cli` with only the features you need (e.g. `--no-default-features --features postgres`) to avoid pulling in unused client libraries (per the getting-started guide).
+- Keep `schema.rs` generated from migrations rather than hand-editing it, so it matches the database.
+- Store the connection URL in a `.env` file (used with `dotenvy`) as shown in the guide.
+- Write reversible migrations (`up.sql` + `down.sql`) and run them through the CLI.
+
+## Common pitfalls
+- Installing `diesel_cli` without the right backend feature → build errors or a CLI that cannot talk to your database; specify the backend feature.
+- Editing `schema.rs` by hand → drift from the real schema; regenerate it from migrations instead.
+
+## Examples
+```rust
+use diesel::prelude::*;
+
+#[derive(Queryable, Selectable)]
+#[diesel(table_name = crate::schema::users)]
+struct User { id: i32, name: String }
+
+let conn = &mut PgConnection::establish(&database_url)?;
+let results = users::table
+    .filter(users::name.eq("Ada"))
+    .select(User::as_select())
+    .load(conn)?;
+```
+
+## Further reading
+- https://diesel.rs/guides/getting-started — getting started
+- https://diesel.rs/guides/all-about-inserts — inserts guide
+
+## Related skills
+- ../gorm — Go's standard ORM (contrast: another typed-language ORM)
+- ../prisma — type-safe ORM in the TS ecosystem

package/skills/stacks/orm/django-orm/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: django-orm
+description: Django's built-in ORM — models, QuerySets, migrations, and the admin; consult for relational data access inside a Django project.
+domain: stack
+category: orm
+tags: [orm, python, django, models, queryset, migrations]
+official_sources:
+  - https://docs.djangoproject.com/en/stable/topics/db/
+  - https://github.com/django/django
+verified: 2026-06-16
+---
+
+# Django ORM
+
+## Overview
+The Django ORM ships with the Django web framework and is the single, definitive source of truth for your data: each model maps to a database table, and you query through lazy QuerySets. It includes a migration system and integrates with the Django admin. Read this when building data access inside a Django project rather than as a standalone library (the ORM is not distributed separately).
+
+## Official sources
+- Docs: https://docs.djangoproject.com/en/stable/topics/db/
+- Repo: https://github.com/django/django
+
+## Core concepts
+- **Models**: subclasses of `django.db.models.Model`; each field maps to a column and each model to a table.
+- **QuerySets**: lazy, chainable query objects (`Model.objects.filter(...)`) that hit the database only when evaluated.
+- **Managers**: the `objects` manager is the query entry point; custom managers add reusable query logic.
+- **Migrations**: schema changes are captured by `makemigrations` and applied with `migrate`.
+- **Relationships**: `ForeignKey`, `ManyToManyField`, `OneToOneField` model associations with related-object access.
+- **Aggregation & raw SQL**: `annotate`/`aggregate` for grouped queries, plus escape hatches for raw SQL when needed.
+
+## Best practices
+- Use `select_related` (joins) and `prefetch_related` (separate queries) to avoid N+1 when traversing relations (per docs).
+- Always create and review migrations with `makemigrations`/`migrate`; keep them in version control.
+- Defer or restrict columns with `only()`/`defer()` and `values()` when you do not need full model instances.
+- Wrap multi-step writes in `transaction.atomic()` for atomicity.
+
+## Common pitfalls
+- Iterating related objects in a loop without `select_related`/`prefetch_related` → N+1 query storms.
+- Assuming QuerySets execute immediately → they are lazy and re-evaluating one repeatedly re-runs the query; cache with `list()` when reused.
+
+## Examples
+```python
+from django.db import models
+
+class User(models.Model):
+    name = models.CharField(max_length=50)
+
+# querying
+ada = User.objects.create(name="Ada")
+adults = User.objects.filter(name="Ada").select_related()
+```
+
+## Further reading
+- https://docs.djangoproject.com/en/stable/topics/db/queries/ — making queries
+- https://docs.djangoproject.com/en/stable/topics/db/optimization/ — query optimization
+
+## Related skills
+- ../sqlalchemy — standalone Python ORM/toolkit alternative
+- ../prisma — type-safe ORM in the TS ecosystem

package/skills/stacks/orm/drizzle/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: drizzle
+description: Lightweight, headless TypeScript-first SQL ORM with zero dependencies and SQL-like queries; consult for type-safe SQL in Node/edge runtimes.
+domain: stack
+category: orm
+tags: [orm, typescript, nodejs, sql, serverless, postgresql]
+official_sources:
+  - https://orm.drizzle.team/docs/overview
+  - https://github.com/drizzle-team/drizzle-orm
+verified: 2026-06-16
+---
+
+# Drizzle ORM
+
+## Overview
+Drizzle is a headless, TypeScript-first ORM that stays close to SQL: you describe tables in TypeScript and write queries with a SQL-like fluent API. It is lightweight (~7.4kb minified+gzipped), tree-shakeable, and ships with zero dependencies, making it well suited to serverless and edge runtimes (Bun, Deno, Cloudflare Workers). Read this when you want type safety without a heavy abstraction layer over SQL.
+
+## Official sources
+- Docs: https://orm.drizzle.team/docs/overview
+- Repo: https://github.com/drizzle-team/drizzle-orm
+- Install / get started: https://orm.drizzle.team/docs/get-started
+
+## Install / setup
+```bash
+npm i drizzle-orm pg
+npm i -D drizzle-kit @types/pg
+```
+
+## Core concepts
+- **Schema in TypeScript**: tables/columns are declared with helpers like `pgTable`, giving full inference for queries.
+- **Two query styles**: a SQL-like query builder (`select().from()...`) and a relational queries API for ergonomic nested reads.
+- **drizzle-kit**: the companion CLI for generating and applying migrations from your TS schema.
+- **Driver-agnostic**: connect via the appropriate driver (node-postgres, postgres.js, MySQL, SQLite/libSQL, etc.).
+- **Headless / no codegen runtime**: types come from your schema declarations, not a generated client.
+
+## Best practices
+- Define schema in dedicated files and import them where queries run so types stay inferred end to end.
+- Use `drizzle-kit generate` to produce migration SQL and apply it with `drizzle-kit migrate` (per Drizzle docs) rather than hand-editing tables.
+- Pick the query API to match the task: the query builder for explicit SQL, relational queries for nested fetches.
+- Pin and review generated migrations in version control before applying to production.
+
+## Common pitfalls
+- Expecting Prisma-style automatic client generation → Drizzle is headless; types derive from your schema declarations, so keep schema imports accurate.
+- Mixing incompatible driver and dialect (e.g. a `pg` driver with a MySQL schema) → choose the driver/dialect pair the docs specify for your database.
+
+## Examples
+```ts
+import { drizzle } from 'drizzle-orm/node-postgres'
+import { pgTable, serial, text } from 'drizzle-orm/pg-core'
+import { eq } from 'drizzle-orm'
+
+export const users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  name: text('name'),
+})
+
+const db = drizzle(process.env.DATABASE_URL!)
+const ada = await db.select().from(users).where(eq(users.name, 'Ada'))
+```
+
+## Further reading
+- https://orm.drizzle.team/docs/migrations — migrations with drizzle-kit
+- https://orm.drizzle.team/docs/rqb — relational queries API
+
+## Related skills
+- ../prisma — schema-DSL ORM with codegen alternative
+- ../knex — lower-level SQL query builder

package/skills/stacks/orm/gorm/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: gorm
+description: The fantastic, developer-friendly ORM for Go with associations, hooks, transactions, and auto-migration; consult for relational data access in Go.
+domain: stack
+category: orm
+tags: [orm, go, golang, database, migrations, associations]
+official_sources:
+  - https://gorm.io/docs/
+  - https://github.com/go-gorm/gorm
+verified: 2026-06-16
+---
+
+# GORM
+
+## Overview
+GORM is the de-facto ORM library for Go, aiming to be developer-friendly. It maps Go structs to tables and provides associations, hooks, transactions, eager loading, and auto-migration, with driver support for PostgreSQL, MySQL, SQLite, SQL Server, and others. Read this when building Go services that need a full-featured ORM rather than hand-written SQL.
+
+## Official sources
+- Docs: https://gorm.io/docs/
+- Repo: https://github.com/go-gorm/gorm
+- Install / index: https://gorm.io/docs/index.html
+
+## Install / setup
+```bash
+go get -u gorm.io/gorm
+go get -u gorm.io/driver/sqlite
+```
+
+## Core concepts
+- **Models**: plain Go structs whose fields map to columns; embed `gorm.Model` for ID/timestamps/soft-delete.
+- **`*gorm.DB`**: the database handle opened with `gorm.Open(driver, &gorm.Config{})`; carries chainable method calls.
+- **CRUD chain methods**: `Create`, `First`/`Find`, `Where`, `Update`, `Delete` build and run queries.
+- **Associations**: `Has One`, `Has Many`, `Belongs To`, `Many To Many` with `Preload` for eager loading.
+- **AutoMigrate**: creates/updates tables to match struct definitions.
+- **Hooks & transactions**: lifecycle callbacks (`BeforeCreate` etc.) and `db.Transaction(func...)` for atomic work.
+
+## Best practices
+- Open the database once and reuse the shared `*gorm.DB`; it manages an underlying connection pool.
+- Use `Preload` (or joins) to load associations and avoid N+1 queries (per docs).
+- Treat `AutoMigrate` as convenient for development; review schema changes carefully before relying on it in production (it only adds, it will not delete columns).
+- Always check the returned `error` (and `RowsAffected`) on query chains.
+
+## Common pitfalls
+- Ignoring the `.Error` field on a chained call → silent failures; inspect `result.Error` after each operation.
+- Expecting `AutoMigrate` to drop or rename columns → it does not remove columns; use explicit migrations for destructive changes.
+
+## Examples
+```go
+import (
+  "gorm.io/gorm"
+  "gorm.io/driver/sqlite"
+)
+
+type User struct {
+  gorm.Model
+  Name string
+}
+
+db, _ := gorm.Open(sqlite.Open("app.db"), &gorm.Config{})
+db.AutoMigrate(&User{})
+db.Create(&User{Name: "Ada"})
+
+var u User
+db.Where("name = ?", "Ada").First(&u)
+```
+
+## Further reading
+- https://gorm.io/docs/models.html — declaring models
+- https://gorm.io/docs/preload.html — preloading associations
+
+## Related skills
+- ../diesel — Rust's type-safe ORM (contrast: another typed-language ORM)
+- ../prisma — type-safe ORM in the TS ecosystem

package/skills/stacks/orm/knex/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: knex
+description: Flexible multi-dialect SQL query builder for Node.js with transactions, pooling, and migrations; consult when you want SQL control without a full ORM.
+domain: stack
+category: orm
+tags: [query-builder, nodejs, sql, migrations, transactions, postgresql]
+official_sources:
+  - https://knexjs.org/
+  - https://github.com/knex/knex
+verified: 2026-06-16
+---
+
+# Knex.js
+
+## Overview
+Knex is a batteries-included, multi-dialect SQL query builder for Node.js supporting PostgreSQL, MySQL/MariaDB, SQLite3, MSSQL, CockroachDB, and Oracle. It builds SQL with a fluent, chainable API and adds transactions, connection pooling, streaming, and a migration/seed system. Read this when you want fine SQL control and portability without the abstraction of a full ORM.
+
+## Official sources
+- Docs: https://knexjs.org/
+- Repo: https://github.com/knex/knex
+- Install / guide: https://knexjs.org/guide/#node-js
+
+## Install / setup
+```bash
+npm install knex --save
+npm install pg
+```
+
+## Core concepts
+- **Knex instance**: configured with a `client` (dialect) and `connection`; created once and reused.
+- **Query builder**: chainable methods (`select`, `where`, `join`, `insert`, `update`, `del`) that compile to SQL.
+- **Schema builder**: `knex.schema.createTable(...)` for DDL.
+- **Migrations & seeds**: versioned schema changes and seed data run via the Knex CLI.
+- **Transactions**: `knex.transaction(async trx => …)` for atomic multi-statement work.
+- **Connection pooling**: built-in pool managed per Knex instance.
+
+## Best practices
+- Install only the driver for your database (e.g. `pg`, `mysql2`, `sqlite3`) as the install guide instructs.
+- Create a single Knex instance and share it; each instance owns a connection pool.
+- Use migrations for all schema changes and commit them to version control.
+- Use parameterized builder methods (not string concatenation) to avoid SQL injection; use `knex.raw` with bindings when raw SQL is needed.
+
+## Common pitfalls
+- Creating multiple Knex instances → multiple pools that can exhaust database connections; reuse one instance.
+- Interpolating user input into `knex.raw` strings → SQL injection; pass values as bindings (`?`) instead.
+
+## Examples
+```js
+const knex = require('knex')({
+  client: 'pg',
+  connection: process.env.DATABASE_URL,
+})
+
+await knex('users').insert({ name: 'Ada' })
+const users = await knex('users').where({ name: 'Ada' }).select('*')
+```
+
+## Further reading
+- https://knexjs.org/guide/migrations.html — migrations
+- https://knexjs.org/guide/query-builder.html — query builder reference
+
+## Related skills
+- ../drizzle — TS-first SQL ORM that also stays close to SQL
+- ../sequelize — full ORM built atop query-builder concepts

package/skills/stacks/orm/mongoose/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: mongoose
+description: MongoDB object modeling (ODM) for Node.js with schemas, validation, and middleware; consult for structured MongoDB access in JS/TS.
+domain: stack
+category: orm
+tags: [odm, mongodb, nodejs, javascript, typescript, schema]
+official_sources:
+  - https://mongoosejs.com/docs/
+  - https://github.com/Automattic/mongoose
+verified: 2026-06-16
+---
+
+# Mongoose
+
+## Overview
+Mongoose is an Object Data Modeling (ODM) library for MongoDB designed to work in an asynchronous environment. It adds schemas, type casting, validation, query building, and middleware on top of the MongoDB driver. Read this when you want structure and validation around an otherwise schemaless MongoDB database in Node.js (or Deno).
+
+## Official sources
+- Docs: https://mongoosejs.com/docs/
+- Repo: https://github.com/Automattic/mongoose
+- Install / index: https://mongoosejs.com/docs/index.html
+
+## Install / setup
+```bash
+npm install mongoose
+```
+
+## Core concepts
+- **Schema**: defines document shape, types, defaults, and validation rules for a collection.
+- **Model**: a constructor compiled from a schema (`mongoose.model()`) used to create and query documents.
+- **Documents**: model instances with getters/setters, validation, and `.save()`.
+- **Queries**: chainable query builder (`Model.find().where()...`) returning thenable queries.
+- **Middleware (hooks)**: `pre`/`post` hooks on operations like `save`/`validate` for cross-cutting logic.
+- **Population**: `populate()` resolves referenced documents across collections (Mongoose's join-like feature).
+
+## Best practices
+- Call `mongoose.connect()` once at startup and reuse the connection; Mongoose buffers operations until connected.
+- Define validation and required fields in the schema so invalid documents are rejected before write.
+- Use `lean()` for read-only queries to skip hydrating full Mongoose documents and improve performance.
+- Use `populate()` selectively (with field selection) to avoid pulling large referenced documents.
+
+## Common pitfalls
+- Relying on `populate()` like a SQL join for heavy relational workloads → it issues extra queries; model data access patterns accordingly.
+- Expecting MongoDB to enforce the schema → only Mongoose enforces it; writes via the raw driver bypass validation.
+
+## Examples
+```js
+const mongoose = require('mongoose')
+await mongoose.connect(process.env.MONGODB_URI)
+
+const userSchema = new mongoose.Schema({ name: { type: String, required: true } })
+const User = mongoose.model('User', userSchema)
+
+const ada = await User.create({ name: 'Ada' })
+const users = await User.find({ name: 'Ada' }).lean()
+```
+
+## Further reading
+- https://mongoosejs.com/docs/guide.html — schemas guide
+- https://mongoosejs.com/docs/populate.html — population
+
+## Related skills
+- ../prisma — also supports MongoDB with a typed client
+- ../sequelize — ORM for SQL databases (contrast: relational vs document)

package/skills/stacks/orm/prisma/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: prisma
+description: Type-safe TS/JS ORM with a declarative schema DSL, auto-generated client, and migrations; consult when modeling data in Node.js.
+domain: stack
+category: orm
+tags: [orm, typescript, nodejs, database, migrations, postgresql]
+official_sources:
+  - https://www.prisma.io/docs
+  - https://github.com/prisma/prisma
+verified: 2026-06-16
+---
+
+# Prisma ORM
+
+## Overview
+Prisma is a next-generation ORM for Node.js and TypeScript. You declare your data model in a single `schema.prisma` file using its schema DSL, then Prisma generates a fully type-safe query client and manages SQL migrations. Read this when you need ergonomic, type-checked database access against PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, MongoDB, or CockroachDB.
+
+## Official sources
+- Docs: https://www.prisma.io/docs
+- Repo: https://github.com/prisma/prisma
+- Install / quickstart: https://www.prisma.io/docs/getting-started/quickstart
+
+## Install / setup
+```bash
+npm install prisma @types/pg --save-dev
+npm install @prisma/client @prisma/adapter-pg pg dotenv
+npx prisma init --output ../generated/prisma
+```
+
+## Core concepts
+- **Prisma schema (`schema.prisma`)**: the single source of truth — declares the datasource, generator, and `model` definitions in Prisma's DSL.
+- **Prisma Client**: an auto-generated, type-safe query builder; regenerate it with `npx prisma generate` after schema changes.
+- **Prisma Migrate**: turns schema changes into SQL migration files via `npx prisma migrate dev`.
+- **Models, fields, and relations**: each `model` maps to a table; relation fields and `@relation` express foreign keys.
+- **Prisma Studio**: a GUI to browse and edit data, launched with `npx prisma studio`.
+
+## Best practices
+- Keep the schema as the source of truth and commit migration files; use `migrate dev` in development and `migrate deploy` in production (per Prisma docs).
+- Run `prisma generate` whenever the schema changes so the client's types stay in sync.
+- Instantiate a single `PrismaClient` and reuse it; avoid creating many instances which exhausts the connection pool.
+- Use `select`/`include` to fetch only needed fields and relations rather than over-fetching.
+
+## Common pitfalls
+- Instantiating `PrismaClient` per request (common in serverless/hot-reload) → exhausts connections; use a shared singleton.
+- Forgetting to run `prisma generate` after editing the schema → stale types and runtime mismatches; regenerate after every change.
+
+## Examples
+```ts
+import { PrismaClient } from './generated/prisma'
+const prisma = new PrismaClient()
+
+const user = await prisma.user.create({
+  data: { email: 'a@example.com', name: 'Ada' },
+})
+const users = await prisma.user.findMany({ where: { name: 'Ada' } })
+```
+
+## Further reading
+- https://www.prisma.io/docs/orm/prisma-schema — Prisma schema reference
+- https://www.prisma.io/docs/orm/prisma-migrate — Prisma Migrate guide
+
+## Related skills
+- ../drizzle — lighter-weight TypeScript SQL ORM alternative
+- ../typeorm — decorator-based TS/JS ORM alternative

package/skills/stacks/orm/sequelize/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: sequelize
+description: Mature promise-based JS/TS ORM for SQL databases with models, associations, and transactions; consult for established Node.js relational data access.
+domain: stack
+category: orm
+tags: [orm, nodejs, javascript, typescript, sql, transactions]
+official_sources:
+  - https://sequelize.org/docs/v6/
+  - https://github.com/sequelize/sequelize
+verified: 2026-06-16
+---
+
+# Sequelize
+
+## Overview
+Sequelize is a mature, promise-based ORM for Node.js that targets SQL databases including PostgreSQL, MySQL, MariaDB, SQLite, and SQL Server. It provides model definitions, associations, eager/lazy loading, transactions, and read replication. Read this when working in an established JavaScript/TypeScript codebase that uses Sequelize or when you want a battle-tested relational ORM.
+
+## Official sources
+- Docs: https://sequelize.org/docs/v6/
+- Repo: https://github.com/sequelize/sequelize
+- Install / getting started: https://sequelize.org/docs/v6/getting-started/
+
+## Install / setup
+```bash
+npm install --save sequelize
+```
+
+## Core concepts
+- **Sequelize instance**: the connection object created with a connection URI or options, plus the chosen dialect driver.
+- **Models**: defined via `sequelize.define()` or by extending `Model`; map to tables with typed attributes.
+- **Associations**: `hasOne`, `hasMany`, `belongsTo`, `belongsToMany` express relationships and generate helper methods.
+- **Querying**: finder methods (`findAll`, `findOne`, `findByPk`) with `where` operators and `include` for eager loading.
+- **Transactions**: managed (`sequelize.transaction(async t => …)`) or unmanaged, for atomic multi-statement work.
+- **Migrations & seeders**: managed via the separate Sequelize CLI.
+
+## Best practices
+- Install the dialect-specific driver alongside Sequelize (e.g. `pg`, `mysql2`, `sqlite3`) as the docs require.
+- Use managed transactions so commit/rollback is handled automatically on success/error.
+- Prefer migrations over `sync({ force: true })` in production, which drops and recreates tables.
+- Use `include` deliberately and select only needed attributes to avoid N+1 and over-fetching.
+
+## Common pitfalls
+- Running `sequelize.sync({ force: true })` against a real database → drops all tables; use migrations instead.
+- Forgetting to install the dialect driver → connection fails at startup; install the matching driver package.
+
+## Examples
+```js
+const { Sequelize, DataTypes } = require('sequelize')
+const sequelize = new Sequelize(process.env.DATABASE_URL)
+
+const User = sequelize.define('User', {
+  name: { type: DataTypes.STRING },
+})
+
+await sequelize.authenticate()
+const ada = await User.create({ name: 'Ada' })
+```
+
+## Further reading
+- https://sequelize.org/docs/v6/core-concepts/model-basics/ — model basics
+- https://sequelize.org/docs/v6/other-topics/transactions/ — transactions
+
+## Related skills
+- ../typeorm — decorator-based TS/JS ORM alternative
+- ../knex — lower-level SQL query builder Sequelize sits above

package/skills/stacks/orm/sqlalchemy/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: sqlalchemy
+description: The de-facto Python SQL toolkit and ORM with Core expression language and full ORM layer; consult for relational data access in Python.
+domain: stack
+category: orm
+tags: [orm, python, sql, database, core, session]
+official_sources:
+  - https://docs.sqlalchemy.org/
+  - https://github.com/sqlalchemy/sqlalchemy
+verified: 2026-06-16
+---
+
+# SQLAlchemy
+
+## Overview
+SQLAlchemy is the de-facto Python SQL toolkit and Object Relational Mapper. It offers two layers: **Core**, a Python SQL expression language and database abstraction, and the **ORM**, which maps classes to tables using the unit-of-work and identity-map patterns. Read this for relational database access in Python when you want full control over SQL alongside high-level ORM mapping.
+
+## Official sources
+- Docs: https://docs.sqlalchemy.org/
+- Repo: https://github.com/sqlalchemy/sqlalchemy
+- Install: https://docs.sqlalchemy.org/en/20/intro.html#installation
+
+## Install / setup
+```bash
+pip install SQLAlchemy
+```
+
+## Core concepts
+- **Engine**: the starting point created with `create_engine()`; manages DBAPI connections and the connection pool.
+- **Core vs ORM**: Core exposes the SQL Expression Language (`Table`, `select()`); the ORM maps classes via declarative models.
+- **Declarative models**: classes inheriting from a `DeclarativeBase` with `Mapped`/`mapped_column` (2.0 style) map to tables.
+- **Session**: the ORM's unit of work — tracks changes and flushes them in a transaction; obtain via `Session`/`sessionmaker`.
+- **2.0 unified query API**: `select()` with `session.execute()` / `session.scalars()` is the modern querying style.
+- **Relationships**: `relationship()` defines associations with configurable lazy/eager loading strategies.
+
+## Best practices
+- Create one `Engine` per database and reuse it; do not create engines per request (per docs, the engine owns the pool).
+- Scope `Session` to a logical unit of work and use it as a context manager / `session.begin()` so transactions commit or roll back cleanly.
+- Use the 2.0-style `select()` API and `Mapped`/`mapped_column` typing for new code.
+- Configure relationship loading (`selectin`, `joined`) deliberately to control eager vs lazy loading and avoid N+1.
+
+## Common pitfalls
+- Sharing a single `Session` across threads/requests → it is not thread-safe; use a fresh session per unit of work (or `scoped_session`).
+- Triggering lazy loads after the session closes → `DetachedInstanceError`; load needed relationships eagerly or keep the session open.
+
+## Examples
+```python
+from sqlalchemy import create_engine, String
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, Session
+
+class Base(DeclarativeBase): ...
+
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(50))
+
+engine = create_engine("postgresql+psycopg://localhost/app")
+Base.metadata.create_all(engine)
+with Session(engine) as session:
+    session.add(User(name="Ada"))
+    session.commit()
+```
+
+## Further reading
+- https://docs.sqlalchemy.org/en/20/orm/quickstart.html — ORM quickstart
+- https://docs.sqlalchemy.org/en/20/tutorial/index.html — unified tutorial
+
+## Related skills
+- ../django-orm — Python ORM bundled with Django
+- ../prisma — type-safe ORM in the TS ecosystem