@@ -0,0 +1,117 @@
1+=================
2+Query SQL servers
3+=================
4+
5+Now you can query SQL servers using searx. The following ones are supported:
6+
7+* `PostgreSQL`_
8+* `MySQL`_
9+* `SQLite`_
10+
11+All of the engines above are added to ``settings.yml`` just commented out, as you have to
12+set the required attributes for the engines, e.g. ``database``. By default, the engines use
13+``key-value`` template for displaying results. If you are not satisfied with the original result layout,
14+you can use your owm template by placing the template under
15+``searx/templates/{theme_name}/result_templates/{template_name}`` and setting
16+``result_template`` attribute to ``{template_name}``.
17+
18+As mentioned in previous blog posts, if you do not wish to expose these engines on a
19+public instance, you can still add them and limit the access by setting ``tokens``
20+as described in the `blog post about private engines`_.
21+
22+Configure the engines
23+=====================
24+
25+The configuration of the new database engines are similar. You must put a valid
26+SELECT SQL query in ``query_str``. At the moment you can only bind at most
27+one parameter in your query. By setting the attribute ``limit`` you can
28+define how many results you want from the SQL server. Basically, it
29+is the same as the LIMIT keyword in SQL.
30+
31+Please, do not include LIMIT or OFFSET in your SQL query as the engines
32+rely on these keywords during paging. If you want to configure the number of returned results
33+use the option ``limit``.
34+
35+PostgreSQL
36+----------
37+
38+PostgreSQL is a powerful and robust open source database.
39+
40+Before configuring the PostgreSQL engine, you must install the dependency ``psychopg2``.
41+
42+You can find an example configuration below:
43+
44+.. code:: yaml
45+
46+ - name : postgresql
47+ engine : postgresql
48+ database : my_database
49+ username : searx
50+ password : password
51+ query_str : 'SELECT * from my_table WHERE my_column = %(query)s'
52+ shortcut : psql
53+
54+
55+MySQL
56+-----
57+
58+MySQL is said to be the most popular open source database.
59+
60+Before enabling MySQL engine, you must install the package ``mysql-connector-python``.
61+
62+The authentication plugin is configurable by setting ``auth_plugin`` in the attributes.
63+By default it is set to ``caching_sha2_password``.
64+
65+This is an example configuration for quering a MySQL server:
66+
67+.. code:: yaml
68+
69+ - name : mysql
70+ engine : mysql_server
71+ database : my_database
72+ username : searx
73+ password : password
74+ limit : 5
75+ query_str : 'SELECT * from my_table WHERE my_column=%(query)s'
76+ shortcut : mysql
77+
78+
79+SQLite
80+------
81+
82+SQLite is a small, fast and reliable SQL database engine. It does not require
83+any extra dependency.
84+
85+You can read from your database ``my_database`` using this example configuration:
86+
87+.. code:: yaml
88+
89+ - name : sqlite
90+ engine : sqlite
91+ shortcut: sq
92+ database : my_database
93+ query_str : 'SELECT * FROM my_table WHERE my_column=:query'
94+
95+
96+Next steps
97+==========
98+
99+The next step is to add support for more data stores, e.g. Redis and MongoDB.
100+
101+Acknowledgement
102+===============
103+
104+This development was sponsored by `Search and Discovery Fund`_ of `NLnet Foundation`_ .
105+
106+.. _PostgreSQL: https://www.postgresql.org/
107+.. _MySQL: https://www.mysql.com/
108+.. _SQLite: https://www.sqlite.org/index.html
109+.. _blog post about private engines: private-engines.html#private-engines
110+.. _Search and Discovery Fund: https://nlnet.nl/discovery
111+.. _NLnet Foundation: https://nlnet.nl/
112+
113+
114+| Happy hacking.
115+| kvch // 2021.05.23 23:16
116+
117+