README.md (3718B)
1 # DBConnection 2 3 Database connection behaviour and database connection pool designed for 4 handling transaction, prepare/execute, cursors and client process 5 describe/encode/decode. 6 7 Examples of using the `DBConnection` behaviour are available in 8 `./examples/db_agent/` and `./examples/tcp_connection/`. 9 10 There is also [a series of articles on building database adapters](http://blog.plataformatec.com.br/2018/11/building-a-new-mysql-adapter-for-ecto-part-i-hello-world/). It includes articles covering both DBConnection and Ecto integrations. 11 12 ## Contributing 13 14 Run unit tests with: 15 16 $ mix test 17 18 To run the integration tests (for each available pool): 19 20 $ mix test.pools 21 22 To run all tests: 23 24 $ mix test.all 25 26 ## Design 27 28 This library is made of four main modules: 29 30 * `DBConnection` - this is the code running on the client 31 and the specification of the DBConnection API 32 33 * `DBConnection.Connection` - this is the process that 34 establishes the database connection 35 36 * `DBConnection.ConnectionPool` - this is the connection 37 pool. A client asks the connection pool for a connection. 38 There is also an ownership pool, used mostly during tests, 39 which we won't discuss here. 40 41 * `DBConnection.Holder` - the holder is responsible for 42 keeping the connection and checkout state. It is modelled 43 by using an ETS table. 44 45 Once a connection is created, it creates a holder and 46 assigns the connection pool as the heir. Then the holder 47 is promptly given away to the pool. The connection itself 48 is mostly a dummy. It is there to handle connections and pings. 49 The state itself (such as the socket) is all in the holder. 50 51 Once there is a checkout, the pool gives the holder to the 52 client process and stores all relevant information in the 53 holder table itself. If the client terminates without 54 checking in, then the holder is given back to the pool via 55 the heir mechanism. The pool will then discard the connection. 56 57 One important design detail in DBConnection is that it avoids 58 copying data. Other database libraries would send a request 59 to the connection process, perform the query in the connection 60 process, and then send it back to the client. This means a lot of 61 data copying in Elixir. DBConnection keeps the socket in the 62 holder and works on it directly. 63 64 DBConnection also takes all of the care necessary to handle 65 failures, and it shuts down the connection and the socket 66 whenever the client does not check in the connection to avoid 67 recycling sockets/connections in a corrupted state (such as a socket 68 that is stuck inside a transaction). 69 70 ### Deadlines 71 72 When a checkout happens, a deadline is started by the client 73 to send a message to the pool after a time interval. If the 74 deadline is reached and the connection is still checked out, 75 the holder is deleted and the connection is terminated. If the 76 client tries to use a terminated connection, an error will 77 be raised (see `Holder.handle/4`). 78 79 ### Pool 80 81 The queuing algorithm used by the pool is [CoDel](https://queue.acm.org/appendices/codel.html) 82 which allows us to plan for overloads and reject requests 83 without clogging the pool once checkouts do not read a certain 84 target. 85 86 ## License 87 88 Copyright 2015 James Fish 89 90 Licensed under the Apache License, Version 2.0 (the "License"); 91 you may not use this file except in compliance with the License. 92 You may obtain a copy of the License at 93 94 http://www.apache.org/licenses/LICENSE-2.0 95 96 Unless required by applicable law or agreed to in writing, software 97 distributed under the License is distributed on an "AS IS" BASIS, 98 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 99 See the License for the specific language governing permissions and 100 limitations under the License.