DEV Community: Shahid

Stop Running 5 Databases: PostgreSQL Does It All in 2026

Shahid — Mon, 15 Jun 2026 10:37:20 +0000

How a 35-year-old open-source database became the default choice for relational storage, full-text search, vector AI workloads, geospatial queries, and event-driven architecture — in a single deployment.

Most production architectures look like a small city: a relational database for core data, a document store for flexible schemas, an Elasticsearch cluster for search, a vector database for AI-powered features, and a message broker stitching it all together. Five services. Five deployment pipelines. Five monitoring dashboards. Five points of failure — all to solve problems that, in most applications, one database already handles.

That database is PostgreSQL. It started as a research project at UC Berkeley in the 1980s and has quietly evolved into one of the most capable data platforms ever built. In 2026, as teams race to bolt AI onto their stacks without doubling infrastructure costs, Postgres has emerged as the default answer — not because it's new, but because it was built right.

What Makes Postgres Different

At its core, Postgres is a relational, ACID-compliant SQL database: tables, rows, foreign keys, joins, everything you'd expect. What separates it architecturally from MySQL or SQLite is that it was built for extensibility from day one. There is a formalized plugin API that lets you add new data types, new index strategies, and entirely new capabilities via a single CREATE EXTENSION command. This is not a bolt-on feature or a marketing checkbox — it is a deeply deliberate design choice baked into the query engine itself.

The result: Postgres doesn't just store data. It becomes the entire data layer of your application, without stitching together a fleet of specialized services you need to deploy, monitor, and keep in sync.

Replacing the Document Store: JSONB

The standard pitch for MongoDB has always been: relational schemas are too rigid for modern applications. Postgres answers that directly with JSONB — a binary-encoded JSON column type that lets you store fully schemaless documents right next to your strict relational tables, in the same database, under the same transaction.

You can query deep into nested JSON using path expressions, check for key existence, test containment, and — critically — put a GIN index on the entire document so those queries stay fast at scale:

CREATE TABLE users (
  id     SERIAL PRIMARY KEY,
  email  TEXT NOT NULL,
  data   JSONB
);

CREATE INDEX idx_users_data ON users USING GIN (data);

-- Find all users on the 'pro' plan
SELECT email
FROM users
WHERE data @> '{"plan": "pro"}';

Your schemaless layer and your relational layer live in the same table, under the same backup, in the same SELECT. No data synchronization. No eventual consistency headaches. No second server.

Replacing Elasticsearch: Built-in Full-Text Search

Elasticsearch is powerful — but it's also one of the heaviest pieces of infrastructure you can operate. It needs its own cluster, its own memory tuning, its own index lifecycle management, and it demands you keep two copies of your data in sync at all times.

Postgres has a native full-text search engine that handles tokenization, stemming (so "running" matches "run" and "runs"), stop-word filtering, relevance ranking, and indexed retrieval. For the overwhelming majority of product search boxes and content discovery features, it is more than sufficient:

-- GIN-indexed full-text search
CREATE INDEX idx_articles_fts
ON articles USING GIN (to_tsvector('english', title || ' ' || body));

-- Ranked search results
SELECT title,
       ts_rank(to_tsvector('english', title || ' ' || body), query) AS rank
FROM articles,
     to_tsquery('english', 'distributed & systems') AS query
WHERE to_tsvector('english', title || ' ' || body) @@ query
ORDER BY rank DESC;

The only time Elasticsearch genuinely pulls ahead is at massive scale with advanced requirements — complex multi-language synonym pipelines, cross-cluster federation, or deep faceted navigation. For everything else, Postgres saves you an entire infrastructure tier.

Replacing Pinecone and Weaviate: AI-Native Vector Search

This is the capability that has become non-negotiable in 2026. Every application now has an AI feature. Every AI feature needs semantic search. The pgvector extension adds a native vector column type and approximate nearest-neighbor (ANN) search, making Postgres the backbone of Retrieval-Augmented Generation (RAG) pipelines without standing up a dedicated vector database.

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE documents (
  id        SERIAL PRIMARY KEY,
  content   TEXT,
  embedding vector(1536)
);

-- HNSW index for fast approximate nearest-neighbor search
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);

-- Semantic similarity search
SELECT content,
       1 - (embedding <=> '[0.12, 0.47, ...]') AS similarity
FROM documents
ORDER BY embedding <=> '[0.12, 0.47, ...]'
LIMIT 5;

For workloads under roughly 100 million vectors, Postgres with pgvector eliminates dedicated vector database overhead with no measurable quality trade-off. The real advantage over standalone vector databases isn't just eliminating a service — it's composability: your vector search can be combined with WHERE filters, JOINs across tables, and Row-Level Security in a single query. Pinecone cannot join against your application data. Postgres can.

Replacing Redis and RabbitMQ: Queues and Pub/Sub

Two underused, underappreciated Postgres features handle most messaging needs without introducing a broker.

LISTEN / NOTIFY is a lightweight pub/sub mechanism built directly into the wire protocol. One session publishes a text payload to a named channel; every subscribed session receives it in milliseconds. It's not Kafka — but for triggering background workers, pushing cache invalidation events, or wiring up a simple notification system, it's zero-infrastructure pub/sub.

SELECT FOR UPDATE SKIP LOCKED turns an ordinary table into a reliable, concurrent job queue. Multiple workers pull jobs simultaneously without race conditions, because each SELECT atomically locks the row it claims and skips all rows already locked by other workers:

-- Worker atomically claims the next available job
BEGIN;

SELECT * FROM jobs
WHERE status = 'pending'
ORDER BY created_at
FOR UPDATE SKIP LOCKED
LIMIT 1;

-- ... process the job ...

UPDATE jobs SET status = 'done' WHERE id = :id;
COMMIT;

If a worker crashes mid-job, the transaction rolls back and the row becomes claimable again — automatic exactly-once delivery, built on the ACID guarantees you already have.

Replacing Geospatial APIs: PostGIS

The PostGIS extension is one of the most capable geospatial engines in the entire software ecosystem — commercial or otherwise. It adds geometry and geography column types (points, lines, polygons, multipolygons), spatial indexing via GiST, and a rich library of functions for distance calculations, intersection tests, buffering, and coordinate system transformations:

-- Find all stores within 5km of a user's location in Bengaluru
SELECT name,
       ST_Distance(location, ST_MakePoint(77.5946, 12.9716)::geography) AS dist_meters
FROM stores
WHERE ST_DWithin(
  location,
  ST_MakePoint(77.5946, 12.9716)::geography,
  5000
)
ORDER BY dist_meters;

Entire commercial GIS platforms used by governments and logistics companies worldwide are built on PostGIS. It replaces the need for a separate geospatial API service for any proximity or boundary query against your own data.

The SQL You're Probably Under-Using

Beyond extensions, most developers use roughly 60% of Postgres's SQL capabilities. The remaining 40% eliminates entire categories of application-layer code.

Window Functions compute aggregates across rows related to the current row without collapsing them like GROUP BY does — running totals, moving averages, percentile ranks, all in a single pass:

