Astrologue-Website/developer/invercargill-sql-inversion/index.html

<!doctype html>
<html lang="en-nz">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Invercargill-Sql-Inversion — Astrologue Developer</title>
  <meta name="description" content="The Inversion integrations for Invercargill-Sql: DatabaseConfigurator, MigrationStartupService and InversionTypeProvider wire the database into the dependency-injection container. Free software, LGPL-3.0-or-later.">
  <meta name="color-scheme" content="light dark">
  <meta name="theme-color" content="#f2ebda" media="(prefers-color-scheme: light)">
  <meta name="theme-color" content="#0a0a12" media="(prefers-color-scheme: dark)">
  <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Ccircle cx='32' cy='32' r='27' fill='none' stroke='%23a8801f' stroke-width='4'/%3E%3Cpath d='M32 8l6 18 18 6-18 6-6 18-6-18-18-6 18-6z' fill='%23a8801f'/%3E%3Ccircle cx='32' cy='32' r='4' fill='%23003078'/%3E%3C/svg%3E">
  <meta property="og:title" content="Invercargill-Sql-Inversion — Astrologue Developer">
  <meta property="og:description" content="DatabaseConfigurator, MigrationStartupService and InversionTypeProvider: the glue that wires Invercargill-Sql into the Inversion container.">
  <meta property="og:type" content="website">
  <link rel="stylesheet" href="../../assets/css/style.css">
</head>
<body>
  <a class="skip-link" href="#main">Skip to content</a>

  <header class="masthead">
    <div class="container masthead__inner">
      <a class="brand" href="../../">
        <img class="brand__logo brand__logo--light" src="../../assets/img/astrologue-light.png" width="392" height="89" alt="Astrologue">
        <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
      </a>
      <nav class="site-nav" aria-label="Primary">
        <ul class="site-nav__list">
          <li><a href="../../">Home</a></li>
          <li><a href="../../#news">News</a></li>
          <li><a href="../../#download">Download</a></li>
          <li><a href="../" aria-current="page">Developer</a></li>
          <li><a class="nav-cta" href="../../#download">Get Astrologue</a></li>
        </ul>
      </nav>
    </div>
  </header>

  <main id="main">

    <nav class="breadcrumb" aria-label="Breadcrumb">
      <div class="container">
        <ol>
          <li><a href="../../">Astrologue</a></li>
          <li><a href="../">Developer</a></li>
          <li aria-current="page">Invercargill-Sql-Inversion</li>
        </ol>
      </div>
    </nav>

    <section class="docs-header">
      <div class="container">
        <p class="kicker"><span>Data · The database, wired</span></p>
        <h1>Invercargill-Sql-Inversion</h1>
        <p class="lede">The Inversion integrations for Invercargill-Sql. Three classes — DatabaseConfigurator, MigrationStartupService and InversionTypeProvider — turn the database layer from something you wire by hand into something the container hands you.</p>
        <dl class="docs-facts">
          <div><dt>Version</dt> <dd><code>0.1</code></dd></div>
          <div><dt>Licence</dt> <dd>LGPL-3.0-or-later</dd></div>
          <div><dt>Package</dt> <dd><code>usm&nbsp;install&nbsp;invercargill-sql-inversion</code></dd></div>
          <div><dt>Language</dt> <dd>Vala</dd></div>
        </dl>
      </div>
    </section>

    <section class="band band--plain" id="docs">
      <div class="container docs-layout">

        <nav class="docs-toc" aria-label="On this page">
          <h2>On this page</h2>
          <ul>
            <li><a href="#overview">Overview</a></li>
            <li><a href="#features">Features</a></li>
            <li><a href="#installation">Installation</a></li>
            <li><a href="#usage">Usage &amp; documentation</a></li>
            <li><a href="#package">Package &amp; source</a></li>
          </ul>
        </nav>

        <div class="docs-prose">

          <header class="section-head" id="overview">
            <p class="kicker"><span>Overview</span></p>
            <h2>Integration glue, honestly scoped</h2>
          </header>
          <p>This repository ships no README — its three source files are the whole story, and this page summarises what they actually do. Invercargill-Sql-Inversion is glue in the good sense: the connective tissue that lets an application declare its database, entities, projections and migrations once, and have the <a href="../inversion/">Inversion</a> container resolve <a href="../invercargill-sql/">Invercargill-Sql</a>'s connections, dialects, runners, mappers and sessions ever after.</p>
          <p>Without it, every application repeats the same wiring — open a connection from a connection string, create a dialect, build a migration runner, register a type registry, construct sessions. With it, that wiring is one configurator object and a handful of registrations.</p>

          <header class="section-head" id="features">
            <p class="kicker"><span>Features</span></p>
            <h2>The three classes</h2>
          </header>
          <ul class="docs-features">
            <li><strong>DatabaseConfigurator.</strong> Registers a connection from a connection string, plus the dialect factory, migration runner, type provider and ORM session — with an auto-detected lifecycle.</li>
            <li><strong>add_entity, add_migration, add_projection.</strong> Fluent registration of mappers, migrations and projection definitions, each tagged with typed metadata.</li>
            <li><strong>MigrationStartupService.</strong> A startup-lifecycle service that gathers every registered migration and runs the schema to latest when the container initialises.</li>
            <li><strong>InversionTypeProvider.</strong> Answers "which mapper or projection belongs to this Vala type?" by querying registration metadata — the bridge the ORM's registry needs.</li>
            <li><strong>Lifecycle detection.</strong> In-memory databases register as singletons, file databases as scoped — the sensible default, overridable per registration.</li>
          </ul>

          <header class="section-head" id="installation">
            <p class="kicker"><span>Installation</span></p>
            <h2>Getting the library</h2>
          </header>
          <figure class="code-plate">
            <pre><code>usm install invercargill
