Skip to content

Commit e10f23c

Browse files
ianf-mongodbianf-mongodb
authored
Merge branch 'master' into DOCS-16498
2 parents 0294093 + 01eea4b commit e10f23c

21 files changed

+1119
-33
lines changed

‎snooty.toml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,11 +34,11 @@ toc_landing_pages = [
3434
"code-generation/generate-app-code",
3535
"code-generation/query-converter",
3636
"diagrams/manage-diagrams",
37-
"getting-started"
37+
"getting-started",
38+
"prerequisites"
3839
]
3940

4041
[constants]
4142
ddl = ":abbr:`DDL (Data Definition Language)`"
4243
job = "sync job" #this will be updated to migration job in the near future.
4344
job_plural = "sync jobs" #this will be updated to migration jobs in the near future.
44-

‎source/code-generation.txt

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -42,12 +42,6 @@ application code:
4242
-
4343
- ``C#``, ``Java``, ``JavaScript``, and ``JSON`` application code
4444

45-
46-
.. note::
47-
48-
Query Converter is currently in private preview. For sign-up details,
49-
see :ref:`rm-query-converter`.
50-
5145
Get Started
5246
-----------
5347

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

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -15,21 +15,14 @@ procedures to MongoDB syntax. Relational Migrator considers the mapping
1515
rules and schema transformations defined in your project when converting
1616
your SQL code.
1717

18-
Sign Up for Private Preview
19-
---------------------------
20-
21-
The Query Converter feature is in private
22-
preview. To request private preview access, use the sign-up form within the
23-
Relational Migrator application:
24-
25-
.. include:: /includes/fact-request-private-preview.rst
26-
2718
.. toctree::
2819
:hidden:
2920
:titlesonly:
3021

22+
/code-generation/query-converter/ai-and-data-usage-information
3123
/code-generation/query-converter/enable-query-converter
3224
/code-generation/query-converter/convert-queries
3325
/code-generation/query-converter/convert-stored-procedures
26+
/code-generation/query-converter/convert-triggers
3427
/code-generation/query-converter/convert-views
3528
/code-generation/query-converter/refresh-database-objects

