Add example DAG & how-to guide for sqlite (#13196)

airflow/providers/sqlite/example_dags/__init__.py

@@ -0,0 +1,17 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.

airflow/providers/sqlite/example_dags/example_sqlite.py

@@ -0,0 +1,70 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""
+This is an example DAG for the use of the SqliteOperator.
+In this example, we create two tasks that execute in sequence.
+The first task calls an sql command, defined in the SQLite operator,
+which when triggered, is performed on the connected sqlite database.
+The second task is similar but instead calls the SQL command from an external file.
+"""
+
+from airflow import DAG
+from airflow.providers.sqlite.operators.sqlite import SqliteOperator
+from airflow.utils.dates import days_ago
+
+default_args = {'owner': 'airflow'}
+
+dag = DAG(
+    dag_id='example_sqlite',
+    default_args=default_args,
+    schedule_interval='@daily',
+    start_date=days_ago(2),
+    tags=['example'],
+)
+
+# [START howto_operator_sqlite]
+
+# Example of creating a task that calls a common CREATE TABLE sql command.
+create_table_sqlite_task = SqliteOperator(
+    task_id='create_table_sqlite',
+    sqlite_conn_id='sqlite_conn_id',
+    sql=r"""
+    CREATE TABLE table_name (
+        column_1 string,
+        column_2 string,
+        column_3 string
+    );
+    """,
+    dag=dag,
+)
+
+# [END howto_operator_sqlite]
+
+# [START howto_operator_sqlite_external_file]
+
+# Example of creating a task that calls an sql command from an external file.
+external_create_table_sqlite_task = SqliteOperator(
+    task_id='create_table_sqlite_external_file',
+    sqlite_conn_id='sqlite_conn_id',
+    sql='/scripts/create_table.sql',
+    dag=dag,
+)
+
+# [END howto_operator_sqlite_external_file]
+
+create_table_sqlite_task >> external_create_table_sqlite_task

airflow/providers/sqlite/operators/sqlite.py

@@ -26,9 +26,15 @@ class SqliteOperator(BaseOperator):
     """
     Executes sql code in a specific Sqlite database
 
-    :param sql: the sql code to be executed. (templated)
-    :type sql: str or string pointing to a template file. File must have
-        a '.sql' extensions.
+    .. seealso::
+        For more information on how to use this operator, take a look at the guide:
+        :ref:`howto/operator:SqliteOperator`
+
+    :param sql: the sql code to be executed. Can receive a str representing a
+        sql statement, a list of str (sql statements), or reference to a template file.
+        Template reference are recognized by str ending in '.sql'
+        (templated)
+    :type sql: str or list[str]
     :param sqlite_conn_id: reference to a specific sqlite database
     :type sqlite_conn_id: str
     :param parameters: (optional) the parameters to render the SQL query with.

airflow/providers/sqlite/provider.yaml

@@ -27,10 +27,13 @@ versions:
 integrations:
   - integration-name: SQLite
     external-doc-url: https://www.sqlite.org/index.html
+    how-to-guide:
+      - /docs/apache-airflow-providers-sqlite/operators.rst
     tags: [software]
 
 operators:
   - integration-name: SQLite
+
     python-modules:
       - airflow.providers.sqlite.operators.sqlite
 

docs/apache-airflow-providers-sqlite/connections/sqlite.rst

@@ -0,0 +1,36 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+ ..   http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+
+
+SQLite Connection
+=================
+The SQLite connection type provides connection to a SQLite database.
+
+Configuring the Connection
+--------------------------
+Host (required)
+    The host to connect to.
+
+Schema (optional)
+    Specify the schema name to be used in the database.
+
+Login (required)
+    Specify the user name to connect.
+
+Password (required)
+    Specify the password to connect.

docs/apache-airflow-providers-sqlite/index.rst

@@ -22,12 +22,25 @@
 Content
 -------
 
+.. toctree::
+    :maxdepth: 1
+    :caption: Guides
+
+    Connection types <connections/sqlite>
+    Operators <operators>
+
 .. toctree::
     :maxdepth: 1
     :caption: References
 
     Python API <_api/airflow/providers/sqlite/index>
 
+.. toctree::
+    :maxdepth: 1
+    :caption: Resources
+
+    Example DAGs <https://github.com/apache/airflow/tree/master/airflow/providers/sqlite/example_dags>
+
 .. toctree::
     :maxdepth: 1
     :caption: Resources

docs/apache-airflow-providers-sqlite/operators.rst

@@ -0,0 +1,75 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+ ..   http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+
+
+.. _howto/operator:SqliteOperator:
+
+SqliteOperator
+==============
+
+Use the :class:`~airflow.providers.sqlite.operators.SqliteOperator` to execute
+Sqlite commands in a `Sqlite <https://sqlite.org/lang.html>`__ database.
+
+
+Using the Operator
+^^^^^^^^^^^^^^^^^^
+
+Use the ``sqlite_conn_id`` argument to connect to your Sqlite instance where
+the connection metadata is structured as follows:
+
+.. list-table:: Sqlite Airflow Connection Metadata
+   :widths: 25 25
+   :header-rows: 1
+
+   * - Parameter
+     - Input
+   * - Host: string
+     - MySql hostname
+   * - Schema: string
+     - Set schema to execute Sql operations on by default
+   * - Login: string
+     - Sqlite user
+   * - Password: string
+     - Sqlite user password
+   * - Port: int
+     - Sqlite port
+
+An example usage of the SqliteOperator is as follows:
+
+.. exampleinclude:: /../../airflow/providers/sqlite/example_dags/example_sqlite.py
+    :language: python
+    :start-after: [START howto_operator_sqlite]
+    :end-before: [END howto_operator_sqlite]
+
+Furthermore, you can use an external file to execute the SQL commands. Script folder must be at the same level as DAG.py file.
+
+.. exampleinclude:: /../../airflow/providers/sqlite/example_dags/example_sqlite.py
+    :language: python
+    :start-after: [START howto_operator_sqlite_external_file]
+    :end-before: [END howto_operator_sqlite_external_file]
+
+Reference
+^^^^^^^^^
+For further information, look at:
+
+* `Sqlite Documentation <https://www.sqlite.org/index.html>`__
+
+.. note::
+
+  Parameters given via SqliteOperator() are given first-place priority
+  relative to parameters set via Airflow connection metadata (such as ``schema``, ``login``, ``password`` etc).

docs/apache-airflow-providers-sqlite/redirects.txt

@@ -0,0 +1 @@
+connections/index.rst connections/sqlite.rst