Skip to content

Commit 68a4c6e

Browse files
Antony BaileyAntony Bailey
Antony Bailey
authored and
Antony Bailey
committed
docs update
1 parent 9195025 commit 68a4c6e

File tree

4 files changed

+185
-1
lines changed

4 files changed

+185
-1
lines changed

‎CODE_OF_CONDUCT.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ representative at an online or offline event.
5555

5656
Instances of abusive, harassing, or otherwise unacceptable behavior may be
5757
reported to the project maintainers responsible for enforcement at
58-
[INSERT EMAIL ADDRESS]. All complaints will be reviewed and investigated
58+
support@antonybailey.net. All complaints will be reviewed and investigated
5959
promptly and fairly.
6060

6161
All project maintainers are obligated to respect the privacy and security of the

‎DESIGN.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# pySQLY Design Document
2+
3+
This document outlines the architectural design and patterns used in pySQLY.
4+
5+
## Architecture Overview
6+
7+
pySQLY follows a layered architecture with the following components:
8+
9+
1. **Core Layer**: Handles parsing, validation, and execution of SQLY queries
10+
2. **Connector Layer**: Provides database-specific implementations
11+
3. **Error Handling Layer**: Centralizes error management
12+
4. **CLI Layer**: Provides command-line interface functionality
13+
14+
The following diagram illustrates the high-level architecture:
15+
16+
```bash
17+
┌─────────────┐ ┌─────────────┐
18+
│ Client │ │ CLI │
19+
└─────┬───────┘ └──────┬──────┘
20+
│ │
21+
▼ ▼
22+
┌─────────────────────────────────┐
23+
│ SQLYExecutor │
24+
└─────────────┬───────────────────┘
25+
│
26+
┌─────────┴─────────┐
27+
│ │
28+
▼ ▼
29+
┌─────────┐ ┌──────────────┐
30+
│SQLYParser│ │SQLYUtils │
31+
└─────────┘ └──────┬───────┘
32+
│
33+
▼
34+
┌───────────────────┐
35+
│DatabaseConnector │
36+
└─────────┬─────────┘
37+
│
38+
┌───────┴────────┐
39+
│ │
40+
▼ ▼
41+
┌────────────┐ ┌─────────────┐
42+
│ Specific │...│ Specific │
43+
│Connectors │ │Connectors │
44+
└────────────┘ └─────────────┘
45+
```
46+
47+
## Design Patterns
48+
49+
1. **Factory Pattern**: The `DBConnectorFactory` class creates appropriate database connector instances based on the database type, abstracting the creation logic.
50+
51+
2. **Strategy Pattern**: Different database connectors implement a common interface (`IDBConnector`), allowing the rest of the application to work with different databases uniformly.
52+
53+
3. **Facade Pattern**: The `SQLYExecutor` class provides a simplified interface to the complex subsystem of parsing, validation, and execution.
54+
55+
4. **Composite Pattern**: SQLY queries are composed as structured YAML objects that can represent complex SQL statements.
56+
57+
## Core Components
58+
59+
### SQLYParser
60+
61+
Responsible for parsing YAML queries into Python dictionaries. Uses PyYAML for YAML parsing.
62+
63+
### SQLYUtils
64+
65+
Contains utility functions for validating and translating SQLY queries to SQL statements.
66+
67+
### SQLYExecutor
68+
69+
The main entry point for query execution. Orchestrates the parsing, validation, and execution process.
70+
71+
## Database Connectors
72+
73+
The connector layer follows an interface-based design:
74+
75+
1. `IDBConnector`: Interface defining the contract for all database connectors
76+
2. `BaseDBConnector`: Abstract implementation with common functionality
77+
3. Specific connectors: Database-specific implementations (SQLite, MariaDB, PostgreSQL, Oracle, MSSQL)
78+
79+
## Error Handling Strategy
80+
81+
pySQLY implements a hierarchical exception system:
82+
83+
1. `SQLYError`: Base exception class
84+
2. `SQLYParseError`: For parsing errors
85+
3. `SQLYExecutionError`: For execution errors
86+
4. `SQLYConnectorError`: For database connector errors
87+
88+
This allows for fine-grained exception handling and appropriate error messages.
89+
90+
## Extension Points
91+
92+
pySQLY is designed to be extensible in several ways:
93+
94+
1. **New Database Support**: Add new connectors by implementing the `IDBConnector` interface
95+
2. **Query Features**: Extend the YAML format and the translation logic in `SQLYUtils`
96+
3. **Result Processing**: Add post-processing capabilities to transform query results
97+
98+
## Performance Considerations
99+
100+
1. Connection pooling is handled at the database driver level
101+
2. YAML parsing is optimized using PyYAML's safe_load
102+
3. Parameter binding is used to prevent SQL injection and improve performance
103+
104+
## Future Architectural Improvements
105+
106+
1. **Connection Pooling**: Implement a custom connection pooling mechanism
107+
2. **Async Support**: Add asynchronous query execution capabilities
108+
3. **Query Caching**: Implement caching for frequently executed queries
109+
4. **Result Set Pagination**: Support for paginated results for large data sets