SELECT
  order_date,
  amount,
  SUM(amount) OVER (ORDER BY order_date) AS running_total,
  AVG(amount) OVER (
    ORDER BY order_date
    ROWS BETWEEN 6 PRECEDING AND CURRENT ROW
  ) AS rolling_7day_avg
FROM orders;

Recursive CTEs walk tree structures — org hierarchies, category trees, threaded comments, dependency graphs — in pure SQL, with no application-side recursion or multiple round trips:

WITH RECURSIVE category_tree AS (
  SELECT id, name, parent_id, 0 AS depth
  FROM categories WHERE parent_id IS NULL

  UNION ALL

  SELECT c.id, c.name, c.parent_id, t.depth + 1
  FROM categories c
  JOIN category_tree t ON c.parent_id = t.id
)
SELECT * FROM category_tree ORDER BY depth, name;

Atomic Upserts handle the classic insert-or-update race condition with a single statement — no optimistic locking, no read-then-write, no race:

INSERT INTO inventory (product_id, stock)
VALUES (42, 100)
ON CONFLICT (product_id) DO UPDATE
  SET stock = EXCLUDED.stock,
      updated_at = NOW();

Indexes: A Write Tax for a Read Benefit

Postgres gives you multiple index types, each precision-engineered for a different access pattern. Picking the right one is one of the highest-leverage optimizations available:

Index Type	Best For	Typical Use Case
B-tree	Equality, ranges, ordering (default)	`WHERE created_at > '2025-01-01'`
GIN	JSONB keys, full-text search, arrays	`data @> '{"plan": "pro"}'`
GiST	Geometry, ranges, fuzzy matching	`ST_DWithin(location, point, 500)`
BRIN	Massive append-only time-series tables	IoT sensor logs, event streams
HNSW / IVFFlat	Vector ANN similarity search	Embedding-based semantic retrieval

Every index is a write tax for a read benefit — it makes INSERT, UPDATE, and DELETE slightly slower because Postgres maintains the index alongside the table. Add indexes surgically, guided by EXPLAIN ANALYZE output, not speculatively:

EXPLAIN (ANALYZE, BUFFERS)
SELECT * FROM orders WHERE customer_id = 1234 AND status = 'shipped';

The most important thing to look for in the output: Seq Scan vs Index Scan. A sequential scan on a large table is your bottleneck. An appropriately chosen index on the same query is your fix.

PostgreSQL 18: Built for the AI Era

PostgreSQL 18, released in 2026, doubles down on AI-era workloads with several meaningful improvements.

Asynchronous I/O significantly reduces latency on storage-bound operations, directly benefiting heavy embedding writes and similarity search workloads
Skip-scan on multicolumn indexes makes filtering around vector similarity searches dramatically faster
UUIDv7 index optimization improves insert and scan performance for tables that use UUID primary keys — common in distributed and event-driven systems
Automatic data checksums are now enabled by default on new clusters, eliminating a common silent data corruption risk
OAuth 2.0 authentication support out of the box for enterprise identity integration

These aren't cosmetic improvements — they're direct responses to the workload patterns that have emerged as teams integrate LLMs and AI features into their production stacks.

Under the Hood: Three Mechanisms That Explain Everything

Three internal systems explain most of Postgres's observable behavior — and knowing them prevents a category of production incidents.

MVCC (Multi-Version Concurrency Control) is why readers and writers never block each other. When you update a row, Postgres doesn't overwrite it. It writes a new version of the row and marks the old one as expired. Every transaction sees the world as it existed when that transaction started, regardless of what other transactions are doing concurrently. This is what makes SERIALIZABLE isolation achievable without locking tables.

WAL (Write-Ahead Log) is why Postgres survives crashes with full consistency. Every change is written to a sequential log before it's applied to data files on disk. On restart after a crash, Postgres replays the WAL and arrives at exactly the state it would have been in had the crash never happened. The same WAL stream is also shipped to read replicas in real time — replication is essentially a free side effect of crash recovery.

VACUUM and Dead Tuple Bloat is the tax you pay for MVCC. Because old row versions aren't overwritten, they accumulate as "dead tuples" on disk. The background autovacuum process reclaims this space continuously. In write-heavy workloads, autovacuum can fall behind — leading to table bloat, index bloat, and eventually a transaction ID wraparound emergency. Monitor pg_stat_user_tables for n_dead_tup values that keep climbing.

Scaling Postgres: What's Real and What's Honest

Read scaling is well-understood: stream the WAL to standby servers and route SELECT queries across them. Read replicas are typically milliseconds behind the primary.
Write scaling is the honest hard limit. One primary accepts all writes. When you genuinely hit that ceiling, these are your options:

Table Partitioning — splits large tables (by month, by region, by tenant) into physical partitions; Postgres prunes irrelevant partitions at query time, dramatically reducing scan sizes on time-series or multi-tenant data
Citus — distributes both data and queries across a cluster of Postgres nodes, enabling horizontal write scaling while keeping the full Postgres SQL interface
PgBouncer — not a scaling tool but an operational necessity. Each Postgres connection is a full OS process consuming 5–10MB of RAM. Serverless functions and connection-heavy frameworks will exhaust your connection limit quickly. PgBouncer pools thousands of application connections onto a small, stable set of real server connections, and it belongs in every production deployment ***

When to Reach for Something Else

Postgres is honest about its limits. You should be too.

Pure hot-path in-memory cache at millions of ops/sec → Redis; Postgres is not a memory store
Horizontal write sharding across 10+ nodes from day one → purpose-built distributed systems like Cassandra or CockroachDB
Petabyte-scale OLAP with complex aggregations → columnar engines like ClickHouse, DuckDB, or BigQuery will be orders of magnitude faster
High-throughput real-time event streaming → Kafka or Redpanda own that space; NOTIFY doesn't match their throughput guarantees

The engineering discipline is: start with Postgres, measure your actual bottlenecks, and add specialized tooling only when you've conclusively outgrown what Postgres offers. The biggest architectural mistake teams make is adding distributed complexity in anticipation of hypothetical scale that never arrives.

Why the License Is a Competitive Moat

Postgres is governed by the PostgreSQL Global Development Group — a community intentionally structured so that no single company can change its terms. The license is permissive, similar in spirit to BSD/MIT. You own your deployment. You control your upgrade path.

This is not a footnote. In recent years, MongoDB switched to SSPL and Redis changed to BSL, sending engineering teams scrambling for alternatives. That cannot structurally happen with Postgres. The community governance model is the moat — and in a world where vendor lock-in risk has become a real architecture consideration, that stability has genuine business value.

The Single-Database Architecture

One database. One backup strategy. One set of credentials. One monitoring dashboard. One EXPLAIN ANALYZE. It handles your relational data, your documents, your full-text search, your vector embeddings, your geospatial queries, your job queue, and your pub/sub events — and it has been reliably doing so for production systems at scale for over thirty years.

In 2026, the question isn't whether Postgres is capable enough. The question is whether your architecture has already added five services it didn't need.

Testing MCP Server Tools in AI Agents — A Practical Guide

Shahid — Sun, 24 May 2026 08:26:10 +0000

Building an MCP server is only half the job. The other half — testing its tools — is where most developers drop the ball.

