electric-schema-shapes
Design Postgres schema and Electric shape definitions together for a new feature. Covers single-table shape constraint, cross-table joins using multiple shapes, WHERE clause design for tenant isolation, column selection for bandwidth optimization, replica mode choice (default vs full for old_value), enum casting in WHERE clauses, and txid handshake setup with pg_current_xact_id() for optimistic writes. Load when designing database tables for use with Electric shapes.
소스 정보
- 저장소
- electric-sql/electric
- 최근 소스 활동
- 2026년 3월 6일 21:27
- 감지된 SKILL.md 언어
- 영어
- 스타
- 10,384
- 포크
- 392
설치 방법
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
소스 파일 검토
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
SKILL.md 표시 중
SKILL.md
소스 지침 · 읽기 전용 미리보기- name
- electric-schema-shapes
- description
- Design Postgres schema and Electric shape definitions together for a new feature. Covers single-table shape constraint, cross-table joins using multiple shapes, WHERE clause design for tenant isolation, column selection for bandwidth optimization, replica mode choice (default vs full for old_value), enum casting in WHERE clauses, and txid handshake setup with pg_current_xact_id() for optimistic writes. Load when designing database tables for use with Electric shapes.
- type
- core
- library
- electric
- library_version
- 1.5.10
- requires
- ["electric-shapes"]
- sources
- ["electric-sql/electric:AGENTS.md","electric-sql/electric:website/docs/guides/shapes.md"]
This skill builds on electric-shapes. Read it first for ShapeStream configuration.
# Electric — Schema and Shapes
## Setup
Design tables knowing each shape syncs one table. For cross-table data, use multiple shapes with client-side joins.
```sql
-- Schema designed for Electric shapes
CREATE TABLE todos (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
org_id UUID NOT NULL,
text TEXT NOT NULL,
completed BOOLEAN DEFAULT false,
created_at TIMESTAMPTZ DEFAULT now()
);
ALTER TABLE todos REPLICA IDENTITY FULL;
```
```ts
import { ShapeStream } from '@electric-sql/client'
const todoStream = new ShapeStream({
url: '/api/todos', // Proxy sets: table=todos, where=org_id=$1
})
```
## Core Patterns
### Cross-table data with multiple shapes
```ts
// Each shape syncs one table — join client-side
const todoStream = new ShapeStream({ url: '/api/todos' })
const userStream = new ShapeStream({ url: '/api/users' })
// With TanStack DB, use .join() in live queries:
// q.from({ todo: todoCollection })
// .join({ user: userCollection }, ({ todo, user }) => eq(todo.userId, user.id))
```
### Choose replica mode
```ts
// Default: only changed columns sent on update
const stream = new ShapeStream({ url: '/api/todos' })
// Full: all columns + old_value on updates (more bandwidth, needed for diffs)
const stream = new ShapeStream({
url: '/api/todos',
params: { replica: 'full' },
})
```
### Backend txid handshake for optimistic writes
Call `pg_current_xact_id()::xid::text` inside the same transaction as your mutation. If you query it outside the transaction, you get a different txid and the client will never reconcile.
```ts
// API endpoint — txid MUST be in the same transaction as the INSERT
app.post('/api/todos', async (req, res) => {
const client = await pool.connect()
try {
await client.query('BEGIN')
const result = await client.query(
'INSERT INTO todos (id, text, org_id) VALUES ($1, $2, $3) RETURNING id',
[crypto.randomUUID(), req.body.text, req.body.orgId]
)
const txResult = await client.query(
'SELECT pg_current_xact_id()::xid::text AS txid'
)
await client.query('COMMIT')
// txid accepts number | bigint | `${bigint}`
res.json({ id: result.rows[0].id, txid: parseInt(txResult.rows[0].txid) })
} finally {
client.release()
}
})
```
```ts
// Client awaits txid before dropping optimistic state
await todoCollection.utils.awaitTxId(txid)
```
## Common Mistakes
### HIGH Designing shapes that span multiple tables
Wrong:
```ts
const stream = new ShapeStream({
url: '/api/data',
params: {
table: 'todos JOIN users ON todos.user_id = users.id',
},
})
```
Correct:
```ts
const todoStream = new ShapeStream({ url: '/api/todos' })
const userStream = new ShapeStream({ url: '/api/users' })
```
Shapes are single-table only. Cross-table data requires multiple shapes joined client-side via TanStack DB live queries.
Source: `AGENTS.md:104-105`
### MEDIUM Using enum columns without casting to text in WHERE
Wrong:
```ts
// Proxy route
originUrl.searchParams.set('where', "status IN ('active', 'done')")
```
Correct:
```ts
originUrl.searchParams.set('where', "status::text IN ('active', 'done')")
```
Enum types in WHERE clauses require explicit `::text` cast. Without it, the query may fail or return unexpected results.
Source: `packages/sync-service/lib/electric/replication/eval/env/known_functions.ex`
### HIGH Not setting up txid handshake for optimistic writes
Wrong:
```ts
// Backend: just INSERT, return id
app.post('/api/todos', async (req, res) => {
const result = await db.query(
'INSERT INTO todos (text) VALUES ($1) RETURNING id',
[req.body.text]
)
res.json({ id: result.rows[0].id })
})
```
Correct:
```ts
// Backend: INSERT and return txid in same transaction
app.post('/api/todos', async (req, res) => {
const client = await pool.connect()
try {
await client.query('BEGIN')
const result = await client.query(
'INSERT INTO todos (text) VALUES ($1) RETURNING id',
[req.body.text]
)
const txResult = await client.query(
'SELECT pg_current_xact_id()::xid::text AS txid'
)
await client.query('COMMIT')
res.json({ id: result.rows[0].id, txid: parseInt(txResult.rows[0].txid) })
} finally {
client.release()
}
})
```
Without txid, the UI flickers when optimistic state is dropped before the synced version arrives from Electric. The client uses `awaitTxId(txid)` to hold optimistic state until the real data syncs.
Source: `AGENTS.md:116-119`
See also: electric-shapes/SKILL.md — Shapes are immutable; dynamic filters require new ShapeStream instances.
See also: electric-orm/SKILL.md — Schema design affects both shapes (read) and ORM queries (write).
## Version
Targets @electric-sql/client v1.5.10.
GitHub에서 보기