CINXE.COM

<!doctype html> <html lang="en"> <head> <title>DB Migration | Docs | 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"> <title>Create All DDL | Docs | Ebean</title> </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><span class="last">DB migrations</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 "> <a href="/docs/intro">Introduction</a> </li> <li class="nav0 active"> <a class="active" href="/docs">Documentation</a> <ul> <li class="nav1 "> <a href="/docs/best-practice">Best practice</a> </li> <li class="nav1 "> <a href="/docs/query">Query</a> </li> <li class="nav1 "> <a href="/docs/persist">Persist</a> </li> <li class="nav1 "> <a href="/docs/transactions">Transactions</a> </li> <li class="nav1 "> <a href="/docs/mapping">Mapping</a> </li> <li class="nav1 active"> <a class="active" href="/docs/ddl-generation">DDL & Migrations</a> <ul> <li class="nav1 "> <a href="/docs/ddl-generation">DDL Generation</a> </li> <li class="nav1 "> <a href="/docs/extra-ddl">Extra DDL</a> </li> <li class="nav1 active"> <a class="active" href="/docs/db-migrations">DB Migrations</a> <ul class="nav nav-scroll"> <li > <a href="#dependencies">Dependencies</a> </li> <li > <a href="#generate">Generate a Migration</a> </li> <li > <a href="#run">Run migrations</a> </li> </ul> </li> <li class="nav1 "> <a href="/docs/db-migrations/detail">DB Migrations details</a> </li> </ul> </li> <li class="nav1 "> <a href="/docs/logging">Logging</a> </li> <li class="nav1 "> <a href="/docs/testing">Testing</a> </li> <li class="nav1 "> <a href="/docs/read-replicas">Read Replicas</a> </li> <li class="nav1 "> <a href="/docs/database">Database platforms</a> </li> <li class="nav1 "> <a href="/docs/multi-database">Multiple databases</a> </li> <li class="nav1 "> <a href="/docs/kotlin">Kotlin</a> </li> <li><a href="/docs/tuning">Tuning</a></li> <li class="nav1 "> <a href="/docs/features">Features</a> </li> </ul> </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="db-migrations">DB Migrations</h2> <p> DB Migrations are DDL changes that are applied typically when the application is started. </p> <p> Ebean can generate the migrations for us by performing a <code>diff</code> on the model and then generating database platform specific DDL for the change. </p> <p> Ebean can also run the migrations (similar to FlywayDb). It is recommended to use Ebean's built in migration runner rather than <code>FlywayDb</code> or <code>LiquiBase</code>. </p> <h2 id="dependencies">Dependencies</h2> <p> Add either ebean-test as a test scope dependency (which includes ebean-ddl-generator and other dependencies). </p> <div class="syntax xml"><div class="highlight"><pre><span></span><span class="nt"><dependency></span> <span class="nt"><groupId></span>io.ebean<span class="nt"></groupId></span> <span class="nt"><artifactId></span>ebean-test<span class="nt"></artifactId></span> <span class="nt"><version></span>14.1.0<span class="nt"></version></span> <span class="nt"><scope></span>test<span class="nt"></scope></span> <span class="nt"></dependency></span> </pre></div> </div> <p> OR add ebean-ddl-generator as a test scope dependency. </p> <div class="syntax xml"><div class="highlight"><pre><span></span><span class="nt"><dependency></span> <span class="nt"><groupId></span>io.ebean<span class="nt"></groupId></span> <span class="nt"><artifactId></span>ebean-test<span class="nt"></artifactId></span> <span class="nt"><version></span>14.1.0<span class="nt"></version></span> <span class="nt"><scope></span>test<span class="nt"></scope></span> <span class="nt"></dependency></span> </pre></div> </div> <h2 id="generate">Generate a Migration</h2> <p> In <code>src/test/java</code> add code to generate migrations. This first example generates database migrations for a single database platform - Postgres in this example. </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="kn">package</span> <span class="nn">main</span><span class="o">;</span> <span class="kn">import</span> <span class="nn">io.ebean.annotation.Platform</span><span class="o">;</span> <span class="kn">import</span> <span class="nn">io.ebean.dbmigration.DbMigration</span><span class="o">;</span> <span class="kn">import</span> <span class="nn">java.io.IOException</span><span class="o">;</span> <span class="kd">public</span> <span class="kd">class</span> <span class="nc">MigrationGenerator</span> <span class="o">{</span> <span class="cm">/**</span> <span class="cm"> * Generate the next "DB schema DIFF" migration.</span> <span class="cm"> */</span> <span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">IOException</span> <span class="o">{</span> <span class="n">DbMigration</span> <span class="n">dbMigration</span> <span class="o">=</span> <span class="n">DbMigration</span><span class="o">.</span><span class="na">create</span><span class="o">();</span> <span class="n">dbMigration</span><span class="o">.</span><span class="na">setPlatform</span><span class="o">(</span><span class="n">Platform</span><span class="o">.</span><span class="na">POSTGRES</span><span class="o">);</span> <span class="n">dbMigration</span><span class="o">.</span><span class="na">generateMigration</span><span class="o">();</span> <span class="o">}</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">import</span> <span class="nn">io.ebean.annotation.Platform</span> <span class="k">import</span> <span class="nn">io.ebean.dbmigration.DbMigration</span> <span class="k">fun</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="n">DbMigration</span><span class="p">.</span><span class="n">create</span><span class="p">().</span><span class="n">apply</span> <span class="p">{</span> <span class="n">setPlatform</span><span class="p">(</span><span class="n">Platform</span><span class="p">.</span><span class="n">POSTGRES</span><span class="p">)</span> <span class="p">}.</span><span class="n">generateMigration</span><span class="p">()</span> <span class="p">}</span> </pre></div> </div> </div> <h3 id="multi-generation">Multi-platform migration generation</h3> <p> To generate migrations for multiple different database platforms we use <code>addPlatform()</code> for each platform we want to generate migrations for. In the below example we generate migrations for Postgres, SqlServer and MySql. </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="o">...</span> <span class="kd">public</span> <span class="kd">class</span> <span class="nc">MigrationGenerator</span> <span class="o">{</span> <span class="cm">/**</span> <span class="cm"> * Generate the next "DB schema DIFF" migration.</span> <span class="cm"> */</span> <span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">IOException</span> <span class="o">{</span> <span class="n">DbMigration</span> <span class="n">dbMigration</span> <span class="o">=</span> <span class="n">DbMigration</span><span class="o">.</span><span class="na">create</span><span class="o">();</span> <span class="n">dbMigration</span><span class="o">.</span><span class="na">addPlatform</span><span class="o">(</span><span class="n">Platform</span><span class="o">.</span><span class="na">POSTGRES</span><span class="o">);</span> <span class="n">dbMigration</span><span class="o">.</span><span class="na">addPlatform</span><span class="o">(</span><span class="n">Platform</span><span class="o">.</span><span class="na">SQLSERVER17</span><span class="o">);</span> <span class="n">dbMigration</span><span class="o">.</span><span class="na">addPlatform</span><span class="o">(</span><span class="n">Platform</span><span class="o">.</span><span class="na">MYSQL</span><span class="o">);</span> <span class="n">dbMigration</span><span class="o">.</span><span class="na">generateMigration</span><span class="o">();</span> <span class="o">}</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="p">...</span> <span class="k">fun</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="n">DbMigration</span><span class="p">.</span><span class="n">create</span><span class="p">().</span><span class="n">apply</span> <span class="p">{</span> <span class="n">addPlatform</span><span class="p">(</span><span class="n">Platform</span><span class="p">.</span><span class="n">POSTGRES</span><span class="p">)</span> <span class="n">addPlatform</span><span class="p">(</span><span class="n">Platform</span><span class="p">.</span><span class="n">SQLSERVER17</span><span class="p">)</span> <span class="n">addPlatform</span><span class="p">(</span><span class="n">Platform</span><span class="p">.</span><span class="n">MYSQL</span><span class="p">)</span> <span class="p">}.</span><span class="n">generateMigration</span><span class="p">()</span> <span class="p">}</span> </pre></div> </div> </div> <p> Run the main method to generate the database migration. If nothing has changed then no migration will be generated. If the model has changed then the database migration is generated for the DIFF to the model. </p> <p> Running the generation starts Ebean in offline mode (we do not need a database running to generate the migration). Ebean performs a DIFF to the model and generates the migration DDL script(s) for the platforms that we specified. </p> <p> By default the generated migrations go into <code>src/main/resources/dbmigration</code>. </p> <h2 id="run">Running migrations</h2> <p> To get Ebean to run the DB migrations on startup: </p> <h4>1. Set <code>ebean.migration.run</code> to true</h4> <h5>Via properties - e.g. application.properties</h5> <div class="syntax properties"><div class="highlight"><pre><span></span><span class="c">## run migrations when the Ebean starts</span> <span class="na">ebean.migration.run</span><span class="o">=</span><span class="s">true</span> </pre></div> </div> <h5>Via yaml - e.g. application.yaml</h5> <div class="syntax yml"><div class="highlight"><pre><span></span><span class="c1">## run migrations when the Ebean starts</span> <span class="nt">ebean</span><span class="p">:</span> <span class="nt">migration</span><span class="p">:</span> <span class="nt">run</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">true</span> </pre></div> </div> <h4>2. Add ebean-migration dependency</h4> <p> Add <code>io.ebean:ebean-migration</code> as a dependency if it is not already. </p> <div class="syntax xml"><div class="highlight"><pre><span></span><span class="nt"><dependency></span> <span class="nt"><groupId></span>io.ebean<span class="nt"></groupId></span> <span class="nt"><artifactId></span>ebean-migration<span class="nt"></artifactId></span> <span class="nt"><version></span>13.6.0<span class="nt"></version></span> <span class="nt"></dependency></span> </pre></div> </div> <p> With <code>ebean.migration.run=true</code> then when Ebean starts it will look at the migrations and run any that need to be run. The migration runner will by default create a table called <code>db_migration</code> that holds the metadata about the migrations that have been run and inserts into this table when migrations are successfully executed. </p> <nav class="next"> <p class="next"> <a href="/docs/db-migrations/detail" class="btn">Next: DB Migration details</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>