Tutorial copy db

draft/tutorial/copy-database.txt

@@ -0,0 +1,126 @@
+=================================================
+Copy or Clone Database without Intermediate Files
+=================================================
+
+.. default-domain:: mongodb
+
+Sypnosis
+--------
+
+One may need to copy a :term:`database` from one server to another,
+rename a :term:`database`, or move a :term:`database` within the same
+server, seed a development server from a production server, or create
+a test environment with production data. The :program:`copyDatabase`
+and :program:`cloneDatabase` function in MongoDB can help one in these
+situations.
+
+This document oulines the procedure to copy MongoDB :term:`databases`
+using the :program:`copyDatabase` and :program:`cloneDatabase`
+command.
+
+While :program:`mongodump` and :program:`mongorestore` tools are
+available, the copy database commands are faster as there are no
+intermediate files to be created.
+
+.. warning::
+
+   Copy procedures with :program:`copyDatabase` and
+   :program:`cloneDatabase` do not lock the database, so writes may
+   still occur during the copy process at the source. This will
+   produce a destination database that is inconsistent with the source
+   database.
+
+   If your needs are for consistent database copies, consider using
+   :program:`mongodump` and :program:`mongorestore` instead. More
+   details on these programs can be found in :ref:`database dump
+   <database-dump>` and :ref:`database restore <database-restore`.
+
+Considerations
+--------------
+
+- These commands must be run on the destination server.
+
+- These commands do not work with the total data set of a :term:`shard
+  cluster`.
+
+- There must be enough free disk storage on the destination server for the
+  database from the source server.
+
+- The :program:`copyDatabase` commands may be run on a :term:`secondary`
+  member.
+
+
+Process
+-------
+
+Copy a Database from Another Server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To copy database named ``test`` on server ``db0.example.net`` to
+another server ``db1.example.net`` naming it to ``records``.
+
+- Verify name of database, ``test``, you want to copy on the source
+  server, ``db0.example.net``.
+
+- Log onto the destination server, ``db1.example.net``.
+
+- Run the following command from :program:`mongo shell` on the
+  destination server, ``db1.example.net``.
+
+.. code-block:: javascript
+
+   db.copyDatabase( test, records, db0.example.net )
+
+Copy a Database within a Server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To rename a database from ``test`` to ``records`` within the
+same server, ``db1.example.net``.
+
+- Log onto the destination server, ``db1.example.net``.
+
+- Run the following command from :program:`mongo shell` on the
+  destination server, ``db1.example.net``.
+
+.. code-block:: javascript
+
+   db.copyDatabase( test, records )
+
+Copy a Database with Authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the source server requires ``username`` and ``password``
+authentication, you can include these parameters in the
+:program:`copyDatabase` command.
+
+To copy ``test`` to ``records`` from the source server
+``db0.example.net``, which requires ``username`` and ``password``
+authentication, to ``db1.example.net`` use the following procedure.
+
+- Log onto the destination server, ``db1.example.net``.
+
+- Run the following command from :program:`mongo shell` on the
+  destination server, ``db1.example.net``.
+
+.. code-block:: javascript
+
+   db.copyDatabase( test, records, db0.example.net, username, password)
+
+Copy a Database Using CloneDatabase Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:program:`cloneDatabase` is similar to :program:`copyDatabase` but is
+limited to only copying a database from another server while
+preserving the database name.
+
+To copy a database from ``db0.example.net`` to ``db1.example.net``, on
+``db1.example.net`` follow these procedures.
+
+- Log onto the destination server, ``db1.example.net``.
+
+- Run the following command from :program:`mongo shell` on the
+  destination server, ``db1.example.net``.
+
+.. code-block:: javascript
+
+   db.cloneDatabase( db0.example.net )