usm install invercargill-sql
usm install inversion
usm install invercargill-sql-inversion</code></pre>
            <figcaption>USM resolves the dependency chain; the explicit steps are for reading order.</figcaption>
          </figure>
          <p>From source:</p>
          <figure class="code-plate">
            <pre><code>git clone &lt;the Invercargill-Sql-Inversion repository&gt;
cd Invercargill-Sql-Inversion
meson setup build
ninja -C build
ninja -C build install</code></pre>
            <figcaption>Requires the three libraries above installed first.</figcaption>
          </figure>
          <figure class="code-plate">
            <pre><code>valac --pkg invercargill-sql-inversion my-program.vala</code></pre>
            <figcaption>The binding pulls in its <code>.deps</code> chain automatically.</figcaption>
          </figure>

          <header class="section-head" id="usage">
            <p class="kicker"><span>Usage &amp; documentation</span></p>
            <h2>Wiring a database in one place</h2>
          </header>
          <p>The configurator injects the container it lives in, so configuration reads as plain registrations:</p>
          <figure class="code-plate">
            <pre><code>var db = new DatabaseConfigurator();
db.register_connection("sqlite::memory:");</code></pre>
            <figcaption>The entry point, from <code>src/DatabaseConfigurator.vala</code>. In-memory databases default to the singleton lifecycle; file databases to scoped — pass a lifecycle to override.</figcaption>
          </figure>
          <p>That one call registers the connection itself, a transient <code>SqlDialect</code> from the connection string's scheme, a transient <code>MigrationRunner</code>, the <code>TypeProvider</code>, and an <code>OrmSession</code> sharing the connection's lifecycle. Then entities, projections and migrations join the container with their own fluent calls:</p>
          <figure class="code-plate">
            <pre><code>db.add_entity&lt;User&gt;(b =&gt; b
    .table("users")
    .column&lt;int64?&gt;("id", u =&gt; u.id, (u, v) =&gt; u.id = v)
    .column&lt;string&gt;("name", u =&gt; u.name, (u, v) =&gt; u.name = v));

db.add_projection&lt;UserSummary&gt;(b =&gt; { /* projection columns */ });

db.add_migration&lt;V001_CreateUsers&gt;();</code></pre>
            <figcaption>Shape from <code>src/DatabaseConfigurator.vala</code> — each registration tags the container entry with typed <code>MapperTypeInfo</code> metadata.</figcaption>
          </figure>
          <p>To have the schema ready before the application serves anything, one more line:</p>
          <figure class="code-plate">
            <pre><code>db.migrate_on_startup();