If you're using the Vercel AI SDK to build AI agents with Model Context Protocol (MCP), you already know how powerful tool-calling can be. But an untested tool is a liability. A hallucinating LLM calling a broken tool can cause cascading failures that are notoriously hard to debug in production. This guide walks you through a layered testing strategy — from fast unit tests to full end-to-end evaluations.

Why Testing MCP Tools Is Uniquely Hard

MCP tools sit at the intersection of three systems: your server logic, the LLM's tool selection behavior, and the AI SDK's execution pipeline. A bug can live in any one of them. Testing just the server in isolation gives you false confidence — you also need to verify that the LLM actually picks the right tool for a given prompt, and that the AI SDK correctly routes the call.

Layer 1: Unit Test Tool Logic Directly

Before involving any LLM, test your tool's execute() function in complete isolation. The AI SDK lets you invoke tool execution directly with a typed input:

const result = await tools['search-docs'].execute(
  { query: 'MCP transport options' },
  { messages: [], toolCallId: 'test-001' }
);

expect(result.documents.length).toBeGreaterThan(0);

This runs in milliseconds, costs nothing, and catches the most common bugs — wrong output shapes, missing error handling, and schema mismatches.

Layer 2: Inspect Schemas with the MCP Inspector

Run the official @modelcontextprotocol/inspector CLI tool against your server before writing a single test:

npx @modelcontextprotocol/inspector node dist/server.js

The browser UI lets you browse all registered tools, manually invoke them with custom inputs, and inspect raw JSON-RPC payloads. This is your smoke test — it confirms your server is reachable and your schemas are well-formed. Do this after every new tool you add.

Layer 3: Mock the LLM for Integration Tests

Real LLM API calls are slow, flaky, and expensive in CI pipelines. The AI SDK ships a MockLanguageModelV1 in ai/test specifically for this:

import { MockLanguageModelV1 } from 'ai/test';
import { generateText } from 'ai';

const mockModel = new MockLanguageModelV1({
  doGenerate: async () => ({
    finishReason: 'tool-calls',
    toolCalls: [{
      toolCallType: 'function',
      toolCallId: 'call-1',
      toolName: 'get-weather',
      args: JSON.stringify({ location: 'Bengaluru' }),
    }],
    rawCall: { rawPrompt: null, rawSettings: {} },
    usage: { promptTokens: 10, completionTokens: 5 },
  }),
});

const { toolResults } = await generateText({
  model: mockModel,
  tools: mcpTools,
  prompt: 'What is the weather in Bengaluru?',
});

This tests your entire AI agent pipeline — tool registration, execution, result parsing — without a single API call.

Layer 4: Evaluate Tool Selection Accuracy

The hardest problem to test is: will the LLM choose the right tool? A tool with a vague description might get ignored. A poorly scoped tool might be called when it shouldn't be. Use mcp-evals for structured grading:

import { evalTool } from 'mcp-evals';

const result = await evalTool({
  prompt: 'Find all open GitHub issues labeled bug',
  expectedTool: 'list-github-issues',
  grader: 'openai/gpt-4o',
});

console.log(`Score: ${result.score}, Passed: ${result.passed}`);

Run these evals whenever you change a tool's name, description, or input schema — those are the highest-risk moments.

The One Rule That Saves Hours of Debugging

Always call await mcpClient.close() after every test. Leaving MCP connections open causes port conflicts, zombie processes, and flaky tests in CI. Wrap every test suite in a beforeAll/afterAll block:

beforeAll(async () => { mcpClient = await createMCPClient({ ... }); });
afterAll(async () => { await mcpClient.close(); });

What to Test at Each Layer

Layer	Speed	Cost	Tests
`tool.execute()` directly	Fast	Free	Logic, output schema, error handling
MCP Inspector	Manual	Free	Schema validity, tool discoverability
`MockLanguageModelV1`	Fast	Free	Full agent pipeline, tool routing
`mcp-evals` grading	Slow	LLM cost	Tool selection accuracy by description

Start with Layer 1 for every tool, use Layer 3 for CI, and run Layer 4 before any deployment that touches tool descriptions or names. Your future self — staring at a 3 AM production incident — will thank you.

Have questions about testing a specific tool type? Drop them in the comments below.

How do I calculate how many shares to buy based on ATR and risk management?

Shahid — Sun, 10 May 2026 06:42:51 +0000

One of the most common questions I see from traders is: "I like this setup — but how many shares should I buy?"

Most people guess. Or buy a round number. Or deploy whatever cash they have.

Here's the systematic answer using ATR.

The Framework

ATR(14) tells you how much a stock moves on an average day. Using that as your stop foundation means your stop is calibrated to the stock's actual volatility — not an arbitrary percentage.

Step 1 — Stop Distance
Stop Distance = ATR × Multiplier

2× ATR → short-term / swing trades
3× ATR → positional / long-term (recommended)
4× ATR → very wide, for high-volatility stocks

Step 2 — Risk Budget
Risk Budget = Capital × Risk %
Standard: 1% of capital per trade.
₹1,00,000 capital → ₹1,000 max loss per trade

Step 3 — Position Size
Units = Risk Budget ÷ Stop Distance

Example (round numbers)

Stock price: ₹500 | ATR(14): ₹5 | Capital: ₹1,00,000

ATR Mult	Stop Dist	Stop Price	Units	Deployed	Max Loss
2×	₹10	₹490	100	₹50,000	₹1,000
3× ★	₹15	₹485	66	₹33,000	₹990
4×	₹20	₹480	50	₹25,000	₹1,000

Notice the max loss stays ~₹1,000 across all levels. The multiplier controls stop tightness — not your risk amount. Your position size automatically adjusts.

The YOLO trap

Buying 200 units (full ₹1L deployed) with a 3× ATR stop risks:
200 × ₹15 = ₹3,000 = 3% of capital in one trade.

Across 4 simultaneous positions that's 12% exposure. One bad week is devastating.

ATR position sizing keeps each trade capped at 1% regardless of entry price or volatility level.

Free Calculator

I built a browser-based tool that does all this math instantly — enter your ATR, entry price, capital and risk %, and it simulates across all multiplier levels with a comparison table and charts.

🔗 https://trade-atr.sk7.workers.dev/

No login, no signup — runs entirely in your browser.

npm vs pnpm: The Ultimate Command Comparison Cheat Sheet

Shahid — Fri, 22 Aug 2025 13:49:58 +0000

pnpm and npm are both package managers for JavaScript, but they handle dependency installation and management differently. Direct command translation between npm and pnpm is nearly 1:1—most operations you run in npm can be run in pnpm with the same arguments, but under the hood, pnpm is typically faster and far more disk-efficient due to its unique content-addressable storage approach and symlinking strategy.

Below is a direct, command-by-command comparison between npm and pnpm for common package management tasks. The table uses npm as the reference, with the equivalent pnpm command, and notes any important behavioral differences.

