CINXE.COM

<!doctype html> <html lang="en"> <head> <title>Database & DB | Intro | Ebean</title> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"> <link rel="shortcut icon" href="/images/favicon.ico"> <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto|Source+Sans+Pro|Ubuntu&display=swap"> <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.1.0/css/all.css" integrity="sha384-lKuwvrZot6UHsBSfcMvOkWwlCMgc0TaWr+30HWe3a4ltaBwTZhyTEggF5tJv8tbt" crossorigin="anonymous"> <link rel="stylesheet" href="/css/reset3.css"> <link rel="stylesheet" href="/css/site3.css"> <link rel="stylesheet" href="/css/pygments3.css"> </head> <body> <div id="main"> <div id="banner"> <header> <nav id="top"> <h1 id="breadcrumb"> <a class="nav-logo" href="/"><img src="/images/logo-200.png" height="35"></a>  <a href="/docs">Documentation</a><span class="sep"> / </span><a href="/docs/intro/">Introduction</a><span class="sep"> / </span><span class="last">Database & DB</span> </h1> <ul> <li><a onclick="toggleTheme();" title="switch dark light theme"><i class="fas fa-adjust"></i></a></li> </ul> </nav> </header> </div> <div class="grid grid-docs"> <aside> <nav class="side"> <ul> <li class="nav0 "> <a href="/docs/getting-started">Getting started</a> </li> <li class="nav0 active"> <a class="active" href="/docs/intro">Introduction</a> <ul> <li class="nav1 active"> <a class="active" href="/docs/intro/database">Database & DB</a> <ul class="nav nav-scroll"> <li > <a href="#database">Database</a> </li> <li > <a href="#db">DB</a> </li> <li > <a href="#ebeanserver">EbeanServer</a> </li> <li > <a href="#ebean">Ebean</a> </li> </ul> </li> <li class="nav1 "> <a href="/docs/intro/configuration">Configuration</a> </li> <li class="nav1 "> <a href="/docs/intro/first-entity">First entity</a> </li> <li class="nav1 "> <a href="/docs/intro/queries">Queries</a> </li> <li class="nav1 "> <a href="/docs/intro/logging">Logging</a> </li> <li class="nav1 "> <a href="/docs/intro/db-migrations">DB Migrations</a> </li> <li class="nav1 "> <a href="/docs/intro/limitations">Limitations</a> </li> <li class="nav1 "> <a href="/docs/trouble-shooting">Trouble shooting</a> </li> </ul> </li> <li class="nav0 "> <a href="/docs">Documentation</a> </li> <li class="nav0 "> <a href="/support">Getting help</a> </li> <li class="nav0 "> <a target="_blank" href="/apidoc/13">API Javadoc</a> </li> <li class="nav0 "> <a href="/videos">Videos</a> </li> <li class="nav0 "> <a href="/docs/upgrading">Upgrading</a> </li> <li class="nav0 "> <a href="/releases">Releases</a> </li> </ul> </nav> </aside> <article> <form action="https://www.google.com/search" method="get" class="inline-form"> <input type="hidden" name="as_sitesearch" value="ebean.io"> <div id="page-search"> <div class="input-group"> <input class="frm" name="q" id="searchinput" type="text" placeholder="Search... (press 's' to focus)" data-placeholder-focus="Search... (use '↑', '↓' and '⏎' to select results)" data-placeholder-blur="Search... (press 's' to focus)" autocomplete="off"> <div class="input-group-btn"> <button class="frm" type="submit"><i class="fas fa-search"></i></button> </div> </div> <div id="page-search-results" style="display: none;"> <ul id="search-results-container" class="search-results"><li class=" active"><a href="/docs" title="Docs"><span style="color:#777;">Docs</span> Documentation </a></li><li class=""><small style="color:#999;">And 101 more...</small></li></ul> </div> </div> </form> <h2 id="database">Database</h2> <p> <code>io.ebean.Database</code> provides most of the functionality including queries, saving, deleting and transactions. </p> <ul class="code nav nav-tabs mytabs"> <li role="presentation" class="javaActive active"><a onclick="setLang('java');">java</a></li> <li role="presentation" class="kotlinActive"><a onclick="setLang('kt');">kotlin</a></li> </ul> <div class="code-java"> <div class="syntax java"><div class="highlight"><pre><span></span><span class="c1">// persist ...</span> <span class="n">Customer</span> <span class="n">customer</span> <span class="o">=</span> <span class="o">...</span> <span class="n">database</span><span class="o">.</span><span class="na">save</span><span class="o">(</span><span class="n">customer</span><span class="o">);</span> <span class="c1">// fetch ...</span> <span class="n">List</span><span class="o"><</span><span class="n">Customer</span><span class="o">></span> <span class="n">customers</span> <span class="o">=</span> <span class="n">database</span><span class="o">.</span><span class="na">find</span><span class="o">(</span><span class="n">Customer</span><span class="o">.</span><span class="na">class</span><span class="o">)</span> <span class="o">.</span><span class="na">findList</span><span class="o">();</span> <span class="c1">// transactions ...</span> <span class="k">try</span> <span class="o">(</span><span class="n">Transaction</span> <span class="n">transaction</span> <span class="o">=</span> <span class="n">database</span><span class="o">.</span><span class="na">beginTransaction</span><span class="o">())</span> <span class="o">{</span> <span class="c1">// fetch and persist beans etc ...</span> <span class="n">transaction</span><span class="o">.</span><span class="na">commit</span><span class="o">();</span> <span class="o">}</span> </pre></div> </div> </div> <div class="code-kt"> <div class="syntax java"><div class="highlight"><pre><span></span><span class="c1">// persist ...</span> <span class="k">val</span> <span class="n">customer</span> <span class="o">=</span> <span class="o">...</span> <span class="n">database</span><span class="o">.</span><span class="na">save</span><span class="o">(</span><span class="n">customer</span><span class="o">)</span> <span class="c1">// fetch ...</span> <span class="k">val</span> <span class="n">customers</span> <span class="o">=</span> <span class="n">database</span><span class="o">.</span><span class="na">find</span><span class="o">(</span><span class="n">Customer</span><span class="o">::</span><span class="n">class</span><span class="o">.</span><span class="na">java</span><span class="o">)</span> <span class="o">.</span><span class="na">findList</span><span class="o">()</span> <span class="c1">// transactions ...</span> <span class="n">database</span><span class="o">.</span><span class="na">beginTransaction</span><span class="o">().</span><span class="na">use</span> <span class="o">{</span> <span class="n">transaction</span> <span class="o">-></span> <span class="c1">// fetch and persist beans etc ...</span> <span class="n">transaction</span><span class="o">.</span><span class="na">commit</span><span class="o">();</span> <span class="o">}</span> </pre></div> </div> </div> <h3>javax.sql.DataSource</h3> <p> A Database instance has an JDBC DataSource associating it one to one to an actual database. </p> <p> Note that a Database can have a second read only DataSource that can be used for performance reasons (for read only queries) and potentially connect to database read replicas. </p> <h3 id="default">Default database</h3> <p> One database can be specified as the <code>default database</code>. The default Database instance is registered with <code>DB</code> and then can be obtained via <code>DB.getDefault()</code>. </p> <div class="code-java"> <div class="syntax java"><div class="highlight"><pre><span></span><span class="c1">// obtain the "default" database</span> <span class="n">Database</span> <span class="n">database</span> <span class="o">=</span> <span class="n">DB</span><span class="o">.</span><span class="na">getDefault</span><span class="o">();</span> </pre></div> </div> </div> <div class="code-kt"> <div class="syntax kotlin"><div class="highlight"><pre><span></span><span class="c1">// obtain the "default" database</span> <span class="k">val</span> <span class="py">database</span> <span class="p">=</span> <span class="n">DB</span><span class="p">.</span><span class="n">getDefault</span><span class="p">()</span> </pre></div> </div> </div> <h3>Named database</h3> <p> Each Database instance has a name and can be registered with <code>DB</code> and then obtained by it's name via <code>DB.byName()</code> </p> <ul class="code nav nav-tabs mytabs"> <li role="presentation" class="javaActive active"><a onclick="setLang('java');">java</a></li> <li role="presentation" class="kotlinActive"><a onclick="setLang('kt');">kotlin</a></li> </ul> <div class="code-java"> <div class="syntax java"><div class="highlight"><pre><span></span><span class="c1">// obtain a database by it's name</span> <span class="n">Database</span> <span class="n">hrDatabase</span> <span class="o">=</span> <span class="n">DB</span><span class="o">.</span><span class="na">byName</span><span class="o">(</span><span class="s">"hr"</span><span class="o">);</span> </pre></div> </div> </div> <div class="code-kt"> <div class="syntax kotlin"><div class="highlight"><pre><span></span><span class="c1">// obtain a database by it's name</span> <span class="k">val</span> <span class="py">hrDatabase</span> <span class="p">=</span> <span class="n">DB</span><span class="p">.</span><span class="n">byName</span><span class="p">(</span><span class="s">"hr"</span><span class="p">)</span> </pre></div> </div> </div> <h3>Model uses default database</h3> <p> When our entity beans extend <a href="/docs/intro/first-entity/model">Model</a> and we use <em>save()</em> that is actually using the default database. </p> <ul class="code nav nav-tabs mytabs"> <li role="presentation" class="javaActive active"><a onclick="setLang('java');">java</a></li> <li role="presentation" class="kotlinActive"><a onclick="setLang('kt');">kotlin</a></li> </ul> <div class="code-java"> <div class="syntax java"><div class="highlight"><pre><span></span><span class="n">Customer</span> <span class="n">customer</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Customer</span><span class="o">(</span><span class="s">"Roberto"</span><span class="o">)</span> <span class="c1">// use the default database</span> <span class="n">customer</span><span class="o">.</span><span class="na">save</span><span class="o">()</span> </pre></div> </div> </div> <div class="code-kt"> <div class="syntax kotlin"><div class="highlight"><pre><span></span><span class="k">val</span> <span class="py">customer</span> <span class="p">=</span> <span class="n">Customer</span><span class="p">(</span><span class="s">"Roberto"</span><span class="p">)</span> <span class="c1">// use the default database</span> <span class="n">customer</span><span class="p">.</span><span class="n">save</span><span class="p">()</span> </pre></div> </div> </div> <h3>Query beans use default database</h3> <p> When we create a Query bean and execute the query that also is actually using the default database. </p> <ul class="code nav nav-tabs mytabs"> <li role="presentation" class="javaActive active"><a onclick="setLang('java');">java</a></li> <li role="presentation" class="kotlinActive"><a onclick="setLang('kt');">kotlin</a></li> </ul> <div class="code-java"> <div class="syntax java"><div class="highlight"><pre><span></span><span class="c1">// use the default database</span> <span class="n">List</span><span class="o"><</span><span class="n">Customer</span><span class="o">></span> <span class="n">customers</span> <span class="o">=</span> <span class="k">new</span> <span class="n">QCustomer</span><span class="o">()</span> <span class="o">.</span><span class="na field">status</span><span class="o">.</span><span class="na">equalTo</span><span class="o">(</span><span class="n">Status</span><span class="o">.</span><span class="na">NEW</span><span class="o">)</span> <span class="o">.</span><span class="na field">billingAddress</span><span class="o">.</span><span class="na field">city</span><span class="o">.</span><span class="na">equalTo</span><span class="o">(</span><span class="s">"Auckland"</span><span class="o">)</span> <span class="o">.</span><span class="na">findList</span><span class="o">();</span> </pre></div> </div> </div> <div class="code-kt"> <div class="syntax kotlin"><div class="highlight"><pre><span></span><span class="c1">// use the default database</span> <span class="k">val</span> <span class="py">customers</span> <span class="p">=</span> <span class="n">QCustomer</span><span class="p">()</span> <span class="p">.</span><span class="n field">status</span><span class="p">.</span><span class="n">equalTo</span><span class="p">(</span><span class="n">Status</span><span class="p">.</span><span class="n">NEW</span><span class="p">)</span> <span class="p">.</span><span class="n field">billingAddress</span><span class="p">.</span><span class="n field">city</span><span class="p">.</span><span class="n">equalTo</span><span class="p">(</span><span class="s">"Auckland"</span><span class="p">)</span> <span class="p">.</span><span class="n">findList</span><span class="p">()</span> </pre></div> </div> </div> <p class="mtm"> Note that in practice when using <a href="/docs/intro/first-entity/model">Model</a> for persisting , <a href="/docs/query/query-beans">Query beans</a> for entity queries and <a href="/docs/transactions">@Transactional</a> for transactions then we tend to only use database directly for <a href="/docs/query/dtoquery">DTO queries</a>, <a href="/docs/query/sqlquery">SQL queries</a> and <a href="/docs/query/sqlupdate">SQL updates</a>. </p> <h3>Configuration</h3> <p> Details for <a href="/docs/intro/configuration">configuration</a> of database instances programmatically and via properties is in the next section. </p> <p> </p> <h2 id="db" class="tg">DB (io.ebean.DB)</h2> <ul> <li>DB holds a <b>registry</b> of database instances (keyed by name)</li> <li>DB holds one Database instance known as the <b>default database</b></li> <li>DB has <b>convenience</b> methods to operate on the default database</li> </ul> <p> </p> <h3>Obtain default or named database instance</h3> <p> When an Database instance is created it can be registered with DB. We can then use <code>DB</code> to obtain those Database instances by name and we can obtain the default database via <code>DB.getDefault()</code>. </p> <div class="code-java"> <div class="syntax java"><div class="highlight"><pre><span></span><span class="c1">// obtain the "default" database</span> <span class="n">Database</span> <span class="n">server</span> <span class="o">=</span> <span class="n">DB</span><span class="o">.</span><span class="na">getDefault</span><span class="o">();</span> <span class="c1">// obtain the HR database by name</span> <span class="n">Database</span> <span class="n">hrDB</span> <span class="o">=</span> <span class="n">DB</span><span class="o">.</span><span class="na">byName</span><span class="o">(</span><span class="s">"hr"</span><span class="o">);</span> </pre></div> </div> </div> <h3>DB convenience methods</h3> <p> DB has convenience methods that effectively proxy through to the default database. This is useful and convenient as many applications only use a single database. </p> <div class="code-java"> <div class="syntax java"><div class="highlight"><pre><span></span><span class="n">Customer</span> <span class="n">customer</span> <span class="o">=</span> <span class="o">...</span> <span class="c1">// save using the 'default' database</span> <span class="n">DB</span><span class="o">.</span><span class="na">save</span><span class="o">(</span><span class="n">customer</span><span class="o">);</span> <span class="c1">// which is the same as</span> <span class="n">Database</span> <span class="n">defaultDatabase</span> <span class="o">=</span> <span class="n">DB</span><span class="o">.</span><span class="na">getDefault</span><span class="o">()</span> <span class="n">defaultDatabase</span><span class="o">.</span><span class="na">save</span><span class="o">(</span><span class="n">customer</span><span class="o">);</span> </pre></div> </div> </div> <h3>DB is optional</h3> <p> Note that you don't have to use the DB singleton in your application at all - it's use is completely optional. Instead we can create the Database instance(s) and <code>inject</code> them where needed. We typically do this using <code>Spring</code> or <code>Guice</code> or a similar DI framework. </p> <p> We can do both and have Database instances registered with DB and the DI Context and in this way access the database instance(s) either way. </p> <h2 id="ebeanserver">EbeanServer</h2> <p> Database and EbeanServer are the same thing. </p> <p> <code>io.ebean.EbeanServer</code> is the older original name for <code>io.ebean.Database</code>. They can be used interchangably. In time EbeanServer will be deprecated and code should migrate to use io.ebean.Database. </p> <h2 id="ebean">Ebean</h2> <p> DB and Ebean are the same thing. </p> <p> <code>io.ebean.Ebean</code> is the older original name for <code>io.ebean.DB</code>. They can be used interchangeably. In time use of Ebean will be deprecated and code should migrate to use io.ebean.DB. </p> <nav class="next"> <p class="edit-page"> <a href="https://github.com/ebean-orm/website-source/blob/master/docs/intro/database/index.html"><i class="fab fa-github"></i> Edit Page</a> </p> <p class="next"> <a href="/docs/intro/configuration" class="btn btn-info">Next: Configuration</a> </p> </nav> </article> </div> </div> <script src="https://code.jquery.com/jquery-3.4.1.slim.min.js" integrity="sha384-J6qa4849blE2+poT4WnyKhv5vZF5SrPo0iEjwBvKU7imGFAV0wwj1yYfoRSJoZ+n" crossorigin="anonymous"></script> <script src="/js/site3.js"></script> <script src="/js/search3.js"></script> <script async src="https://www.googletagmanager.com/gtag/js?id=UA-75181644-1"></script> <script> window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-75181644-1'); </script> </body> </html>