moebius

# Moebius

[![Hex.pm](https://img.shields.io/hexpm/v/moebius.svg)](https://hex.pm/packages/moebius)
[![Docs](https://img.shields.io/badge/hex-docs-blue.svg)](https://hexdocs.pm/moebius)
[![CI](https://github.com/robconery/moebius/actions/workflows/elixir.yml/badge.svg)](https://github.com/robconery/moebius/actions/workflows/elixir.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**A functional query library for Elixir and PostgreSQL.** You pipe small functions together to build a query, then hand it to a database to run. You get plain maps back.

```elixir
import Moebius.Query

{:ok, users} =
  db(:users)
  |> filter(:order_count, gt: 5)
  |> sort(:last, :asc)
  |> limit(20)
  |> Moebius.Db.run()
```

Moebius is *not* an ORM. There are no schemas, no mappings and no migrations; only queries and data. It leans on PostgreSQL as hard as it can: JSONB documents, full-text search, `COPY`, cursors, savepoints and `EXPLAIN` are all a function call away.

- [Why Moebius exists](#why-moebius-exists)
- [What's new in 5.0](#whats-new-in-50)
- [Installation](#installation) and [configuration](#configuration)
- [Querying](#querying), [writing](#inserting-updating-and-deleting), [joins](#joins), [aggregates](#aggregates), [full-text search](#full-text-search)
- [Documents (JSONB)](#documents-jsonb)
- [SQL files and functions](#sql-files-and-functions)
- [Bulk loading](#bulk-loading), [streaming](#streaming-large-results), [transactions](#transactions), [EXPLAIN](#asking-postgres-how-it-will-run-a-query)
- [Types](#types), [errors](#errors) and [safety](#safety)
- [Contributing](#contributing)

## Why Moebius exists

PostgreSQL is one of the best pieces of software ever written, and most of us use about a tenth of it. It stores documents as well as any document database. It does full-text search, ranked, in any language you can find a dictionary for. It loads a hundred thousand rows in the time it takes to blink, streams results through cursors, nests transactions with savepoints, and will tell you exactly how it plans to run your query if you just ask. All of that has been sitting there for years, waiting.

The usual way in is an ORM, and an ORM's job is to stand between you and the database. That's a fine job if what you want is objects. But if what you want is *Postgres*, all of it, then every layer in the way is something you have to learn, configure, and eventually work around. I've spent more evenings than I'd like to admit fighting a mapping layer to get it to emit a query I could have typed in thirty seconds.

Elixir gives us a better option. A query is just data. A pipe is just a function handing data to the next function. So a query builder can be nothing more than a handful of small functions that each add one clause to a struct, and a database module that runs the struct when you're ready. No schemas to keep in sync, no migrations to generate, no magic to debug at 11pm. You can read the whole thing in an afternoon