Task	npm Command	pnpm Command	Notes
Initialize project	`npm init`	`pnpm init`	Both create `package.json`; behavior identical.
Install all dependencies	`npm install`	`pnpm install`	pnpm uses a global store and symlinks for speed/space; npm duplicates packages.
Add dependency	`npm add <package>`	`pnpm add <package>`	Both save to `package.json` by default; options like `--save-dev` work the same.
Add dev dependency	`npm add -D <package>`	`pnpm add -D <package>`	Both add to `devDependencies`.
Add optional dependency	`npm add -O <package>`	`pnpm add -O <package>`	Both add to `optionalDependencies`.
Add global package	`npm add -g <package>`	`pnpm add -g <package>`	pnpm's global store is more efficient.
Remove package	`npm remove <package>`	`pnpm remove <package>`	Both remove from `package.json` and `node_modules`.
Update package	`npm update <package>`	`pnpm update <package>`	pnpm updates from its global store, often faster.
Check outdated packages	`npm outdated`	`pnpm outdated`	Both show outdated packages.
Run script	`npm run <script>`	`pnpm <script>`	pnpm does not require `run` keyword if script exists in `package.json`.
Run command	`npx <command>`	`pnpm dlx <command>`	pnpm uses `dlx` to download and run commands like `npx`.
Prune node_modules	`npm prune`	`pnpm prune`	pnpm always removes extraneous/orphaned packages, no package args allowed.
List installed packages	`npm ls`	`pnpm ls`	Both list dependency trees.
Audit for vulnerabilities	`npm audit`	`pnpm audit`	Both check for security issues.
Install pnpm globally	`npm install -g pnpm`	–	`pnpm` can be installed via npm or other methods.

Key Differences Under the Hood

Installation Speed & Disk Space: pnpm is typically much faster and uses far less disk space than npm, especially in large projects, because it stores each package version once globally and symlinks into project node_modules.
Dependency Resolution: pnpm enforces strict dependency resolution, which can help avoid "phantom" dependencies (packages not listed in package.json but still accessible). npm’s flattened node_modules can sometimes allow this.
Monorepo/Workspaces: pnpm has built-in, optimized support for monorepos and workspaces; npm requires extra configuration for similar features.
Ecosystem: npm has the largest ecosystem and widest compatibility; pnpm’s is growing but smaller.
Global Store: pnpm’s global store is a major architectural difference—reducing duplication across all projects on your system.

When to Use Which

Use npm if you want maximum ecosystem compatibility, are working on small projects, or need the broadest community support.
Use pnpm if you value disk space, installation speed, strict dependency isolation, or are managing large projects/monorepos.

Summary

For most day-to-day commands, just replace npm with pnpm. The key differences are internal (speed, disk usage, dependency resolution), not in the command syntax. However, pnpm’s architecture means your projects will install faster, use less disk space, and be more strictly isolated—benefits that grow with project size and complexity.

If you need a specific npm command translated to pnpm that isn’t listed above, just ask—the mapping is nearly always straightforward!

From Zero to AI-Powered Developer: Your Complete Claude Code CLI Setup Guide

Shahid — Wed, 06 Aug 2025 06:43:45 +0000

Setting up your development environment with AI assistance used to be a pipe dream. Today, it's a 10-minute process that could transform how you write code forever. Here's everything you need to know to get Claude Code running on your system—from installation to your first AI-powered commit.

The landscape of software development is shifting rapidly, and at the center of this transformation is Claude Code—Anthropic's command-line AI assistant that brings enterprise-level coding capabilities directly to your terminal. Whether you're a seasoned developer or just starting your coding journey, this comprehensive guide will get you up and running with one of 2025's most powerful development tools.

Why Claude Code Setup Matters More Than Ever

Before diving into the technical details, it's worth understanding what makes Claude Code different from other AI coding tools. Unlike browser-based chatbots or IDE plugins that work in isolation, Claude Code operates as a full-fledged development partner that can read your entire codebase, understand your project architecture, and make coordinated changes across multiple files simultaneously.

The setup process might seem straightforward, but getting it right from the beginning can mean the difference between a seamless development experience and hours of troubleshooting down the line.

Pre-Flight Check: System Requirements That Actually Matter

The Baseline Requirements

Before you begin, ensure your system meets these essential requirements:

Operating Systems: macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows 10+ (with WSL 1, WSL 2, or Git for Windows)
Hardware: 4GB+ RAM minimum

Software: Node.js 18+ (LTS version strongly recommended)
Network: Stable internet connection for authentication and AI processing
Shell Environment: Works optimally with Bash, Zsh, or Fish
Geographic Location: Must be in an Anthropic-supported country

The Often-Overlooked Details

What the documentation doesn't emphasize enough is that your shell choice can significantly impact your experience. While Claude Code works across different shells, Bash and Zsh users report the most stable experience, particularly when integrating with IDE workflows and managing complex project structures.

Installation Methods: Choosing Your Path to Success

Method 1: NPM Installation (The Reliable Standard)

For most developers, the NPM route provides the most predictable setup experience:

npm install -g @anthropic-ai/claude-code

Critical Warning: Never use sudo with this command. The sudo npm install -g approach can create permission issues and security vulnerabilities that will plague your entire setup. If you encounter permission errors, configure your npm permissions properly or consider the local installation method instead.

This approach works best when you have a properly configured Node.js environment and npm permissions set up correctly on your system.

Method 2: Native Binary Installation (The Cutting-Edge Choice)

For developers who want access to the latest features or need to avoid npm permission complexities entirely, the native binary installation offers a compelling alternative.

For macOS, Linux, and WSL:

# Install stable version (recommended for most users)
curl -fsSL https://claude.ai/install.sh | bash

# Install latest version (for early adopters)
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Install specific version (for compatibility requirements)
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

For Windows PowerShell:

# Install stable version
irm https://claude.ai/install.ps1 | iex

# Install latest version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

The native binary installation often provides better performance and eliminates dependency conflicts, making it particularly attractive for developers working in complex environments.

Method 3: Local Installation Migration

If you already have a global npm installation and are experiencing autoupdater permission issues, Claude Code provides a seamless migration path:

claude migrate-installer

This command transitions your installation to a local setup that avoids common permission pitfalls. Some users may be automatically migrated to this method during updates.

Platform-Specific Considerations That Make or Break Your Setup

Windows: Navigating the Complexity

Windows users have two primary paths, each with distinct advantages:

Option 1: WSL Integration (Strongly Recommended)
Both WSL 1 and WSL 2 are fully supported, but the experience is significantly smoother within a Linux subsystem. Install Ubuntu 20.04+ or Debian 10+ through WSL, then follow the standard Linux installation process.

Option 2: Native Windows with Git Bash
This approach requires Git for Windows and additional configuration. For portable Git installations, you'll need to specify the bash path:

$env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

Linux and macOS: The Straightforward Path

Installation on Unix-based systems is typically seamless using either the npm or native binary methods. The primary consideration is ensuring your Node.js version meets the LTS requirements.

Post-Installation Verification: Ensuring Everything Works

After installation, verification is crucial to avoid discovering setup issues during critical development moments:

# Check installation health and configuration
claude doctor

# Verify global availability and version
claude --version

If you used the native binary installation method, you might need to add Claude to your system PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile

Remember to restart your terminal or source your profile for PATH changes to take effect.

Authentication: Your Gateway to AI-Powered Development

Claude Code offers three distinct authentication approaches, each suited to different use cases:

