Skip to content

Commit 38b1bf1

Browse files
ianf-mongodbianf-mongodb
authored
DOCSP-42425-Merge-Test-Bench-Feature-Branch (#163)
* DOCSP-40890 Stage Query Converter Test Bench TOC (#145) * DOCSP-40890 Stage Query Converter Test Bench TOC * DOCSP-40959 Add Query Converter Test Bench Stub Page (#146) * DOCSP-40959 Add Query Converter Test Bench Stub Page * DOCSP-41803-install-query-runner-task-page (#155) * DOCSP-41803-install-query-runner-task-page * DOCSP-40960-compare-queries-task (#157) * DOCSP-40960-compare-queries-task * DOCSP-42425-Merge-Test-Bench-Feature-Branch * *
1 parent e0b1515 commit 38b1bf1

File tree

5 files changed

+370
-2
lines changed

5 files changed

+370
-2
lines changed

‎snooty.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,8 @@ toc_landing_pages = [
3838
"getting-started",
3939
"jobs/prerequisites",
4040
"api-docs",
41-
"deployment-considerations"
41+
"deployment-considerations",
42+
"code-generation/query-converter-test-queries"
4243
]
4344

4445
[constants]

‎source/code-generation/query-converter-test-queries.txt

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
.. _rm-query-converter-test-bench:
2+
3+
============
4+
Test Queries
5+
============
6+
7+
.. meta::
8+
:keywords: relational migrator, test converted queries
9+
10+
.. facet::
11+
:name: genre
12+
:values: reference
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 1
18+
:class: singlecol
19+
20+
Use the :guilabel:`Test Queries` pane to test SQL queries,
21+
views, and stored procedures converted by :ref:`rm-query-converter`.
22+
This feature uses the project's source
23+
and destination database connections and allows you to
24+
run the original SQL and converted MongoDB code.
25+
The results from each query are displayed on the
26+
:guilabel:`Test Queries` pane, allowing for a side-by-side
27+
comparison.
28+
29+
Use Cases
30+
---------
31+
32+
The :guilabel:`Test Queries` pane allows you to:
33+
34+
- Compare your original and converted
35+
query results in a single place.
36+
- Increase your confidence in code automatically
37+
converted by the Query Converter.
38+
- See potential logic errors and edit the converted
39+
code before moving it to production.
40+
41+
Requirements
42+
------------
43+
44+
To test converted queries in Relational Migrator,
45+
you must run the Query Runner Docker container. This
46+
container can be run locally or hosted remotely.
47+
For details, see :ref:`rm-install-query-runner`.
48+
49+
Get Started
50+
-----------
51+
52+
- :ref:`rm-install-query-runner`
53+
- :ref:`rm-compare-converted-queries`
54+
55+
.. toctree::
56+
:hidden:
57+
:titlesonly:
58+
59+
/code-generation/query-converter/test-converted-queries/install-query-runner
60+
/code-generation/query-converter/test-converted-queries/compare-converted-queries

‎source/code-generation/query-converter.txt

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,4 +25,5 @@ your SQL code.
2525
/code-generation/query-converter/convert-stored-procedures
2626
/code-generation/query-converter/convert-triggers
2727
/code-generation/query-converter/convert-views
28-
/code-generation/query-converter/refresh-database-objects
28+
/code-generation/query-converter/refresh-database-objects
29+
/code-generation/query-converter-test-queries

‎source/code-generation/query-converter/test-converted-queries/compare-converted-queries.txt

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
.. _rm-compare-converted-queries:
2+
3+
=========================
4+
Compare Converted Queries
5+
=========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
You can use the :guilabel:`Test Queries` pane to compare source
14+
and destination queries, views, and stored procedure results
15+
in Relational Migrator. The :guilabel:`Test Queries` can
16+
help you verify the accuracy of converted code and
17+
show the source and destination data after you run a sync job.
18+
19+
About this Task
20+
---------------
21+
22+
The :guilabel:`Test Queries` pane is split into three separate
23+
user interfaces: ``Console``, ``Results``, and ``Messages``.
24+
Click the pill buttons next to :guilabel:`Test Queries` to
25+
change the user interface. The following table summarizes
26+
each user interface:
27+
28+
.. list-table::
29+
:header-rows: 1
30+
:widths: 20 80
31+
32+
* - User Interface
33+
- Description
34+
* - Console
35+
- This is the default user interface of the
36+
:guilabel:`Test Queries` pane. You can click
37+
the :guilabel:`Run Source Query` button to
38+
run all converted queries. You can also specify
39+
parameters for stored procedures in the
40+
:guilabel:`Source Script` text field.
41+
* - Results
42+
- This user interface is used to view the query results
43+
from the source and destination queries. You must run
44+
a source or destination query to view the ``Results``
45+
user interface.
46+
* - Messages
47+
- This user interface is used to show messages from each
48+
database connection. You can see error messages,
49+
execution stats, and any print statements.
50+
51+
Before you Begin
52+
----------------
53+
54+
- You must sign in to your Atlas account in Relational Migrator.
55+
For details, see :ref:`rm-atlas-log-in`.
56+
57+
- For details on how to turn on Query Converter, see
58+
:ref:`rm-enable-query-converter`.
59+
60+
- To use the :guilabel:`Test Queries` pane, Relational
61+
Migrator must have access to the Query Runner. For details
62+
on how to setup Query Runner, see :ref:`rm-install-query-runner`.
63+
64+
Steps
65+
-----
66+
67+
.. procedure::
68+
:style: normal
69+
70+
.. step:: Select a query on the :guilabel:`Query Converter` pane
71+
72+
a. From the :guilabel:`Code Generation` tab, click the
73+
:guilabel:`Query Converter` pane.
74+
75+
.. note::
76+
77+
If you are not already logged into your Atlas account or have
78+
an expired session, you must login to proceed.
79+
80+
#. On the left-hand :guilabel:`Queries` pane, select a query, view,
81+
or stored procedure.
82+
83+
#. If your query has not been converted, select a
84+
:guilabel:`Target Language` and click :guilabel:`Convert`
85+
:icon-lg:`Sparkle`.
86+
87+
.. step:: Open the :guilabel:`Test Queries` pane
88+
89+
a. From the :guilabel:`Code Generation` tab, click the
90+
:guilabel:`Query Converter` pane.
91+
92+
#. On the bottom-right of the screen, click the :icon-lg:`ChevronUp`
93+
button.
94+
95+
.. step:: *(Optional)* Specify parameters
96+
97+
If you're converting a stored procedure with parameters, specify the
98+
stored procedure's parameters in the :guilabel:`Source Script` text field.
99+
100+
For example, for the following PostGreSQL stored procedure:
101+
102+
.. code-block:: sql
103+
:copyable: false
104+
105+
CREATE OR REPLACE PROCEDURE PUBLIC.CANCEL_CUSTOMER_ORDERS(IN CUST_ID INTEGER)
106+
LANGUAGE PLPQSQL
107+
108+
AS $PROCEDURE$
109+
BEGIN
110+
UPDATE ORDERS SET STATUS = 'CANCELLED' WHERE CUSTOMER_ID = CUST_ID;
111+
END;$PROCEDURE$
112+
113+
Specify the ``CUST_ID`` in the :guilabel:`Source Script` text field
114+
by replacing ``<value>`` with the customer ID:
115+
116+
.. code-block:: sql
117+
:copyable: false
118+
:emphasize-lines: 7
119+
120+
DO
121+
$$
122+
DECLARE
123+
CUST_ID INTEGER;
124+
BEGIN
125+
--TODO: Set parameter values here
126+
CUST_ID := <value>
127+
128+
CALL public.cancel_customer_orders(cust_id);
129+
END;
130+
$$
131+
132+
.. step:: Run the source query
133+
134+
a. On the :guilabel:`Test Queries`
135+
pane, click the :guilabel:`Run Source Query`
136+
button.
137+
138+
#. Enter the connection details to your source database.
139+
140+
#. On the :guilabel:`Connection Details` form, click :guilabel:`Run`.
141+
142+
The data from the source database populates in the
143+
:guilabel:`Results` user interface. You can click
144+
the :guilabel:`Messages` pill to see execution
145+
statistics such as ``Execution Time``, ``Row Count``,
146+
error messages, and print statements.
147+
148+
.. step:: Run the converted query
149+
150+
a. On the :guilabel:`Test Queries`
151+
pane, click :guilabel:`Run Converted Query`
152+
button.
153+
154+
#. Enter the connection details to your database.
155+
156+
#. On the :guilabel:`Connection Details` form, click :guilabel:`Run`.
157+
158+
159+
The data from the destination database populates
160+
on the right-side of the :guilabel:`Results` user
161+
interface.
162+
163+
#. You can use the :guilabel:`Results` pane to compare the
164+
source and destination data and types.
165+
166+
.. note::
167+
168+
You can click the :icon-lg:`Menu` and
169+
:icon-lg:`Apps` buttons to switch between
170+
the document and row view for the data.
171+
172+
.. step:: *(Optional)* Edit the converted query
173+
174+
If the destination query needs to be changed, you can make
175+
code changes in the :guilabel:`Converted MongoDB Query`
176+
pane and run the updated query.
177+
178+
a. On the :guilabel:`Converted MongoDB Query` pane,
179+
click the :icon-lg:`Edit` button.
180+
181+
#. Edit the code and click :guilabel:`Save`.
182+
183+
#. Click :guilabel:`Run Converted Query`.
184+
185+
Learn More
186+
----------
187+
188+
- :ref:`rm-convert-queries`
189+
- :ref:`rm-convert-views`
190+
- :ref:`rm-convert-stored-procedures`

‎source/code-generation/query-converter/test-converted-queries/install-query-runner.txt

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
.. _rm-install-query-runner:
2+
3+
====================
4+
Install Query Runner
5+
====================
6+
7+
.. meta::
8+
:keywords: query runner, relational migrator, docker, prerequisite
9+
10+
.. facet::
11+
:name: genre
12+
:values: tutorial
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 1
18+
:class: singlecol
19+
20+
To use the :guilabel:`Test Queries` pane, Relational
21+
Migrator must have access to the Query Runner.
22+
Query Runner is a Docker container with
23+
all the dependencies needed to test your converted
24+
queries.
25+
26+
About this Task
27+
---------------
28+
29+
- If the version of Query Runner is different than the
30+
version of Relational Migrator, a warning banner displays.
31+
32+
- To update Query Runner to the latest version, run
33+
the ``docker pull`` command from step number one.
34+
35+
- Query Runner operates using the ``http`` protocol.
36+
Requests made from a remote machine are not encrypted.
37+
38+
- Query Runner can run either locally or remotely.
39+
40+
Before you Begin
41+
----------------
42+
43+
Install `Docker <https://www.docker.com/get-started/>`__.
44+
45+
Steps
46+
-----
47+
48+
.. procedure::
49+
:style: normal
50+
51+
.. step:: Get the Query Runner Image
52+
53+
.. code-block:: sh
54+
55+
docker pull public.ecr.aws/v4d7k6c9/relational-migrator-query-runner
56+
57+
.. step:: Run the Image as a Container
58+
59+
- To run the container locally:
60+
61+
.. code-block:: sh
62+
63+
docker run --name relational-migrator-query-runner -p 127.0.0.1:6080:6080 public.ecr.aws/v4d7k6c9/relational-migrator-query-runner
64+
65+
- To run the container remotely:
66+
67+
a. Add the server address where the
68+
service is running to the ``migrator.language-runner.server.address`` in the
69+
``user.properties``.
70+
71+
For example:
72+
73+
.. code-block:: sh
74+
75+
migrator.language-runner.server.address: http://myserver:6080
76+
77+
.. tip::
78+
79+
For details on where the ``user.properties`` file is located,
80+
see :ref:`file-location`.
81+
82+
#. After changing the ``user.properties`` file, restart Relational Migrator.
83+
84+
#. Launch the container from your remote server or container hosting service.
85+
86+
To launch the container on your remote server expose port ``6080``
87+
with the following docker command:
88+
89+
.. code-block:: sh
90+
91+
docker run --name relational-migrator-query-runner -p 6080:6080 public.ecr.aws/v4d7k6c9/relational-migrator-query-runner
92+
93+
.. step:: Confirm the Query Runner container is running
94+
95+
In your web browser, navigate to the host and port the Query Runner
96+
container is using. For example:
97+
`http://localhost:6080/status <http://localhost:6080/status>`__.
98+
99+
Check the ``status`` field of the JSON data returned from the
100+
``status`` endpoint. A status of ``ok`` means the container is
101+
running:
102+
103+
.. code-block::
104+
:copyable: false
105+
106+
{
107+
"status":"ok",
108+
"server":"App Mod Language Runner",
109+
"commitHash":"159119004c2bf8c534e15e5895acb9bc1bfb5b8d",
110+
"version":"20240627"
111+
}
112+
113+
Next Steps
114+
----------
115+
116+
- :ref:`rm-compare-converted-queries`

0 commit comments

Comments
 (0)