Skip to content

DOCSP-36792: Add default database connection admonition #2888

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Apr 24, 2024
Merged

DOCSP-36792: Add default database connection admonition #2888

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8a4ff94
DOCSP-36792: DB_CONNECTION configuration for facades
norareidy Apr 19, 2024
9afca8e
wording, add link
norareidy Apr 19, 2024
d388d9e
move tip to query builders
norareidy Apr 19, 2024
969e338
describe options
norareidy Apr 22, 2024
75b6fc9
remove env
norareidy Apr 22, 2024
1e510fd
AB feedback
norareidy Apr 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/query-builder.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,14 @@ The following example shows the syntax of a query builder call:
DB::collection('<collection name>')
// chain methods by using the "->" object operator
->get();
.. tip::

Before using the ``DB::collection()`` method, ensure that you specify MongoDB as your application's
default database connection. For instructions on setting the database connection,
see the :ref:`laravel-quick-start-connect-to-mongodb` step in the Quick Start.

If MongoDB is not your application's default database, you can use the ``DB::connection()`` method
to specify a MongoDB connection. Pass a value of ``"mongodb"`` to the ``connection()`` method.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should mention that one should pass the connection name (for which we use "mongodb" in our examples). Also, I suggest using a code snippet for this purpose:

Suggested change
If MongoDB is not your application's default database, you can use the ``DB::connection()`` method
to specify a MongoDB connection. Pass a value of ``"mongodb"`` to the ``connection()`` method.
If MongoDB is not your application's default database, you can use the ``DB::connection()`` method
to specify a MongoDB connection. Pass a the name of the connection to the ``connection()`` method:
.. code-block:: php
$connection = DB::connection('mongodb');


This guide provides examples of the following types of query builder operations:

Expand Down
4 changes: 2 additions & 2 deletions docs/quick-start/configure-mongodb.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Configure Your MongoDB Connection

.. code-block:: php

'default' => env('DB_CONNECTION', 'mongodb'),
'default' => 'mongodb',
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If people want to update their default connection, it might be in the env var DB_CONNECTION in the .env file.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line should set the default connection to MongoDB even if the DB_CONNECTION variable is set to something else in .env. But I updated the admonition (in query-builder.txt) to give two options on how to set MongoDB as the connection, if that helps clarify

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I remain convinced that this is the not the right way to change the default connection. @alcaeus any opinion?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Laravel's default configuration uses env variables, and I agree that we shouldn't deviate too far from this.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, I changed these code snippets back to using env variables. Since we don't explain the .env file or its variables in the quick start, I made a ticket to add this info.


Add the following highlighted ``mongodb`` entry to the ``connections`` array
in the same file. Replace the ``<connection string>`` placeholder with the
Expand All @@ -35,7 +35,7 @@ Configure Your MongoDB Connection
'connections' => [
'mongodb' => [
'driver' => 'mongodb',
'dsn' => env('DB_URI', '<connection string>'),
'dsn' => '<connection string>',
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As the connection string is likely to differ between environments (e.g. dev, staging, prod), we should stick with the Laravel default of providing this in an environment variable.

Suggested change
'dsn' => '<connection string>',
'dsn' => env('DB_URI', '<connection string>'),

'database' => 'sample_mflix',
],

Expand Down