Skip to content

Commit c5d5a4d

Browse files
committed
📝 Add documentation for the project and its architecture
1 parent fb4a628 commit c5d5a4d

File tree

7 files changed

+283
-71
lines changed

7 files changed

+283
-71
lines changed

CODE_OF_CONDUCT.md

+133
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
2+
# Contributor Covenant Code of Conduct
3+
4+
## Our Pledge
5+
6+
We as members, contributors, and leaders pledge to make participation in our
7+
community a harassment-free experience for everyone, regardless of age, body
8+
size, visible or invisible disability, ethnicity, sex characteristics, gender
9+
identity and expression, level of experience, education, socio-economic status,
10+
nationality, personal appearance, race, religion, or sexual identity
11+
and orientation.
12+
13+
We pledge to act and interact in ways that contribute to an open, welcoming,
14+
diverse, inclusive, and healthy community.
15+
16+
## Our Standards
17+
18+
Examples of behavior that contributes to a positive environment for our
19+
community include:
20+
21+
* Demonstrating empathy and kindness toward other people
22+
* Being respectful of differing opinions, viewpoints, and experiences
23+
* Giving and gracefully accepting constructive feedback
24+
* Accepting responsibility and apologizing to those affected by our mistakes,
25+
and learning from the experience
26+
* Focusing on what is best not just for us as individuals, but for the
27+
overall community
28+
29+
Examples of unacceptable behavior include:
30+
31+
* The use of sexualized language or imagery, and sexual attention or
32+
advances of any kind
33+
* Trolling, insulting or derogatory comments, and personal or political attacks
34+
* Public or private harassment
35+
* Publishing others' private information, such as a physical or email
36+
address, without their explicit permission
37+
* Other conduct which could reasonably be considered inappropriate in a
38+
professional setting
39+
40+
## Enforcement Responsibilities
41+
42+
Community leaders are responsible for clarifying and enforcing our standards of
43+
acceptable behavior and will take appropriate and fair corrective action in
44+
response to any behavior that they deem inappropriate, threatening, offensive,
45+
or harmful.
46+
47+
Community leaders have the right and responsibility to remove, edit, or reject
48+
comments, commits, code, wiki edits, issues, and other contributions that are
49+
not aligned to this Code of Conduct, and will communicate reasons for moderation
50+
decisions when appropriate.
51+
52+
## Scope
53+
54+
This Code of Conduct applies within all community spaces, and also applies when
55+
an individual is officially representing the community in public spaces.
56+
Examples of representing our community include using an official email address,
57+
posting via an official social media account, or acting as an appointed
58+
representative at an online or offline event.
59+
60+
## Enforcement
61+
62+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
63+
reported to the community leaders responsible for enforcement at
64+
65+
All complaints will be reviewed and investigated promptly and fairly.
66+
67+
All community leaders are obligated to respect the privacy and security of the
68+
reporter of any incident.
69+
70+
## Enforcement Guidelines
71+
72+
Community leaders will follow these Community Impact Guidelines in determining
73+
the consequences for any action they deem in violation of this Code of Conduct:
74+
75+
### 1. Correction
76+
77+
**Community Impact**: Use of inappropriate language or other behavior deemed
78+
unprofessional or unwelcome in the community.
79+
80+
**Consequence**: A private, written warning from community leaders, providing
81+
clarity around the nature of the violation and an explanation of why the
82+
behavior was inappropriate. A public apology may be requested.
83+
84+
### 2. Warning
85+
86+
**Community Impact**: A violation through a single incident or series
87+
of actions.
88+
89+
**Consequence**: A warning with consequences for continued behavior. No
90+
interaction with the people involved, including unsolicited interaction with
91+
those enforcing the Code of Conduct, for a specified period of time. This
92+
includes avoiding interactions in community spaces as well as external channels
93+
like social media. Violating these terms may lead to a temporary or
94+
permanent ban.
95+
96+
### 3. Temporary Ban
97+
98+
**Community Impact**: A serious violation of community standards, including
99+
sustained inappropriate behavior.
100+
101+
**Consequence**: A temporary ban from any sort of interaction or public
102+
communication with the community for a specified period of time. No public or
103+
private interaction with the people involved, including unsolicited interaction
104+
with those enforcing the Code of Conduct, is allowed during this period.
105+
Violating these terms may lead to a permanent ban.
106+
107+
### 4. Permanent Ban
108+
109+
**Community Impact**: Demonstrating a pattern of violation of community
110+
standards, including sustained inappropriate behavior, harassment of an
111+
individual, or aggression toward or disparagement of classes of individuals.
112+
113+
**Consequence**: A permanent ban from any sort of public interaction within
114+
the community.
115+
116+
## Attribution
117+
118+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
119+
version 2.0, available at
120+
[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0].
121+
122+
Community Impact Guidelines were inspired by
123+
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
124+
125+
For answers to common questions about this code of conduct, see the FAQ at
126+
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available
127+
at [https://www.contributor-covenant.org/translations][translations].
128+
129+
[homepage]: https://www.contributor-covenant.org
130+
[v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html
131+
[Mozilla CoC]: https://github.com/mozilla/diversity
132+
[FAQ]: https://www.contributor-covenant.org/faq
133+
[translations]: https://www.contributor-covenant.org/translations
Loading
Loading
Loading

website/src/components/footer.astro

+70-69
Original file line numberDiff line numberDiff line change
@@ -5,81 +5,82 @@ const { footnote } = Astro.props;
55
---
66

77
<footer
8-
class="flex flex-col md:flex-row items-center md:justify-between p-7 bg-[#05060c] rounded-[14px] shadow-glow border border-[#2d2d2d] gap-8 sm:gap-4"
8+
class="flex flex-col md:flex-row items-center md:justify-between py-5 px-7 bg-[#05060c] rounded-[14px] shadow-glow border border-[#2d2d2d] gap-8 sm:gap-4"
99
>
10-
<div
11-
class="text-white/60 flex flex-col items-center text-center md:items-start md:text-left"
12-
>
13-
<Logo />
14-
<p class="mt-1 text-xs">
15-
Copyright © 2024 · <a href="https://julienc.me">Julien Cagniart</a> · <br
16-
/>
17-
All rights reserved
18-
</p>
19-
<div class="flex-row flex mt-6 gap-4 text-white/50">
20-
<a href="https://github.com/julien040/anyquery/">
21-
<svg
22-
class="w-5 h-5"
23-
viewBox="0 0 24 24"
24-
xmlns="http://www.w3.org/2000/svg"
25-
><path
26-
fill="currentColor"
27-
d="M12 2A10 10 0 0 0 2 12c0 4.42 2.87 8.17 6.84 9.5c.5.08.66-.23.66-.5v-1.69c-2.77.6-3.36-1.34-3.36-1.34c-.46-1.16-1.11-1.47-1.11-1.47c-.91-.62.07-.6.07-.6c1 .07 1.53 1.03 1.53 1.03c.87 1.52 2.34 1.07 2.91.83c.09-.65.35-1.09.63-1.34c-2.22-.25-4.55-1.11-4.55-4.92c0-1.11.38-2 1.03-2.71c-.1-.25-.45-1.29.1-2.64c0 0 .84-.27 2.75 1.02c.79-.22 1.65-.33 2.5-.33s1.71.11 2.5.33c1.91-1.29 2.75-1.02 2.75-1.02c.55 1.35.2 2.39.1 2.64c.65.71 1.03 1.6 1.03 2.71c0 3.82-2.34 4.66-4.57 4.91c.36.31.69.92.69 1.85V21c0 .27.16.59.67.5C19.14 20.16 22 16.42 22 12A10 10 0 0 0 12 2"
28-
></path></svg
29-
>
30-
</a>
31-
<a href="https://x.com/JulienC_me">
32-
<svg
33-
class="w-5 h-5"
34-
viewBox="0 0 256 256"
35-
xmlns="http://www.w3.org/2000/svg"
36-
><path
37-
fill="currentColor"
38-
d="m218.12 209.56l-61-95.8l59.72-65.69a12 12 0 0 0-17.76-16.14l-55.27 60.84l-37.69-59.21A12 12 0 0 0 96 28H48a12 12 0 0 0-10.12 18.44l61 95.8l-59.76 65.69a12 12 0 1 0 17.76 16.14l55.31-60.84l37.69 59.21A12 12 0 0 0 160 228h48a12 12 0 0 0 10.12-18.44M166.59 204L69.86 52h19.55l96.73 152Z"
39-
></path>
40-
</svg>
41-
</a>
10+
<div
11+
class="text-white/60 flex flex-col items-center text-center md:items-start md:text-left"
12+
>
13+
<Logo />
14+
<p class="mt-1 text-xs">
15+
Copyright © 2024 · <a href="https://julienc.me">Julien Cagniart</a>
16+
· <br />
17+
All rights reserved
18+
</p>
19+
<div class="flex-row flex mt-6 gap-4 text-white/50">
20+
<a href="https://github.com/julien040/anyquery/">
21+
<svg
22+
class="w-5 h-5"
23+
viewBox="0 0 24 24"
24+
xmlns="http://www.w3.org/2000/svg"
25+
><path
26+
fill="currentColor"
27+
d="M12 2A10 10 0 0 0 2 12c0 4.42 2.87 8.17 6.84 9.5c.5.08.66-.23.66-.5v-1.69c-2.77.6-3.36-1.34-3.36-1.34c-.46-1.16-1.11-1.47-1.11-1.47c-.91-.62.07-.6.07-.6c1 .07 1.53 1.03 1.53 1.03c.87 1.52 2.34 1.07 2.91.83c.09-.65.35-1.09.63-1.34c-2.22-.25-4.55-1.11-4.55-4.92c0-1.11.38-2 1.03-2.71c-.1-.25-.45-1.29.1-2.64c0 0 .84-.27 2.75 1.02c.79-.22 1.65-.33 2.5-.33s1.71.11 2.5.33c1.91-1.29 2.75-1.02 2.75-1.02c.55 1.35.2 2.39.1 2.64c.65.71 1.03 1.6 1.03 2.71c0 3.82-2.34 4.66-4.57 4.91c.36.31.69.92.69 1.85V21c0 .27.16.59.67.5C19.14 20.16 22 16.42 22 12A10 10 0 0 0 12 2"
28+
></path></svg
29+
>
30+
</a>
31+
<a href="https://x.com/JulienC_me">
32+
<svg
33+
class="w-5 h-5"
34+
viewBox="0 0 256 256"
35+
xmlns="http://www.w3.org/2000/svg"
36+
><path
37+
fill="currentColor"
38+
d="m218.12 209.56l-61-95.8l59.72-65.69a12 12 0 0 0-17.76-16.14l-55.27 60.84l-37.69-59.21A12 12 0 0 0 96 28H48a12 12 0 0 0-10.12 18.44l61 95.8l-59.76 65.69a12 12 0 1 0 17.76 16.14l55.31-60.84l37.69 59.21A12 12 0 0 0 160 228h48a12 12 0 0 0 10.12-18.44M166.59 204L69.86 52h19.55l96.73 152Z"
39+
></path>
40+
</svg>
41+
</a>
42+
</div>
4243
</div>
43-
</div>
44-
<div
45-
class="flex flex-row flex-wrap items-center justify-center text-[0.825rem] text-white/70 gap-4 md:gap-12"
46-
>
47-
<div class="flex flex-col">
48-
<p class="text-white/50 mb-1">Guide</p>
49-
<a href="/docs/#installation" class="">Install</a>
50-
<a href="/docs/usage/running-queries/" class="">Running a query</a>
51-
<a href="/docs/usage/mysql-server/" class="">MySQL compatibility</a>
52-
<a href="/docs/usage/plugins/" class="">Install plugin</a>
53-
<a href="/docs/usage/exporting-results/" class="">JSON/CSV export</a>
54-
<a href="/docs/developers" class="">Developers</a>
44+
<div
45+
class="flex flex-row flex-wrap items-center justify-center text-[0.825rem] text-white/70 gap-4 md:gap-12"
46+
>
47+
<div class="flex flex-col">
48+
<p class="text-white/50 mb-1">Guide</p>
49+
<a href="/docs/#installation" class="">Install</a>
50+
<a href="/docs/usage/running-queries/" class="">Running a query</a>
51+
<a href="/docs/usage/mysql-server/" class="">MySQL compatibility</a>
52+
<a href="/docs/usage/plugins/" class="">Install plugin</a>
53+
<a href="/docs/usage/exporting-results/" class="">JSON/CSV export</a
54+
>
55+
<a href="/docs/developers" class="">Developers</a>
56+
</div>
57+
<div class="flex flex-col">
58+
<p class="text-white/50 mb-1">Connection guide</p>
59+
<a href="/connection-guide/drizzle" class="">Drizzle</a>
60+
<a href="/connection-guide/datasette" class="">Datasette</a>
61+
<a href="/connection-guide/tablePlus" class="">TablePlus</a>
62+
<a href="/connection-guide/metabase" class="">Metabase</a>
63+
<a href="/connection-guide/datagrip" class="">Datagrip</a>
64+
<a href='/connection-guide/dbeaver"' class="">DBeaver</a>
65+
</div>
66+
<div class="flex flex-col">
67+
<p class="text-white/50 mb-1">Popular plugins</p>
68+
<a href="/integrations/notion" class="">Notion</a>
69+
<a href="/integrations/airtable" class="">Airtable</a>
70+
<a href="/integrations/github" class="">GitHub</a>
71+
<a href="/integrations/notes" class="">Apple Notes</a>
72+
<a href="/integrations/git" class="">Git</a>
73+
<a href="/integrations/google_sheets" class="">Google Sheets</a>
74+
</div>
5575
</div>
56-
<div class="flex flex-col">
57-
<p class="text-white/50 mb-1">Connection guide</p>
58-
<a href="/connection-guide/drizzle" class="">Drizzle</a>
59-
<a href="/connection-guide/datasette" class="">Datasette</a>
60-
<a href="/connection-guide/tablePlus" class="">TablePlus</a>
61-
<a href="/connection-guide/metabase" class="">Metabase</a>
62-
<a href="/connection-guide/datagrip" class="">Datagrip</a>
63-
<a href='/connection-guide/dbeaver"' class="">DBeaver</a>
64-
</div>
65-
<div class="flex flex-col">
66-
<p class="text-white/50 mb-1">Popular plugins</p>
67-
<a href="/integrations/notion" class="">Notion</a>
68-
<a href="/integrations/airtable" class="">Airtable</a>
69-
<a href="/integrations/github" class="">GitHub</a>
70-
<a href="/integrations/notes" class="">Apple Notes</a>
71-
<a href="/integrations/git" class="">Git</a>
72-
<a href="/integrations/google_sheets" class="">Google Sheets</a>
73-
</div>
74-
</div>
7576
</footer>
7677

7778
{
78-
footnote && (
79-
<div class="text-white/30 text-center mt-4 text-[0.7rem]">
80-
<p>{footnote}</p>
81-
</div>
82-
)
79+
footnote && (
80+
<div class="text-white/30 text-center mt-4 text-[0.7rem]">
81+
<p>{footnote}</p>
82+
</div>
83+
)
8384
}
8485

8586
<!-- To facilite reading, a trailing div is added to the end of the file -->

website/src/content/docs/docs/developers/Project/architecture.md

+54-1
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,57 @@ title: Architecture
33
description: Learn how Anyquery is built and how it works
44
---
55

6-
TODO
6+
Anyquery is a SQL query engine that enables you to execute SQL queries on virtually anything. It is built on top of [SQLite](https://www.sqlite.org/index.html) and [Vitess](https://vitess.io/). Thank you for your interest in the architecture of Anyquery. This document explains how Anyquery is built and how it works.
7+
8+
## Core technologies
9+
10+
Anyquery is built on top of two main technologies: SQLite and Vitess.
11+
12+
### SQLite
13+
14+
[SQLite](https://www.sqlite.org/index.html) is a C library that provides a lightweight yet powerful SQL database engine. It has a virtual table mechanism that allows you to extend the SQL engine with custom tables. Anyquery uses this mechanism to provide tables that interact with external systems.
15+
16+
### Vitess
17+
18+
[Vitess](https://vitess.io/) is a database clustering system for horizontal scaling of MySQL. While we don't use its clustering capabilities, we use it to provide a MySQL-compatible server that can interact with the virtual tables provided by SQLite. We also leverage its SQL parsing capabilities to rewrite SQL queries on the fly so that MySQL queries can be executed on SQLite tables.
19+
20+
## Architecture
21+
22+
Here is a few diagrams that explain how Anyquery works.
23+
24+
### Namespace
25+
26+
They represent an instance of Anyquery. Each namespace has its own SQLite database (with multiple connections possible) and its own MySQL server.
27+
28+
![Namespace](/images/docs/Anyquery-diagram-namespace.png)
29+
30+
### Shell
31+
32+
The shell is a command-line interface that allows you to interact with Anyquery. It connects to a namespace and executes SQL queries.
33+
34+
![Shell](/images/docs/Anyquery-diagram-shell.png)
35+
36+
### MySQL server
37+
38+
Anyquery can act as a MySQL server, allowing you to connect to it using any MySQL client. This is useful if the shell client is not sufficient for your needs. The MySQL server connects to a [`*sql.DB`](https://pkg.go.dev/database/sql#DB) object that interacts with the SQLite database. It rewrites the SQL queries on the fly so that MySQL queries can be executed on SQLite tables.
39+
40+
![MySQL server](/images/docs/Anyquery-diagram-mysql.png)
41+
42+
## Folder structure
43+
44+
Here is the folder structure of Anyquery:
45+
46+
- `cmd/`: contains the commands declaration for [spf13/cobra](https://github.com/spf13/cobra).
47+
- `controller/`: contains the controllers that handle each command execution.
48+
- `module/`: contains the modules that acts as virtual tables for SQLite.
49+
`module/module.go` contains the virtual table for SQLite that connects to the plugins. <br>
50+
Other files in this folder are the virtual tables that read files (json, csv, etc.).
51+
- `namespace/`: contains the namespace that manages the SQLite database and the MySQL server. It also features views that acts as `information_schema` and the query rewriter. Finally, it defines a few SQL functions that are not supported by SQLite.
52+
- `other/`: contains the `prql` binding.
53+
- `plugins/`: contains the plugins and extensions that can be downloaded from the registry. These are not subject to the Contributor License Agreement (CLA) and the AGPL license.
54+
- `rpc/`: contains the client/server RPC communication and helpers for writing a plugin.
55+
- `website/`: contains the website that is built with Astro and hosted on [Cloudflare Pages](https://pages.cloudflare.com/).
56+
57+
## Additional resources
58+
59+
I don't have the time to write a full documentation on the architecture of Anyquery. However, feel free to ask me any question on the GitHub discussions or by email at [[email protected]](mailto:[email protected]). I will be happy to answer your questions and complete this document with the information you need.

website/src/content/docs/docs/developers/Project/contributing.md

+26-1
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,29 @@ title: Contributing
33
description: Learn how to contribute to Anyquery
44
---
55

6-
TODO
6+
We welcome contributions to Anyquery. You can contribute minor patches by submitting a pull request to the repository. I don't currently accept big changes, but you can open an issue to discuss what you would like to contribute.
7+
8+
## Testing
9+
10+
Before submitting a pull request, please make sure that your changes pass the tests. You can run the tests with the following command:
11+
12+
```bash
13+
./runTest.sh
14+
```
15+
16+
## CLA
17+
18+
For legal reasons, I prefer to have a Contributor License Agreement (CLA) in place before accepting a pull request from you. The Contributor License Agreement (CLA) only applies to the core project. Any plugins published in the Anyquery registry and contributed under the `plugins` directory are not subject to the CLA.
19+
You can find the CLA [here](https://gist.github.com/julien040/e0fd1fd00a4d5c36305c09ace655e5b4).
20+
21+
When you submit a pull request, you will be asked to accept the CLA. If you have any questions about the CLA, please feel free to ask at [[email protected]](mailto:[email protected]).
22+
23+
## Code of Conduct
24+
25+
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. You can find the Code of Conduct [here](https://github.com/julien040/anyquery/blob/main/CODE_OF_CONDUCT.md).
26+
27+
## How to contribute
28+
29+
1. Fork the repository
30+
2. Make your changes
31+
3. Submit a pull request

0 commit comments

Comments
 (0)