# Implementing an Object Relational Mapper

If you've been building your database connection and Models manually, you could upgrade your toolset by introducing an ORM.

This document is intended as a scaffold to help you setup DataMapper in a Sinatra project. It is not a walkthrough, or a guide, but should help you to navigate the ActiveRecord documentation and get to a working implementation.

## Considerations

### Benefits of using an ORM

- Built in tools for managing migrations
- Built in methods for interacting with the database
- Avoids having to embed SQL queries into Ruby code
- Quicker implementation of models

### Common pitfalls

- Can be difficult to setup for the first time
- Hides the complexity of database interactions making debugging harder

## Getting Started

### Adding Dependencies

At this stage you need to think about what tools you'll need to introduce to the project to start using DataMapper.

You'll need to think about how you're going to interact with DataMapper in your codebase, and also how DataMapper will interact with the database.

- Where can you find information about getting started in the DataMapper documentation?
- What dependencies do you need to install?
- How do you add dependencies to Ruby projects?

### Connecting to the development database

Make sure you can connect to the development database using DataMapper when running your code locally.

- Where you should you write the code to connect to the database?
- Where should this code be run?
- How do you connect to a database in DataMapper?
- What is the URL of the database? How can you find this out?

Hint! Your database should be running on `localhost` e.g. `postgresql://localhost/my_database_development`

The [postgresql docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) do give some guidance, but it's difficult to work out the exact format without some prior knowledge.

### Connecting to the test database

When you're running tests, you'll want to connect to the test database.

- When do you need to check the environment to find out which database to connect to?
- What is a good way to check the environment to code is running in? *(Hint: think about environment variables)*
- How can you make sure that the right database URL is used when DataMapper connects to the test database?

### Defining your first model

Choose which Model you are going to re-write (or create) using DataMapper.

- How do you create Models using DataMapper?
- What are properties? What do they correspond to in the database?
- What data type should each property be? Explore the DataMapper documentation to find out what data types are available for Model properties

It's best to stick to a simple model without associations initially, but think about creating associations once you have at least two Models setup.

### Finalize & Migrate

Once you have created a Model, you'll need to make sure that these are finalized and migrated every time you connect to the database.

- In which file should the finalize and migrate steps be called?
- What does each of these steps do?
- How can you verify the success of the model creation and migration?
- What is the difference between migrate and upgrade?

### Create a resource

Now you're ready to try creating a resource with the new Model. Update your controller in line with the DataMapper guidane.

- What does creating a new resource return?
- Has the resource been created in the database?
- What is the difference between `create` and `new`?

## Useful Resources

[DataMapper](https://datamapper.org/)
[Postgresql](https://www.postgresql.org/docs/11/index.html)

### Note
It should be possible to migrate your models to DataMapper individually, but I haven't had a chane to verify this! Approach with caution 🚧

###### tags: `databases` `relational databases` `practical` `makersbnb`