@minhduydev/mdpi 0.3.0

package/dist/template/.pi/skills/supabase/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: supabase
+description: Use when working with any Supabase service — database operations, edge functions, auth, storage, or project management. MUST load before writing Supabase queries, RLS policies, or edge functions.
+---
+
+# Supabase Platform (MCP)
+
+## When to Use
+
+- When you need to manage Supabase projects, databases, or edge functions via MCP.
+
+## When NOT to Use
+
+- When the backend is not Supabase or MCP access is unavailable.
+
+
+## Available Tools
+
+### Account & Projects
+
+- `list_projects` - Lists all Supabase projects
+- `get_project` - Gets details for a specific project
+- `list_organizations` - Lists all organizations
+
+### Database
+
+- `list_tables` - Lists all tables in specified schemas
+- `list_extensions` - Lists PostgreSQL extensions
+- `list_migrations` - Lists database migrations
+- `execute_sql` - Executes raw SQL queries
+
+### Development
+
+- `get_project_url` - Gets the API URL for a project
+- `get_publishable_keys` - Gets anonymous API keys (client-safe)
+- `generate_typescript_types` - Generates TypeScript types from schema
+
+### Edge Functions
+
+- `list_edge_functions` - Lists all Edge Functions
+- `get_edge_function` - Retrieves Edge Function file contents
+- `deploy_edge_function` - Deploys or updates an Edge Function
+
+### Debugging
+
+- `get_logs` - Retrieves logs by service type
+- `get_advisors` - Gets security/performance advisory notices
+
+### Documentation
+
+- `search_docs` - Searches Supabase documentation
+
+## Workflow
+
+### Quick Start
+
+```
+# List projects
+skill_mcp(skill_name="supabase", tool_name="list_projects")
+
+# List tables in database
+skill_mcp(skill_name="supabase", tool_name="list_tables")
+
+# Execute SQL query
+skill_mcp(skill_name="supabase", tool_name="execute_sql", arguments='{"query": "SELECT * FROM users LIMIT 10"}')
+
+# Generate TypeScript types
+skill_mcp(skill_name="supabase", tool_name="generate_typescript_types")
+
+# Search docs
+skill_mcp(skill_name="supabase", tool_name="search_docs", arguments='{"query": "auth custom claims"}')
+```
+
+### Get Project Credentials
+
+```
+# Get API URL and keys for project
+skill_mcp(skill_name="supabase", tool_name="get_project_url")
+skill_mcp(skill_name="supabase", tool_name="get_publishable_keys")
+
+# List Edge Functions
+skill_mcp(skill_name="supabase", tool_name="list_edge_functions")
+
+# Deploy Edge Function
+skill_mcp(skill_name="supabase", tool_name="deploy_edge_function", arguments='{"name": "my-function", "import_map": {...}, "entrypoint": "index.ts"}')
+```
+
+### Debug Issues
+
+```
+# Get logs by service
+skill_mcp(skill_name="supabase", tool_name="get_logs", arguments='{"service": "postgres", "limit": 100}')
+
+# Check advisories
+skill_mcp(skill_name="supabase", tool_name="get_advisors")
+```
+
+## Security Notes
+
+- **Read-only mode**: Set `"read_only": true` in mcp.json to disable write operations
+- **Project scoping**: Use `project_ref` to limit access to specific projects
+- **Environment variables**: Set `SUPABASE_ACCESS_TOKEN` for authentication
+
+## Server Options
+
+For advanced usage, modify `mcp.json`:
+
+```json
+{
+  "supabase": {
+    "command": "npx",
+    "args": ["-y", "@supabase/mcp@latest"],
+    "env": {
+      "SUPABASE_ACCESS_TOKEN": "your-token-here"
+    },
+    "includeTools": ["list_tables", "execute_sql", "..."]
+  }
+}
+```
+
+Configuration options:
+
+- `project_ref` - Scope to specific project (recommended)
+- `read_only` - Restrict to read-only operations (recommended)
+- `features` - Enable specific tool groups
+
+> **Note**: This skill loads 14 essential tools. Excludes experimental (branching) and storage tools that require paid plans.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll disable RLS during development" | RLS is your security boundary. Disabling it in dev creates habits that leak to production. |
+| "The auto-generated API is fine as-is" | Auto-generated APIs expose everything. Restrict to what the client actually needs. |
+| "I'll add indexes when queries get slow" | Missing indexes on Supabase hit hard under even moderate load. Index from the start. |
+
+## Red Flags
+
+- RLS policies disabled or set to permissive
+- Service role key used in client-side code
+- No row-level security defined for user-specific data
+- Real-time subscriptions without cleanup on component unmount
+- Database functions without SECURITY DEFINER review
+
+## Verification
+
+After implementing Supabase:
+
+- [ ] RLS policies are defined and tested for each table
+- [ ] Service role key is never used in client-side code
+- [ ] Row-level security correctly scopes data to the authenticated user
+- [ ] Real-time subscriptions are cleaned up on component unmount
+- [ ] Database functions are reviewed for SECURITY DEFINER implications