Option 1: Anthropic Console (Default Path)

Requires an active billing account at console.anthropic.com
Uses OAuth for secure authentication
Navigate to your project directory and run claude to begin the authentication flow

Option 2: Claude App Integration (Pro/Max Plans)

Perfect for developers with existing Claude Pro or Max subscriptions
Provides unified billing and account management
Log in with your Claude.ai credentials during the initial launch

Option 3: Enterprise Platforms

Designed for organizations using Amazon Bedrock or Google Vertex AI
Requires additional configuration for cloud infrastructure integration
Ideal for enterprise environments with existing AI platform investments

First Session: Making Contact with Your AI Development Partner

Your first Claude Code session sets the foundation for all future interactions:

Navigate to your project directory:

cd /path/to/your/project

Launch Claude Code:

claude

Complete the authentication flow following the prompts
You'll be greeted with the welcome interface:

✻ Welcome to Claude Code!
...
> Try "create a util logging.py that..."

This welcome prompt isn't just ceremonial—it's your first indication that Claude Code has successfully connected to Anthropic's servers and is ready to assist with your development workflow.

Essential Configuration for Maximum Effectiveness

Environment Variables for Advanced Users

While not required for basic operation, setting up environment variables can enhance your Claude Code experience:

# For direct API access (add to ~/.bashrc, ~/.zshrc, or ~/.profile)
export ANTHROPIC_API_KEY="your-api-key-here"

# For Amazon Bedrock integration
export CLAUDE_CODE_USE_BEDROCK=1

# For Google Vertex AI integration
export CLAUDE_CODE_USE_VERTEX=1

Project-Level Context: The CLAUDE.md Secret Weapon

One of Claude Code's most powerful features is its ability to maintain project context through a CLAUDE.md file placed in your project root. This file acts as a persistent briefing document that Claude Code references for every interaction:

# Project: Web Application Backend

## Structure
- `src/` - Main application code
- `tests/` - Test suites and fixtures
- `docs/` - Project documentation
- `config/` - Configuration files

## Conventions
- Use TypeScript for all new files
- Follow REST API naming conventions
- Implement comprehensive error handling

This context file dramatically improves Claude Code's understanding of your project, resulting in more accurate suggestions and fewer misaligned implementations.

Command Reference: Your Daily Development Arsenal

Understanding Claude Code's command structure is essential for effective usage:

Command	Purpose	Use Case
`claude`	Start interactive mode	Beginning a development session
`claude "task"`	Execute one-time task	Quick fixes or implementations
`claude -p "query"`	Run query and exit	Getting explanations or guidance
`claude -c`	Continue recent conversation	Resuming interrupted work
`claude -r`	Resume previous conversation	Returning to earlier discussions
`claude commit`	Create Git commit	Automated commit message generation
`/clear`	Clear conversation history	Starting fresh within a session
`/help`	Show available commands	Discovering new capabilities
`/config`	Configure settings	Customizing your experience

IDE Integration: Bringing AI Into Your Editor

VS Code Integration Made Simple

Claude Code's VS Code integration transforms your editor into an AI-powered development environment:

Start Claude Code from your VS Code terminal:

claude

Enable IDE integration:

> /ide

Install the extension when prompted Claude Code will automatically detect VS Code and guide you through extension installation. Alternatively, you can manually install the claude-code.vsix file from your installation directory.

Support for Alternative IDEs

Claude Code also integrates with Cursor and other modern editors using a similar process—start Claude Code from the editor's terminal and use the /ide command to enable integration.

Troubleshooting: Solving Common Setup Challenges

Permission Errors

Use the local installation method: claude migrate-installer
Never use sudo with npm installation
Configure npm permissions properly for your user account

Windows Compatibility Issues

Prioritize WSL for the best experience
Ensure Git for Windows is properly installed for native usage
Configure the correct Git Bash path for portable installations

Authentication Problems

Run claude doctor to diagnose authentication status
Re-authenticate using claude /login
Verify you're accessing Claude Code from a supported geographic region

PATH Configuration Issues

Add Claude to your PATH following the post-installation instructions
Remove outdated aliases or symlinks that might conflict
Restart your terminal session after PATH modifications

Beyond Setup: What Comes Next

With Claude Code properly installed and configured, you're positioned to leverage one of the most sophisticated AI development tools available today. The setup process we've covered here creates the foundation for:

Multi-file debugging and refactoring across complex codebases
Intelligent code generation that understands your project's patterns
Automated testing and documentation that stays in sync with your code
Architecture-aware suggestions that respect your existing design decisions

The Investment in Your Development Future

Setting up Claude Code properly isn't just about getting a tool running—it's about establishing a development workflow that can adapt and scale with your projects. The time invested in understanding authentication options, configuring environment variables, and creating comprehensive project context pays dividends in every subsequent coding session.

Whether you're building your next startup, contributing to open source, or tackling enterprise-scale applications, Claude Code's CLI interface provides a consistent, powerful foundation for AI-assisted development.

Your development environment is ready. Your AI coding partner is waiting. The only question remaining is: what will you build first?

Ready to take your development workflow to the next level? With Claude Code properly configured, you're just one claude command away from experiencing the future of software development.

Generate Full Stack React Native Expo project in Seconds ⌚🚀

Shahid — Thu, 17 Jul 2025 07:46:32 +0000

Generate Full Stack React Native project in Seconds.

Run the below command and get relax npx rn-new@latest rn-nw-rnr2 --react-navigation --nativewind --npm --i18next --firebase --drawer --tabs --import-alias --no-install

Ready-made React & Next.js blocks, Framer Motion FX

Shahid — Thu, 17 Jul 2025 07:28:15 +0000

Elevate your next project with a curated suite of minimalist, production-ready UI components crafted in Tailwind CSS, React, and Next.js. Copy-and-paste landing pages, portfolios, and full-stack templates—complete with seamless Supabase integration—let you launch in minutes. Built-in Framer Motion animations, mobile-first responsiveness, and WCAG-focused accessibility ensure every site looks polished and performs flawlessly. Ship professional, scalable web experiences faster than ever.
Visit https://skiper-ui.com

A Practical Guide to Gemini CLI

Shahid — Sun, 06 Jul 2025 05:16:08 +0000

Advanced Usage Examples for Gemini CLI

Gemini CLI is a powerful AI assistant for developers, but its true potential shines when you leverage its advanced features and workflow integrations. Here are practical, effective usage examples to help you get more out of Gemini CLI:

1. Deep Codebase Exploration and Summarization

Summarize architecture and module roles:

  gemini -p "@./ Summarize the architecture and main modules of this project"

Explain a specific function or file:

  gemini -p "@src/utils/helpers.js Explain the purpose and logic of this file"

Map data flows or dependencies:

  gemini -p "@src/ @lib/ Map the data flow between these directories"

2. Automated Bug Detection and Fixing

Analyze and fix a GitHub issue:

  gemini -p "@search https://github.com/yourrepo/issues/123 Analyze this issue and suggest a fix plan"

Detect and fix bugs in a directory:

  gemini -p "@src/ Scan for common bugs and suggest fixes"

Apply suggested code changes:
- Gemini will preview diffs and ask for your approval before applying edits[1].

