Restructure README following SQLite extension best practices#6
Conversation
Co-authored-by: gabewillen <91307534+gabewillen@users.noreply.github.com>
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
| # Use Cypher to create nodes and relationships | ||
| conn.execute("SELECT cypher_execute('CREATE (p:Person {name: \"Alice\", age: 30})')") | ||
| conn.execute("SELECT cypher_execute('CREATE (p:Person {name: \"Bob\", age: 25})')") | ||
| conn.execute("SELECT cypher_execute(\"CREATE (a:Person {name: \\\"Alice\\\"})-[:KNOWS]->(b:Person {name: \\\"Bob\\\"})\")") |
There was a problem hiding this comment.
Bug: Cypher CREATE: Unintended Node Duplication
The code creates Alice and Bob as Person nodes (lines 80-81), then uses CREATE (a:Person {...})-[:KNOWS]->(b:Person {...}) which creates new duplicate nodes instead of linking the existing ones. In Cypher, CREATE with a pattern creates new nodes. To link existing nodes, use MATCH (a:Person {name: "Alice"}), (b:Person {name: "Bob"}) CREATE (a)-[:KNOWS]->(b) or create nodes and relationships in a single CREATE statement from the start.
| # Create relationships with properties | ||
| conn.execute("SELECT cypher_execute('CREATE (a:Person {name: \"Bob\"})-[:KNOWS {since: 2020}]->(b:Person {name: \"Charlie\"})')") | ||
| conn.execute("SELECT cypher_execute('CREATE (p:Person {name: \"Bob\", age: 25})')") | ||
| conn.execute("SELECT cypher_execute(\"CREATE (a:Person {name: \\\"Alice\\\"})-[:KNOWS {since: 2020}]->(b:Person {name: \\\"Bob\\\"})\")") |
There was a problem hiding this comment.
Bug: Cypher Creates Duplicate Nodes, Not Links
The code creates Alice and Bob as Person nodes (lines 199-200), then uses CREATE (a:Person {...})-[:KNOWS {...}]->(b:Person {...}) which creates new duplicate nodes instead of linking the existing ones. In Cypher, CREATE with a pattern creates new nodes. To link existing nodes, use MATCH (a:Person {name: "Alice"}), (b:Person {name: "Bob"}) CREATE (a)-[:KNOWS {...}]->(b) or create nodes and relationships in a single CREATE statement from the start.
There was a problem hiding this comment.
Pull Request Overview
This PR restructures the README to follow SQLite extension best practices, improving discoverability and reducing friction for new users. The changes transform a feature-heavy document into a usage-first guide modeled after successful SQLite extensions like sqlite-vec and sqlean.
Key changes:
- Added 13-section table of contents for direct navigation
- Reordered content to prioritize Quick Start before deep technical details
- Added Platform Support and Troubleshooting sections for common user pain points
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # Use Cypher to create nodes and relationships | ||
| conn.execute("SELECT cypher_execute('CREATE (p:Person {name: \"Alice\", age: 30})')") | ||
| conn.execute("SELECT cypher_execute('CREATE (p:Person {name: \"Bob\", age: 25})')") | ||
| conn.execute("SELECT cypher_execute(\"CREATE (a:Person {name: \\\"Alice\\\"})-[:KNOWS]->(b:Person {name: \\\"Bob\\\"})\")") |
There was a problem hiding this comment.
Trailing whitespace at the end of the line. Remove the space after the closing parenthesis to maintain clean formatting.
| conn.execute("SELECT cypher_execute(\"CREATE (a:Person {name: \\\"Alice\\\"})-[:KNOWS]->(b:Person {name: \\\"Bob\\\"})\")") | |
| conn.execute("SELECT cypher_execute(\"CREATE (a:Person {name: \\\"Alice\\\"})-[:KNOWS]->(b:Person {name: \\\"Bob\\\"})\")") |
| # Create relationships with properties | ||
| conn.execute("SELECT cypher_execute('CREATE (a:Person {name: \"Bob\"})-[:KNOWS {since: 2020}]->(b:Person {name: \"Charlie\"})')") | ||
| conn.execute("SELECT cypher_execute('CREATE (p:Person {name: \"Bob\", age: 25})')") | ||
| conn.execute("SELECT cypher_execute(\"CREATE (a:Person {name: \\\"Alice\\\"})-[:KNOWS {since: 2020}]->(b:Person {name: \\\"Bob\\\"})\")") |
There was a problem hiding this comment.
Trailing whitespace at the end of the line. Remove the space after the closing parenthesis to maintain clean formatting.
| conn.execute("SELECT cypher_execute(\"CREATE (a:Person {name: \\\"Alice\\\"})-[:KNOWS {since: 2020}]->(b:Person {name: \\\"Bob\\\"})\")") | |
| conn.execute("SELECT cypher_execute(\"CREATE (a:Person {name: \\\"Alice\\\"})-[:KNOWS {since: 2020}]->(b:Person {name: \\\"Bob\\\"})\")") |
|
|
||
| **Supported Cypher:** | ||
| - `CREATE` - Create nodes and relationships with labels/properties | ||
| - `MATCH` - Pattern matching with labels and relationships |
There was a problem hiding this comment.
Trailing whitespace at the end of the line. Remove the extra spaces after 'relationships' to maintain clean formatting.
| - `MATCH` - Pattern matching with labels and relationships | |
| - `MATCH` - Pattern matching with labels and relationships |
| -- Query nodes by label | ||
| SELECT * FROM graph_nodes WHERE labels LIKE '%Person%'; | ||
|
|
||
| -- Query edges by type |
There was a problem hiding this comment.
Trailing whitespace at the end of the line. Remove the extra spaces after 'type' in the comment to maintain clean formatting.
| -- Query edges by type | |
| -- Query edges by type |
| # Use Cypher to create nodes and relationships | ||
| conn.execute("SELECT cypher_execute('CREATE (p:Person {name: \"Alice\", age: 30})')") | ||
| conn.execute("SELECT cypher_execute('CREATE (p:Person {name: \"Bob\", age: 25})')") | ||
| conn.execute("SELECT cypher_execute(\"CREATE (a:Person {name: \\\"Alice\\\"})-[:KNOWS]->(b:Person {name: \\\"Bob\\\"})\")") |
There was a problem hiding this comment.
[nitpick] The quote escaping pattern is inconsistent across code examples. Lines 80-81 use single-quoted strings with escaped double quotes inside, while line 82 uses a double-quoted string with escaped inner quotes. Consider using a consistent pattern throughout all examples for better readability.
| conn.execute("SELECT cypher_execute(\"CREATE (a:Person {name: \\\"Alice\\\"})-[:KNOWS]->(b:Person {name: \\\"Bob\\\"})\")") | |
| conn.execute("SELECT cypher_execute('CREATE (a:Person {name: \"Alice\"})-[:KNOWS]->(b:Person {name: \"Bob\"})')") |
* Initial plan * Restructure and optimize README based on SQLite extension best practices Co-authored-by: gabewillen <91307534+gabewillen@users.noreply.github.com> * Update README.md --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: gabewillen <91307534+gabewillen@users.noreply.github.com> Co-authored-by: Jeffrey Jewett <jeffrey.jewett@gmail.com>
Description
Reorganized README to follow SQLite extension conventions, improving discoverability and reducing time-to-first-run for new users.
Related Issues
Closes #
Type of Change
Changes Made
Structure
New Sections
Enhanced Sections
Best Practices Applied
Testing
make test)Test Evidence
Documentation
Checklist
Breaking Changes
N/A
Performance Impact
Screenshots / Examples
Before: 290 lines, 7 sections, no TOC, duplicate content
After: 497 lines, 13 sections, comprehensive TOC, modeled after sqlite-vec/sqlean
Additional Context
Researched SQLite extension READMEs (sqlite-vec, sqlean, rqlite) to identify common patterns:
Reviewer Notes
Focus on:
For Maintainers:
Original prompt
💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.
Note
Rewrite of README to a usage‑first layout with TOC, quick start, focused examples, API/compatibility tables, troubleshooting, and clearer installation/feature status.
What → Quick Start → Features → Installation → Usage Examples → API → Performance → Platform Support → Troubleshooting.make.Cypher,SQL Functions,Social Network Analysis).cypher_execute, SQL function APIs, and virtual table schema with direct SQL query samples.FEATURES.mdandROADMAP.md.CONTRIBUTING.md, examples directory, and other docs.Written by Cursor Bugbot for commit 31ae082. This will update automatically on new commits. Configure here.