# Manage SQL Models using Rudder CLI


<blockquote class="announcement">
  <div class="tip-quote">
    
    <div class="tip-text">This feature is in <strong>Public Beta</strong> as part of RudderStack&rsquo;s Early Access Program, where we work with early users and customers to test new features and get feedback before making them generally available.</div>
  </div>
</blockquote>

<p>The <strong>SQL Models</strong> feature in Rudder CLI lets you manage your <a href="https://www.rudderstack.com/docs/activate/models/" >Reverse ETL SQL model sources</a> through a Git-based workflow. It lets you store your SQL model configurations as YAML files in Git repositories, and use standard Git workflows to collaborate on any changes.</p>
<p>This approach brings version control, collaboration, and review processes to your SQL model configurations, addressing key limitations of managing these resources solely through the UI.</p>
<!-- end-chunk -->
<!-- begin-chunk -->
<h2 id="key-features">Key features</h2><p><strong>Bi-directional management</strong></p>
<ul>
<li>Create new SQL model resources directly from CLI</li>
<li>Import existing SQL model sources from your workspace into Git</li>
</ul>
<p><strong>Validation and preview</strong></p>
<ul>
<li>Validate SQL syntax and connectivity before deployment</li>
<li>Preview query results to ensure correctness</li>
<li>Check primary key constraints and column mappings</li>
</ul>
<p><strong>Flexible configuration</strong></p>
<ul>
<li>Define SQL queries inline in YAML files or reference external <code>.sql</code> files</li>
<li>Support for multiple warehouse types (listed below)</li>
</ul>
<p><strong>Automation ready</strong></p>
<ul>
<li>GitHub Actions integration for CI/CD workflows</li>
<li>Dry-run capabilities to preview changes before applying them</li>
<li>Cross-domain resource management alongside <a href="https://www.rudderstack.com/docs/dev-tools/rudder-cli/data-catalog-and-tracking-plans/" >Data Catalog and Tracking Plan resources</a></li>
</ul>
<!-- end-chunk -->
<!-- begin-chunk -->
<h2 id="supported-warehouses">Supported warehouses</h2><p>The SQL Models feature supports the following data warehouses:</p>
<ul>
<li>PostgreSQL</li>
<li>MySQL</li>
<li>Snowflake</li>
<li>Amazon Redshift</li>
<li>Google BigQuery</li>
<li>Databricks</li>
<li>Trino</li>
</ul>
<!-- end-chunk -->
<!-- begin-chunk -->
<h2 id="workflow-overview">Workflow overview</h2><ol>
<li>Configure your Git repository and Rudder CLI project.</li>
<li>Create new SQL models or import existing ones from your workspace.</li>
<li>Make changes to your SQL models using your preferred editor.</li>
<li>Validate your changes using the <code>validate</code> command and <code>apply</code> command in dry-run mode (via the <code>--dry-run</code> flag).</li>
<li>Use the <code>preview</code> command for SQL validation and connection validation.</li>
<li>Apply your changes using the <code>apply</code> command.</li>
<li>Create pull requests for team review and approval.</li>
<li>Automatically sync approved changes to your workspace via GitHub Actions.</li>
</ol>
<!-- end-chunk -->
<!-- begin-chunk -->
<h2 id="before-you-begin">Before you begin</h2><p>Before you begin, make sure you have:</p>
<ul>
<li><a href="https://www.rudderstack.com/docs/dev-tools/rudder-cli/" >Rudder CLI</a> installed and configured locally</li>
<li>A Rudder CLI project directory for storing the SQL model YAML resources</li>
<li><a href="https://www.rudderstack.com/docs/dev-tools/rudder-cli/github-actions/" >GitHub Actions</a> configured if you want automated syncing in CI/CD</li>
<li>A <a href="https://www.rudderstack.com/docs/access-management/service-access-tokens/#workspace-sat" >workspace-level Service Access Token</a> in the RudderStack dashboard with the following <a href="https://www.rudderstack.com/docs/access-management/policies-overview/#resource-permissions" >permissions</a> to manage SQL models:</li>
</ul>
<table>
  <thead>
      <tr>
          <th>Resource</th>
          <th>Permissions</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td>SQL Models</td>
          <td><strong>Create &amp; Delete</strong>, <strong>Edit</strong></td>
      </tr>
  </tbody>
</table>

<ul>
<li><strong>If you&rsquo;re on Free or self-hosted plan, or for testing and development only</strong>: Generate a <a href="https://www.rudderstack.com/docs/access-management/personal-access-tokens/" >Personal Access Token</a> with <strong>Read-Write</strong> role</li>
</ul>