‎SECURITY.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Security Policy
2+
3+
## Supported Versions
4+
5+
Use this section to tell people about which versions of your project are
6+
currently being supported with security updates.
7+
8+
| Version | Supported |
9+
| ------- | ------------------ |
10+
| 0.1.x | :white_check_mark: |
11+
12+
## Reporting a Vulnerability
13+
14+
The pySQLY team takes security issues seriously. We appreciate your efforts
15+
to responsibly disclose your findings and will make every effort to acknowledge
16+
your contributions.
17+
18+
To report a security issue, please email security@sqly.example.com with a
19+
description of the issue, the steps you took to create the issue, affected
20+
versions, and if known, mitigations for the issue.
21+
22+
We aim to respond to security reports within 48 hours. If for some reason you
23+
don't get a response within that timeframe, please follow up via email to ensure
24+
we received your original message.
25+
26+
After the initial reply to your report, the security team will keep you informed
27+
of the progress towards a fix and full announcement, and may ask for additional
28+
information or guidance.
29+
30+
## Security Best Practices for Using pySQLY
31+
32+
When using pySQLY in your applications, consider these security best practices:
33+
34+
1. **Always sanitize user inputs**: While pySQLY helps prevent SQL injection by
35+
using parameterized queries, it's still important to validate and sanitize all
36+
user inputs before processing them.
37+
38+
2. **Use principle of least privilege**: Configure your database users with
39+
the minimum required permissions for your application to function.
40+
41+
3. **Keep dependencies updated**: Regularly update pySQLY and its dependencies
42+
to ensure you have the latest security patches.
43+
44+
4. **Store connection strings securely**: Never hard-code database credentials in
45+
your source code. Use environment variables or a secure secret management system.
46+
47+
5. **Log responsibly**: Be careful not to log sensitive information like queries
48+
that might contain personal data or credentials.
49+
50+
Thank you for helping keep pySQLY and its community safe!

‎_config.yml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,29 @@
11
remote_theme: pages-themes/architect@v0.2.0
22
plugins:
33
- jekyll-remote-theme
4+
- jekyll-seo-tag
5+
6+
# Site settings
47
title: Python Standard Query Language (pySQLY) Documentation
8+
description: A powerful Python library for standardized SQL querying
9+
show_downloads: true
10+
google_analytics: # Add your GA tracking ID here if needed
11+
12+
# Theme customization
13+
colors:
14+
header: "#2E7BCF"
15+
gradient_top: "#2E7BCF"
16+
gradient_bottom: "#2A6DA9"
17+
link: "#2E7BCF"
18+
section_headings: "#2E7BCF"
19+
20+
# Navigation
21+
nav:
22+
- title: Home
23+
url: /
24+
- title: Documentation
25+
url: /docs/
26+
- title: Examples
27+
url: /examples/
28+
- title: GitHub
29+
url: https://github.com/Standard-Query-Language/pySQLY

0 commit comments

Comments
 (0)