GOMODULES/goose
1
0
Fork 0
mirror of https://github.com/pressly/goose.git synced 2025-07-11 13:08:39 +00:00
Code Issues Packages Projects Releases Wiki Activity
goose/documentation/provider/index.html

2122 lines
48 KiB
HTML
Raw Permalink Blame History

<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="The missing goose docs.">
<link rel="canonical" href="https://pressly.github.io/goose/documentation/provider/">
<link rel="prev" href="../annotations/">
<link rel="next" href="../cli-commands/">
<link rel="alternate" type="application/rss+xml" title="RSS feed" href="../../feed_rss_created.xml">
<link rel="alternate" type="application/rss+xml" title="RSS feed of updated content" href="../../feed_rss_updated.xml">
<link rel="icon" href="../../assets/goose_logo_cropped.png">
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.5.45+insiders-4.53.14">
<title>Goose provider - pressly/goose</title>
<link rel="stylesheet" href="../../assets/stylesheets/main.12320a83.min.css">
<link rel="stylesheet" href="../../assets/stylesheets/palette.ab4e12ef.min.css">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
<style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
<link rel="stylesheet" href="../../stylesheets/extra.css">
<script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
<meta property="og:type" content="website" />
<meta property="og:title" content="Goose provider - pressly/goose" />
<meta property="og:description" content="The missing goose docs." />
<meta property="og:image" content="https://pressly.github.io/goose/assets/images/social/documentation/provider.png" />
<meta property="og:image:type" content="image/png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:url" content="https://pressly.github.io/goose/documentation/provider/" />
<meta property="twitter:card" content="summary_large_image" />
<meta property="twitter:title" content="Goose provider - pressly/goose" />
<meta property="twitter:description" content="The missing goose docs." />
<meta property="twitter:image" content="https://pressly.github.io/goose/assets/images/social/documentation/provider.png" />
</head>
<body dir="ltr" data-md-color-scheme="default" data-md-color-primary="white" data-md-color-accent="light-blue">
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#goose-provider" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<header class="md-header" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href="../.." title="pressly/goose" class="md-header__button md-logo" aria-label="pressly/goose" data-md-component="logo">
<img src="../../assets/goose_logo.png" alt="logo">
</a>
<label class="md-header__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
pressly/goose
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
Goose provider
</span>
</div>
</div>
</div>
<label class="md-header__button md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
</label>
<div class="md-search" data-md-component="search" role="dialog">
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
<label class="md-search__icon md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
</label>
<nav class="md-search__options" aria-label="Search">
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>
</button>
</nav>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
<div class="md-search-result" data-md-component="search-result">
<div class="md-search-result__meta">
Initializing search
</div>
<ol class="md-search-result__list" role="presentation"></ol>
</div>
</div>
</div>
</div>
</div>
<div class="md-header__source">
<a href="https://github.com/pressly/goose" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81"/></svg>
</div>
<div class="md-source__repository">
pressly/goose
</div>
</a>
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<nav class="md-tabs" aria-label="Tabs" data-md-component="tabs">
<div class="md-grid">
<ul class="md-tabs__list">
<li class="md-tabs__item">
<a href="../.." class="md-tabs__link">
Getting Started
</a>
</li>
<li class="md-tabs__item md-tabs__item--active">
<a href="../annotations/" class="md-tabs__link">
Documentation
</a>
</li>
<li class="md-tabs__item">
<a href="../../blog/" class="md-tabs__link">
Blog
</a>
</li>
</ul>
</div>
</nav>
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary md-nav--lifted" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href="../.." title="pressly/goose" class="md-nav__button md-logo" aria-label="pressly/goose" data-md-component="logo">
<img src="../../assets/goose_logo.png" alt="logo">
</a>
pressly/goose
</label>
<div class="md-nav__source">
<a href="https://github.com/pressly/goose" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81"/></svg>
</div>
<div class="md-source__repository">
pressly/goose
</div>
</a>
</div>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_1" >
<div class="md-nav__link md-nav__container">
<a href="../.." class="md-nav__link ">
<span class="md-ellipsis">
Getting Started
</span>
</a>
<label class="md-nav__link " for="__nav_1" id="__nav_1_label" tabindex="0">
<span class="md-nav__icon md-icon"></span>
</label>
</div>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_1_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_1">
<span class="md-nav__icon md-icon"></span>
Getting Started
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../installation/" class="md-nav__link">
<span class="md-ellipsis">
Installation
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2" checked>
<label class="md-nav__link" for="__nav_2" id="__nav_2_label" tabindex="">
<span class="md-ellipsis">
Documentation
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_2">
<span class="md-nav__icon md-icon"></span>
Documentation
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_2_1" >
<label class="md-nav__link" for="__nav_2_1" id="__nav_2_1_label" tabindex="">
<span class="md-ellipsis">
Concepts
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_2_1_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_2_1">
<span class="md-nav__icon md-icon"></span>
Concepts
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../annotations/" class="md-nav__link">
<span class="md-ellipsis">
SQL file annotations
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2_2" checked>
<label class="md-nav__link" for="__nav_2_2" id="__nav_2_2_label" tabindex="">
<span class="md-ellipsis">
Library
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_2_2_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_2_2">
<span class="md-nav__icon md-icon"></span>
Library
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc">
<span class="md-ellipsis">
Goose provider
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
<span class="md-ellipsis">
Goose provider
</span>
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#provider" class="md-nav__link">
<span class="md-ellipsis">
Provider
</span>
</a>
<nav class="md-nav" aria-label="Provider">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#dialect" class="md-nav__link">
<span class="md-ellipsis">
Dialect
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#db" class="md-nav__link">
<span class="md-ellipsis">
db
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#fsys" class="md-nav__link">
<span class="md-ellipsis">
fsys
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#provider-options" class="md-nav__link">
<span class="md-ellipsis">
Provider Options
</span>
</a>
<nav class="md-nav" aria-label="Provider Options">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#withstore" class="md-nav__link">
<span class="md-ellipsis">
WithStore
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#withverbose" class="md-nav__link">
<span class="md-ellipsis">
WithVerbose
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#withsessionlocker" class="md-nav__link">
<span class="md-ellipsis">
WithSessionLocker
</span>
</a>
<nav class="md-nav" aria-label="WithSessionLocker">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#postgres" class="md-nav__link">
<span class="md-ellipsis">
Postgres
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#withexcludenames" class="md-nav__link">
<span class="md-ellipsis">
WithExcludeNames
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#withexcludeversions" class="md-nav__link">
<span class="md-ellipsis">
WithExcludeVersions
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#withgomigrations" class="md-nav__link">
<span class="md-ellipsis">
WithGoMigrations
</span>
</a>
<nav class="md-nav" aria-label="WithGoMigrations">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#newgomigration" class="md-nav__link">
<span class="md-ellipsis">
NewGoMigration
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#withdisableglobalregistry" class="md-nav__link">
<span class="md-ellipsis">
WithDisableGlobalRegistry
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#withallowoutoforder" class="md-nav__link">
<span class="md-ellipsis">
WithAllowOutofOrder
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#withdisableversioning" class="md-nav__link">
<span class="md-ellipsis">
WithDisableVersioning
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_2_3" >
<label class="md-nav__link" for="__nav_2_3" id="__nav_2_3_label" tabindex="">
<span class="md-ellipsis">
CLI
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_2_3_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_2_3">
<span class="md-nav__icon md-icon"></span>
CLI
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../cli-commands/" class="md-nav__link">
<span class="md-ellipsis">
Commands
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../environment-variables/" class="md-nav__link">
<span class="md-ellipsis">
Environment variables
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_2_4" >
<label class="md-nav__link" for="__nav_2_4" id="__nav_2_4_label" tabindex="">
<span class="md-ellipsis">
Guides
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_2_4_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_2_4">
<span class="md-nav__icon md-icon"></span>
Guides
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../custom-store/" class="md-nav__link">
<span class="md-ellipsis">
Custom store
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_3" >
<div class="md-nav__link md-nav__container">
<a href="../../blog/" class="md-nav__link ">
<span class="md-ellipsis">
Blog
</span>
</a>
<label class="md-nav__link " for="__nav_3" id="__nav_3_label" tabindex="0">
<span class="md-nav__icon md-icon"></span>
</label>
</div>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3">
<span class="md-nav__icon md-icon"></span>
Blog
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_3_2" >
<label class="md-nav__link" for="__nav_3_2" id="__nav_3_2_label" tabindex="0">
<span class="md-ellipsis">
Archive
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_2_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_2">
<span class="md-nav__icon md-icon"></span>
Archive
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../blog/archive/2024/" class="md-nav__link">
<span class="md-ellipsis">
2024
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../blog/archive/2023/" class="md-nav__link">
<span class="md-ellipsis">
2023
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../blog/archive/2022/" class="md-nav__link">
<span class="md-ellipsis">
2022
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../blog/archive/2021/" class="md-nav__link">
<span class="md-ellipsis">
2021
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle md-toggle--indeterminate" type="checkbox" id="__nav_3_3" >
<label class="md-nav__link" for="__nav_3_3" id="__nav_3_3_label" tabindex="0">
<span class="md-ellipsis">
Categories
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_3_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_3">
<span class="md-nav__icon md-icon"></span>
Categories
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../blog/category/blog/" class="md-nav__link">
<span class="md-ellipsis">
Blog
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../blog/category/clickhouse/" class="md-nav__link">
<span class="md-ellipsis">
ClickHouse
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../blog/category/general/" class="md-nav__link">
<span class="md-ellipsis">
General
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../blog/category/go-migrations/" class="md-nav__link">
<span class="md-ellipsis">
Go migrations
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../blog/category/package/" class="md-nav__link">
<span class="md-ellipsis">
Package
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../blog/category/sql-migrations/" class="md-nav__link">
<span class="md-ellipsis">
SQL migrations
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../blog/category/testing/" class="md-nav__link">
<span class="md-ellipsis">
Testing
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#provider" class="md-nav__link">
<span class="md-ellipsis">
Provider
</span>
</a>
<nav class="md-nav" aria-label="Provider">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#dialect" class="md-nav__link">
<span class="md-ellipsis">
Dialect
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#db" class="md-nav__link">
<span class="md-ellipsis">
db
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#fsys" class="md-nav__link">
<span class="md-ellipsis">
fsys
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#provider-options" class="md-nav__link">
<span class="md-ellipsis">
Provider Options
</span>
</a>
<nav class="md-nav" aria-label="Provider Options">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#withstore" class="md-nav__link">
<span class="md-ellipsis">
WithStore
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#withverbose" class="md-nav__link">
<span class="md-ellipsis">
WithVerbose
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#withsessionlocker" class="md-nav__link">
<span class="md-ellipsis">
WithSessionLocker
</span>
</a>
<nav class="md-nav" aria-label="WithSessionLocker">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#postgres" class="md-nav__link">
<span class="md-ellipsis">
Postgres
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#withexcludenames" class="md-nav__link">
<span class="md-ellipsis">
WithExcludeNames
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#withexcludeversions" class="md-nav__link">
<span class="md-ellipsis">
WithExcludeVersions
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#withgomigrations" class="md-nav__link">
<span class="md-ellipsis">
WithGoMigrations
</span>
</a>
<nav class="md-nav" aria-label="WithGoMigrations">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#newgomigration" class="md-nav__link">
<span class="md-ellipsis">
NewGoMigration
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#withdisableglobalregistry" class="md-nav__link">
<span class="md-ellipsis">
WithDisableGlobalRegistry
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#withallowoutoforder" class="md-nav__link">
<span class="md-ellipsis">
WithAllowOutofOrder
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#withdisableversioning" class="md-nav__link">
<span class="md-ellipsis">
WithDisableVersioning
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<h1 id="goose-provider">Goose provider</h1>
<p>The <a href="https://pkg.go.dev/github.com/pressly/goose/v3#Provider">Provider</a> type is the entry point for
the goose library. It initializes the state and provides methods to run migrations. It does not have
global state, so you can create multiple providers with different configurations.</p>
<p>Initialize a provider by calling <code>goose.NewProvider()</code>:</p>
<div class="highlight"><pre><span></span><code><span class="kd">func</span><span class="w"> </span><span class="nx">NewProvider</span><span class="p">(</span>
<span class="w"> </span><span class="nx">dialect</span><span class="w"> </span><span class="nx">Dialect</span><span class="p">,</span>
<span class="w"> </span><span class="nx">db</span><span class="w"> </span><span class="o">*</span><span class="nx">sql</span><span class="p">.</span><span class="nx">DB</span><span class="p">,</span>
<span class="w"> </span><span class="nx">fsys</span><span class="w"> </span><span class="nx">fs</span><span class="p">.</span><span class="nx">FS</span><span class="p">,</span>
<span class="w"> </span><span class="nx">opts</span><span class="w"> </span><span class="o">...</span><span class="nx">ProviderOption</span><span class="p">,</span>
<span class="p">)</span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="nx">Provider</span><span class="p">,</span><span class="w"> </span><span class="kt">error</span><span class="p">){</span>
<span class="w"> </span><span class="c1">// ...</span>
<span class="p">}</span>
</code></pre></div>
<h2 id="provider">Provider</h2>
<h4 id="dialect">Dialect</h4>
<p>The <code>Dialect</code> defines the SQL dialect of the database. Simply put, goose needs to know the raw SQL
syntax of the database its working with.</p>
<p>Each dialect has a corresponding constant backed by a
<a href="https://pkg.go.dev/github.com/pressly/goose/v3@v3.20.0/database#Store">database.Store</a>
implementation.</p>
<p>For most users its sufficient to <strong>use one of the natively supported dialects</strong> and not worry about
the database store. For more advanced users, you may bring your own dialect and store, see the
<a href="">TODO</a> section for more information.</p>
<h4 id="db">db</h4>
<p>The <code>*sql.DB</code> is the database connection that goose will use to run migrations. Goose intentionally
does not care which database driver is used.</p>
<p>The caller is responsible for matching the dialect with the database driver. For example, if you are
using the <code>goose.DialectPostgres</code> dialect, you'd pick the <a href="https://github.com/jackc/pgx">jackc/pgx</a>
driver.</p>
<h4 id="fsys">fsys</h4>
<p>The <a href="https://pkg.go.dev/io/fs#FS"><code>fs.FS</code></a> is the filesystem abstraction that goose will use to read
migration files. This is will typically be <a href="https://pkg.go.dev/os#DirFS"><code>os.DirFS</code></a>,
<a href="https://pkg.go.dev/embed#FS"><code>embed.FS</code></a>.</p>
<p>Quite often you may have a heirarchy of directories with migrations, in which case you can use
<a href="https://pkg.go.dev/fs#Sub"><code>fs.Sub</code></a> to create a sub filesystem.</p>
<div class="highlight"><pre><span></span><code><span class="nx">fsys</span><span class="p">,</span><span class="w"> </span><span class="nx">err</span><span class="w"> </span><span class="o">:=</span><span class="w"> </span><span class="nx">fs</span><span class="p">.</span><span class="nx">Sub</span><span class="p">(</span><span class="nx">embeddedFS</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;migrations&quot;</span><span class="p">)</span>
</code></pre></div>
<p>And then pass the <code>fsys</code> to the provider.</p>
<h2 id="provider-options">Provider Options</h2>
<p>The <code>ProviderOption</code> is a functional option type that allows you to configure and customize the
provider.</p>
<h3 id="withstore">WithStore</h3>
<h3 id="withverbose">WithVerbose</h3>
<div class="highlight"><pre><span></span><code><span class="kd">func</span><span class="w"> </span><span class="nx">WithVerbose</span><span class="p">(</span><span class="nx">b</span><span class="w"> </span><span class="kt">bool</span><span class="p">)</span>
</code></pre></div>
<p>This option enables verbose logging of the migration process. For example, here's the output of
running an up migration with verbose logging:</p>
<div class="highlight"><pre><span></span><code>goose:<span class="w"> </span>OK<span class="w"> </span>up<span class="w"> </span>00001_users_table.sql<span class="w"> </span><span class="o">(</span><span class="m">1</span>.32ms<span class="o">)</span>
goose:<span class="w"> </span>OK<span class="w"> </span>up<span class="w"> </span>00002_add_users.go<span class="w"> </span><span class="o">(</span><span class="m">638</span>.96µs<span class="o">)</span>
goose:<span class="w"> </span>OK<span class="w"> </span>up<span class="w"> </span>00003_count_users.go<span class="w"> </span><span class="o">(</span><span class="m">561</span>.58µs<span class="o">)</span>
goose:<span class="w"> </span>successfully<span class="w"> </span>migrated<span class="w"> </span>database,<span class="w"> </span>current<span class="w"> </span>version:<span class="w"> </span><span class="m">3</span>
</code></pre></div>
<p>By default, the provider methods do not log anything by default.</p>
<h3 id="withsessionlocker">WithSessionLocker</h3>
<div class="highlight"><pre><span></span><code><span class="kd">func</span><span class="w"> </span><span class="nx">WithSessionLocker</span><span class="p">(</span><span class="nx">locker</span><span class="w"> </span><span class="nx">lock</span><span class="p">.</span><span class="nx">SessionLocker</span><span class="p">)</span>
</code></pre></div>
<p>By default, goose <strong>does not</strong> lock the database during migrations. It is up to the caller to ensure
migrations are run in a safe manner. Which means in certain environments, such as Kubernetes, you
may have multiple instances of your application running migrations concurrently.</p>
<p>By configuring a
<a href="https://pkg.go.dev/github.com/pressly/goose/v3@v3.20.0/lock#SessionLocker"><code>SessionLocker</code></a>, you
can ensure that only one instance of your application runs migrations at a time.</p>
<p>The <a href="https://pkg.go.dev/github.com/pressly/goose/v3@v3.20.0/lock">lock package</a> provides a few
implementations of the <code>SessionLocker</code> interface:</p>
<h4 id="postgres">Postgres</h4>
<p>The
<a href="https://pkg.go.dev/github.com/pressly/goose/v3@v3.20.0/lock#NewPostgresSessionLocker"><code>NewPostgresSessionLocker</code></a>
function creates a <code>SessionLocker</code> that can be used to acquire and release a lock for
synchronization purposes. The lock acquisition is retried until it is successfully acquired or until
the failure threshold is reached.</p>
<p>The default lock duration is set to 5 minutes, and the default unlock duration is set to 1 minute.
These can be tuned.</p>
<h3 id="withexcludenames">WithExcludeNames</h3>
<div class="highlight"><pre><span></span><code><span class="kd">func</span><span class="w"> </span><span class="nx">WithExcludeNames</span><span class="p">(</span><span class="nx">excludes</span><span class="w"> </span><span class="p">[]</span><span class="kt">string</span><span class="p">)</span>
</code></pre></div>
<p>The option excludes the given file names from the list of migrations. If called multiple times, the
list of excludes is merged.</p>
<h3 id="withexcludeversions">WithExcludeVersions</h3>
<div class="highlight"><pre><span></span><code><span class="kd">func</span><span class="w"> </span><span class="nx">WithExcludeVersions</span><span class="p">(</span><span class="nx">versions</span><span class="w"> </span><span class="p">[]</span><span class="kt">int64</span><span class="p">)</span>
</code></pre></div>
<p>This option excludes the given versions from the list of migrations. If called multiple times, the
list of excludes is merged.</p>
<h3 id="withgomigrations">WithGoMigrations</h3>
<div class="highlight"><pre><span></span><code><span class="kd">func</span><span class="w"> </span><span class="nx">WithGoMigrations</span><span class="p">(</span><span class="nx">migrations</span><span class="w"> </span><span class="o">...*</span><span class="nx">Migration</span><span class="p">)</span>
</code></pre></div>
<p>This option adds the given Go migration to the list of migrations. The migration <strong>must be</strong>
constructed using the
<a href="https://pkg.go.dev/github.com/pressly/goose/v3#NewGoMigration"><code>NewGoMigration</code></a> constructor.</p>
<h4 id="newgomigration">NewGoMigration</h4>
<div class="highlight"><pre><span></span><code><span class="kd">func</span><span class="w"> </span><span class="nx">NewGoMigration</span><span class="p">(</span><span class="nx">version</span><span class="w"> </span><span class="kt">int64</span><span class="p">,</span><span class="w"> </span><span class="nx">up</span><span class="p">,</span><span class="w"> </span><span class="nx">down</span><span class="w"> </span><span class="o">*</span><span class="nx">GoFunc</span><span class="p">)</span><span class="w"> </span><span class="o">*</span><span class="nx">Migration</span>
</code></pre></div>
<p>This function creates a new Go migration, which may be registered with a provider or globally.</p>
<p>Both up and down functions may be <code>nil</code>, in which case the migration will be recorded in the
versions table but no functions will be run. This is useful for recording (up) or deleting (down) a
version without running any functions.</p>
<p>A Go migration can either be executed within or outside a transaction and only one can be set. If
both are set, an error will be returned.</p>
<div class="highlight"><pre><span></span><code><span class="nx">RunTx</span><span class="w"> </span><span class="kd">func</span><span class="p">(</span><span class="nx">ctx</span><span class="w"> </span><span class="nx">context</span><span class="p">.</span><span class="nx">Context</span><span class="p">,</span><span class="w"> </span><span class="nx">tx</span><span class="w"> </span><span class="o">*</span><span class="nx">sql</span><span class="p">.</span><span class="nx">Tx</span><span class="p">)</span><span class="w"> </span><span class="kt">error</span>
<span class="c1">// or</span>
<span class="nx">RunDB</span><span class="w"> </span><span class="kd">func</span><span class="p">(</span><span class="nx">ctx</span><span class="w"> </span><span class="nx">context</span><span class="p">.</span><span class="nx">Context</span><span class="p">,</span><span class="w"> </span><span class="nx">db</span><span class="w"> </span><span class="o">*</span><span class="nx">sql</span><span class="p">.</span><span class="nx">DB</span><span class="p">)</span><span class="w"> </span><span class="kt">error</span>
</code></pre></div>
<h3 id="withdisableglobalregistry">WithDisableGlobalRegistry</h3>
<div class="highlight"><pre><span></span><code><span class="kd">func</span><span class="w"> </span><span class="nx">WithDisableGlobalRegistry</span><span class="p">(</span><span class="nx">b</span><span class="w"> </span><span class="kt">bool</span><span class="p">)</span>
</code></pre></div>
<p>This option disables the global registry. By default, goose uses a global registry to store all
migrations. This is useful for running migrations in a single process. If you are running migrations
in multiple processes, you should disable the global registry and register migrations with the
provider.</p>
<h3 id="withallowoutoforder">WithAllowOutofOrder</h3>
<div class="highlight"><pre><span></span><code><span class="kd">func</span><span class="w"> </span><span class="nx">WithAllowOutofOrder</span><span class="p">(</span><span class="nx">b</span><span class="w"> </span><span class="kt">bool</span><span class="p">)</span>
</code></pre></div>
<p>This option allows migrations to be run out-of-order, this is often called "allow missing"
migrations. By default, goose will error if it detects that a migration is missing.</p>
<p>For example: migrations 1,3 are applied to the database and then versions 2,6 are introduced. If
this option is true, then goose will apply 2 (missing) and 6 (new) instead of raising an error.</p>
<p>The final order of applied migrations will be: 1,3,2,6. Out-of-order migrations are always applied
first, followed by new migrations.</p>
<h3 id="withdisableversioning">WithDisableVersioning</h3>
<div class="highlight"><pre><span></span><code><span class="kd">func</span><span class="w"> </span><span class="nx">WithDisableVersioning</span><span class="p">(</span><span class="nx">b</span><span class="w"> </span><span class="kt">bool</span><span class="p">)</span>
</code></pre></div>
<p>This option disables versioning. Disabling versioning allows applying migrations without tracking
the versions in the database schema table. Useful for tests, seeding a database or running ad-hoc
queries. By default, goose will track all versions in the database schema table.</p>
</article>
</div>
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
</div>
<button type="button" class="md-top md-icon" data-md-component="top" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg>
Back to top
</button>
</main>
<footer class="md-footer">
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-copyright">
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs Insiders
</a>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<script id="__config" type="application/json">{"base": "../..", "features": ["navigation.instant", "navigation.tracking", "navigation.sections", "navigation.expand", "navigation.tabs", "navigation.indexes", "navigation.top", "content.code.annotate", "content.code.copy"], "search": "../../assets/javascripts/workers/search.c7c1ca2c.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script>
<script src="../../assets/javascripts/bundle.203fd0bc.min.js"></script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink