README.md (7313B)
1 <img width="250" src="https://github.com/elixir-ecto/ecto/raw/master/guides/images/logo.png" alt="Ecto"> 2 3 --- 4 5 [](https://github.com/elixir-ecto/ecto/actions) [](https://hex.pm/packages/ecto) [](https://hexdocs.pm/ecto/) 6 7 ## Installation 8 9 Add `:ecto` to the list of dependencies in `mix.exs`: 10 11 ```elixir 12 def deps do 13 [ 14 {:ecto, "~> 3.8"} 15 ] 16 end 17 ``` 18 19 ## About 20 21 Ecto is a toolkit for data mapping and language integrated query for Elixir. Here is an example: 22 23 ```elixir 24 # In your config/config.exs file 25 config :my_app, ecto_repos: [Sample.Repo] 26 27 config :my_app, Sample.Repo, 28 database: "ecto_simple", 29 username: "postgres", 30 password: "postgres", 31 hostname: "localhost", 32 port: "5432" 33 34 # In your application code 35 defmodule Sample.Repo do 36 use Ecto.Repo, 37 otp_app: :my_app, 38 adapter: Ecto.Adapters.Postgres 39 end 40 41 defmodule Sample.Weather do 42 use Ecto.Schema 43 44 schema "weather" do 45 field :city # Defaults to type :string 46 field :temp_lo, :integer 47 field :temp_hi, :integer 48 field :prcp, :float, default: 0.0 49 end 50 end 51 52 defmodule Sample.App do 53 import Ecto.Query 54 alias Sample.{Weather, Repo} 55 56 def keyword_query do 57 query = 58 from w in Weather, 59 where: w.prcp > 0 or is_nil(w.prcp), 60 select: w 61 62 Repo.all(query) 63 end 64 65 def pipe_query do 66 Weather 67 |> where(city: "Kraków") 68 |> order_by(:temp_lo) 69 |> limit(10) 70 |> Repo.all 71 end 72 end 73 ``` 74 75 Ecto is commonly used to interact with databases, such as PostgreSQL and MySQL via [Ecto.Adapters.SQL](https://hexdocs.pm/ecto_sql) ([source code](https://github.com/elixir-ecto/ecto_sql)). Ecto is also commonly used to map data from any source into Elixir structs, whether they are backed by a database or not. 76 77 See the [getting started guide](https://hexdocs.pm/ecto/getting-started.html) and the [online documentation](https://hexdocs.pm/ecto) for more information. Other resources available are: 78 79 * [Programming Ecto](https://pragprog.com/book/wmecto/programming-ecto), by Darin Wilson and Eric Meadows-Jönsson, which guides you from fundamentals up to advanced concepts 80 81 * [The Little Ecto Cookbook](https://dashbit.co/ebooks/the-little-ecto-cookbook), a free ebook by Dashbit, which is a curation of the existing Ecto guides with some extra contents 82 83 ## Usage 84 85 You need to add both Ecto and the database adapter as a dependency to your `mix.exs` file. The supported databases and their adapters are: 86 87 | Database | Ecto Adapter | Dependencies | 88 | :--------- | :--------------------- | :------------------------------------------------------------------------ | 89 | PostgreSQL | Ecto.Adapters.Postgres | [ecto_sql][ecto_sql] (requires Ecto v3.0+) + [postgrex][postgrex] | 90 | MySQL | Ecto.Adapters.MyXQL | [ecto_sql][ecto_sql] (requires Ecto v3.3+) + [myxql][myxql] | 91 | MSSQL | Ecto.Adapters.Tds | [ecto_sql][ecto_sql] (requires Ecto v3.4+) + [tds][tds] | 92 | SQLite3 | Ecto.Adapters.SQLite3 | [ecto_sql][ecto_sql] (requires Ecto v3.5+) + [ecto_sqlite3][ecto_sqlite3] | 93 | ETS | Etso | [ecto][ecto] + [etso][etso] | 94 95 [ecto]: https://github.com/elixir-ecto/ecto 96 [ecto_sql]: https://github.com/elixir-ecto/ecto_sql 97 [postgrex]: https://github.com/elixir-ecto/postgrex 98 [myxql]: https://github.com/elixir-ecto/myxql 99 [tds]: https://github.com/livehelpnow/tds 100 [ecto_sqlite3]: https://github.com/elixir-sqlite/ecto_sqlite3 101 [etso]: https://github.com/evadne/etso 102 103 For example, if you want to use PostgreSQL, add to your `mix.exs` file: 104 105 ```elixir 106 defp deps do 107 [ 108 {:ecto_sql, "~> 3.0"}, 109 {:postgrex, ">= 0.0.0"} 110 ] 111 end 112 ``` 113 114 Then run `mix deps.get` in your shell to fetch the dependencies. If you want to use another database, just choose the proper dependency from the table above. 115 116 Finally, in the repository definition, you will need to specify the `adapter:` respective to the chosen dependency. For PostgreSQL it is: 117 118 ```elixir 119 defmodule MyApp.Repo do 120 use Ecto.Repo, 121 otp_app: :my_app, 122 adapter: Ecto.Adapters.Postgres, 123 ... 124 ``` 125 126 ## Supported Versions 127 128 | Branch | Support | 129 | ------ | ------------------------ | 130 | v3.7 | Bug fixes | 131 | v3.6 | Security patches only | 132 | v3.5 | Security patches only | 133 | v3.4 | Security patches only | 134 | v3.3 | Security patches only | 135 | v3.2 | Unsupported from 02/2022 | 136 | v3.1 | Unsupported from 02/2020 | 137 | v3.0 | Unsupported from 02/2020 | 138 | v2.2 | Unsupported from 02/2022 | 139 | v2.1 | Unsupported from 10/2018 | 140 | v2.0 | Unsupported from 08/2017 | 141 | v1.1 | Unsupported from 03/2018 | 142 | v1.0 | Unsupported from 05/2017 | 143 144 With version 3.0, Ecto API has become stable. Our main focus is on providing 145 bug fixes and incremental changes. 146 147 ## Important links 148 149 * [Documentation](https://hexdocs.pm/ecto) 150 * [Mailing list](https://groups.google.com/forum/#!forum/elixir-ecto) 151 * [Examples](https://github.com/elixir-ecto/ecto/tree/master/examples) 152 153 ## Running tests 154 155 Clone the repo and fetch its dependencies: 156 157 $ git clone https://github.com/elixir-ecto/ecto.git 158 $ cd ecto 159 $ mix deps.get 160 $ mix test 161 162 Note that `mix test` does not run the tests in the `integration_test` folder. To run integration tests, you can clone `ecto_sql` in a sibling directory and then run its integration tests with the `ECTO_PATH` environment variable pointing to your Ecto checkout: 163 164 $ cd .. 165 $ git clone https://github.com/elixir-ecto/ecto_sql.git 166 $ cd ecto_sql 167 $ mix deps.get 168 $ ECTO_PATH=../ecto mix test.all 169 170 ### Running containerized tests 171 172 It is also possible to run the integration tests under a containerized environment using [earthly](https://earthly.dev/get-earthly): 173 174 $ earthly -P +all 175 176 You can also use this to interactively debug any failing integration tests using: 177 178 $ earthly -P -i --build-arg ELIXIR_BASE=1.8.2-erlang-21.3.8.21-alpine-3.13.1 +integration-test 179 180 Then once you enter the containerized shell, you can inspect the underlying databases with the respective commands: 181 182 PGPASSWORD=postgres psql -h 127.0.0.1 -U postgres -d postgres ecto_test 183 MYSQL_PASSWORD=root mysql -h 127.0.0.1 -uroot -proot ecto_test 184 sqlcmd -U sa -P 'some!Password' 185 186 ## Logo 187 188 "Ecto" and the Ecto logo are Copyright (c) 2020 Dashbit. 189 190 The Ecto logo was designed by [Dane Wesolko](https://www.danewesolko.com). 191 192 ## License 193 194 Copyright (c) 2013 Plataformatec \ 195 Copyright (c) 2020 Dashbit 196 197 Licensed under the Apache License, Version 2.0 (the "License"); 198 you may not use this file except in compliance with the License. 199 You may obtain a copy of the License at [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0) 200 201 Unless required by applicable law or agreed to in writing, software 202 distributed under the License is distributed on an "AS IS" BASIS, 203 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 204 See the License for the specific language governing permissions and 205 limitations under the License.