‎source/code-generation/query-converter/ai-and-data-usage-information.txt

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
.. _rm-ai-and-data-usage:
2+
3+
=============================
4+
AI and Data Usage Information
5+
=============================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
The Query Converter feature is powered by Generative AI
14+
(Gen AI), and may give inaccurate responses. Please see our `Generative AI FAQ
15+
<https://dochub.mongodb.org/core/faq-ai-features>`__
16+
for more information about Gen AI in MongoDB products.
17+
18+
Third Party Providers
19+
---------------------
20+
21+
Query Converter currently uses the `Azure OpenAI Service
22+
<https://azure.microsoft.com/en-us/products/ai-services/openai-service>`__
23+
hosted by Microsoft. This is subject to change in the future.
24+
25+
How Your Data is Used
26+
---------------------
27+
28+
When you use Query Converter, the following information is sent to
29+
MongoDB's backend and/or the third party AI provider:
30+
31+
- The full text of your query or stored procedure.
32+
- The definition of any relational database tables used in the query.
33+
These definitions include the table names, column names, data types,
34+
and any primary or foreign key relationships.
35+
- The definition of your MongoDB collections and mapping rules.
36+
These definitions include the relationships between the collections
37+
and tables used in the query and the collection names, field names
38+
and data types.
39+
40+
The information that is sent is not shared with any other third
41+
parties or stored by the AI provider. Relational Migrator does not send
42+
database connection strings, credentials, or any raw data from your
43+
databases.
44+
45+
By default, your original query text and the AI-converted query
46+
telemetry data is stored by MongoDB for up to one year to help us
47+
provide support and improve the service. If you do not want
48+
your data to be stored, you have the option to opt out:
49+
50+
.. include:: /includes/fact-disable-query-converter.rst
51+
52+
Disable Query Converter
53+
-----------------------
54+
55+
Query Converter is available in the Relational Migrator UI once you have
56+
:ref:`enabled the query converter feature <rm-enable-query-converter>`.
57+
If you no longer want to use the feature, you can ignore it and no data
58+
will be sent to generative AI models. If needed, you can hide the
59+
feature by clearing all browser data for the Relational Migrator host.

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

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
.. _rm-convert-triggers:
2+
3+
================
4+
Convert Triggers
5+
================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
You can import and convert your SQL triggers to
14+
:ref:`MongoDB Atlas Triggers <atlas-triggers>` with the query converter.
15+
The query converter considers the SQL code and relational schema defined
16+
in your project when converting your triggers.
17+
18+
About this Task
19+
---------------
20+
21+
.. include:: /includes/fact-query-converter-generic.rst
22+
23+
Before you Begin
24+
----------------
25+
26+
- Your relational database must have at least one trigger to convert.
27+
28+
- .. include:: /includes/fact-query-converter-disclaimer.rst
29+
30+
Steps
31+
-----
32+
33+
.. procedure::
34+
:style: connected
35+
36+
.. step:: Navigate to the query converter pane
37+
38+
From the :guilabel:`Code Generation` tab, click the
39+
:guilabel:`Query Converter` pane.
40+
41+
If it is your first time accessing Query Converter or your session
42+
has expired, click :guilabel:`Log In To Use Query Converter`
43+
and provide your Atlas credentials.
44+
45+
.. step:: Open the query converter view
46+
47+
- If it is your first time using the query converter in your
48+
project, click :guilabel:`Import From Database`.
49+
50+
- If your project already has converted SQL code, click the
51+
:guilabel:`Manage Database Objects` button on the left
52+
pane.
53+
54+
.. step:: Select triggers
55+
56+
a. On the :guilabel:`Import Database Objects` modal, click
57+
the :icon-fa5:`chevron-right` icon next to :guilabel:`Database`.
58+
59+
#. Click the :icon-fa5:`chevron-right` icon next to your schema.
60+
61+
#. Click the :icon-fa5:`chevron-right` icon next to
62+
:guilabel:`Triggers`.
63+
64+
You can toggle triggers for conversion by clicking
65+
the :icon-fa5:`check-square` icon next to a trigger's
66+
name. All triggers are selected by default.
67+
68+
#. Click :guilabel:`Save`.
69+
70+
The code for each trigger in your database
71+
schema is imported into your project and is visible in the
72+
left :guilabel:`Query Converter` pane under
73+
:guilabel:`Triggers`.
74+
75+
.. step:: Convert the SQL trigger
76+
77+
a. Click a trigger's name from the left pane under
78+
:guilabel:`Triggers`.
79+
80+
.. tip::
81+
82+
.. include:: /includes/fact-query-converter-filter.rst
83+
84+
The SQL trigger code displays in the
85+
:guilabel:`Imported Trigger` pane.
86+
87+
#. Click the :guilabel:`Convert` button. Wait for the query
88+
converter to convert your code.
89+
90+
The converted MongoDB code displays
91+
on the :guilabel:`Converted MongoDB Query` pane.
92+
93+
#. Click the :icon-fa5:`copy` icon on the
94+
:guilabel:`Converted MongoDB Query` pane to copy the MongoDB
95+
code to your clipboard.
96+
97+
.. step:: Create the Trigger in Atlas
98+
99+
a. Login to your `Atlas account <https://cloud.mongodb.com/v2/>`__.
100+
101+
#. From the :guilabel:`Overview` screen, click :guilabel:`Triggers`.
102+
103+
#. Click :guilabel:`Add Trigger`.
104+
105+
.. tip::
106+
107+
The converted MongoDB code contains commented lines for
108+
all the variables you must select in Atlas to create
109+
your trigger. For example:
110+
111+
.. code-block:: javascript
112+
:copyable: false
113+
114+
// Collection Name: products
115+
// Operation Type: Insert
116+
117+
#. Enter a name for the trigger in the :guilabel:`Name` text
118+
field.
119+
120+
#. Select the :guilabel:`Cluster Name`, the
121+
:guilabel:`Database Name` and the
122+
:guilabel:`Collection Name`.
123+
124+
#. Select the :guilabel:`Operation Type` as
125+
:guilabel:`Insert Document`.
126+
127+
#. Toggle the :guilabel:`Document Preimage` and
128+
:guilabel:`Full Document` switches to on.
129+
130+
#. Enter converted MongoDB code in the :guilabel:`Function`
131+
text field.
132+
133+
.. important::
134+
135+
Update the ``clusterName`` and ``databaseName`` in
136+
the generated Atlas code to match your cluster and
137+
database name.
138+
139+
#. Click :guilabel:`Save` to save the Atlas trigger.
140+
141+
Example
142+
-------
143+
144+
Convert a MySQL Trigger
145+
~~~~~~~~~~~~~~~~~~~~~~~
146+
147+
The following example shows a MySQL trigger converter to Atlas:
148+
149+
.. tabs::
150+
151+
.. tab:: Relational Input
152+
:tabid: sql-input-1
153+
154+
.. code-block:: sql
155+
:copyable: false
156+
157+
CREATE TRIGGER TRIGGER_UPPER_PRODUCTS
158+
BEFORE INSERT
159+
ON MYDATABASE.PRODUCTS
160+
FOR EACH ROW
161+
SET NEW.FULL_NAME = UPPER(new.FULL_NAME)
162+
163+
.. tab:: MongoDB Output
164+
:tabid: mongodb-output-1
165+
166+
.. code-block:: javascript
167+
:emphasize-lines: 14-15
168+
:copyable: false
169+
170+
// The relational database trigger has been converted to MongoDB Atlas Triggers format.
171+
// To create a trigger, open your Atlas project (https://cloud.mongodb.com) and choose Triggers
172+
// For more on Atlas triggers see the docs: https://www.mongodb.com/docs/atlas/triggers/
173+
// Create your trigger using the following settings and paste the code into the Function section:
174+
// Watch Against: Collection
175+
// Cluster Name: Ensure clusterName matches selection in Atlas Trigger configuration
176+
// Database Name: Ensure databaseName matches selection in Atlas Trigger configuration
177+
// Collection Name: products
178+
// Operation Type: Insert
179+
// Full Document: On
180+
// Document Preimage: Off
181+
182+
exports = async function(changeEvent) {
183+
const clusterName = "clusterName";
184+
const databaseName = "databaseName";
185+
186+
const { fullDocument } = changeEvent;
187+
const db = context.services.get(clusterName).db(databaseName);
188+
const collection = db.collection('products');
189+
190+
if (fullDocument && fullDocument.fullName) {
191+
fullDocument.fullName = fullDocument.fullName.toUpperCase();
192+
await collection.updateOne({ _id: fullDocument._id }, { $set: { fullName: fullDocument.fullName } });
193+
}
194+
};
195+
196+
Learn More
197+
----------
198+
199+
- :ref:`rm-convert-views`
200+
- :ref:`rm-convert-queries`
201+
- :ref:`rm-convert-stored-procedures`

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

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -15,14 +15,6 @@ stored procedures to MongoDB syntax. The query converter considers the
1515
mapping rules and schema transformations defined in your project when converting
1616
your SQL code.
1717