container.initialise();</code></pre>
            <figcaption><code>migrate_on_startup()</code> registers the <code>MigrationStartupService</code> on the STARTUP lifecycle; when the container initialises, it creates a scope, resolves every registered <code>Migration</code>, hands them to the runner, and migrates to latest.</figcaption>
          </figure>
          <p>Downstream, the ORM asks for mappers through the type provider rather than a hand-built registry:</p>
          <figure class="code-plate">
            <pre><code>public class InversionTypeProvider : Object, TypeProvider {

    private Scope scope = inject&lt;Scope&gt;();

    public EntityMapper? get_mapper_for_type(GLib.Type type) throws Error {
        var reg = scope.get_registrations(typeof(EntityMapper))
            .where(r =&gt; r.get_metadata&lt;MapperTypeInfo&gt;()
                        .any(i =&gt; i.mapper_type == type))
            .first_or_default();
        return reg == null ? null
            : (EntityMapper)scope.resolve_registration(reg);
    }
    // get_projection_for_type, has_mapper_for_type likewise
}</code></pre>
            <figcaption>Condensed from <code>src/InversionTypeProvider.vala</code> — the metadata written at registration time is what answers the type question here.</figcaption>
          </figure>

          <header class="section-head" id="package">
            <p class="kicker"><span>Package &amp; source</span></p>
            <h2>The ledger</h2>
          </header>
          <dl class="docs-package">
            <div><dt>Version</dt><dd><code>0.1</code> (from <code>MANIFEST.usm</code>)</dd></div>
            <div><dt>Licence</dt><dd>LGPL-3.0-or-later — free to run, study, share and improve; the LGPL keeps it free to link from any program.</dd></div>
            <div><dt>Package</dt><dd><code>usm install invercargill-sql-inversion</code></dd></div>
            <div><dt>Provides</dt><dd><code>libinvercargill-sql-inversion.so</code>, <code>invercargill-sql-inversion.h</code>, <code>invercargill-sql-inversion.vapi</code> + <code>.deps</code>, <code>invercargill_sql_inversion-0.1.gir</code>, <code>invercargill_sql_inversion-0.1.typelib</code>, <code>invercargill-sql-inversion.pc</code></dd></div>
            <div><dt>Needs at runtime</dt><dd>GLib, GObject, <code>libinvercargill-1.so</code>, <code>libinvercargill-sql.so</code> and <code>libinversion-0.1.so</code>.</dd></div>
            <div><dt>Source</dt><dd>The repository <code>Tilo15/Invercargill-Sql-Inversion</code> on the Astrologue forge (git over ssh, port 222). Free software: the licence guarantees your right to the source.</dd></div>
          </dl>

          <nav class="docs-siblings" aria-label="Neighbours in the catalogue">
            <p>Its neighbours:</p>
            <ul>
              <li><a href="../invercargill-sql/">Invercargill-Sql</a></li>
              <li><a href="../inversion/">Inversion</a></li>
              <li><a href="../spry/">Spry</a></li>
            </ul>
          </nav>

          <nav class="docs-pager" aria-label="Project pages">
            <a class="docs-pager__link docs-pager__link--prev" href="../invercargill-sql/">
              <span>Previous</span>
              <strong>Invercargill-Sql</strong>
            </a>
            <p class="docs-pager__up"><a href="../">All eleven</a></p>
            <a class="docs-pager__link docs-pager__link--next" href="../astralis/">
              <span>Next in the catalogue</span>
              <strong>Astralis</strong>
            </a>
          </nav>

        </div>
      </div>
    </section>

  </main>

  <footer class="site-footer">
    <div class="container">
      <div class="footer-grid">
        <div class="foot-brand">
          <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
          <p>An operating system for change — kept for self sufficiency, resilience, and software freedom, so regular people can hold the power of general purpose computers in their own hands.</p>
        </div>
        <nav aria-label="The four freedoms">
          <p class="foot-title">The Four Freedoms</p>
          <ol class="freedoms">
            <li><strong>Run</strong> the software as you wish, for any purpose.</li>
            <li><strong>Study</strong> the source and change it to do your computing as you wish.</li>
            <li><strong>Share</strong> copies so you can help others.</li>
            <li><strong>Modify</strong> and publish your versions so everyone benefits.</li>
          </ol>
        </nav>
        <nav aria-label="Site">
          <p class="foot-title">Site</p>
          <ul class="foot-list">
            <li><a href="../../">Home</a></li>
            <li><a href="../../#news">News</a></li>
            <li><a href="../../#download">Download</a></li>
            <li><a href="../">Developer</a></li>
          </ul>
        </nav>
      </div>
      <p class="colophon">Set in Cinzel and EB Garamond (SIL Open Font License). Astrologue is free software, licensed GPL-3.0-or-later: take it, tend it, pass it on. The libraries are LGPL-3.0-or-later, so they remain free to link.</p>
    </div>
  </footer>
</body>
</html>