package/dist/template/.pi/skills/supabase-postgres-best-practices/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: supabase-postgres-best-practices
+description: MUST load when writing, reviewing, or optimizing Postgres queries, schema designs, indexes, or RLS policies in Supabase. Covers Supabase-specific Postgres performance patterns and common pitfalls.
+---
+
+# Supabase Postgres Best Practices
+
+## When to Use
+
+- When optimizing or reviewing Postgres performance, schemas, or queries with Supabase guidance.
+
+## When NOT to Use
+
+- When the task is not related to Postgres performance or schema design.
+
+
+## When to Apply
+
+Reference these guidelines when:
+
+- Writing SQL queries or designing schemas
+- Implementing indexes or query optimization
+- Reviewing database performance issues
+- Configuring connection pooling or scaling
+- Optimizing for Postgres-specific features
+- Working with Row-Level Security (RLS)
+
+## Rule Categories by Priority
+
+| Priority | Category                 | Impact      | Prefix      |
+| -------- | ------------------------ | ----------- | ----------- |
+| 1        | Query Performance        | CRITICAL    | `query-`    |
+| 2        | Connection Management    | CRITICAL    | `conn-`     |
+| 3        | Security & RLS           | CRITICAL    | `security-` |
+| 4        | Schema Design            | HIGH        | `schema-`   |
+| 5        | Concurrency & Locking    | MEDIUM-HIGH | `lock-`     |
+| 6        | Data Access Patterns     | MEDIUM      | `data-`     |
+| 7        | Monitoring & Diagnostics | LOW-MEDIUM  | `monitor-`  |
+| 8        | Advanced Features        | LOW         | `advanced-` |
+
+## How to Use
+
+Read individual rule files for detailed explanations and SQL examples:
+
+```
+rules/query-missing-indexes.md
+rules/schema-partial-indexes.md
+rules/_sections.md
+```
+
+Each rule file contains:
+
+- Brief explanation of why it matters
+- Incorrect SQL example with explanation
+- Correct SQL example with explanation
+- Optional EXPLAIN output or metrics
+- Additional context and references
+- Supabase-specific notes (when applicable)
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "The ORM handles query optimization" | ORMs generate correct SQL, not efficient SQL. Review query plans. |
+| "This query is fast enough for now" | "Fast enough" at 100 rows is broken at 100K rows. Test with realistic data volumes. |
+| "I don't need to understand EXPLAIN output" | EXPLAIN is the difference between guessing and knowing. Learn it. |
+
+## Red Flags
+
+- Queries without EXPLAIN ANALYZE review
+- Missing indexes on foreign key columns used in JOINs
+- SELECT * on tables with large text/JSONB columns
+- No connection pooling configured
+- COUNT(*) used without WHERE on large tables
+
+## Verification
+
+After writing Supabase Postgres queries:
+
+- [ ] EXPLAIN ANALYZE output reviewed for each new query
+- [ ] Indexes exist on columns used in WHERE, JOIN, and ORDER BY
+- [ ] COUNT(*) queries on large tables use estimates or caching
+- [ ] Connection pooling is configured for production
+- [ ] Query performance is measured under realistic data volume

package/dist/template/.pi/skills/supabase-postgres-best-practices/rules/advanced-full-text-search.md

