Skip to content

Commit 448aa79

Browse files
andinuxandinux
committed
New postgresql extension WIP 1
1 parent 1e89d29 commit 448aa79

22 files changed

+5840
-12
lines changed

‎AGENTS.md‎

Lines changed: 555 additions & 0 deletions
Large diffs are not rendered by default.

‎CLAUDE.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## General Technical Documentation
6+
7+
For comprehensive technical information about the SQLite Sync architecture, build system, CRDT implementation, and design patterns, see [AGENTS.md](./AGENTS.md).
8+
9+
This file contains:
10+
- Project overview and architecture
11+
- Build commands and testing
12+
- Core components and patterns
13+
- Performance considerations
14+
- Design principles and constraints
15+
16+
## Development Workflow
17+
18+
### Adding New SQL Functions
19+
20+
1. Implement in `src/sqlite/cloudsync_sqlite.c` (e.g., `cloudsync_xyz_func`)
21+
2. Register in `cloudsync_register()` via `sqlite3_create_function()`
22+
3. Document in `API.md`
23+
4. Add tests in `test/unit.c`
24+
25+
### Modifying CRDT Logic
26+
27+
The merge algorithm lives in `cloudsync.c`:
28+
- `merge_insert()` - Handles row-level merge decisions
29+
- `merge_insert_col()` - Handles column-level merge decisions
30+
- Algorithm-specific logic controlled by `table->algo` enum
31+
32+
**Performance requirement**: Merge code is hot-path (processes every incoming change during sync). Always use prepared statements stored in `cloudsync_table_context`. Never compile SQL at runtime in merge functions. See [AGENTS.md - Performance Considerations](./AGENTS.md#performance-considerations) for details.
33+
34+
### Schema Migrations
35+
36+
The extension tracks its schema version in `cloudsync_settings.schemaversion`. When the schema changes:
37+
1. Increment version in migration code
38+
2. Add migration logic in `dbutils_settings_init()`
39+
3. Handle both fresh installs and upgrades
40+
41+
### Platform-Specific Code
42+
43+
- Most code is platform-agnostic C
44+
- Platform detection via `CLOUDSYNC_DESKTOP_OS` macro (macOS, Linux desktop, Windows)
45+
- Network layer can use native APIs (macOS NSURLSession) with `NATIVE_NETWORK` flag
46+
- File I/O helpers (`cloudsync_file_*`) only available on desktop platforms
47+
48+
## Specialized Subagents
49+
50+
When working on specific areas of the codebase, you can launch specialized subagents with domain expertise.
51+
52+
### PostgreSQL Extension Agent
53+
54+
**Purpose**: Implement the PostgreSQL version of SQLite Sync extension
55+
56+
**Context**: The codebase has a database abstraction layer (`database.h`) with database-specific implementations in subdirectories. PostgreSQL-specific code lives in `src/postgresql/`. The goal is to create a fully functional PostgreSQL extension that implements the same CRDT sync logic.
57+
58+
**Launch command**:
59+
```
60+
Use the Task tool with prompt: "Implement the PostgreSQL backend for SQLite Sync. Study the database.h abstraction layer and src/sqlite/database_sqlite.c implementation, then implement src/postgresql/database_postgresql.c with full PostgreSQL support including prepared statements, value binding, and transaction hooks."
61+
```
62+
63+
**Key files to study**:
64+
- `src/database.h` - Abstract database API
65+
- `src/sqlite/database_sqlite.c` - SQLite implementation (reference)
66+
- `src/postgresql/database_postgresql.c` - PostgreSQL implementation
67+
- `src/cloudsync.c` - Uses database abstraction (must work unchanged)
68+
69+
**Requirements**:
70+
- Implement all functions in `database.h` using libpq (PostgreSQL C API)
71+
- Maintain same semantics as SQLite version
72+
- Handle PostgreSQL-specific data types mapping
73+
- Test with PostgreSQL backend
74+
75+
**Testing approach**:
76+
- Modify Makefile to link against libpq
77+
- Create PostgreSQL-specific test suite
78+
- Verify CRDT operations work identically to SQLite
79+
80+
### Other Potential Subagents
81+
82+
Consider creating specialized agents for:
83+
- **WASM/Browser Agent**: Optimize for WebAssembly builds and OPFS storage
84+
- **Network Protocol Agent**: Enhance sync protocol or add new backends
85+
- **CRDT Algorithm Agent**: Implement new conflict resolution algorithms
86+
- **Performance Optimization Agent**: Profile and optimize hot-path code
87+
88+
## Slash Commands
89+
90+
Custom slash commands help automate common development tasks in this repository.
91+
92+
### Available Commands
93+
94+
Create slash commands in `.claude/commands/` directory. Each command is a markdown file executed when invoked.
95+
96+
### Example: `/review-sync` - Review Sync Logic
97+
98+
**File**: `.claude/commands/review-sync.md`
99+
100+
```markdown
101+
Please review the CRDT synchronization logic for correctness and performance:
102+
103+
1. Read and analyze the merge algorithm in `src/cloudsync.c`:
104+
- `merge_insert()` function
105+
- `merge_insert_col()` function
106+
- Vector clock comparison logic
107+
108+
2. Check for potential issues:
109+
- Race conditions in concurrent merges
110+
- Memory leaks in error paths
111+
- Inefficient SQL queries (should use prepared statements)
112+
- Incorrect handling of tombstones
113+
114+
3. Verify compliance with design principles from AGENTS.md:
115+
- Hot-path code uses prepared statements
116+
- No runtime SQL compilation in merge functions
117+
- Proper error handling
118+
119+
4. Suggest improvements with specific code examples
120+
121+
Please provide a summary of findings and recommendations.
122+
```
123+
124+
**Usage**: Type `/review-sync` in Claude Code to trigger this review workflow.
125+
126+
### Example: `/test-crdt` - Test CRDT Algorithm
127+
128+
**File**: `.claude/commands/test-crdt.md`
129+
130+
```markdown
131+
Create a comprehensive test scenario for CRDT conflict resolution:
132+
133+
1. Design a multi-device sync test with:
134+
- 3 devices making concurrent changes
135+
- Updates to same row, different columns
136+
- Updates to same column (conflict)
137+
- Deletions with concurrent updates
138+
139+
2. Generate test code in `test/unit.c` format
140+
141+
3. Show expected outcomes based on:
142+
- Vector clock values (db_version, seq, site_id)
143+
- CRDT algorithm (CLS/GOS/DWS/AWS)
144+
- Deterministic conflict resolution
145+
146+
4. Run the test and verify results
147+
148+
Focus on edge cases that could expose bugs in the merge algorithm.
149+
```
150+
151+
### Creating New Slash Commands
152+
153+
To add a new command:
154+
155+
1. Create `.claude/commands/<command-name>.md`
156+
2. Write the prompt describing the task
157+
3. Use `/command-name` to invoke it
158+
159+
**Useful commands to create**:
160+
- `/add-function` - Scaffold a new SQL function with tests
161+
- `/optimize-query` - Analyze and optimize a SQL query
162+
- `/check-leaks` - Review code for memory leaks
163+
- `/cross-compile` - Build for all platforms and report issues
164+
- `/benchmark-merge` - Profile merge performance
165+
166+
## Branch Information
167+
168+
Main branch: `main`
169+
Current working branch: `database-api` - Database abstraction layer refactoring
170+
171+
**macOS Testing Note:** If the default `/usr/bin/sqlite3` doesn't support loading extensions, set the SQLITE3 variable when running tests (Adjust the version path if using a specific version like /opt/homebrew/Cellar/sqlite/3.50.4/bin/sqlite3:
172+
```
173+
make test SQLITE3=/opt/homebrew/bin/sqlite3
174+
make unittest SQLITE3=/opt/homebrew/bin/sqlite3
175+
```

‎CODEX.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# CODEX.md
2+
3+
Guidance for Codex agents working in this repository.
4+
5+
## Reference
6+
7+
- For full architecture/build/performance details, read `AGENTS.md`.
8+
- Comments and documentation must be written in English unless explicitly instructed otherwise (even if prompts use another language).
9+
- Table names to augment are limited to 512 characters; size SQL buffers accordingly.
10+
- Prefer static buffers with `sqlite3_snprintf` for SQL construction when practical (e.g., fixed pattern + table name in a 1024-byte buffer) instead of dynamic `sqlite3_mprintf`.
11+
- Parameterless SQL should live as global constants in `database_<engine>.c` and be imported via `extern`; parameterized SQL belongs in database-layer functions so each backend can build it correctly.
12+
13+
## Workflow Expectations
14+
15+
- Use `rg`/`rg --files` for search; avoid slow scans.
16+
- Default to ASCII; only introduce non-ASCII if already used and necessary.
17+
- Keep changes tight; add comments only when code is non-obvious.
18+
- Do not revert unrelated user changes or use destructive git commands.
19+
- Prefer `apply_patch` for single-file edits; avoid for generated outputs.
20+
21+
## Build & Test
22+
23+
- Build: `make` (outputs `dist/cloudsync.*`).
24+
- Test: `make test` (builds extension + unit tests). No network expected.
25+
26+
## Hot-Path Notes
27+
28+
- Hot-path code (triggers, merge, commit hooks) must use prepared statements stored on the table context; never compile SQL at runtime in these paths. See `cloudsync.c` and `dbutils.c`.
29+
30+
## SQL Function/File Pointers
31+
32+
- New SQLite functions: implement in `src/sqlite/cloudsync_sqlite.c`, register in `cloudsync_register()`, document in `API.md`, test in `test/unit.c`.
33+
- CRDT merge logic: `src/cloudsync.c` (`merge_insert`, `merge_insert_col`).
34+
- Database abstractions: `src/database.h`, with implementations in `src/sqlite/database_sqlite.c` (SQLite) and `src/postgresql/database_postgresql.c` (PostgreSQL).
35+
36+
## Ask/Escalate When
37+
38+
- Network or privileged commands are needed, or a command fails due to sandbox.
39+
- The workspace is dirty in unexpected ways or destructive actions are requested.

‎Makefile‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -437,5 +437,11 @@ help:
437437
@echo " help - Display this help message"
438438
@echo " xcframework - Build the Apple XCFramework"
439439
@echo " aar - Build the Android AAR package"
440+
@echo ""
441+
@echo "PostgreSQL Targets:"
442+
@echo " make postgres-help - Show PostgreSQL-specific targets"
443+
444+
# Include PostgreSQL extension targets
445+
include docker/Makefile.postgresql
440446

441447
.PHONY: all clean test unittest extension help version xcframework aar

0 commit comments

Comments
 (0)