npm package: @schemalens/introspector
Description: PostgreSQL schema introspection engine for SchemaLens
Latest version: 0.5.0

# SchemaLens

**Schema version control for PostgreSQL and Supabase.**

SchemaLens tracks your database schema the same way Git tracks your code — every table, view, function, policy, index, trigger, enum, and extension is written to plain SQL files in your repository. Changes are diffed, versioned, and deployable with a single command.

---

## How It Works

```
Your Repo                 CLI                  SchemaLens SaaS
──────────                 ───                  ───────────────
schema/
  tables/       ←──── schemalens pull ─────── introspects live DB
  views/              schemalens status        shows diff
  functions/          schemalens deploy ──────► applies SQL to DB
  ...                       │
                            └──── auto-sync ──► dashboard snapshot
```

1. **Pull** — `schemalens pull --env dev` introspects your live database and writes SQL files to `schema/`
2. **Edit** — modify files in `schema/` directly, or let migrations drive the changes
3. **Status** — `schemalens status --env dev` shows what's different between your files and the live DB
4. **Deploy** — `schemalens deploy --env prod --confirm` applies your local changes to the target database
5. **Dashboard** — every pull/deploy auto-syncs a snapshot to the SchemaLens web UI for visual history

---

## Quick Start

### 1. Install the CLI

```bash
npm install -g @schemalens/cli
```

### 2. Set up your project

```bash
schemalens init
```

This runs an interactive wizard that creates `schema/_meta/.schemalens.yml` in your repo.

### 3. Snapshot your database

```bash
schemalens pull --env dev
```

Your schema is now tracked in `schema/` — commit these files to your repo.

### 4. See what changed

```bash
schemalens status --env dev
```

### 5. Deploy a change

```bash
# Dry run first (default)
schemalens deploy --env staging

# Apply for real
schemalens deploy --env staging --confirm
```

---

## Configuration (`schema/_meta/.schemalens.yml`)

```yaml
version: 1
schema_dir: schema
allow_destructive: false

environments:
  dev:
    connection_string: env(DATABASE_URL)          # resolves $DATABASE_URL
  staging:
    connection_string: env(DATABASE_URL_STAGING)
  prod:
    # Leave connection_string out when using linked mode (see below)

# Optional: link to SchemaLens SaaS for dashboard + passwordless connection
project_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  # copy from Project Settings
api_key: env(SCHEMALENS_API_KEY)                  # generate in Project Settings
```

### Linked mode (no local DATABASE_URL needed)

When `project_id` and `api_key` are set, you can omit `connection_string` for any environment. The CLI will securely fetch the connection details from the SchemaLens SaaS using your API key — no secrets in your local environment.

---

## CLI Reference

| Command | Description |
|---------|-------------|
| `schemalens init` | Interactive setup — creates `.schemalens.yml` |
| `schemalens pull --env <env>` | Introspect live DB → write schema files |
| `schemalens status --env <env>` | Show diff between local files and live DB |
| `schemalens deploy --env <env>` | Dry-run deploy plan |
| `schemalens deploy --env <env> --confirm` | Apply changes to the database |
| `schemalens deploy --env <env> --allow-destructive` | Allow DROP operations |
| `schemalens deploy --env <env> --rename table.old:new` | Confirm a column rename |

---

## SaaS Setup

### Create a project

1. Sign in at [schemalens.dev](https://www.schemalens.dev)
2. Click **New Project**
3. Either **Connect with Supabase** (uses your Supabase Personal Access Token to auto-fill credentials) or enter details manually
4. Save — your project ID is shown in Project Settings

### Generate an API key

1. Open Project Settings → CLI Access
2. Click **Generate Key**
3. Copy the key (shown once) — set it as `SCHEMALENS_API_KEY` in your environment
4. Add `project_id` and `api_key: env(SCHEMALENS_API_KEY)` to `.schemalens.yml`

From this point, every `schemalens pull` and `schemalens deploy --confirm` will automatically push a snapshot to your dashboard.

---

## Tracked Object Types

| Type | Files | Description |
|------|-------|-------------|
| Tables | `schema/tables/<name>/definition.sql` | Columns, constraints |
| Views | `schema/views/<name>.sql` | Full view definition |
| Functions | `schema/functions/<name>.sql` | Stored procedures |
| Triggers | `schema/tables/<name>/triggers.sql` | Per-table triggers |
| Policies | `schema/tables/<name>/policies.sql` | RLS policies |
| Indexes | `schema/tables/<name>/indexes.sql` | Non-primary indexes |
| Enums | `schema/enums/<name>.sql` | Custom enum types |
| Extensions | `schema/extensions/enabled.sql` | Enabled extensions |

---

## Security

| Item | Where it lives |
|------|---------------|
| Database connection string | Your local environment variable (`DATABASE_URL`) — never committed |
| Database password (linked mode) | SchemaLens SaaS, stored server-side, never returned to the browser |
| SchemaLens API key | Your environment (`SCHEMALENS_API_KEY`) — stored as a hash in our database |
| Schema files (`schema/`) | Your Git repository — contains DDL only, no credentials |

---

## AI Integration

Add the SchemaLens skill to your AI coding agent (Claude Code, etc.) so it understands your schema workflows, CLI commands, and safety guardrails:

```
https://www.schemalens.dev/skills/claude-code.md
```

The skill teaches your AI agent to:
- Read your `schema/` files to answer questions about your database structure
- Run the correct SchemaLens commands at the right time
- Always dry-run before deploying, and ask for confirmation before destructive operations
- Follow the pull-after-deploy workflow to keep schema files in sync

The skill file is also bundled with the CLI at `@schemalens/cli/skills/schemalens.md`.

---

## Development

```bash
# Clone and install
git clone https://github.com/your-org/schemalens
npm install

# Run the web app
cd apps/web && npm run dev

# Build the CLI
cd packages/cli && npm run build

# Run CLI from source
cd packages/cli && npx tsx src/index.ts pull --env dev
```

### Environment variables (web app)

```
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

# Optional: Upstash Redis for rate limiting
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=
```


### Resend
## https://resend.com/  
## pearl.shah1909@gmail.com

### supabase
## itoolsolutionsapp@gmail.com