@@ -0,0 +1,55 @@
+---
+title: Use tsvector for Full-Text Search
+impact: MEDIUM
+impactDescription: 100x faster than LIKE, with ranking support
+tags: full-text-search, tsvector, gin, search
+---
+
+## Use tsvector for Full-Text Search
+
+LIKE with wildcards can't use indexes. Full-text search with tsvector is orders of magnitude faster.
+
+**Incorrect (LIKE pattern matching):**
+
+```sql
+-- Cannot use index, scans all rows
+select * from articles where content like '%postgresql%';
+
+-- Case-insensitive makes it worse
+select * from articles where lower(content) like '%postgresql%';
+```
+
+**Correct (full-text search with tsvector):**
+
+```sql
+-- Add tsvector column and index
+alter table articles add column search_vector tsvector
+  generated always as (to_tsvector('english', coalesce(title,'') || ' ' || coalesce(content,''))) stored;
+
+create index articles_search_idx on articles using gin (search_vector);
+
+-- Fast full-text search
+select * from articles
+where search_vector @@ to_tsquery('english', 'postgresql & performance');
+
+-- With ranking
+select *, ts_rank(search_vector, query) as rank
+from articles, to_tsquery('english', 'postgresql') query
+where search_vector @@ query
+order by rank desc;
+```
+
+Search multiple terms:
+
+```sql
+-- AND: both terms required
+to_tsquery('postgresql & performance')
+
+-- OR: either term
+to_tsquery('postgresql | mysql')
+
+-- Prefix matching
+to_tsquery('post:*')
+```
+
+Reference: [Full Text Search](https://supabase.com/docs/guides/database/full-text-search)

package/dist/template/.pi/skills/supabase-postgres-best-practices/rules/advanced-jsonb-indexing.md

@@ -0,0 +1,49 @@
+---
+title: Index JSONB Columns for Efficient Querying
+impact: MEDIUM
+impactDescription: 10-100x faster JSONB queries with proper indexing
+tags: jsonb, gin, indexes, json
+---
+
+## Index JSONB Columns for Efficient Querying
+
+JSONB queries without indexes scan the entire table. Use GIN indexes for containment queries.
+
+**Incorrect (no index on JSONB):**
+
+```sql
+create table products (
+  id bigint primary key,
+  attributes jsonb
+);
+
+-- Full table scan for every query
+select * from products where attributes @> '{"color": "red"}';
+select * from products where attributes->>'brand' = 'Nike';
+```
+
+**Correct (GIN index for JSONB):**
+
+```sql
+-- GIN index for containment operators (@>, ?, ?&, ?|)
+create index products_attrs_gin on products using gin (attributes);
+
+-- Now containment queries use the index
+select * from products where attributes @> '{"color": "red"}';
+
+-- For specific key lookups, use expression index
+create index products_brand_idx on products ((attributes->>'brand'));
+select * from products where attributes->>'brand' = 'Nike';
+```
+
+Choose the right operator class:
+
+```sql
+-- jsonb_ops (default): supports all operators, larger index
+create index idx1 on products using gin (attributes);
+
+-- jsonb_path_ops: only @> operator, but 2-3x smaller index
+create index idx2 on products using gin (attributes jsonb_path_ops);
+```
+
+Reference: [JSONB Indexes](https://www.postgresql.org/docs/current/datatype-json.html#JSON-INDEXING)

package/dist/template/.pi/skills/supabase-postgres-best-practices/rules/conn-idle-timeout.md

@@ -0,0 +1,46 @@
+---
+title: Configure Idle Connection Timeouts
+impact: HIGH
+impactDescription: Reclaim 30-50% of connection slots from idle clients
+tags: connections, timeout, idle, resource-management
+---
+
+## Configure Idle Connection Timeouts
+
+Idle connections waste resources. Configure timeouts to automatically reclaim them.
+
+**Incorrect (connections held indefinitely):**
+
+```sql
+-- No timeout configured
+show idle_in_transaction_session_timeout;  -- 0 (disabled)
+
+-- Connections stay open forever, even when idle
+select pid, state, state_change, query
+from pg_stat_activity
+where state = 'idle in transaction';
+-- Shows transactions idle for hours, holding locks
+```
+
+**Correct (automatic cleanup of idle connections):**
+
+```sql
+-- Terminate connections idle in transaction after 30 seconds
+alter system set idle_in_transaction_session_timeout = '30s';
+
+-- Terminate completely idle connections after 10 minutes
+alter system set idle_session_timeout = '10min';
+
+-- Reload configuration
+select pg_reload_conf();
+```
+
+For pooled connections, configure at the pooler level:
+
+```ini
+# pgbouncer.ini
+server_idle_timeout = 60
+client_idle_timeout = 300
+```
+
+Reference: [Connection Timeouts](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-IDLE-IN-TRANSACTION-SESSION-TIMEOUT)

package/dist/template/.pi/skills/supabase-postgres-best-practices/rules/conn-limits.md

@@ -0,0 +1,44 @@
+---
+title: Set Appropriate Connection Limits
+impact: CRITICAL
+impactDescription: Prevent database crashes and memory exhaustion
+tags: connections, max-connections, limits, stability
+---
+
+## Set Appropriate Connection Limits
+
+Too many connections exhaust memory and degrade performance. Set limits based on available resources.
+
+**Incorrect (unlimited or excessive connections):**
+
+```sql
+-- Default max_connections = 100, but often increased blindly
+show max_connections;  -- 500 (way too high for 4GB RAM)
+
+-- Each connection uses 1-3MB RAM
+-- 500 connections * 2MB = 1GB just for connections!
+-- Out of memory errors under load
+```
+
+**Correct (calculate based on resources):**
+
+```sql
+-- Formula: max_connections = (RAM in MB / 5MB per connection) - reserved
+-- For 4GB RAM: (4096 / 5) - 10 = ~800 theoretical max
+-- But practically, 100-200 is better for query performance
+
+-- Recommended settings for 4GB RAM
+alter system set max_connections = 100;
+
+-- Also set work_mem appropriately
+-- work_mem * max_connections should not exceed 25% of RAM
+alter system set work_mem = '8MB';  -- 8MB * 100 = 800MB max
+```
+
+Monitor connection usage:
+
+```sql
+select count(*), state from pg_stat_activity group by state;
+```
+
+Reference: [Database Connections](https://supabase.com/docs/guides/platform/performance#connection-management)

package/dist/template/.pi/skills/supabase-postgres-best-practices/rules/conn-pooling.md

@@ -0,0 +1,41 @@
+---
+title: Use Connection Pooling for All Applications
+impact: CRITICAL
+impactDescription: Handle 10-100x more concurrent users
+tags: connection-pooling, pgbouncer, performance, scalability
+---
+
+## Use Connection Pooling for All Applications
+
+Postgres connections are expensive (1-3MB RAM each). Without pooling, applications exhaust connections under load.
+
+**Incorrect (new connection per request):**
+
+```sql
+-- Each request creates a new connection
+-- Application code: db.connect() per request
+-- Result: 500 concurrent users = 500 connections = crashed database
+
+-- Check current connections
+select count(*) from pg_stat_activity;  -- 487 connections!
+```
+
+**Correct (connection pooling):**
+
+```sql
+-- Use a pooler like PgBouncer between app and database
+-- Application connects to pooler, pooler reuses a small pool to Postgres
+
+-- Configure pool_size based on: (CPU cores * 2) + spindle_count
+-- Example for 4 cores: pool_size = 10
+
+-- Result: 500 concurrent users share 10 actual connections
+select count(*) from pg_stat_activity;  -- 10 connections
+```
+
+Pool modes:
+
+- **Transaction mode**: connection returned after each transaction (best for most apps)
+- **Session mode**: connection held for entire session (needed for prepared statements, temp tables)
+
+Reference: [Connection Pooling](https://supabase.com/docs/guides/database/connecting-to-postgres#connection-pooler)

package/dist/template/.pi/skills/supabase-postgres-best-practices/rules/conn-prepared-statements.md

@@ -0,0 +1,46 @@
+---
+title: Use Prepared Statements Correctly with Pooling
+impact: HIGH
+impactDescription: Avoid prepared statement conflicts in pooled environments
+tags: prepared-statements, connection-pooling, transaction-mode
+---
+
+## Use Prepared Statements Correctly with Pooling
+
+Prepared statements are tied to individual database connections. In transaction-mode pooling, connections are shared, causing conflicts.
+
+**Incorrect (named prepared statements with transaction pooling):**
+
+```sql
+-- Named prepared statement
+prepare get_user as select * from users where id = $1;
+
+-- In transaction mode pooling, next request may get different connection
+execute get_user(123);
+-- ERROR: prepared statement "get_user" does not exist
+```
+
+**Correct (use unnamed statements or session mode):**
+
+```sql
+-- Option 1: Use unnamed prepared statements (most ORMs do this automatically)
+-- The query is prepared and executed in a single protocol message
+
+-- Option 2: Deallocate after use in transaction mode
+prepare get_user as select * from users where id = $1;
+execute get_user(123);
+deallocate get_user;
+
+-- Option 3: Use session mode pooling (port 5432 vs 6543)
+-- Connection is held for entire session, prepared statements persist
+```
+
+Check your driver settings:
+
+```sql
+-- Many drivers use prepared statements by default
+-- Node.js pg: { prepare: false } to disable
+-- JDBC: prepareThreshold=0 to disable
+```
+
+Reference: [Prepared Statements with Pooling](https://supabase.com/docs/guides/database/connecting-to-postgres#connection-pool-modes)

package/dist/template/.pi/skills/supabase-postgres-best-practices/rules/data-batch-inserts.md

@@ -0,0 +1,54 @@
+---
+title: Batch INSERT Statements for Bulk Data
+impact: MEDIUM
+impactDescription: 10-50x faster bulk inserts
+tags: batch, insert, bulk, performance, copy
+---
+
+## Batch INSERT Statements for Bulk Data
+
+Individual INSERT statements have high overhead. Batch multiple rows in single statements or use COPY.
+
+**Incorrect (individual inserts):**
+
+```sql
+-- Each insert is a separate transaction and round trip
+insert into events (user_id, action) values (1, 'click');
+insert into events (user_id, action) values (1, 'view');
+insert into events (user_id, action) values (2, 'click');
+-- ... 1000 more individual inserts
+
+-- 1000 inserts = 1000 round trips = slow
+```
+
+**Correct (batch insert):**
+
+```sql
+-- Multiple rows in single statement
+insert into events (user_id, action) values
+  (1, 'click'),
+  (1, 'view'),
+  (2, 'click'),
+  -- ... up to ~1000 rows per batch
+  (999, 'view');
+
+-- One round trip for 1000 rows
+```
+
+For large imports, use COPY:
+
+```sql
+-- COPY is fastest for bulk loading
+copy events (user_id, action, created_at)
+from '/path/to/data.csv'
+with (format csv, header true);
+
+-- Or from stdin in application
+copy events (user_id, action) from stdin with (format csv);
+1,click
+1,view
+2,click
+\.
+```
+
+Reference: [COPY](https://www.postgresql.org/docs/current/sql-copy.html)

package/dist/template/.pi/skills/supabase-postgres-best-practices/rules/data-n-plus-one.md

@@ -0,0 +1,53 @@
+---
+title: Eliminate N+1 Queries with Batch Loading
+impact: MEDIUM-HIGH
+impactDescription: 10-100x fewer database round trips
+tags: n-plus-one, batch, performance, queries
+---
+
+## Eliminate N+1 Queries with Batch Loading
+
+N+1 queries execute one query per item in a loop. Batch them into a single query using arrays or JOINs.
+
+**Incorrect (N+1 queries):**
+
+```sql
+-- First query: get all users
+select id from users where active = true;  -- Returns 100 IDs
+
+-- Then N queries, one per user
+select * from orders where user_id = 1;
+select * from orders where user_id = 2;
+select * from orders where user_id = 3;
+-- ... 97 more queries!
+
+-- Total: 101 round trips to database
+```
+
+**Correct (single batch query):**
+
+```sql
+-- Collect IDs and query once with ANY
+select * from orders where user_id = any(array[1, 2, 3, ...]);
+
+-- Or use JOIN instead of loop
+select u.id, u.name, o.*
+from users u
+left join orders o on o.user_id = u.id
+where u.active = true;
+
+-- Total: 1 round trip
+```
+
+Application pattern:
+
+```sql
+-- Instead of looping in application code:
+-- for user in users: db.query("SELECT * FROM orders WHERE user_id = $1", user.id)
+
+-- Pass array parameter:
+select * from orders where user_id = any($1::bigint[]);
+-- Application passes: [1, 2, 3, 4, 5, ...]
+```
+
+Reference: [N+1 Query Problem](https://supabase.com/docs/guides/database/query-optimization)

package/dist/template/.pi/skills/supabase-postgres-best-practices/rules/data-pagination.md

@@ -0,0 +1,50 @@
+---
+title: Use Cursor-Based Pagination Instead of OFFSET
+impact: MEDIUM-HIGH
+impactDescription: Consistent O(1) performance regardless of page depth
+tags: pagination, cursor, keyset, offset, performance
+---
+
+## Use Cursor-Based Pagination Instead of OFFSET
+
+OFFSET-based pagination scans all skipped rows, getting slower on deeper pages. Cursor pagination is O(1).
+
+**Incorrect (OFFSET pagination):**
+
+```sql
+-- Page 1: scans 20 rows
+select * from products order by id limit 20 offset 0;
+
+-- Page 100: scans 2000 rows to skip 1980
+select * from products order by id limit 20 offset 1980;
+
+-- Page 10000: scans 200,000 rows!
+select * from products order by id limit 20 offset 199980;
+```
+
+**Correct (cursor/keyset pagination):**
+
+```sql
+-- Page 1: get first 20
+select * from products order by id limit 20;
+-- Application stores last_id = 20
+
+-- Page 2: start after last ID
+select * from products where id > 20 order by id limit 20;
+-- Uses index, always fast regardless of page depth
+
+-- Page 10000: same speed as page 1
+select * from products where id > 199980 order by id limit 20;
+```
+
+For multi-column sorting:
+
+```sql
+-- Cursor must include all sort columns
+select * from products
+where (created_at, id) > ('2024-01-15 10:00:00', 12345)
+order by created_at, id
+limit 20;
+```
+
+Reference: [Pagination](https://supabase.com/docs/guides/database/pagination)