softr-vibe-coding 1.1.0

package/datasources/overview.md

@@ -0,0 +1,41 @@
+# Data Source Overview
+
+## Comparison Matrix
+
+| Data Source | Max Records | Concurrent Users | Security | Skill Level | Vibe Coding Approach |
+|---|---|---|---|---|---|
+| Softr Databases | 1M+ | Unlimited | Medium | Low | `useRecords` + `q.select()` |
+| Airtable | 500K | 200-300 | Medium | Low | `useRecords` + `q.select()` |
+| Google Sheets | 1M+ | 50-100 | Low | Low | `useRecords` + `q.select()` |
+| SmartSuite | 500K | 200-300 | Medium | Low | `useRecords` + `q.select()` |
+| HubSpot | 1M+ | 500-1000 | Medium | Medium | `useRecords` + `q.select()` |
+| monday.com | 500K | 50-100 | Low | Low | `useRecords` + `q.select()` |
+| Xano | Unlimited | Unlimited | High | High | `useRecords` + `q.select()` |
+| SQL Database | Unlimited | Unlimited | High | High | `useRecords` + `q.select()` |
+| Supabase | Unlimited | Unlimited | High | High | `useRecords` + `q.select()` |
+| Notion | 1M+ | 50-100 | Medium | Low | `useRecords` + `q.select()` |
+| ClickUp | 500K | 50-100 | Medium | Low | `useRecords` + `q.select()` |
+| Coda | 1M+ | 200-300 | Medium | Low | `useRecords` + `q.select()` |
+| BigQuery | Unlimited | N/A | Low | Medium | `useRecords` + `q.select()` |
+| REST API | Unlimited | N/A | Varies | High | `useProxyFetch` + `useQuery` |
+
+## Selection Guide
+
+- **New projects with no existing data** -> Softr Databases (no rate limits, native performance, included in subscription)
+- **Existing spreadsheet data** -> Airtable or Google Sheets (easy migration, one-click import from Airtable)
+- **Scalable backend with full API control** -> Xano, Supabase, or SQL
+- **Any data source not natively supported** -> REST API
+
+## Key Concepts
+
+- Softr does **not store or sync** external data -- it proxies requests in real-time (with 24-hour caching).
+- Data is connected to **dynamic blocks** (List, Grid, Table, Kanban, Chart, Form, etc.) in the Softr Studio.
+- **Multiple data sources** can coexist in a single Softr app, even on the same page.
+- Softr IP addresses to whitelist for secured databases: `3.120.79.212`, `3.123.159.186`, `52.58.246.121`
+
+## User Sync Availability
+
+| Source | 2-Way User Sync |
+|---|---|
+| Softr Databases, Airtable, Google Sheets, HubSpot, Notion, Coda, monday.com, SmartSuite, ClickUp, Xano, Supabase, SQL Database | Supported |
+| BigQuery, REST API | Not supported |

package/datasources/reading.md

