|
1 | 1 | <!doctype html><html lang=en><head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1,shrink-to-fit=no"><meta http-equiv=x-ua-compatible content="ie=edge"><link rel=stylesheet href=https://actix.rs/css/bootstrap-reboot.css><link rel=stylesheet href=https://actix.rs/css/bootstrap.css><link rel=stylesheet href=https://actix.rs/css/font-awesome.min.css><link rel=stylesheet href=https://actix.rs/css/actix.css><link rel=stylesheet href=https://actix.rs/css/highlight.css><link rel=icon href=https://actix.rs/favicon.ico title=actix><title>Databases</title></head><body><header class="navbar navbar-light navbar-toggleable-md bd-navbar"><nav class=actix-main-nav><div class="d-flex justify-content-between hidden-lg-up"><a href=https://actix.rs/ class=navbar-brand><img src=https://actix.rs/img/logo-nav.png class=align-middle alt></a> |
2 | 2 | <button class="navbar-toggle collapsed" type=button data-toggle=collapse data-target=#actix-main-nav aria-label="Toggle navigation" aria-controls=actix-main-nav aria-expanded=false> |
3 | 3 | <span class=navbar-toggler-icon></span></button></div><div class="navbar-collapse collapse" id=actix-main-nav><ul class="nav navbar-nav"><li class="nav-item hd-lg-down"><a class=navbar-brand href=https://actix.rs/><img src=https://actix.rs/img/logo-nav.png class=align-middle alt></a></li><li class=nav-item><a class=nav-link href=https://actix.rs/>Home</a></li><li class=nav-item><a class=nav-link href=https://actix.rs/docs/>Documentation</a></li><li class=nav-item><a class=nav-link href=https://actix.rs/community/>Community</a></li><li class=nav-item><a class=nav-link href=https://actix.rs/code/>Code</a></li></ul></div></nav></header><div class=actix-pageheader><div class=container><h1 class=display-4>Databases</h1></div></div><div class="container actix-docs"><div class=row><div class=col-md-3><button class="btn doctoggle" type=button data-toggle=collapse data-target=#collapsing-docnav aria-expanded=false aria-controls=collapsing-docnav> |
4 | | -Toggle navigation</button><nav class="leftnav collapse show" id=collapsing-docnav><div><h5>Introduction</h5><div><ul class=nav><li><a href=https://actix.rs/docs/>Welcome</a></li><li><a href=https://actix.rs/docs/whatis/>What is Actix Web</a></li></ul></div><h5>Basics</h5><div><ul class=nav><li><a href=https://actix.rs/docs/getting-started/>Getting Started</a></li><li><a href=https://actix.rs/docs/application/>Application</a></li><li><a href=https://actix.rs/docs/server/>Server</a></li><li><a href=https://actix.rs/docs/handlers/>Handlers</a></li><li><a href=https://actix.rs/docs/extractors/>Extractors</a></li></ul></div><h5>Advanced</h5><div><ul class=nav><li><a href=https://actix.rs/docs/errors/>Errors</a></li><li><a href=https://actix.rs/docs/url-dispatch/>URL Dispatch</a></li><li><a href=https://actix.rs/docs/request/>Requests</a></li><li><a href=https://actix.rs/docs/response/>Responses</a></li><li><a href=https://actix.rs/docs/testing/>Testing</a></li><li><a href=https://actix.rs/docs/middleware/>Middleware</a></li><li><a href=https://actix.rs/docs/static-files/>Static Files</a></li></ul></div><h5>Protocols</h5><div><ul class=nav><li><a href=https://actix.rs/docs/websockets/>Websockets</a></li><li><a href=https://actix.rs/docs/http2/>HTTP/2</a></li></ul></div><h5>Patterns</h5><div><ul class=nav><li><a href=https://actix.rs/docs/autoreload/>Auto-Reloading</a></li><li class=active><a href=https://actix.rs/docs/databases/>Databases</a></li></ul></div><h5>Diagrams</h5><div><ul class=nav><li><a href=https://actix.rs/docs/http_server_init/>HTTP Server Initialization</a></li><li><a href=https://actix.rs/docs/conn_lifecycle/>Connection Lifecycle</a></li></ul></div><h5>API Documentation</h5><div><ul class=nav><li><a href=https://docs.rs/actix target=view_window>actix <span class="fa fa-external-link"></span></a></li><li><a href=https://docs.rs/actix-web/ target=view_window>actix-web <span class="fa fa-external-link"></span></a></li></ul></div></div></nav></div><div class=col-md-9><div class=actix-content><h1 id=async-options>Async Options</h1><p>We have several example projects showing use of async database adapters:</p><ul><li>Postgres: <a href=https://github.com/actix/examples/tree/master/databases/postgres>https://github.com/actix/examples/tree/master/databases/postgres</a></li><li>SQLite: <a href=https://github.com/actix/examples/tree/master/databases/sqlite>https://github.com/actix/examples/tree/master/databases/sqlite</a></li><li>MongoDB: <a href=https://github.com/actix/examples/tree/master/databases/mongodb>https://github.com/actix/examples/tree/master/databases/mongodb</a></li></ul><h1 id=diesel>Diesel</h1><p>The current version of Diesel (v1) does not support asynchronous operations, so it is important to use the <a href=https://docs.rs/actix-web/3/actix_web/web/fn.block.html><code>web::block</code></a> function to offload your database operations to the Actix runtime thread-pool.</p><p>You can create action functions that correspond to all the operations your app will perform on the database.</p><div class=highlight><pre class=chroma><code class=language-rust data-lang=rust><span class=k>fn</span> <span class=nf>insert_new_user</span><span class=p>(</span><span class=n>db</span>: <span class=kp>&</span><span class=nc>SqliteConnection</span><span class=p>,</span><span class=w> </span><span class=n>user</span>: <span class=nc>CreateUser</span><span class=p>)</span><span class=w> </span>-> <span class=nb>Result</span><span class=o><</span><span class=n>User</span><span class=p>,</span><span class=w> </span><span class=n>Error</span><span class=o>></span><span class=w> </span><span class=p>{</span><span class=w> |
| 4 | +Toggle navigation</button><nav class="leftnav collapse show" id=collapsing-docnav><div><h5>Introduction</h5><div><ul class=nav><li><a href=https://actix.rs/docs/>Welcome</a></li><li><a href=https://actix.rs/docs/whatis/>What is Actix Web</a></li></ul></div><h5>Basics</h5><div><ul class=nav><li><a href=https://actix.rs/docs/getting-started/>Getting Started</a></li><li><a href=https://actix.rs/docs/application/>Application</a></li><li><a href=https://actix.rs/docs/server/>Server</a></li><li><a href=https://actix.rs/docs/handlers/>Handlers</a></li><li><a href=https://actix.rs/docs/extractors/>Extractors</a></li></ul></div><h5>Advanced</h5><div><ul class=nav><li><a href=https://actix.rs/docs/errors/>Errors</a></li><li><a href=https://actix.rs/docs/url-dispatch/>URL Dispatch</a></li><li><a href=https://actix.rs/docs/request/>Requests</a></li><li><a href=https://actix.rs/docs/response/>Responses</a></li><li><a href=https://actix.rs/docs/testing/>Testing</a></li><li><a href=https://actix.rs/docs/middleware/>Middleware</a></li><li><a href=https://actix.rs/docs/static-files/>Static Files</a></li></ul></div><h5>Protocols</h5><div><ul class=nav><li><a href=https://actix.rs/docs/websockets/>Websockets</a></li><li><a href=https://actix.rs/docs/http2/>HTTP/2</a></li></ul></div><h5>Patterns</h5><div><ul class=nav><li><a href=https://actix.rs/docs/autoreload/>Auto-Reloading</a></li><li class=active><a href=https://actix.rs/docs/databases/>Databases</a></li></ul></div><h5>Diagrams</h5><div><ul class=nav><li><a href=https://actix.rs/docs/http_server_init/>HTTP Server Initialization</a></li><li><a href=https://actix.rs/docs/conn_lifecycle/>Connection Lifecycle</a></li></ul></div><h5>API Documentation</h5><div><ul class=nav><li><a href=https://docs.rs/actix target=view_window>actix <span class="fa fa-external-link"></span></a></li><li><a href=https://docs.rs/actix-web/ target=view_window>actix-web <span class="fa fa-external-link"></span></a></li></ul></div></div></nav></div><div class=col-md-9><div class=actix-content><h1 id=async-options>Async Options</h1><p>We have several example projects showing use of async database adapters:</p><ul><li>Postgres: <a href=https://github.com/actix/examples/tree/master/databases/postgres>https://github.com/actix/examples/tree/master/databases/postgres</a></li><li>SQLite: <a href=https://github.com/actix/examples/tree/master/databases/sqlite>https://github.com/actix/examples/tree/master/databases/sqlite</a></li><li>MongoDB: <a href=https://github.com/actix/examples/tree/master/databases/mongodb>https://github.com/actix/examples/tree/master/databases/mongodb</a></li></ul><h1 id=diesel>Diesel</h1><p>The current version of Diesel (v1) does not support asynchronous operations, so it is important to use the <a href=https://docs.rs/actix-web/4/actix_web/web/fn.block.html><code>web::block</code></a> function to offload your database operations to the Actix runtime thread-pool.</p><p>You can create action functions that correspond to all the operations your app will perform on the database.</p><div class=highlight><pre class=chroma><code class=language-rust data-lang=rust><span class=k>fn</span> <span class=nf>insert_new_user</span><span class=p>(</span><span class=n>db</span>: <span class=kp>&</span><span class=nc>SqliteConnection</span><span class=p>,</span><span class=w> </span><span class=n>user</span>: <span class=nc>CreateUser</span><span class=p>)</span><span class=w> </span>-> <span class=nb>Result</span><span class=o><</span><span class=n>User</span><span class=p>,</span><span class=w> </span><span class=n>Error</span><span class=o>></span><span class=w> </span><span class=p>{</span><span class=w> |
5 | 5 | </span><span class=w> </span><span class=k>use</span><span class=w> </span><span class=bp>self</span>::<span class=n>schema</span>::<span class=n>users</span>::<span class=n>dsl</span>::<span class=o>*</span><span class=p>;</span><span class=w> |
6 | 6 | </span><span class=w> |
7 | 7 | </span><span class=w> </span><span class=c1>// Create insertion model |
|
42 | 42 | </span><span class=w> </span><span class=p>.</span><span class=n>run</span><span class=p>()</span><span class=w> |
43 | 43 | </span><span class=w> </span><span class=p>.</span><span class=k>await</span><span class=w> |
44 | 44 | </span><span class=w></span><span class=p>}</span><span class=w> |
45 | | -</span></code></pre></div><p>Now, in a request handler, use the <code>Data<T></code> extractor to get the pool from app state and get a connection from it. This provides an owned database connection that can be passed into a <a href=https://docs.rs/actix-web/3/actix_web/web/fn.block.html><code>web::block</code></a> closure. Then just call the action function with the necessary arguments and <code>.await</code> the result.</p><p>This example also maps the error to an <code>HttpResponse</code> before using the <code>?</code> operator but this is not necessary if your return error type implements <a href=https://docs.rs/actix-web/3/actix_web/trait.ResponseError.html><code>ResponseError</code></a>.</p><div class=highlight><pre class=chroma><code class=language-rust data-lang=rust><span class=k>async</span><span class=w> </span><span class=k>fn</span> <span class=nf>index</span><span class=p>(</span><span class=n>pool</span>: <span class=nc>web</span>::<span class=n>Data</span><span class=o><</span><span class=n>DbPool</span><span class=o>></span><span class=p>,</span><span class=w> </span><span class=n>name</span>: <span class=nc>web</span>::<span class=n>Path</span><span class=o><</span><span class=p>(</span><span class=nb>String</span><span class=p>)</span><span class=o>></span><span class=p>)</span><span class=w> </span>-> <span class=nc>impl</span><span class=w> </span><span class=n>Responder</span><span class=w> </span><span class=p>{</span><span class=w> |
| 45 | +</span></code></pre></div><p>Now, in a request handler, use the <code>Data<T></code> extractor to get the pool from app state and get a connection from it. This provides an owned database connection that can be passed into a <a href=https://docs.rs/actix-web/4/actix_web/web/fn.block.html><code>web::block</code></a> closure. Then just call the action function with the necessary arguments and <code>.await</code> the result.</p><p>This example also maps the error to an <code>HttpResponse</code> before using the <code>?</code> operator but this is not necessary if your return error type implements <a href=https://docs.rs/actix-web/4/actix_web/trait.ResponseError.html><code>ResponseError</code></a>.</p><div class=highlight><pre class=chroma><code class=language-rust data-lang=rust><span class=k>async</span><span class=w> </span><span class=k>fn</span> <span class=nf>index</span><span class=p>(</span><span class=n>pool</span>: <span class=nc>web</span>::<span class=n>Data</span><span class=o><</span><span class=n>DbPool</span><span class=o>></span><span class=p>,</span><span class=w> </span><span class=n>name</span>: <span class=nc>web</span>::<span class=n>Path</span><span class=o><</span><span class=p>(</span><span class=nb>String</span><span class=p>)</span><span class=o>></span><span class=p>)</span><span class=w> </span>-> <span class=nc>impl</span><span class=w> </span><span class=n>Responder</span><span class=w> </span><span class=p>{</span><span class=w> |
46 | 46 | </span><span class=w> </span><span class=kd>let</span><span class=w> </span><span class=n>name</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>name</span><span class=p>.</span><span class=n>into_inner</span><span class=p>();</span><span class=w> |
47 | 47 | </span><span class=w> |
48 | 48 | </span><span class=w> </span><span class=kd>let</span><span class=w> </span><span class=n>conn</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>pool</span><span class=p>.</span><span class=n>get</span><span class=p>().</span><span class=n>expect</span><span class=p>(</span><span class=s>"couldn't get db connection from pool"</span><span class=p>);</span><span class=w> |
|
0 commit comments