Skip to content

Commit 7357010

Browse files
rathbomarathboma
committed
readme for each project
1 parent 642da7b commit 7357010

File tree

4 files changed

+428
-0
lines changed

4 files changed

+428
-0
lines changed

‎packages/cli/README.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
<p align="center">
2+
<img src="https://raw.githubusercontent.com/beekeeper-studio/queryleaf/main/logo-transparent-bg-green-shape.png" width="100" height="100" alt="QueryLeaf Logo">
3+
</p>
4+
5+
<h1 align="center">@queryleaf/cli</h1>
6+
7+
<p align="center">SQL to MongoDB query translator - Command Line Interface</p>
8+
9+
## Overview
10+
11+
`@queryleaf/cli` provides a command-line interface for QueryLeaf, allowing you to execute SQL queries against MongoDB directly from your terminal. It leverages the core `@queryleaf/lib` package to parse SQL, transform it into MongoDB commands, and execute those commands.
12+
13+
## Installation
14+
15+
```bash
16+
# Global installation
17+
npm install -g @queryleaf/cli
18+
# or
19+
yarn global add @queryleaf/cli
20+
21+
# Local installation
22+
npm install @queryleaf/cli
23+
# or
24+
yarn add @queryleaf/cli
25+
```
26+
27+
## Usage
28+
29+
```bash
30+
# Basic usage
31+
queryleaf --uri mongodb://localhost:27017 --db mydb "SELECT * FROM users"
32+
33+
# With authentication
34+
queryleaf --uri mongodb://user:pass@localhost:27017 --db mydb "SELECT * FROM users"
35+
36+
# Output formatting
37+
queryleaf --uri mongodb://localhost:27017 --db mydb --format table "SELECT * FROM users"
38+
39+
# Help
40+
queryleaf --help
41+
```
42+
43+
## Example Queries
44+
45+
```bash
46+
# Basic SELECT with WHERE
47+
queryleaf "SELECT name, email FROM users WHERE age > 21"
48+
49+
# Nested field access
50+
queryleaf "SELECT name, address.city FROM users WHERE address.zip = '10001'"
51+
52+
# Array access
53+
queryleaf "SELECT items[0].name FROM orders WHERE items[0].price > 100"
54+
55+
# GROUP BY with aggregation
56+
queryleaf "SELECT status, COUNT(*) as count FROM orders GROUP BY status"
57+
58+
# JOIN between collections
59+
queryleaf "SELECT u.name, o.total FROM users u JOIN orders o ON u._id = o.userId"
60+
```
61+
62+
## Configuration
63+
64+
You can configure the CLI using command-line arguments or environment variables:
65+
66+
| Argument | Environment Variable | Description |
67+
|----------------|----------------------|----------------------------------|
68+
| `--uri` | `MONGODB_URI` | MongoDB connection URI |
69+
| `--db` | `MONGODB_DB` | MongoDB database name |
70+
| `--format` | `QUERYLEAF_FORMAT` | Output format (json, table, csv) |
71+
| `--debug` | `QUERYLEAF_DEBUG` | Enable debug output |
72+
73+
## Links
74+
75+
- [Website](https://queryleaf.com)
76+
- [Documentation](https://queryleaf.com/docs)
77+
- [GitHub Repository](https://github.com/beekeeper-studio/queryleaf)
78+
79+
## License
80+
81+
QueryLeaf is dual-licensed:
82+
83+
- [AGPL-3.0](https://github.com/beekeeper-studio/queryleaf/blob/main/LICENSE.md) for open source use
84+
- [Commercial license](https://github.com/beekeeper-studio/queryleaf/blob/main/COMMERCIAL_LICENSE.md) for commercial use
85+
86+
For commercial licensing options, visit [queryleaf.com](https://queryleaf.com).

‎packages/lib/README.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
<p align="center">
2+
<img src="https://raw.githubusercontent.com/beekeeper-studio/queryleaf/main/logo-transparent-bg-green-shape.png" width="100" height="100" alt="QueryLeaf Logo">
3+
</p>
4+
5+
<h1 align="center">@queryleaf/lib</h1>
6+
7+
<p align="center">SQL to MongoDB query translator - Core library</p>
8+
9+
## Overview
10+
11+
`@queryleaf/lib` is the core library for QueryLeaf, a tool that translates SQL queries into MongoDB commands. It provides the foundation for all QueryLeaf packages by parsing SQL using node-sql-parser, transforming it into an abstract command set, and executing those commands against the MongoDB Node.js driver.
12+
13+
## Features
14+
15+
- Parse SQL statements into an abstract syntax tree
16+
- Compile SQL AST into MongoDB commands
17+
- Execute MongoDB commands using the official driver
18+
- Support for basic SQL operations (SELECT, INSERT, UPDATE, DELETE)
19+
- Advanced querying features:
20+
- Nested field access (e.g., `address.zip`)
21+
- Array element access (e.g., `items[0].name`)
22+
- GROUP BY with aggregation functions (COUNT, SUM, AVG, MIN, MAX)
23+
- JOINs between collections
24+
25+
## Installation
26+
27+
```bash
28+
npm install @queryleaf/lib
29+
# or
30+
yarn add @queryleaf/lib
31+
```
32+
33+
## Usage
34+
35+
```typescript
36+
import { QueryLeaf } from '@queryleaf/lib';
37+
import { MongoClient } from 'mongodb';
38+
39+
// Your existing MongoDB client
40+
const mongoClient = new MongoClient('mongodb://localhost:27017');
41+
await mongoClient.connect();
42+
43+
// Create QueryLeaf with your MongoDB client
44+
const queryLeaf = new QueryLeaf(mongoClient, 'mydatabase');
45+
46+
// Execute SQL queries against your MongoDB database
47+
const results = await queryLeaf.execute('SELECT * FROM users WHERE age > 21');
48+
console.log(results);
49+
50+
// When you're done, close your MongoDB client
51+
await mongoClient.close();
52+
```
53+
54+
### Testing with DummyQueryLeaf
55+
56+
For testing or debugging without a real database, use DummyQueryLeaf:
57+
58+
```typescript
59+
import { DummyQueryLeaf } from '@queryleaf/lib';
60+
61+
// Create a DummyQueryLeaf instance for testing
62+
const queryLeaf = new DummyQueryLeaf('mydatabase');
63+
64+
// Operations will be logged to console but not executed
65+
await queryLeaf.execute('SELECT * FROM users WHERE age > 21');
66+
// [DUMMY MongoDB] FIND in mydatabase.users with filter: { "age": { "$gt": 21 } }
67+
```
68+
69+
## SQL Query Examples
70+
71+
```sql
72+
-- Basic SELECT with WHERE
73+
SELECT name, email FROM users WHERE age > 21
74+
75+
-- Nested field access
76+
SELECT name, address.city FROM users WHERE address.zip = '10001'
77+
78+
-- Array access
79+
SELECT items[0].name FROM orders WHERE items[0].price > 100
80+
81+
-- GROUP BY with aggregation
82+
SELECT status, COUNT(*) as count FROM orders GROUP BY status
83+
84+
-- JOIN between collections
85+
SELECT u.name, o.total FROM users u JOIN orders o ON u._id = o.userId
86+
```
87+
88+
## Links
89+
90+
- [Website](https://queryleaf.com)
91+
- [Documentation](https://queryleaf.com/docs)
92+
- [GitHub Repository](https://github.com/beekeeper-studio/queryleaf)
93+
94+
## License
95+
96+
QueryLeaf is dual-licensed:
97+
98+
- [AGPL-3.0](https://github.com/beekeeper-studio/queryleaf/blob/main/LICENSE.md) for open source use
99+
- [Commercial license](https://github.com/beekeeper-studio/queryleaf/blob/main/COMMERCIAL_LICENSE.md) for commercial use
100+
101+
For commercial licensing options, visit [queryleaf.com](https://queryleaf.com).

‎packages/postgres-server/README.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
<p align="center">
2+
<img src="https://raw.githubusercontent.com/beekeeper-studio/queryleaf/main/logo-transparent-bg-green-shape.png" width="100" height="100" alt="QueryLeaf Logo">
3+
</p>
4+
5+
<h1 align="center">@queryleaf/postgres-server</h1>
6+
7+
<p align="center">PostgreSQL wire-compatible server for QueryLeaf</p>
8+
9+
## Overview
10+
11+
`@queryleaf/postgres-server` provides a PostgreSQL wire protocol compatible server for QueryLeaf, allowing you to connect to MongoDB using standard PostgreSQL clients and drivers. It implements the PostgreSQL wire protocol and leverages the core `@queryleaf/lib` package to translate SQL queries into MongoDB commands.
12+
13+
## Key Features
14+
15+
- Connect to MongoDB using any PostgreSQL client (pgAdmin, psql, etc.)
16+
- Full SQL support for querying MongoDB collections
17+
- Transparent authentication passthrough
18+
- Compatible with any tool that uses PostgreSQL drivers
19+
- Convert MongoDB documents to PostgreSQL-compatible row format
20+
21+
## Installation
22+
23+
```bash
24+
# Global installation
25+
npm install -g @queryleaf/postgres-server
26+
# or
27+
yarn global add @queryleaf/postgres-server
28+
29+
# Local installation
30+
npm install @queryleaf/postgres-server
31+
# or
32+
yarn add @queryleaf/postgres-server
33+
```
34+
35+
## Usage
36+
37+
### Running the Server
38+
39+
```bash
40+
# Start the server with default settings
41+
queryleaf-pg-server
42+
43+
# With specific MongoDB URI and port
44+
queryleaf-pg-server --uri mongodb://localhost:27017 --port 5432
45+
46+
# With authentication
47+
queryleaf-pg-server --uri mongodb://user:pass@localhost:27017
48+
49+
# Help
50+
queryleaf-pg-server --help
51+
```
52+
53+
### Connecting with PostgreSQL Clients
54+
55+
Connect using any PostgreSQL client with these connection parameters:
56+
- Host: localhost (or wherever the server is running)
57+
- Port: 5432 (or your configured port)
58+
- Database: your MongoDB database name
59+
- Username/Password: if required by your MongoDB deployment
60+
61+
Example with psql:
62+
```bash
63+
psql -h localhost -p 5432 -d mydatabase
64+
```
65+
66+
Example connection string:
67+
```
68+
postgresql://localhost:5432/mydatabase
69+
```
70+
71+
## SQL Query Examples
72+
73+
Once connected, you can use SQL syntax to query MongoDB:
74+
75+
```sql
76+
-- Basic SELECT with WHERE
77+
SELECT name, email FROM users WHERE age > 21;
78+
79+
-- Nested field access
80+
SELECT name, address.city FROM users WHERE address.zip = '10001';
81+
82+
-- Array access
83+
SELECT items[0].name FROM orders WHERE items[0].price > 100;
84+
85+
-- GROUP BY with aggregation
86+
SELECT status, COUNT(*) as count FROM orders GROUP BY status;
87+
88+
-- JOIN between collections
89+
SELECT u.name, o.total FROM users u JOIN orders o ON u._id = o.userId;
90+
```
91+
92+
## Configuration
93+
94+
You can configure the server using command-line arguments or environment variables:
95+
96+
| Argument | Environment Variable | Description |
97+
|----------------|-------------------------|----------------------------------|
98+
| `--uri` | `MONGODB_URI` | MongoDB connection URI |
99+
| `--port` | `POSTGRES_PORT` | Server port (default: 5432) |
100+
| `--host` | `POSTGRES_HOST` | Server host (default: 0.0.0.0) |
101+
| `--auth` | `ENABLE_AUTH` | Enable authentication passthrough|
102+
| `--debug` | `DEBUG` | Enable debug output |
103+
104+
## Links
105+
106+
- [Website](https://queryleaf.com)
107+
- [Documentation](https://queryleaf.com/docs)
108+
- [GitHub Repository](https://github.com/beekeeper-studio/queryleaf)
109+
110+
## License
111+
112+
QueryLeaf is dual-licensed:
113+
114+
- [AGPL-3.0](https://github.com/beekeeper-studio/queryleaf/blob/main/LICENSE.md) for open source use
115+
- [Commercial license](https://github.com/beekeeper-studio/queryleaf/blob/main/COMMERCIAL_LICENSE.md) for commercial use
116+
117+
For commercial licensing options, visit [queryleaf.com](https://queryleaf.com).

0 commit comments

Comments
 (0)