<blockquote class="warning">
  <div class="tip-quote">
    
    <div class="tip-text">Any action authenticated by a Personal Access Token will break if the user generating the token is removed from the organization or there is a breaking change to their permissions.</div>
  </div>
</blockquote>
<p><strong>Token permissions for legacy RBAC system</strong></p>
<p>If you are on the <a href="https://www.rudderstack.com/docs/archive/dashboard-guides/user-management/" >legacy Permissions Management (RBAC) system</a>, your workspace-level Service Access Token should have minimum <strong>Admin</strong> permissions.</p>
<p>See <a href="https://www.rudderstack.com/docs/archive/dashboard-guides/service-access-tokens/#generate-service-access-token" >Generate a workspace-level Service Access Token</a> for steps to create the token.</p>

<figure class="image--main "  >
    <a 
         href="/docs/images/access-management/permissions/legacy/admin.webp"
        
        >
        <img src="/docs/images/access-management/permissions/legacy/admin.webp" 
         alt="workspace-level Service Access Token with Admin permission"  
         
         
        decoding="async" loading="lazy" class="img-shortcode"/>
    </a>
    
</figure>

<!-- end-chunk -->
<!-- begin-chunk -->
<h2 id="recommended-project-structure">Recommended project structure</h2><p>The SQL model resources need to be in the location you pass to the <a href="https://www.rudderstack.com/docs/dev-tools/rudder-cli/sql-models/create/#apply-the-sql-model" ><code>apply</code> command</a>. If you don&rsquo;t specify a location, the current directory is used as the project location.</p>

<html lang="en">
<blockquote class="info">
  <div class="tip-quote">
    
    <div class="tip-text">The <code>apply</code> command syncs all Rudder CLI resources it finds under that path (SQL models, Data Catalog, and so on).</div>
  </div>
</blockquote>

</html>
<p>A recommended directory structure for your CLI project is shown:</p>
<div class="rs-code">
  <div class="rs-code__head"><button class="rs-code__copy" type="button">
      
      Copy
    </button>
  </div>
  <div class="highlight"><pre class="chroma"><code class="language-text" data-lang="text">my-rudder-project/
├── sql-models/
│   ├── user-analytics.yaml
│   ├── product-models.yaml
│   └── sql/
│       ├── user-analytics.sql
│       └── product-views.sql
├── data-catalog/
│   ├── events/
│   │   └── product-events.yaml
│   └── properties/
│       └── user-properties.yaml
└── README.md</code></pre></div>
</div>
<!-- end-chunk -->
<!-- begin-chunk -->
<h4 id="key-considerations">Key considerations</h4><ul>
<li><strong>File discovery</strong>: The CLI recursively scans the specified directory for all <code>.yaml</code> and <code>.yml</code> files.</li>
<li><strong>Flexible organization</strong>: You can organize files in any directory structure that makes sense for your project.</li>
<li><strong>External SQL files</strong>: When using the <code>file</code> option in your YAML configurations, ensure the SQL files are accessible relative to the YAML file location.</li>
<li><strong>Mixed resources</strong>: The CLI can manage SQL models alongside Data Catalog resources (events, properties, custom types, Tracking Plans) from the same project directory.</li>
</ul>
<!-- end-chunk -->
<!-- begin-chunk -->
<h2 id="get-started">Get started</h2><ul>
<li>Follow the <a href="https://www.rudderstack.com/docs/dev-tools/rudder-cli/sql-models-walkthrough/" >End-to-End Walkthrough: SQL Models with Rudder CLI</a> for a single guided path through <strong>create</strong>, <strong>import</strong>, <strong>validate</strong>, <strong>preview</strong>, and <strong>apply</strong></li>
<li>See <a href="https://www.rudderstack.com/docs/dev-tools/rudder-cli/sql-models/create/" >Create New SQL Model Resources</a>, <a href="https://www.rudderstack.com/docs/dev-tools/rudder-cli/sql-models/import/" >Import Existing SQL Model Resources</a>, and <a href="https://www.rudderstack.com/docs/dev-tools/rudder-cli/sql-models/validate/" >Validate and Preview Your Models</a> for focused how-tos</li>
<li>See the <a href="https://www.rudderstack.com/docs/dev-tools/rudder-cli/yaml-sql-models/" >SQL Model Resources YAML Reference</a> for field-level specs</li>
<li>Automate with <a href="https://www.rudderstack.com/docs/dev-tools/rudder-cli/github-actions/" >GitHub Actions for Rudder CLI</a></li>
</ul>