Clear ORM
  • Welcome to Clear
  • Introduction
    • Setup
  • Model
    • Defining your model
      • Describing your columns
      • Primary Keys
      • Converters
    • Associations
      • belongs_to
      • has_many
      • has_many through
      • has_one
    • Lifecycle
      • Persistence
      • Validations
      • Triggers
    • Batchs operations
      • Bulk update
      • Bulk insert & delete
    • Transactions & Save Points
      • Transaction & Savepoints
      • Connection pool
    • Locks
  • Querying
    • The collection object
      • Filter the query
        • Filter the query – The Expression Engine
        • Find, First, Last, Offset, Limit
        • Aggregation
        • Ordering & Group by
      • Fetching the query
        • Each and Fetch
        • Cursored fetching
        • Model extra attributes
      • Joins
      • Eager Loading
      • Window and CTE
      • Scopes
    • Writing low-level SQL
      • Select Clause
      • Insert Clause
      • Delete Clause
  • Migrations
    • Manage migrations
    • Call migration script
    • Migration CLI
  • Additional and advanced features
    • JSONB
    • Symbol vs String
    • Enums
    • BCrypt
    • Full Text Search
    • Handling multi-connection
  • Other resources
    • API Documentation
    • Inline documentation
    • Github repository
    • Credits
    • Benchmark
Powered by GitBook
On this page
  • Setup: As new project
  • Setup: In existing project
  • In `shard.yml`
  • In your source code
  • Installation customization
  1. Introduction

Setup

PreviousWelcome to ClearNextDefining your model

Last updated 5 years ago

Setup: As new project

Clear offers a CLI (Command Line Interface) which is still in Alpha. Documentation for building a new project with Clear + will be written once the feature is done. As of now, you can just follow the paragraph below.

Setup: In existing project

$ crystal init app <yourappname>
$ cd <yourappname>

In `shard.yml`

Add your dependency in the dependencies list of your shard.yml

dependencies:
  clear:
    github: anykeyh/clear
    branch: master

Then download the library:

$ shards install

In your source code

Assuming your main entry point of your application is src/main.cr , you can require and initialize Clear:

# append to your require list on top:
require "clear"

# initialize a pool of database connection:
Clear::SQL.init("postgres://postgres@localhost/my_database", 
    connection_pool_size: 5)

Step by Step

  • require "clear" load the source code of Clear and provide everything needed to use the library.

  • Clear::SQL.init prepare a certain number of connection to your database. The URL is a convention used to connect to the database, and follow this schema:

postgres://USER[:PASSWORD]@HOST/DATABASE[?*OPTIONS]
  • connection_pool_size: 5 is optional but offers the possibility to concurrent fibers to run query at the same time. It's useful if you use an event-driven server, like Kemal.

Installation customization

You may want to install a smaller version of Clear by calling :

require "clear/core"

This will add clear without the build-in CLI and without some extensions (jsonb, bcrypt etc...).

More information about the URL notation can be found

Kemal
here