3. Test Generation and Coverage Analysis

Generate unit tests for a file:

  gemini -p "@src/components/Button.jsx Generate unit tests for this component"

Review and improve test coverage:

  gemini -p "@src/ @tests/ Analyze and suggest improvements for test coverage"

Create integration tests:

  gemini -p "@api/ Generate integration tests for all endpoints"

4. Documentation and Reporting

Generate markdown documentation:

  gemini -p "@src/ Generate markdown documentation for all exported functions"

Summarize recent changes as a changelog:

  gemini -p "Summarize all codebase changes today in changelog format"

Save documentation to a file:

  gemini -p "Save this summary as docs/CHANGELOG.md"

5. Workflow Automation and Integration

Automate code review in CI/CD:

Add to your pre-commit hook:

#!/bin/bash
gemini review --staged-files --format=checklist

Generate docs during build:

  gemini docs --input=src/ --output=docs/ --format=markdown

Integrate with Makefile:

  review:
    gemini review --files="$(FILES)" --severity=medium
  docs:
    gemini docs --auto-update --watch

6. Shell and System Commands

Run shell commands directly:

  !ls -al
  !npm test

Search for text within files:

  gemini -p "Find all TODO comments in the codebase"

7. Project Customization and Memory

Define project rules and context in GEMINI.md:

  # Project: E-commerce Platform
  ## Context
  - React frontend, Node.js backend, MongoDB
  ## Standards
  - Use functional components
  - Follow REST API conventions

Store preferences for consistent AI responses:

  gemini -p "Remember: always use async/await in this project"

8. Real-Time Web Search and Research

Ground prompts with live web data:

  gemini -p "@search What are the latest security best practices for Node.js?"

Fetch and analyze external data:

  gemini -p "@web-fetch https://api.example.com/data Analyze this API response"

9. Multi-Agent and MCP Integration

Extend Gemini CLI with custom tools via MCP:
- Configure .gemini/settings.json to add new abilities (e.g., GitHub integration, image generation)[1][2].
Interact with external APIs or services:

  gemini -p "Use the GitHub MCP tool to list all open pull requests"

10. Batch Jobs and Non-Interactive Mode

Automate repetitive tasks:

  gemini --all_files -p "Refactor all functions to use ES6 syntax"

Run in CI/CD pipelines for automated analysis and reporting[3]:

  gemini review --all_files --format=summary

Table: Gemini CLI Built-in Tools Overview

Tool	Command Example	Description
ReadFolder	`ls`	List files/folders in a directory
ReadFile	`read-file`	Read content of a single file
ReadManyFiles	`read-many-files`	Read multiple files at once
FindFiles	`glob`	Search files by pattern
SearchText	`grep`	Search for text within files
Edit	`edit`	Apply code changes via diffs
WriteFile	`write-file`	Create new files with content
Shell	`!npm test`	Run shell/system commands
WebFetch	`web-fetch`	Fetch and analyze web content
GoogleSearch	`web-search`	Perform Google search for real-time info
SaveMemory	`memoryTool`	Store facts/preferences for session

Tips for Effective Use

Use the @ syntax to reference files or directories for context-aware prompts.
Leverage the 1 million token context window for large projects.
Integrate Gemini CLI into your scripts, CI/CD, and editor workflows for automation and consistency.
Customize project behavior with GEMINI.md and settings files for tailored AI responses[1][2][4].

By combining these advanced examples and integrations, you can unlock the full power of Gemini CLI for code analysis, automation, documentation, and workflow optimization[1][2][4][3].

[1] https://www.datacamp.com/tutorial/gemini-cli
[2] https://dev.to/proflead/gemini-cli-full-tutorial-2ab5
[3] https://www.infoq.com/news/2025/07/google-gemini-cli/
[4] https://mpgone.com/how-to-use-gemini-cli-complete-guide-for-developers-and-beginners/
[5] https://github.com/google-gemini/gemini-cli
[6] https://github.com/reugn/gemini-cli
[7] https://buymeacoffee.com/rsahan/gemini-your-terminal-a-comprehensive-guide-using-gemini-cli
[8] https://astconsulting.in/gemini-cli/gemini-cli-future-ai-command-lines
[9] https://www.youtube.com/watch?v=T76NbeTdDFA
[10] https://dev.to/therealmrmumba/7-insane-gemini-cli-tips-that-will-make-you-a-superhuman-developer-2d7h
[11] https://www.youtube.com/watch?v=VSiHh4KyK6A
[12] https://learn.netdata.cloud/docs/ai-&-ml/devops-copilot/gemini-cli
[13] https://www.youtube.com/watch?v=lEBO36eovns
[14] https://www.youtube.com/watch?v=bMSq6ghdIYk
[15] https://cloud.google.com/gemini/docs/codeassist/gemini-cli
[16] https://www.youtube.com/watch?v=CqL5kB8pOfo
[17] https://blog.google/technology/developers/introducing-gemini-cli-open-source-ai-agent/
[18] https://www.reddit.com/r/GeminiAI/comments/1lkojt8/gemini_cli_a_comprehensive_guide_to_understanding/
[19] https://momen.app/blogs/practical-tips-for-using-gemini-cli-in-real-projects/
[20] https://www.youtube.com/watch?v=we2HwLyKYEg
[21] https://github.com/Ramesh-tester/gemini-cli-action
[22] https://www.linkedin.com/pulse/drowning-pull-requests-automate-your-github-workflow-franziska-2rexe
[23] https://cloud.google.com/code/docs/shell/write-code-gemini
[24] https://devops.com/gemini-cli-the-open-source-ai-agent-thats-revolutionizing-terminal-workflows/
[25] https://www.marktechpost.com/2025/06/28/getting-started-with-gemini-command-line-interface-cli/
[26] https://github.com/google-gemini/gemini-cli/actions/workflows/ci.yml
[27] https://www.linkedin.com/pulse/gemini-command-line-interface-cli-ultimate-ai-agent-lozano-grijalba-tkl2f

Gemini CLI: The AI-Powered Command Line Revolution for Developers

Shahid — Sun, 06 Jul 2025 05:14:29 +0000

Introduction

The command line has long been the developer’s home for productivity, automation, and deep code work. With the arrival of Gemini CLI, Google’s open-source AI agent, the terminal is now supercharged with advanced AI capabilities—enabling developers to code, debug, document, and automate tasks using natural language, all from within their favorite shell environment.

What Is Gemini CLI?

Gemini CLI is an open-source command-line tool that brings the power of Google’s Gemini 2.5 Pro model directly to your terminal. It’s designed for developers who want AI assistance for coding, content generation, problem-solving, and workflow automation—without leaving the command line[1][2][3][4].

Key Features:

1 million token context window: Analyze and understand even the largest codebases.
Natural language prompts: Interact with your codebase, files, and tools using plain English.
Real-time web search: Ground your prompts with up-to-date information.
Open-source extensibility: Customize, inspect, and contribute to the tool.
Seamless integration: Works with VS Code, GitHub, and CI/CD pipelines[1][2][3][5].

Installation and Setup

Prerequisites:

Node.js v18 or higher
(Recommended) Python 3.8+ and git for advanced features[4][6]

