constellai 0.3.0

package/skills/stacks/database/mariadb/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: mariadb
+description: Community-developed open-source fork of MySQL with extra storage engines and features; consult for MySQL-compatible relational backends.
+domain: stack
+category: database
+tags: [mariadb, sql, rdbms, relational, mysql-fork]
+official_sources:
+  - https://mariadb.com/docs/
+  - https://github.com/MariaDB/server
+verified: 2026-06-16
+---
+
+# MariaDB
+
+## Overview
+MariaDB is a community-developed fork of MySQL started by core members of the original MySQL team, designed as a drop-in replacement with additional storage engines, features, and a permissive license. Read this when you want a MySQL-compatible relational database with the MariaDB ecosystem (e.g., Galera clustering, additional engines).
+
+## Official sources
+- Docs: https://mariadb.com/docs/
+- Repo (official, MariaDB Foundation/Corporation): https://github.com/MariaDB/server
+- Download: https://mariadb.org/download/
+
+## Install / setup
+MariaDB ships in the standard repositories of major Linux distributions as the `mariadb-server` package. On Ubuntu/Debian (from the official quickstart install guide):
+
+```bash
+sudo apt update
+sudo apt install mariadb-server mariadb-client galera-4
+sudo mariadb-secure-installation
+```
+
+For specific MariaDB versions, the MariaDB download page (mariadb.org/download/) generates tailored repository setup instructions per OS/architecture.
+
+## Core concepts
+- MySQL compatibility: largely a drop-in replacement; the `mysql`/`mariadb` client and wire protocol are compatible.
+- Pluggable storage engines: InnoDB by default, plus MariaDB-specific engines (Aria, ColumnStore, etc.).
+- Galera Cluster: synchronous multi-source replication for high availability (the `galera-4` package).
+- Indexes, transactions, and ACID semantics under InnoDB, as in MySQL.
+- `mariadb-secure-installation` to harden a new server.
+- Character sets/collations: use `utf8mb4` for full Unicode.
+
+## Best practices
+- Use InnoDB for transactional, crash-safe workloads (the default engine).
+- Use `utf8mb4` rather than legacy `utf8` for full Unicode support.
+- Run `mariadb-secure-installation` after install to remove anonymous users and test databases.
+- For high availability, evaluate Galera Cluster rather than rolling your own replication.
+- Verify query plans with `EXPLAIN` and index columns used in joins and filters.
+
+## Common pitfalls
+- Assuming 100% feature parity with the latest MySQL → divergence has grown; check the MariaDB docs for version-specific syntax and functions.
+- Using legacy `utf8` and hitting 4-byte character errors → use `utf8mb4`.
+- Mixing MariaDB and MySQL client/server versions and assuming identical behavior → confirm compatibility for your versions.
+- Skipping `mariadb-secure-installation` on a fresh server → insecure defaults remain.
+
+## Examples
+```sql
+CREATE TABLE orders (
+  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  customer_email VARCHAR(255) NOT NULL,
+  total_cents INT NOT NULL,
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+## Further reading
+- MariaDB quickstart guides: https://mariadb.com/docs/server/mariadb-quickstart-guides/
+- Downloads & repository setup: https://mariadb.org/download/
+
+## Related skills
+- ../mysql — the upstream project MariaDB forked from
+- ../postgresql — alternative open-source RDBMS

package/skills/stacks/database/mongodb/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: mongodb
+description: Document database storing flexible JSON-like (BSON) documents; consult for schema design, indexing, aggregation, and NoSQL data modeling.
+domain: stack
+category: database
+tags: [mongodb, nosql, document, bson, database]
+official_sources:
+  - https://www.mongodb.com/docs/
+  - https://github.com/mongodb/mongo
+verified: 2026-06-16
+---
+
+# MongoDB
+
+## Overview
+MongoDB is a document-oriented NoSQL database that stores flexible, JSON-like documents (BSON) in collections, well suited for evolving schemas and nested data. Read this when modeling document data, designing indexes, writing queries/aggregations, or choosing between embedding and referencing.
+
+## Official sources
+- Docs: https://www.mongodb.com/docs/
+- Repo (official; SSPL v1 license for releases after 2018-10-16): https://github.com/mongodb/mongo
+- Download (Community Server): https://www.mongodb.com/try/download/community
+
+## Install / setup
+Download MongoDB Community Server from mongodb.com/try/download/community for your platform (Ubuntu, Debian, RedHat/CentOS, SUSE, Amazon Linux, macOS, Windows). MongoDB Atlas is the managed cloud alternative; its quick setup uses Homebrew:
+
+```bash
+brew install mongodb-atlas
+atlas setup
+```
+
+For self-hosted Community Server, follow the platform-specific install guide at https://www.mongodb.com/docs/manual/administration/install-community/.
+
+## Core concepts
+- Documents and collections: documents (BSON) are grouped into collections; no fixed schema is required.
+- Flexible schema: fields can vary between documents in the same collection.
+- Indexes: single-field, compound, multikey (arrays), text, and others; needed for query performance.
+- Aggregation pipeline: stages (`$match`, `$group`, `$lookup`, etc.) transform and compute over documents.
+- Embedding vs referencing: model related data inline (embed) or via references depending on access patterns.
+- Replica sets and sharding: replica sets provide HA; sharding partitions data horizontally across shards.
+
+## Best practices
+- Model schema around your application's query patterns; embed data that is read together, reference data that grows unboundedly.
+- Create indexes that support your queries and sorts; confirm usage with `explain()`.
+- Use the aggregation pipeline for server-side data transformation instead of pulling and processing in the app.
+- Prefer a replica set (even of one for dev parity) so transactions and failover behave as in production.
+- Use schema validation rules when you need to enforce document shape.
+
+## Common pitfalls
+- Treating MongoDB like a relational DB with many `$lookup` joins → reconsider the data model; embed where appropriate.
+- Letting documents grow without bound (e.g., ever-growing arrays) → can exceed the 16 MB document limit; use references/bucketing.
+- Forgetting indexes on filtered/sorted fields → full collection scans.
+- Assuming multi-document atomicity without transactions → use transactions (requires a replica set) when you need them.
+
+## Examples
+```javascript
+db.users.insertOne({
+  email: "a@example.com",
+  profile: { name: "Ada", roles: ["admin"] },
+  createdAt: new Date()
+});
+
+db.users.createIndex({ email: 1 }, { unique: true });
+```
+
+## Further reading
+- Data modeling: https://www.mongodb.com/docs/manual/data-modeling/
+- Aggregation: https://www.mongodb.com/docs/manual/aggregation/
+
+## Related skills
+- ../dynamodb — managed key-value/document NoSQL alternative
+- ../redis — in-memory store for caching and ephemeral data

package/skills/stacks/database/mysql/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: mysql
+description: Popular open-source relational database from Oracle; consult for schema design, SQL, storage engines (InnoDB), and replication.
+domain: stack
+category: database
+tags: [mysql, sql, rdbms, relational, innodb]
+official_sources:
+  - https://dev.mysql.com/doc/
+  - https://github.com/mysql/mysql-server
+verified: 2026-06-16
+---
+
+# MySQL
+
+## Overview
+MySQL is a widely deployed open-source relational database maintained by Oracle, known for speed, reliability, and broad ecosystem support. Read this when building on a MySQL backend: designing tables, choosing storage engines, writing SQL, or configuring replication.
+
+## Official sources
+- Docs: https://dev.mysql.com/doc/
+- Repo (official, Oracle): https://github.com/mysql/mysql-server
+- Install / download: https://dev.mysql.com/downloads/
+
+## Install / setup
+On Debian/Ubuntu, MySQL provides the APT Repository (mysql-apt-config) from dev.mysql.com/downloads/. The Community Server, MySQL Shell, MySQL Router, and Workbench are listed there. On macOS the recommended path is via the MySQL Installer / DMG, and on Windows via the MySQL Installer for Windows.
+
+```bash
+# After installing the APT repo config package from dev.mysql.com/downloads/repo/apt/
+sudo apt update
+sudo apt install mysql-server
+```
+
+(Follow the exact repo-config steps on the official APT Repository download page for your distribution.)
+
+## Core concepts
+- Relational model with ACID transactions when using a transactional storage engine.
+- Storage engines: InnoDB (default, transactional, row-level locking, foreign keys) vs MyISAM (non-transactional, table locks).
+- Indexes: B-tree by default; covering, composite, and full-text indexes available.
+- Replication: source/replica (formerly master/slave) for read scaling and availability.
+- Character sets and collations: use `utf8mb4` for full Unicode (including emoji).
+- The `mysql` client and MySQL Shell for administration and scripting.
+
+## Best practices
+- Use the InnoDB storage engine for transactional integrity and crash recovery (it's the default).
+- Use `utf8mb4` character set rather than the legacy `utf8` (which is limited to 3-byte sequences).
+- Add appropriate indexes and verify with `EXPLAIN`; avoid functions on indexed columns in WHERE clauses.
+- Define explicit foreign keys and constraints under InnoDB to enforce referential integrity.
+- Run `mysql_secure_installation` to harden a fresh server.
+
+## Common pitfalls
+- Choosing `utf8` and later hitting 4-byte character failures → use `utf8mb4` from the start.
+- Relying on MyISAM for data that needs transactions or crash safety → use InnoDB.
+- Wrapping indexed columns in functions (e.g., `WHERE DATE(col) = ...`) → prevents index use.
+- Assuming default isolation; MySQL/InnoDB defaults to REPEATABLE READ → know the level your app needs.
+
+## Examples
+```sql
+CREATE TABLE users (
+  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  email VARCHAR(255) NOT NULL,
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE KEY uq_email (email)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+## Further reading
+- The InnoDB storage engine: https://dev.mysql.com/doc/refman/en/innodb-storage-engine.html
+- Optimization: https://dev.mysql.com/doc/refman/en/optimization.html
+
+## Related skills
+- ../mariadb — community-driven MySQL fork
+- ../planetscale — managed MySQL-compatible (Vitess) platform
+- ../postgresql — alternative open-source RDBMS

package/skills/stacks/database/neon/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: neon
+description: Open-source serverless Postgres that separates storage and compute with autoscaling, scale-to-zero, and database branching; consult for serverless Postgres.
+domain: stack
+category: database
+tags: [neon, postgres, serverless, branching, autoscaling]
+official_sources:
+  - https://neon.com/docs
+  - https://github.com/neondatabase/neon
+verified: 2026-06-16
+---
+
+# Neon
+
+## Overview
+Neon is an open-source serverless Postgres platform that separates storage and compute, enabling autoscaling, scale-to-zero, and Git-like database branching. Read this when you want managed PostgreSQL with per-developer/per-preview branches and pay-for-what-you-use compute.
+
+## Official sources
+- Docs: https://neon.com/docs
+- Repo (official): https://github.com/neondatabase/neon
+- Get started / sign up: https://neon.com/docs/get-started-with-neon/signing-up
+
+## Install / setup
+Neon is a managed serverless platform — there is no local server to install for normal use. Get started by signing up at console.neon.tech (email, GitHub, Google, or partner accounts), which provisions a Project with a default production branch. The Neon CLI manages projects and branches from the terminal; install it per the docs:
+
+```bash
+npm install -g neonctl
+```
+
+(See https://neon.com/docs/reference/neon-cli for the authoritative install instructions.)
+
+## Core concepts
+- Project: the top-level container holding branches, databases, and roles.
+- Storage/compute separation: a custom storage layer (Pageserver + Safekeepers for WAL) backs stateless Postgres compute nodes.
+- Branching: create instant, copy-on-write branches of your database for dev, testing, and previews.
+- Autoscaling and scale-to-zero: compute scales with load and can suspend when idle to save cost.
+- Standard Postgres: it is real PostgreSQL, so SQL, drivers, and most extensions work unchanged.
+- Roles and databases live within a branch; resetting a branch to its parent is a core workflow.
+
+## Best practices
+- Use database branches for each feature/PR/preview environment instead of sharing one database.
+- Account for cold starts when compute has scaled to zero in latency-sensitive paths; keep a minimum compute if needed.
+- Use connection pooling (Neon provides a pooled connection string) for serverless/edge clients that open many short connections.
+- Treat it as standard Postgres: apply normal schema design, indexing, and migration practices.
+- Keep the production branch protected and develop on child branches.
+
+## Common pitfalls
+- Ignoring cold-start latency after scale-to-zero → first query on a suspended compute is slower; configure accordingly.
+- Opening many direct (non-pooled) connections from serverless functions → exhausts connections; use the pooled endpoint.
+- Assuming branches are fully isolated forever → they share a parent point-in-time; understand copy-on-write semantics.
+- Forgetting it is plain Postgres and reaching for bespoke tooling → standard Postgres practices apply.
+
+## Examples
+```bash
+# Create a branch for a feature using the Neon CLI
+neonctl branches create --name feature-x
+
+# Get its connection string
+neonctl connection-string feature-x
+```
+
+## Further reading
+- Branching: https://neon.com/docs/introduction/branching
+- Connection pooling: https://neon.com/docs/connect/connection-pooling
+
+## Related skills
+- ../postgresql — the database engine Neon runs
+- ../supabase — Postgres-based backend platform with auth/storage/realtime

package/skills/stacks/database/planetscale/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: planetscale
+description: Managed database platform offering Vitess (MySQL-compatible) and Postgres clusters with branching and non-blocking schema changes; consult for scalable managed SQL.
+domain: stack
+category: database
+tags: [planetscale, vitess, mysql, postgres, managed]
+official_sources:
+  - https://planetscale.com/docs
+  - https://github.com/planetscale/cli
+verified: 2026-06-16
+---
+
+# PlanetScale
+
+## Overview
+PlanetScale is a managed database platform that offers fully managed Vitess (MySQL-compatible, horizontally shardable) clusters and PostgreSQL clusters on locally-attached NVMe storage, with developer features like database branching, deploy requests, and non-blocking schema changes. Read this when you want managed, scalable SQL with a branch-and-merge schema workflow.
+
+## Official sources
+- Docs: https://planetscale.com/docs
+- CLI repo (official): https://github.com/planetscale/cli
+- Org: https://github.com/planetscale
+
+> Note: PlanetScale is a managed cloud platform; there is no single open-source server repo to self-host the product. The `pscale` CLI is open source. As of verification, PlanetScale offers both Vitess and PostgreSQL clusters — check the docs for current engine support.
+
+## Install / setup
+Install the `pscale` CLI via Homebrew (from the official CLI repo README):
+
+```bash
+brew install planetscale/tap/pscale
+```
+
+Some `pscale` commands require a MySQL 8 client in your PATH. See the docs for environment setup.
+
+## Core concepts
+- Managed clusters: Vitess (MySQL-compatible, supports horizontal sharding) and PostgreSQL options.
+- Database branching: create isolated branches of your schema, like Git branches for the database.
+- Deploy requests: review and merge schema changes from a branch to production safely.
+- Non-blocking schema changes: schema migrations apply without locking tables/downtime.
+- High availability: deployments across availability zones with a primary and replicas, with automated failover.
+- Query insights: built-in observability for query performance.
+
+## Best practices
+- Use branches plus deploy requests to review schema changes rather than altering production directly.
+- For Vitess/MySQL, design with the sharding model in mind (Vitess does not support cross-shard foreign keys the way single-node MySQL does).
+- Use the `pscale` CLI and connection strings rather than embedding raw credentials.
+- Verify which engine (Vitess vs Postgres) your project uses, since features and SQL behavior differ.
+- Lean on non-blocking schema changes for online migrations instead of manual lock-heavy ALTERs.
+
+## Common pitfalls
+- Assuming full single-node MySQL semantics on a Vitess cluster → foreign keys and some cross-shard operations differ; check docs.
+- Editing production schema directly instead of via deploy requests → bypasses review/safety.
+- Hardcoding credentials rather than using the CLI/connection management → security and rotation issues.
+- Treating the platform as static → the product is evolving; re-verify engine/feature support against the docs.
+
+## Examples
+```bash
+# Authenticate and create a development branch
+pscale auth login
+pscale branch create my-db dev
+# Connect locally through a secure proxy
+pscale connect my-db dev
+```
+
+## Further reading
+- Environment setup: https://planetscale.com/docs/reference/planetscale-environment-setup
+- Branching: https://planetscale.com/docs
+
+## Related skills
+- ../mysql — the engine family PlanetScale's Vitess clusters are compatible with
+- ../postgresql — the engine behind PlanetScale's Postgres clusters

package/skills/stacks/database/postgresql/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: postgresql
+description: Robust open-source relational database with strong SQL, ACID, and extensibility; consult for schema design, transactions, and indexing.
+domain: stack
+category: database
+tags: [postgresql, sql, rdbms, relational, acid]
+official_sources:
+  - https://www.postgresql.org/docs/
+  - https://github.com/postgres/postgres
+verified: 2026-06-16
+---
+
+# PostgreSQL
+
+## Overview
+PostgreSQL is a mature, open-source object-relational database emphasizing standards compliance, ACID transactions, and extensibility. Read this when choosing a relational store, designing schemas, writing SQL, or tuning indexes and queries for a Postgres backend.
+
+## Official sources
+- Docs: https://www.postgresql.org/docs/
+- Repo (official GitHub mirror; development uses the project's own git): https://github.com/postgres/postgres
+- Install / download: https://www.postgresql.org/download/
+
+## Install / setup
+Ubuntu, via the PostgreSQL Apt repository (from postgresql.org/download/linux/ubuntu/):
+
+```bash
+sudo apt install -y postgresql-common
+sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
+sudo apt update
+sudo apt install postgresql-18
+```
+
+The simplest path (distribution-included package) is:
+
+```bash
+apt install postgresql
+```
+
+## Core concepts
+- Relational model with ACID transactions; everything runs inside a transaction (explicit or implicit).
+- Rich type system: beyond standard SQL types, native JSON/JSONB, arrays, ranges, and user-defined types.
+- MVCC (Multi-Version Concurrency Control): readers don't block writers and vice versa; old row versions are cleaned by VACUUM.
+- Indexes: B-tree (default), plus GIN, GiST, BRIN, and Hash for specialized access patterns (e.g., GIN for JSONB/full-text).
+- Extensions: functionality like PostGIS or pg_trgm loaded via `CREATE EXTENSION`.
+- Roles and privileges: a unified role system handles both users and groups.
+- Schemas: namespaces within a database for organizing objects.
+
+## Best practices
+- Use the appropriate index type for the query; verify plans with `EXPLAIN ANALYZE` before adding indexes blindly.
+- Prefer `JSONB` over `JSON` when you need to index or query inside documents (binary form supports GIN indexing).
+- Let autovacuum run, and monitor for table bloat on high-churn tables (see docs on routine vacuuming).
+- Use connection pooling for high-concurrency apps; each connection is a backend process.
+- Define explicit constraints (NOT NULL, FOREIGN KEY, CHECK, UNIQUE) so the database enforces integrity.
+
+## Common pitfalls
+- Skipping `EXPLAIN ANALYZE` and assuming an index is used → confirm the planner actually chooses it.
+- Treating `JSON` and `JSONB` as interchangeable → `JSON` preserves text and is not efficiently indexable; use `JSONB` for querying.
+- Ignoring VACUUM/autovacuum on write-heavy tables → leads to bloat and transaction ID wraparound risk.
+- Opening one DB connection per request without pooling → process exhaustion under load.
+
+## Examples
+```sql
+CREATE TABLE users (
+  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  email TEXT NOT NULL UNIQUE,
+  profile JSONB NOT NULL DEFAULT '{}',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_users_profile ON users USING GIN (profile);
+```
+
+## Further reading
+- Indexes: https://www.postgresql.org/docs/current/indexes.html
+- Routine vacuuming: https://www.postgresql.org/docs/current/routine-vacuuming.html
+
+## Related skills
+- ../mysql — alternative open-source RDBMS
+- ../supabase — hosted Postgres with auth/storage/realtime
+- ../neon — serverless Postgres
+- ../cockroachdb — distributed, Postgres-wire-compatible SQL

package/skills/stacks/database/redis/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: redis
+description: In-memory data structure store for caching, queues, sessions, and pub/sub; canonical entry for using Redis as cache or fast key-value store.
+domain: stack
+category: database
+tags: [redis, cache, in-memory, key-value, pubsub]
+official_sources:
+  - https://redis.io/docs/latest/
+  - https://github.com/redis/redis
+verified: 2026-06-16
+---
+
+# Redis
+
+## Overview
+Redis is an in-memory data structure store used as a cache, key-value database, message broker, and data structure server. Read this as the canonical entry point when adding caching, session storage, rate limiting, queues, or pub/sub to an application.
+
+## Official sources
+- Docs: https://redis.io/docs/latest/
+- Repo (official; tri-licensed RSALv2/SSPLv1/AGPLv3 for v8.0+): https://github.com/redis/redis
+- Install guide: https://redis.io/docs/latest/operate/oss_and_stack/install/install-stack/
+
+## Install / setup
+Run via Docker (works on all platforms, per the official install docs):
+
+```bash
+docker run -d --name redis -p 6379:6379 redis
+```
+
+On Ubuntu/Debian via the official APT repository:
+
+```bash
+sudo apt-get install lsb-release curl gpg
+curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
+sudo chmod 644 /usr/share/keyrings/redis-archive-keyring.gpg
+echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list
+sudo apt-get update
+sudo apt-get install redis
+```
+
+## Core concepts
+- In-memory storage: data lives in RAM for sub-millisecond access; persistence is optional.
+- Rich data types: strings, lists, sets, sorted sets, hashes, streams, bitmaps, and more.
+- Key expiration (TTL): set per-key expiry for caches and sessions.
+- Persistence options: RDB snapshots and AOF (append-only file) for durability across restarts.
+- Pub/Sub and Streams: messaging patterns for fan-out and durable, consumer-group-based queues.
+- Atomic operations and transactions (`MULTI`/`EXEC`) plus server-side Lua scripting.
+
+## Best practices
+- Set TTLs on cache keys so memory is reclaimed; choose an eviction policy (e.g., `allkeys-lru`) appropriate to a cache.
+- Use the right data type (e.g., sorted sets for leaderboards, streams for queues) rather than serializing blobs.
+- Enable persistence (RDB and/or AOF) if you cannot tolerate losing data on restart; disable it for pure caches.
+- Use pipelining or `MGET`/`MSET` to batch commands and cut round trips.
+- Avoid large single keys and `O(N)` commands (e.g., `KEYS`) on production; use `SCAN` instead.
+
+## Common pitfalls
+- Treating Redis as a durable system of record without persistence/replication → data loss on restart or eviction.
+- Running `KEYS *` in production → blocks the server; use `SCAN`.
+- Storing huge values or huge collections in one key → memory spikes and slow operations.
+- Forgetting eviction policy on a cache → out-of-memory errors when `maxmemory` is hit.
+
+## Examples
+```bash
+# Cache a value for 60 seconds
+SET session:abc "{...}" EX 60
+
+# Leaderboard with a sorted set
+ZADD scores 100 "ada"
+ZREVRANGE scores 0 9 WITHSCORES
+```
+
+## Further reading
+- Data types: https://redis.io/docs/latest/develop/data-types/
+- Persistence: https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/
+
+## Related skills
+- ../mongodb — document database for primary storage
+- ../postgresql — relational system of record to pair with a Redis cache

package/skills/stacks/database/sqlite/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: sqlite
+description: Embedded, serverless, file-based SQL database; consult for local/app storage, on-device data, tests, and zero-config single-file databases.
+domain: stack
+category: database
+tags: [sqlite, sql, embedded, serverless, file-based]
+official_sources:
+  - https://sqlite.org/docs.html
+  - https://github.com/sqlite/sqlite
+verified: 2026-06-16
+---
+
+# SQLite
+
+## Overview
+SQLite is a self-contained, serverless, zero-configuration, transactional SQL database engine where the entire database is stored in a single cross-platform file. Read this when you need embedded storage inside an application, on-device data, test fixtures, or a lightweight single-file database without a server process.
+
+## Official sources
+- Docs: https://sqlite.org/docs.html
+- Repo (official GitHub mirror; canonical development uses Fossil at sqlite.org/src): https://github.com/sqlite/sqlite
+- Download: https://sqlite.org/download.html
+
+## Install / setup
+SQLite is distributed as precompiled command-line tools and as the C "amalgamation" source from the official download page (sqlite.org/download.html). There is no package-manager install command on that page; you download the binary or amalgamation for your platform. On macOS, after downloading the precompiled binary you may need to clear the quarantine attribute:
+
+```bash
+xattr -d com.apple.quarantine <prog>
+```
+
+(Many language runtimes embed SQLite directly, so no separate install is required.)
+
+## Core concepts
+- Serverless and embedded: the library links into your application; there is no separate server process.
+- Single-file database: the whole database (tables, indexes, data) lives in one ordinary file.
+- ACID transactions: writes are atomic and durable even across crashes/power loss.
+- Dynamic typing with type affinity: columns have an affinity rather than rigid types.
+- Write-Ahead Logging (WAL): an alternative journaling mode that improves concurrency for readers during writes.
+- Public domain: the source code is dedicated to the public domain.
+
+## Best practices
+- Enable WAL mode (`PRAGMA journal_mode=WAL;`) for better read/write concurrency in most applications.
+- Use parameterized queries (bound parameters) to avoid SQL injection and improve plan reuse.
+- Wrap bulk inserts in a single transaction; per-statement autocommit is slow for many rows.
+- Use `STRICT` tables when you want rigid type enforcement instead of type affinity.
+- Keep the database file on local disk, not a network filesystem, to avoid locking issues.
+
+## Common pitfalls
+- Assuming rigid typing → SQLite uses type affinity by default; values may be stored as a different type than declared unless you use STRICT tables.
+- Expecting high write concurrency → SQLite serializes writers; it suits single-writer or low-write-concurrency workloads.
+- Running many inserts in autocommit mode → wrap them in a transaction for orders-of-magnitude speedup.
+- Placing the DB file on NFS/network shares → file locking is unreliable there.
+
+## Examples
+```sql
+PRAGMA journal_mode = WAL;
+
+CREATE TABLE notes (
+  id INTEGER PRIMARY KEY,
+  body TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+) STRICT;
+```
+
+## Further reading
+- Datatypes / type affinity: https://sqlite.org/datatype3.html
+- Write-Ahead Logging: https://sqlite.org/wal.html
+
+## Related skills
+- ../postgresql — full client/server RDBMS for larger workloads
+- ../mysql — client/server RDBMS alternative

package/skills/stacks/database/supabase/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: supabase
+description: Open-source Firebase alternative built on Postgres with auth, storage, realtime, and edge functions; consult for full-stack Postgres backends.
+domain: stack
+category: database
+tags: [supabase, postgres, baas, auth, realtime]
+official_sources:
+  - https://supabase.com/docs
+  - https://github.com/supabase/supabase
+verified: 2026-06-16
+---
+
+# Supabase
+
+## Overview
+Supabase is an open-source backend-as-a-service that pairs a hosted PostgreSQL database with authentication, file storage, realtime subscriptions, edge functions, and auto-generated APIs. Read this when building a full-stack app that wants Postgres plus auth/storage/realtime without operating each piece yourself.
+
+## Official sources
+- Docs: https://supabase.com/docs
+- Repo (official): https://github.com/supabase/supabase
+- Local development: https://supabase.com/docs/guides/local-development
+
+## Install / setup
+Install the Supabase CLI and start the local stack (requires a Docker-compatible container runtime), from the official local-development guide:
+
+```sh
+npm install supabase --save-dev
+npx supabase init
+npx supabase start
+```
+
+Alternatively, via Homebrew:
+
+```sh
+brew install supabase/tap/supabase
+supabase init
+supabase start
+```
+
+The local Supabase Studio is available at http://localhost:54323.
+
+## Core concepts
+- Postgres-first: every project is a real PostgreSQL database; you can use full SQL and extensions.
+- Row Level Security (RLS): authorization is enforced in the database via Postgres RLS policies.
+- Auth: built-in user management with email/password, OAuth providers, and JWT-based sessions.
+- Auto-generated APIs: REST (PostgREST) and realtime subscriptions are derived from your schema.
+- Storage: S3-compatible object storage with access controlled by policies.
+- Edge Functions: serverless functions (Deno) for custom server-side logic.
+- Migrations and the CLI: manage schema changes and local-to-prod parity.
+
+## Best practices
+- Enable Row Level Security on all tables exposed to clients and write explicit policies; never rely on client-side checks.
+- Develop locally with the CLI and use migrations so schema changes are versioned and reproducible.
+- Keep the `service_role` key server-side only; use the `anon` key (subject to RLS) in clients.
+- Use the database directly for constraints and triggers rather than enforcing integrity in app code.
+- Generate types from your schema for end-to-end type safety in the client.
+
+## Common pitfalls
+- Forgetting to enable RLS, leaving tables world-readable/writable via the anon key → enable RLS and add policies.
+- Exposing the `service_role` key in frontend code → it bypasses RLS; keep it secret.
+- Making schema changes only in the dashboard → drift between environments; use migrations.
+- Treating it as a black box rather than Postgres → you can and should use SQL, indexes, and extensions.
+
+## Examples
+```sql
+-- Enable RLS and restrict rows to their owner
+alter table profiles enable row level security;
+
+create policy "owner can read" on profiles
+  for select using (auth.uid() = user_id);
+```
+
+## Further reading
+- Row Level Security: https://supabase.com/docs/guides/database/postgres/row-level-security
+- Auth: https://supabase.com/docs/guides/auth
+
+## Related skills
+- ../postgresql — the database engine underneath Supabase
+- ../neon — serverless Postgres alternative