18-
Before you Begin
19-
----------------
20-
21-
The query converter feature is in private
22-
preview. To request private preview access, use the sign-up form within the
23-
Relational Migrator application. For instructions, see
24-
:ref:`rm-query-converter`.
25-
2618
Steps
2719
-----
2820

@@ -36,10 +28,19 @@ Steps
3628

3729
.. step:: Read the user agreement
3830

31+
.. step:: (Optional) Review telemetry preferences
32+
33+
Telemetry data about the source and converted queries are
34+
temporarily stored by MongoDB to improve the query converter
35+
feature. If you do not want your data to be stored, you have
36+
the option to opt out:
37+
38+
.. include:: /includes/fact-disable-query-converter.rst
39+
3940
.. step:: Enable the query converter feature
4041

41-
Click :guilabel:`Use Query Converter`.
42-
The :guilabel:`Query Converter` pane displays.
42+
Click :guilabel:`Start Using Query Converter`.
43+
The :guilabel:`Query Converter` pane is displayed.
4344

4445
Next Steps
4546
----------

‎source/includes/fact-data-prep-oracle-step1.rst

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
The following code creates a new Oracle service account
2+
for Relational Migrator to connect to the Oracle
3+
instance. Alternatively, you can use an existing Oracle
4+
service account to connect to Relational Migrator with
5+
the appropriate permissions.
6+
7+
a. Create a service account:
8+
9+
.. code-block:: sql
10+
:copyable: true
11+
12+
CREATE USER '<user>'@'localhost' IDENTIFIED BY '<password>';
13+
14+
#. Grant select permissions to the service account:
15+
16+
The required permission for the service account depend on whether
17+
the tables are owned by the service account used to run the sync job.
18+
To check table ownership run the following query:
19+
20+
.. code-block:: sql
21+
:copyable: true
22+
23+
SELECT TABLE_NAME, OWNER
24+
FROM ALL_TABLES
25+
WHERE TABLE_NAME ='<table_name>'
26+
ORDER BY OWNER, TABLE_NAME;
27+
28+
If the service account *is* the table owner:
29+
30+
.. code-block:: sql
31+
:copyable: true
32+
33+
GRANT CREATE SESSION TO <user>;
34+
GRANT SELECT ON V_$DATABASE TO <user>;
35+
36+
If the service account *is not* the table owner:
37+
38+
.. code-block:: sql
39+
:copyable: true
40+
41+
GRANT CREATE SESSION TO <user>;
42+
GRANT SELECT_CATALOG_ROLE TO <user>;
43+
GRANT SELECT <table> TO <user>;
44+
GRANT SELECT ON V_$DATABASE TO <user>;
45+
GRANT FLASHBACK ON <table> TO user;

0 commit comments

Comments
 (0)