Quick Start:

Run instantly (no install):

  npx https://github.com/google-gemini/gemini-cli

Global installation:

  npm install -g @google/gemini-cli

Launch Gemini CLI:

  gemini

Authentication:

Authenticate with your Google account or set your API key:

  export GEMINI_API_KEY="your_api_key_here"

API keys can be generated from Google AI Studio or Google Cloud Console[4][6].

Using Gemini CLI in Your Codebase

Project Initialization

Navigate to your project directory:

  cd path/to/your/project

(Optional) Initialize Gemini CLI for project-specific context:

  gemini init

Start the CLI:

  gemini

Natural Language Prompts and File Context

Gemini CLI uses the @ syntax to reference files or directories in prompts:

Single file: @src/main.py
Directory: @src/
Multiple: @src/ @tests/

Example Commands:

Action	Example Command
Summarize architecture	`gemini -p "@./ Summarize the architecture of this project"`
Explain a file	`gemini -p "@src/main.py Explain this file's purpose and structure"`
Analyze dependencies	`gemini -p "@package.json @src/index.js Analyze the dependencies used"`
Review test coverage	`gemini -p "@src/ @tests/ Analyze test coverage for the source code"`
Overview of all files	`gemini --all_files -p "Analyze the project structure and dependencies"`
Summarize today’s changes	`> Give me a summary of all of the changes made to the codebase today.`
Fix a bug or issue	`> Analyze this GitHub issue: [@search ] and suggest a fix plan.`

Advanced Features

Editing and refactoring: Request code improvements or refactoring.
Bug detection and fixing: Let Gemini suggest and apply fixes.
Test generation: Auto-generate test cases for your code.
Documentation: Generate markdown docs, changelogs, and diagrams.
Search grounding: Use @search for real-time information retrieval[2][3][5].

Workflow Integration and Automation

Gemini CLI is designed to fit seamlessly into existing developer workflows:

Editor/IDE Agnostic: Use in any terminal, or integrate with VS Code, IntelliJ, Vim, and more[5].
Git Hooks: Automate code reviews or documentation generation on commit.
Build Scripts & Makefiles: Add AI-powered steps to your build and deployment pipelines.
CI/CD Integration: Run Gemini CLI in non-interactive mode for automated code analysis and reporting.
Custom Extensions: Build and share your own plugins for linting, testing, migration, and security[5][7].

Example: Git Pre-commit Hook

#!/bin/bash
gemini review --staged-files --format=checklist

Example: Automated Documentation

gemini docs --input=src/ --output=docs/ --format=markdown

Real-World Use Cases

Codebase Exploration: Instantly summarize architecture, module roles, and data flows in large projects[2][8].
Bug Audits: Analyze folders of scripts, detect bugs, and receive step-by-step fix plans[8].
Pull Request Management: Scan and auto-close spam PRs, or generate review checklists[9].
Multi-step Workflows: Chain prompts to generate code, tests, docs, and push to GitHub in one go[9].
API Testing: Connect to Postman or Swagger files for automated API validation[10].

Community and Extensibility

Gemini CLI is fully open source (Apache 2.0). Developers can:

Inspect and modify the code for security and transparency.
Contribute features, bug fixes, and extensions.
Share workflow templates and integration patterns with the community[1][11][7].

Best Practices

Use gemini init to set up project-specific configuration (e.g., GEMINI.md).
Reference directories or use --all_files for large projects.
Leverage the 1 million token context window for deep code analysis.
Automate repetitive tasks with scripts and hooks.
Stay updated with community extensions and best practices[5][11][7].

🎁 Want to use Gemini CLI in more advanced way read the below article

Practical Guide to Gemini CLI

Conclusion

Gemini CLI is redefining what’s possible in the terminal. By combining the power of Google’s Gemini AI with the flexibility of the command line, developers can now code, debug, document, and automate with unprecedented speed and intelligence. Whether you’re working solo or as part of a team, Gemini CLI is a must-have tool for the modern developer’s workflow[1][2][3][4][5][11].

For more details, visit the official Gemini CLI documentation and GitHub repository.

[1] https://blog.google/technology/developers/introducing-gemini-cli-open-source-ai-agent/
[2] https://www.datacamp.com/tutorial/gemini-cli
[3] https://www.infoq.com/news/2025/07/google-gemini-cli/
[4] https://www.f22labs.com/blogs/what-is-google-gemini-cli-how-to-install-and-use-it/
[5] https://mpgone.com/how-to-use-gemini-cli-complete-guide-for-developers-and-beginners/
[6] https://dev.to/auden/google-gemini-cli-tutorial-how-to-install-and-use-it-with-images-4phb
[7] https://topmostads.com/google-gemini-cli-free-open-source-guide/
[8] https://javascript.plainenglish.io/i-tried-googles-gemini-cli-and-it-changed-how-i-code-forever-4794d3c02081
[9] https://dev.to/therealmrmumba/7-insane-gemini-cli-tips-that-will-make-you-a-superhuman-developer-2d7h
[10] https://momen.app/blogs/practical-tips-for-using-gemini-cli-in-real-projects/
[11] https://devops.com/gemini-cli-the-open-source-ai-agent-thats-revolutionizing-terminal-workflows/
[12] https://www.zdnet.com/article/geminis-command-line-tool-is-a-hidden-productivity-game-changer-and-its-free/
[13] https://github.com/google-gemini/gemini-cli
[14] https://cloud.google.com/gemini/docs/codeassist/gemini-cli
[15] https://dev.to/proflead/gemini-cli-full-tutorial-2ab5
[16] https://www.youtube.com/watch?v=KUCZe1xBKFM
[17] https://hackernoon.com/complete-gemini-cli-setup-guide-for-your-terminal
[18] https://simonwillison.net/2025/Jun/25/gemini-cli/
[19] https://cloud.google.com/gemini/docs/discover/write-prompts
[20] https://ikala.ai/blog/ai-trends/google-gemini-cli-in-depth-analysis-the-ai-agent-ecosystem-war-for-the-developer-terminal/
[21] https://geminicli.tech
[22] https://www.reddit.com/r/GeminiAI/comments/1lkojt8/gemini_cli_a_comprehensive_guide_to_understanding/
[23] https://www.youtube.com/watch?v=CqL5kB8pOfo
[24] https://www.youtube.com/watch?v=we2HwLyKYEg
[25] https://github.com/google-gemini/gemini-cli/issues/3088/linked_closing_reference
[26] https://www.linkedin.com/pulse/evaluating-google-gemini-cli-my-developer-experience-majid-sheikh-og51f
[27] https://www.reddit.com/r/singularity/comments/1lk5h19/google_introduces_gemini_cli_a_light_opensource/
[28] https://www.linkedin.com/pulse/gemini-cli-future-coding-now-mr-parvez-mosharaf-dfz0c
[29] https://github.com/google-gemini/gemini-cli/issues/2779

open-source animated components for Tailwind and Shadcn

Shahid — Fri, 27 Jun 2025 05:34:22 +0000

open-source component Animation library built with React, TypeScript, Tailwind CSS, Motion and Shadcn CLI
https://animate-ui.com/