@@ -0,0 +1,222 @@
+# Reading Data
+
+Fetching, filtering, sorting, pagination, metrics, charts, and current user.
+
+## Table of Contents
+
+- [Query Builder](#query-builder)
+- [useRecords -- Fetch a Paginated List](#userecords----fetch-a-paginated-list)
+- [useRecord -- Fetch a Single Record](#userecord----fetch-a-single-record)
+- [useLinkedRecords -- Fetch Linked/Related Options](#uselinkedrecords----fetch-linkedrelated-options)
+- [useFieldOptions -- Fetch Single/Multi-Select Choices](#usefieldoptions----fetch-singlemulti-select-choices)
+- [Filtering](#filtering)
+- [Sorting](#sorting)
+- [Current User](#current-user)
+- [Metrics](#metrics)
+- [Chart Data](#chart-data)
+
+## Query Builder
+
+Field mappings must be static (no dynamic keys or computed values -- hard constraint for Softr's static analysis):
+
+```jsx
+import { q } from "@/lib/datasource";
+
+var select = q.select({
+  title: "FIELD_ID1",
+  description: "FIELD_ID2",
+  createdAt: "FIELD_ID3",
+});
+```
+
+## useRecords -- Fetch a Paginated List
+
+```jsx
+import { useRecords, q } from "@/lib/datasource";
+
+var result = useRecords({
+  select: q.select({ name: "FIELD_ID1", email: "FIELD_ID2" }),
+  count: 6,           // records per page (default 6, max 100)
+  where: q.text("name").contains("Alice"),  // optional filter
+  orderBy: q.desc("createdAt"),             // optional sort
+  enabled: true,                            // optional, defer loading
+});
+
+var data = result.data;
+var status = result.status;       // "pending" | "success" | "error"
+var error = result.error;
+var fetchNextPage = result.fetchNextPage;
+var hasNextPage = result.hasNextPage;
+var isFetching = result.isFetching;
+var isFetchingNextPage = result.isFetchingNextPage;
+var refetch = result.refetch;
+var isRefetching = result.isRefetching;
+
+// Flatten pages into a single array:
+var items = (data && data.pages) ? data.pages.flatMap(function(p) { return p.items; }) : [];
+```
+
+**CRITICAL:** Only ONE `useRecords` call per block. Fetch all data in one call and filter client-side. Multiple `useMetric` calls ARE allowed.
+
+### Loading All Records (Auto-Pagination)
+
+```jsx
+import { useState, useEffect } from "react";
+
+var result = useRecords({ select: select, count: 100 });
+
+useEffect(function() {
+  if (result.hasNextPage && !result.isFetchingNextPage && result.status === "success") {
+    result.fetchNextPage();
+  }
+}, [result.hasNextPage, result.isFetchingNextPage, result.status, result.fetchNextPage]);
+```
+
+## useRecord -- Fetch a Single Record
+
+```jsx
+import { useRecord, useCurrentRecordId, q } from "@/lib/datasource";
+
+var recordId = useCurrentRecordId(); // resolves from URL context, can be null
+var result = useRecord({
+  select: q.select({ title: "FIELD_ID1", description: "FIELD_ID2" }),
+  recordId: recordId,
+});
+```
+
+## useLinkedRecords -- Fetch Linked/Related Options
+
+```jsx
+import { q, useLinkedRecords } from "@/lib/datasource";
+
+var result = useLinkedRecords({
+  select: q.select({ category: "$CATEGORY_FIELD_ID" }),
+  field: "category",    // the ALIAS from q.select(), NOT the raw field ID
+  sortOrder: "ASC",     // "ASC" | "DESC"
+  search: "",           // optional search string
+  enabled: true,        // defer loading until needed
+  count: 50,
+});
+
+var options = (result.data && result.data.pages) ? result.data.pages.flatMap(function(p) { return p.items; }) : [];
+```
+
+**CRITICAL:** The `field` prop takes the ALIAS from `q.select()`, NOT the raw field ID. Items are shaped as `{ id, title }` -- use `opt.title` (NOT `opt.label`).
+
+## useFieldOptions -- Fetch Single/Multi-Select Choices
+
+Returns the current option list for any `singleSelect` / `multipleSelects` field — without hardcoding option IDs in your block. Useful when the schema's option list changes (renames, additions, reorders) and you don't want to redeploy the block every time.
+
+```jsx
+import { useFieldOptions, q } from "@/lib/datasource";
+
+var statusOptions = useFieldOptions({
+  select: q.select({ status: "Status" }),
+  field: "status",   // the ALIAS from q.select(), NOT the raw field ID
+});
+
+// statusOptions.options → [{ id: "sel...", label: "Active" }, { id: "sel...", label: "Inactive" }]
+// Each item has `id` (the option's UUID, used in mutate payloads) and `label` (display string).
+```
+
+**When to use this vs. hardcoding:**
+
+- **Use `useFieldOptions`** when option IDs / labels could change post-deploy — selects with rapidly-evolving lists, user-editable choices, or any case where re-pasting blocks for an option rename is annoying.
+- **Hardcode** when the option set is stable and frequently referenced (e.g. a status enum that drives a state machine), so the IDs live in source and rename-safety is enforced by greppable constants.
+
+`useFieldOptions` is the read-side equivalent of using `useLinkedRecords` for foreign records — it abstracts away the field's option store. Items are shaped `{ id, label }` (note: `label`, not `title` like `useLinkedRecords`).
+
+## Filtering
+
+Build filters with typed builders. Filters support up to 2 levels of nesting.
+
+**Text fields** -- `q.text(field)`:
+`is`, `isNot`, `contains`, `startsWith`, `endsWith`, `isOneOf`, `isNoneOf`, `hasAllOf`, `isEmpty`, `isNotEmpty`
+
+**Number fields** -- `q.number(field)`:
+`is`, `isNot`, `gt`, `gte`, `lt`, `lte`, `between`, `isEmpty`, `isNotEmpty`
+
+**Boolean fields** -- `q.boolean(field)`:
+`is`, `isNot`, `isEmpty`, `isNotEmpty`
+
+**Date fields** -- `q.date(field)`:
+`is`, `isNot`, `gt`, `gte`, `lt`, `lte`, `between`, `isNotBetween`, `isEmpty`, `isNotEmpty`
+
+**Array fields** -- `q.array(field)`:
+`is`, `isOneOf`, `isNoneOf`, `hasAllOf`, `isEmpty`, `isNotEmpty`
+
+**Logical combinators**: `q.and(...)`, `q.or(...)`
+
+```jsx
+where: q.and(
+  q.text("name").contains("Alice"),
+  q.number("age").gte(18),
+  q.or(
+    q.boolean("isActive").is(true),
+    q.text("notes").isNotEmpty()
+  )
+)
+```
+
+## Sorting
+
+```jsx
+orderBy: q.desc("createdAt")
+orderBy: q.asc("lastName")
+orderBy: [q.asc("lastName"), q.asc("firstName")]  // multiple fields
+```
+
+## Current User
+
+```jsx
+import { useCurrentUser } from "@/lib/user";
+
+var user = useCurrentUser();
+// Returns null if not logged in
+// Fields: { id, fullName, firstName, lastName, email, avatar } (all string or null)
+```
+
+**For user groups, role, or custom fields** -- use `window.__softr_current_user` (NOT `useCurrentUser()`):
+
+```jsx
+var softrUser = window.__softr_current_user || {};
+var userGroups = softrUser.userGroups || [];
+var isPremium = userGroups.some(function(g) { return g.name === "Premium Member"; });
+```
+
+## Metrics
+
+```jsx
+import { useMetric, q, metric } from "@/lib/datasource";
+
+var result = useMetric({
+  select: q.select({ revenue: "$REVENUE_FIELD_ID" }),
+  metric: metric.sum("revenue"),
+  where: q.date("createdAt").gte("2025-01-01"),
+});
+// result.data is the aggregated value (number)
+```
+
+Aggregations: `metric.sum(field)`, `metric.avg(field)`, `metric.max(field)`, `metric.min(field)`, `metric.distinct(field)`, `metric.count()`
+
+## Chart Data
+
+```jsx
+import { useChartData, q, metric } from "@/lib/datasource";
+
+var result = useChartData({
+  select: q.select({ date: "$DATE_FIELD_ID", revenue: "$REVENUE_FIELD_ID" }),
+  orderBy: q.asc("date"),
+  metric: { revenue: metric.sum("revenue") },
+  groupBy: metric.groupBy("date", metric.bucket.month.long),
+});
+```
+
+Grouping buckets: `metric.bucket.year`, `metric.bucket.month.iso`, `metric.bucket.month.long`, `metric.bucket.day.iso`, `metric.bucket.day.long`
+
+Use **recharts** with shadcn's chart wrapper:
+
+```jsx
+import { LineChart, Line, XAxis, CartesianGrid } from "recharts";
+import { ChartContainer, ChartTooltip, ChartTooltipContent } from "@/components/ui/chart";
+```

package/datasources/rest-api.md

@@ -0,0 +1,206 @@
+# REST API Data Source
+
+## Overview
+
+A generic connector that allows Softr to connect to virtually any external platform or service that exposes an HTTP REST API. This is the escape hatch for any source not natively supported.
+
+**Plan requirement:** Business and Enterprise Softr plans only.
+
+**Authentication:** Any header-based auth (API keys, Bearer tokens, Basic Auth, etc.) configured manually.
+
+**2-way user sync:** Not supported.
+
+**Best for:** Connecting any external service with an API; extending Softr's native integrations; building RevOps or automation workflows where Softr serves as a frontend for tools like Salesforce, Pipedrive, Stripe, Luma, or custom internal APIs.
+
+## Connection Setup
+
+### Step 1: Add REST API as a data source
+Data Sources > Connect Data Source > Choose **REST API**. Select a pre-built template (Stripe, Salesforce, Pipedrive, Asana, Shopify, etc.) or **Add Manually**.
+
+### Step 2: Set up default headers
+These headers apply to all endpoints in the connection:
+- **Name**: A label to identify the REST API connection.
+- **Headers**: Key-value pairs for universal headers (e.g., `Authorization: Bearer YOUR_TOKEN`, custom header for API key, etc.).
+
+### Step 3: Add API Resources (Endpoints)
+Each resource is a specific API endpoint. Supports **GET** and **POST** methods.
+
+For each resource:
+- **Name**: A label for the endpoint.
+- **HTTP Method**: GET (fetch data) or POST (create records).
+- **URL**: The endpoint URL from the API's documentation.
+- **Headers tab**: Endpoint-specific headers (in addition to default headers).
+- **URL Params tab**: Query string parameters. Can use placeholders (see below).
+- **Body tab**: JSON body for POST requests.
+- **Pagination tab**: Configure cursor or offset-based pagination parameters.
+- **Transformer tab**: Vanilla JavaScript to reshape the API's JSON response.
+
+Click **Execute** to test the endpoint before saving.
+
+### Step 4: Schema setup
+After a successful test call:
+- **Key**: The field name from the JSON response.
+- **Type**: TEXT, NUMBER, BOOLEAN, DATE, DATETIME, TIMESTAMP, OBJECT, ARRAY, EMAIL, URL.
+- **Enabled**: Toggle to show/hide the field in Softr Studio.
+- **ID Field**: Mark the unique record identifier.
+
+### Placeholders (dynamic values)
+- `{LOGGED_IN_USER: <FIELD>}` -- inject logged-in user data (e.g., `{LOGGED_IN_USER: StripeID}`)
+- `{recordId}` -- inject the currently selected record ID
+- `{filter.<FIELD>}` -- pass filter/search values from Softr block filters into the API request
+
+Placeholders can be used anywhere: headers, URL, URL params, body.
+
+### Transformer Example
+For APIs with nested responses (e.g., Luma's `entries[].event` structure):
+
+```javascript
+return data.entries.map(function(entry) { return entry.event; });
+```
+
+## Vibe Coding Integration
+
+**REST API data sources use a completely different pattern from Airtable/Softr Database.** They use `useProxyFetch` + `useQuery` instead of `useRecords` + `q.select()`.
+
+### useProxyFetch + useQuery
+
+```jsx
+import { useProxyFetch } from "@/lib/datasource";
+import { useQuery } from "@tanstack/react-query";
+
+export default function Block() {
+  var proxyFetch = useProxyFetch();
+
+  var result = useQuery({
+    queryKey: ["my-data"],
+    queryFn: function() {
+      return proxyFetch("https://api.example.com/v1/data")
+        .then(function(res) {
+          if (!res.ok) throw new Error("Failed to fetch data");
+          return res.json();
+        });
+    },
+  });
+
+  var data = result.data;
+  var status = result.status;   // "pending" | "success" | "error"
+  var error = result.error;
+
+  if (status === "pending") { /* loading UI */ }
+  if (status === "error") { /* error UI */ }
+
+  // Access the raw API response directly -- no record.fields nesting
+  var items = (data && data.entries) || [];
+}
+```
+
+### How It Works
+
+- `useProxyFetch` returns a fetch function that routes requests through Softr's proxy
+- Softr injects the authentication headers configured in the data source automatically
+- API keys are **never exposed** in client-side code
+- The response is the raw API JSON -- access fields directly (e.g., `item.name`, not `record.fields.name`)
+
+### Dynamic Query Parameters
+
+Build URLs with dynamic values. Include them in the `queryKey` so React Query refetches when they change:
+
+```jsx
+var proxyFetch = useProxyFetch();
+var afterDate = new Date().toISOString();
+
+var result = useQuery({
+  queryKey: ["events", afterDate],
+  queryFn: function() {
+    var url = "https://api.example.com/v1/events?after=" + encodeURIComponent(afterDate);
+    return proxyFetch(url)
+      .then(function(res) {
+        if (!res.ok) throw new Error("Failed to fetch");
+        return res.json();
+      });
+  },
+});
+```
+
+### POST Requests
+
+`proxyFetch` accepts the same options as standard `fetch`:
+
+```jsx
+var result = useQuery({
+  queryKey: ["search", searchTerm],
+  queryFn: function() {
+    return proxyFetch("https://api.example.com/v1/search", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ query: searchTerm }),
+    })
+      .then(function(res) {
+        if (!res.ok) throw new Error("Search failed");
+        return res.json();
+      });
+  },
+  enabled: searchTerm.length > 0,
+});
+```
+
+### Sending Webhooks (Non-Proxy)
+
+For outbound requests to services that don't need proxy auth (e.g., Softr workflow webhooks), use regular `fetch()`:
+
+```jsx
+fetch("https://workflows-api.softr.io/v1/workflows/WORKFLOW_ID/executions/EXECUTION_ID", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ data: { key: "value" } }),
+});
+```
+
+### Key Differences from useRecords
+
+| | useRecords (Airtable/Softr DB) | useProxyFetch (REST API) |
+|---|---|---|
+| Field mapping | `q.select()` with aliases | None -- raw API response |
+| Data access | `record.fields.alias` | Direct (e.g., `item.name`) |
+| Response shape | `data.pages[].items[]` | Whatever the API returns |
+| Pagination | Built-in `fetchNextPage` | Manual via URL params + cursor |
+| Filtering | `q.text()`, `q.number()`, etc. | API query params or client-side |
+| Auth | Handled by Softr | Proxied through Softr (key hidden) |
+| Mutations | `useRecordCreate/Update/Delete` | Direct `fetch()` or `proxyFetch()` |
+
+## Limitations
+
+- Supports GET and POST methods only in the data source connector (no PUT, PATCH, DELETE -- use Softr Action buttons with custom API call actions for those)
+- Response data must be parseable JSON
+- No 2-way user sync
+- Requires Business or Enterprise plan
+
+## Debug Utility
+
+Use this block to inspect the raw API response:
+
+```jsx
+import { useProxyFetch } from "@/lib/datasource";
+import { useQuery } from "@tanstack/react-query";
+export default function Block() {
+  var proxyFetch = useProxyFetch();
+  var result = useQuery({
+    queryKey: ["api-inspect"],
+    queryFn: function() {
+      return proxyFetch("YOUR_FULL_API_URL_HERE")
+        .then(function(res) { return res.json(); });
+    },
+  });
+  if (result.status === "pending") return <div className="container py-6"><div className="content"><p>Loading...</p></div></div>;
+  if (result.status === "error") return <div className="container py-6"><div className="content"><p className="text-red-500">Error: {result.error && result.error.message}</p></div></div>;
+  return (
+    <div className="container py-6">
+      <div className="content">
+        <pre style={{ fontSize: 12, whiteSpace: "pre-wrap", wordBreak: "break-all", background: "#f9fafb", padding: 16, borderRadius: 8 }}>
+          {JSON.stringify(result.data, null, 2)}
+        </pre>
+      </div>
+    </div>
+  );
+}
+```

package/datasources/shared-patterns.md

@@ -0,0 +1,9 @@
+# Shared Vibe Coding Patterns
+
+These patterns apply to all data sources that use `useRecords` + `q.select()` (everything except REST API). For REST API, see [rest-api.md](rest-api.md).
+
+| Topic | Guide |
+|---|---|
+| Query builder, useRecords, useRecord, useLinkedRecords, filtering, sorting, pagination, current user, metrics, chart data | [reading.md](reading.md) |
+| Record mutations (create/update/delete), file uploads, linked record format, cross-table REST API writes | [writing.md](writing.md) |
+| `getFieldValue()` helper, field type shapes, record structure, debug utilities (Field Inspector, User Inspector) | [fields.md](fields.md) |

package/datasources/smartsuite.md

@@ -0,0 +1,39 @@
+# SmartSuite
+
+## Overview
+SmartSuite is a work management and relational database platform. Available on Professional plans and above.
+
+## Connection Setup
+1. In the Softr admin, go to your data source settings and select SmartSuite.
+2. Authenticate via OAuth -- you will be redirected to SmartSuite to authorize access.
+3. Choose your Workspace, then select a Solution, then select a Table to connect.
+
+## Vibe Coding Field IDs
+Use the Field Inspector block to determine exact field IDs for this data source.
+
+## Supported Fields
+
+| Field Type     | Writable | Notes |
+|----------------|----------|-------|
+| Text           | Yes      | |
+| Number         | Yes      | |
+| Date           | Yes      | |
+| Dropdown       | Yes      | |
+| Checkbox       | Yes      | |
+| Linked Record  | Yes      | Linked records between SmartSuite tables are supported |
+| Formula        | Read-only | |
+| Rollup         | Read-only | |
+| Lookup         | Read-only | |
+
+## Rate Limits
+Subject to SmartSuite API rate limits. Implement pagination and caching where possible to reduce request volume.
+
+## Gotchas
+- **Linked records** work across SmartSuite tables but require that both tables are within the same Solution.
+- **Formula, Rollup, and Lookup fields** are read-only. Attempting to write to them will fail silently or error.
+- **OAuth tokens** may expire. If data stops loading, re-authenticate via the Softr admin.
+
+## Best For
+- Teams already using SmartSuite as their primary work OS
+- Apps that need relational data across multiple SmartSuite tables
+- Organizations consolidating project management and app building on SmartSuite

package/datasources/softr-database.md

@@ -0,0 +1,47 @@
+# Softr Database
+
+## Overview
+Softr's native built-in database. No external account or integration required. Available on all plans with support for 1M+ records.
+
+## Connection Setup
+No setup needed. Softr Database is available by default in every Softr app. Create tables directly from the Softr admin dashboard under the "Data" section. Import data via CSV, one-click migration from Airtable, or AI-assisted table generation.
+
+## Vibe Coding Field IDs
+Field IDs are short alphanumeric codes (e.g., `"xgETy"`, `"TLhWF"`). These codes are NOT human-readable names.
+
+```jsx
+// CORRECT - use the alphanumeric field ID
+q.select({ name: "xgETy" })
+
+// WRONG - human-readable names do not work
+q.select({ name: "First Name" })
+```
+
+Find field IDs by clicking a field's name in the Data tab (the ID is shown in the field-edit drawer), or via the network inspector technique (DevTools -> Network -> filter `tablespace-with-tables` for the full schema including dropdown option UUIDs). The network inspector method is recommended when working with an AI assistant -- pasting that JSON into the chat eliminates transcription errors. See [fields.md](fields.md#field-inspector-block) for both approaches plus a runtime REST API method. The generic Field Inspector pattern with empty `q.select({})` does NOT work for Softr Database.
+
+## Supported Fields
+
+| Field Type     | Writable | Notes |
+|----------------|----------|-------|
+| Text           | Yes      | |
+| Number         | Yes      | |
+| Date           | Yes      | |
+| File / Image   | Yes      | |
+| Checkbox       | Yes      | |
+| Dropdown       | Yes      | |
+| Relationship   | Yes      | Linked records to other Softr Database tables |
+| Formula        | Read-only | Booleans return as strings: use `=== "1"` for true, `=== "0"` for false |
+
+## Rate Limits
+No API rate limits. Softr Database queries run internally without external API calls, making it the best choice for high-traffic applications.
+
+## Gotchas
+- **Formula boolean values are strings.** A formula that evaluates to true returns `"1"`, not `true`. Always compare with `=== "1"` or `=== "0"`.
+- **Field IDs are opaque codes.** You cannot guess them from column names. Use the Field Inspector block to find them.
+- **Relationships** work similarly to linked records in Airtable but use Softr's internal record IDs.
+
+## Best For
+- New projects starting from scratch
+- High-traffic applications (no rate limit concerns)
+- Teams that do not already have data in an external platform
+- Apps requiring the simplest possible setup

package/datasources/sql-database.md

@@ -0,0 +1,48 @@
+# SQL Database
+
+## Overview
+Direct connection to an external SQL database (PostgreSQL, MySQL, SQL Server, or MariaDB). Available on Business and Enterprise plans only.
+
+## Connection Setup
+1. Ensure your database server is accessible from the internet (or via a static IP).
+2. **Whitelist Softr IP addresses** in your database firewall:
+   - `3.120.79.212`
+   - `3.123.159.186`
+   - `52.58.246.121`
+3. In the Softr admin, go to your data source settings and select SQL Database.
+4. Enter the connection credentials:
+   - Host
+   - Port (defaults: PostgreSQL `5432`, MySQL/MariaDB `3306`, SQL Server `1433`)
+   - Database Name
+   - User
+   - Password
+5. Select the database type (PostgreSQL, MySQL, SQL Server, or MariaDB).
+
+## Vibe Coding Field IDs
+Use the Field Inspector block to determine exact field IDs for this data source.
+
+## Supported Fields
+Field support depends on the underlying database engine. Standard column types for each engine are writable. Generated columns, computed columns, and views are read-only.
+
+| Engine        | Common Writable Types |
+|---------------|----------------------|
+| PostgreSQL    | text, integer, boolean, timestamp, jsonb, uuid, numeric, varchar |
+| MySQL/MariaDB | varchar, int, tinyint, datetime, text, decimal, json, enum |
+| SQL Server    | nvarchar, int, bit, datetime2, decimal, uniqueidentifier |
+
+## Rate Limits
+No Softr-imposed rate limits. Performance depends on your database server's capacity and connection limits. Unlimited records and unlimited concurrent users from Softr's side.
+
+## Gotchas
+- **IP whitelisting is required.** Connections will be refused if the three Softr IPs are not allowed through your firewall.
+- **Custom SQL SELECT queries are supported.** Use the built-in query editor in the Softr admin for advanced retrieval, joins across tables, and filtered views.
+- **Database-level access control applies.** The database user you provide determines what tables and operations are available. Use a scoped user with minimal required permissions.
+- **Default ports matter.** If your database runs on a non-standard port, specify it explicitly in the connection settings.
+- **Connection pooling is managed by Softr.** You do not need to configure a connection pool, but ensure your database allows enough concurrent connections for your expected traffic.
+- **No ORM or migration support.** Softr connects to your existing schema. Table creation and schema changes must be done directly in your database.
+
+## Best For
+- Companies with existing SQL databases that want a no-code frontend
+- Enterprise apps requiring high security with database-level access control
+- Projects needing complex queries with joins across multiple tables
+- Teams that manage their own infrastructure and want full control over the data layer

package/datasources/supabase.md

@@ -0,0 +1,38 @@
+# Supabase
+
+## Overview
+Supabase is an open-source Firebase alternative built on PostgreSQL. Available on Professional plans and above.
+
+## Connection Setup
+1. In your Supabase project, go to **Project Settings > Database**.
+2. Copy the **Session Pooler** connection credentials:
+   - Host
+   - Database name
+   - Port: `5432`
+   - User
+   - Password
+3. **Set the Pool Size to 45 or higher** in Supabase Project Settings > Database. This is required for stable Softr connections.
+4. In the Softr admin, go to your data source settings and select Supabase.
+5. Enter the Session Pooler credentials.
+
+## Vibe Coding Field IDs
+Use the Field Inspector block to determine exact field IDs for this data source.
+
+## Supported Fields
+Field support follows PostgreSQL column types. Standard column types (text, integer, boolean, timestamp, jsonb, uuid, etc.) are writable. Generated/computed columns are read-only.
+
+## Rate Limits
+No Softr-imposed rate limits. Supabase handles concurrency at the database and connection-pool level. Unlimited records and unlimited concurrent users.
+
+## Gotchas
+- **Pool Size must be 45+.** If the Supabase connection pool is too small, Softr connections will be dropped under load. Set this in Supabase Project Settings > Database before connecting.
+- **Use Session Pooler credentials**, not the direct connection string. The Session Pooler is required for connection stability with Softr.
+- **Row Level Security (RLS) applies at the database level.** Supabase RLS policies are enforced on all queries Softr makes. If records are missing, check your RLS policies.
+- **Layer Softr visibility rules on top of RLS.** Softr's user-group visibility settings work independently of Supabase RLS. Use both for defense-in-depth access control.
+- **Port is always 5432.** Do not use the Supabase API port (typically 443) -- Softr connects via PostgreSQL protocol.
+
+## Best For
+- Developer teams comfortable with PostgreSQL
+- Applications with real-time data requirements
+- Projects needing fine-grained Row Level Security
+- Teams wanting an open-source backend with strong community support