*************************
Getting Started (Sinatra)
*************************

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol


New Application
===============

This section shows how to create a new Sinatra application using Mongoid
for data access. The process is similar for other Ruby applications not
using Ruby on Rails.

The complete source code for this application is available `in the
mongoid-demo GitHub repository
<https://github.com/mongoid/mongoid-demo/tree/master/sinatra-minimal>`_.

Create Git Repo
---------------

While not required, we recommend creating a Git repository for your application:

.. code-block:: sh

    git init blog
    cd blog

Commit your changes as you are following this tutorial.


Create Gemfile
--------------

Create a file named ``Gemfile`` with the following contents:

.. code-block:: ruby

    source 'https://rubygems.org'

    gem 'sinatra', '~> 2.0'
    gem 'mongoid', '~> 7.0'


Install Dependencies
--------------------

Run the following commands to install the dependencies:

.. code-block:: sh

    gem install bundler
    bundle install

This command will generate a file named ``Gemfile.lock`` which we recommend
committing to your Git repository.


Run MongoDB Locally
-------------------

To develop locally with MongoDB, `download and install MongoDB
<https://mongodb.com/docs/manual/installation/>`_.

Once MongoDB is installed and running, create a file named ``config/mongoid.yml``
pointing to your deployment. For example, if you launched a standalone
``mongod`` on the default port, the following contents would be appropriate:

.. code-block:: none

    development:
      clients:
        default:
          database: blog_development
          hosts:
            - localhost:27017
          options:
            server_selection_timeout: 1


Use MongoDB Atlas
-----------------

Instead of downloading, installing and running MongoDB locally, you can create
a free MongoDB Atlas account and create a `free MongoDB cluster in Atlas
<https://mongodb.com/docs/manual/tutorial/atlas-free-tier-setup/>`_.
Once the cluster is created, follow the instructions in `connect to the cluster
page <https://docs.atlas.mongodb.com/connect-to-cluster/#connect-to-a-cluster>`_
to obtain the URI. Use the *Ruby driver 2.5 or later* format.

Create a file named ``config/mongoid.yml`` with the following
contents, replacing the URI with the actual URI for your cluster:

.. code-block:: yaml

    development:
      clients:
        default:
          uri: mongodb+srv://user:pass@yourcluster.mongodb.net/blog_development?retryWrites=true&w=majority
          options:
            server_selection_timeout: 5



Basic Application
-----------------

Create a file named ``app.rb`` with the following contents. First, some
requires:

.. code-block:: ruby

    require 'sinatra'
    require 'mongoid'

Load the Mongoid configuration file and configure Mongoid. This is done
automatically when Mongoid is used with Rails, but since we are using Mongoid
with Sinatra, we need to do this ourselves:

.. code-block:: ruby

    Mongoid.load!(File.join(File.dirname(__FILE__), 'config', 'mongoid.yml'))

Now we can define some models:

.. code-block:: ruby

    class Post
      include Mongoid::Document

      field :title, type: String
      field :body, type: String

      has_many :comments
    end

    class Comment
      include Mongoid::Document

      field :name, type: String
      field :message, type: String

      belongs_to :post
    end

... and add some routes:

.. code-block:: ruby

    get '/posts' do
      Post.all.to_json
    end

    post '/posts' do
      post = Post.create!(params[:post])
      post.to_json
    end

    get '/posts/:post_id' do |post_id|
      post = Post.find(post_id)
      post.attributes.merge(
        comments: post.comments,
      ).to_json
    end

    post '/posts/:post_id/comments' do |post_id|
      post = Post.find(post_id)
      comment = post.comments.create!(params[:comment])
      {}.to_json
    end


Run Application
===============

Launch the application:

.. code-block:: sh

    bundle exec ruby app.rb

Try some requests via curl:

.. code-block:: sh

    curl http://localhost:4567/posts
    # => []

    curl -d 'post[title]=hello&post[body]=hello+world' http://localhost:4567/posts
    # => {"_id":{"$oid":"5d8151ec96fb4f0ed5a7a03f"},"body":"hello world","title":"hello"}

    curl http://localhost:4567/posts
    # => [{"_id":{"_id":{"$oid":"5d8151ec96fb4f0ed5a7a03f"},"body":"hello world","title":"hello"}]

    curl -d 'comment[name]=David&comment[message]=I+like' http://localhost:4567/posts/5d8151ec96fb4f0ed5a7a03f/comments
    # => {}

    curl http://localhost:4567/posts/5d8151ec96fb4f0ed5a7a03f
    # => {"_id":{"$oid":"5d8151ec96fb4f0ed5a7a03f"},"title":"hello","body":"hello world","comments":[{"_id":{"$oid":"5d8157ac96fb4f20c5e45c4d"},"message":"I like","name":"David","post_id":{"$oid":"5d8151ec96fb4f0ed5a7a03f"}}]}


Existing Application
====================

To start using Mongoid in an existing Sinatra applications, the steps are
essentially the same as the one given above for a new application:

1. Add the ``mongoid`` dependency to the ``Gemfile``.
2. Create a ``mongoid.yml`` configuration file.
3. Load the configuration file and configure Mongoid in the application.
4. Define Mongoid models.