Setting Up Row-Level Security in Supabase User and Admin Roles

Shahid — Mon, 26 May 2025 17:53:41 +0000

Row-Level Security (RLS) in Supabase is a powerful feature that allows you to control access to your database tables at the row level, ensuring users can only access or modify data they’re authorized to. In this post, we’ll walk through setting up RLS on a profiles table in Supabase, where authenticated users can view and edit their own profiles, and admins can view and edit all profiles. Let’s dive in!

Prerequisites

A Supabase project with authentication enabled.
A profiles table in the public schema with the following columns:
- id (UUID, references auth.users(id)).
- is_admin (boolean, indicates admin status).
Basic familiarity with SQL and Supabase’s dashboard or SQL Editor.

Step 1: Enable RLS on the Profiles Table

First, we need to enable RLS on the profiles table to enforce access control. Without RLS, users could access all rows, which we want to avoid. Run the following SQL command in the Supabase SQL Editor:

ALTER TABLE public.profiles ENABLE ROW LEVEL SECURITY;

This ensures that no one can access the table unless we define explicit RLS policies.

Step 2: Define RLS Policies

We’ll create four RLS policies to achieve our goal:

Allow authenticated users to view their own profile.
Allow authenticated users to edit their own profile.
Allow admins to view all profiles.
Allow admins to edit all profiles.

Policy 1: Authenticated Users View Their Own Profile

This policy allows logged-in users to view their own profile by matching their auth.uid() (the user’s ID from Supabase Auth) with the id column in the profiles table.

CREATE POLICY "Authenticated users can view their own profile"
ON public.profiles
FOR SELECT
TO authenticated
USING (auth.uid() = id);

What it does: Only allows SELECT queries for rows where the authenticated user’s ID matches the id column.
Who it applies to: Users with the authenticated role (logged-in users).

Policy 2: Authenticated Users Edit Their Own Profile

This policy allows users to update their own profile, again by matching auth.uid() with the id column.

CREATE POLICY "Authenticated users can edit their own profile"
ON public.profiles
FOR UPDATE
TO authenticated
USING (auth.uid() = id);

What it does: Permits UPDATE queries only on the user’s own profile row.
Who it applies to: Authenticated users.

Policy 3 & 4: Admins View and Edit All Profiles

Initially, you might write admin policies by checking the is_admin column directly in the profiles table, like this:

CREATE POLICY "Admins can view all profiles"
ON public.profiles
FOR SELECT
TO authenticated
USING (is_admin = true);

CREATE POLICY "Admins can edit all profiles"
ON public.profiles
FOR UPDATE
TO authenticated
USING (is_admin = true);

However, this approach requires Supabase to check the is_admin column for the user’s own row, which can be inefficient, especially for large tables. Instead, we’ll use a security definer function to optimize the admin check.

Step 3: Create a Security Definer Function

To improve performance and maintainability, let’s create a function that checks if a user is an admin by querying their is_admin status. This avoids repetitive table scans in policies.

CREATE OR REPLACE FUNCTION public.is_admin_user(user_id UUID)
RETURNS BOOLEAN
LANGUAGE plpgsql
SECURITY DEFINER
AS $$
DECLARE
  is_admin BOOLEAN;
BEGIN
  SELECT profiles.is_admin INTO is_admin
  FROM public.profiles
  WHERE profiles.id = user_id;
  RETURN is_admin;
END;
$$;

Why use SECURITY DEFINER? It runs with the privileges of the function’s creator, bypassing RLS for the internal query, making it more efficient.
What it does: Takes a user ID, checks their is_admin status in the profiles table, and returns true if they’re an admin, false otherwise.

Now, let’s update the admin policies to use this function:

-- Drop existing admin policies if they exist
DROP POLICY IF EXISTS "Admins can view all profiles" ON public.profiles;
DROP POLICY IF EXISTS "Admins can edit all profiles" ON public.profiles;

-- Create new admin policies using the function
CREATE POLICY "Admins can view all profiles"
ON public.profiles
FOR SELECT
TO authenticated
USING (public.is_admin_user(auth.uid()));

CREATE POLICY "Admins can edit all profiles"
ON public.profiles
FOR UPDATE
TO authenticated
USING (public.is_admin_user(auth.uid()));

These policies allow users identified as admins (via the is_admin_user function) to view or edit all profiles.

Step 4: Auto-Create Profiles for New Users

To ensure every user has a profile (and avoid issues where is_admin_user returns NULL), create a trigger that automatically adds a profile when a new user signs up:

CREATE OR REPLACE FUNCTION public.create_profile_for_new_user()
RETURNS TRIGGER
LANGUAGE plpgsql
AS $$
BEGIN
  INSERT INTO public.profiles (id, is_admin)
  VALUES (NEW.id, FALSE);
  RETURN NEW;
END;
$$;

CREATE TRIGGER on_auth_user_created
AFTER INSERT ON auth.users
FOR EACH ROW
EXECUTE FUNCTION public.create_profile_for_new_user();

This sets is_admin to false by default for new users, ensuring the profiles table is populated.

Step 5: Testing the Policies

To verify everything works:

Test as a Regular User:
- Log in as a non-admin user (is_admin = false).
- Run a query like SELECT * FROM profiles using the Supabase client:
```
 const { data, error } = await supabase.from('profiles').select('*');
 console.log(data, error);
```
This should return only the user’s own profile.
- Try updating another user’s profile (e.g., UPDATE profiles SET ... WHERE id = 'other_user_id'). It should fail.
Test as an Admin:
- Log in as an admin (is_admin = true).
- Run the same SELECT query to confirm access to all profiles.
- Test an UPDATE on any profile; it should succeed.
Use the SQL Editor:
- Simulate a user with call auth.login_as_user('user_email') and test queries directly.

Troubleshooting Tips

No Data Returned: Ensure auth.uid() matches the id column and that the user has a profile. Check if RLS is enabled.
Permission Errors: If you see “new row violates row-level security policy,” verify the policy conditions and the user’s authentication status.
Performance Issues: The is_admin_user function reduces overhead, but ensure the id column is indexed (it is by default if it’s the primary key).
Missing Profiles: If a user lacks a profile row, the is_admin_user function returns NULL. The trigger above prevents this, but double-check for existing users.

Additional Considerations

INSERT and DELETE Policies: If your app allows profile creation or deletion, add policies for INSERT and DELETE. For example:

  CREATE POLICY "Users can create their own profile"
  ON public.profiles
  FOR INSERT
  TO authenticated
  WITH CHECK (auth.uid() = id);

Service Role for Admin Tasks: Use the service_role key for server-side operations that need to bypass RLS, but keep it secure and never expose it client-side.
Scalability: For large tables, monitor query performance. The is_admin_user function is optimized, but consider caching admin status if needed.

Conclusion

With these RLS policies and the is_admin_user function, you’ve set up a secure and scalable access control system for your profiles table in Supabase. Authenticated users can manage their own profiles, while admins have full access to all profiles. Always test thoroughly in a development environment before going live, and consult the Supabase RLS documentation for more details.

Happy coding and let me know in the comments if you have questions or run into issues. I am running supabase self-hosted version. Contact for any paid setup & consulting work!