Dancer2...in::DBIC(3)

📦
version 0.0100 · 3 versions
, in opensuse-leap 16.0

💅 Dancer2::Plugin::DBIC

okay bestie, buckle up — this is the Dancer2::Plugin::DBIC page from the User Contributed Perl Documentation, and it's genuinely one of the most useful little plugins ever. DBIC. Database vibes. Slay. ✨

Version? version 0.0100. Tiny number, big energy. 🎀

✨ SYNOPSIS ✨

here's the whole vibe in one go, no cap:

use Dancer2;
use Dancer2::Plugin::DBIC;

get '/users/:user_id' => sub {
    my $user = schema('default')->resultset('User')->find(param 'user_id');

    # If you are accessing the 'default' schema, then all the following
    # are equivalent to the above:
    $user = schema->resultset('User')->find(param 'user_id');
    $user = resultset('User')->find(param 'user_id');
    $user = rset('User')->find(param 'user_id');

    template user_profile => {
        user => $user
    };
};

dance;

like… look at that. four whole ways to say the same thing and they're all valid. main character energy fr fr. 👑

🌸 DESCRIPTION 🌸

So this plugin makes it so easy to build Dancer2 apps that talk to databases. It literally automatically exports the keyword schema, which hands you back a DBIx::Class::Schema object. Obsessed. 🫶

It also exports the keywords resultset and rset — more on those below.

All you gotta do is configure your database connection info, that's it. And for performance? The schema objects get cached in memory and are lazy loaded the first time you actually access them. The way that it doesn't do work until it has to… iconic. 💅

This plugin is a thin wrapper around DBICx::Sugar. Just so you know what's underneath the glitter. ✨

🦋 CONFIGURATION 🦋

You do the config in your Dancer2 config file. Here's a minimal little example that defines one database named default:

plugins:
  DBIC:
    default:
      dsn: dbi:SQLite:dbname=some.db

And in this example, there are 2 databases configured, named default and foo:

plugins:
  DBIC:
    default:
      dsn: dbi:SQLite:dbname=some.db
      schema_class: MyApp::Schema
    foo:
      dsn: dbi:mysql:foo
      schema_class: Foo::Schema
      user: bob
      password: secret
      options:
        RaiseError: 1
        PrintError: 1

okay so the rules, bestie:

Every database you configure must at least have a dsn option. That dsn option should be the DBI driver connection string. Everything else is optional — optional is the keyword, lowkey everyone forgets it's optional. 🙈

If you only have one schema configured, or one of them is named default, you can call schema with no argument to get the only schema or the default schema respectively. Convenient? extremely. 💅

If you don't provide a schema_class option, then DBIx::Class::Schema::Loader gets used to dynamically load the schema by introspecting the database corresponding to the dsn value. Fair warning though: you need DBIx::Class::Schema::Loader installed to take advantage of that. It's giving "install your dependencies first." 😭

The schema_class option should be a proper Perl package name that Dancer2::Plugin::DBIC will use as a DBIx::Class::Schema class. Optionally, a database configuration may have user, password, and options parameters, as described in the documentation for connect() in DBI.

You may also declare your connection information in this format instead (which might look more familiar if you're a DBIC user already):

plugins:
  DBIC:
    default:
      connect_info:
        - dbi:mysql:foo
        - bob
        - secret
        -
          RaiseError: 1
          PrintError: 1

two whole formats. choose your fighter. 🥊

💖 FUNCTIONS 💖

💜 schema

my $user = schema->resultset('User')->find('bob');

The schema keyword returns a DBIx::Class::Schema object, ready for you to use. 🎀

If you've configured only one database, you can simply call schema with no arguments. If you've configured multiple databases, you can still call schema with no arguments as long as there's a database named default in the configuration.

With no argument, the default schema is returned. Otherwise? You gotta pass schema() the name of the database:

my $user = schema('foo')->resultset('User')->find('bob');

💜 resultset

This is a convenience method that saves you some typing — and honestly, who among us isn't trying to type less. Use this only when you're accessing the default schema.

my $user = resultset('User')->find('bob');

is equivalent to:

my $user = schema->resultset('User')->find('bob');

same thing. shorter. slay. 💅

💜 rset

my $user = rset('User')->find('bob');

This is simply an alias for resultset. that's it. that's the whole function. 🫶

🌈 SCHEMA GENERATION 🌈

There are two approaches for generating schema classes, and yes you have to pick one.

Approach one: generate your own DBIx::Class classes and set the corresponding schema_class setting in your configuration, like we showed above. This is the recommended approach for performance and stability. do this one, bestie, it's the glow-up path. 👑

Approach two: it's also possible to have schema classes dynamically generated if you omit the schema_class configuration setting. This requires you to have DBIx::Class::Schema::Loader installed. The v7 naming scheme will be used for naming the auto generated classes — see "naming" in DBIx::Class::Schema::Loader::Base for more info about naming, iykyk.

For generating your own schema classes, you can use the dbicdump command line tool provided by DBIx::Class::Schema::Loader to help you out. For example, if your app were named Foo, you could run the following from the root of your project directory:

dbicdump -o dump_directory=./lib Foo::Schema dbi:SQLite:/path/to/foo.db

For that example, your schema_class setting would be Foo::Schema. cute, right? 🍓

⭐ SEE ALSO ⭐

  • DBICx::Sugar

🧚 CONTRIBUTORS 🧚

look at this lineup. legends, all of them. 🔥

👑 AUTHOR 👑

Naveed Massjouni <naveed@vt.edu>

This software is copyright (c) 2013 by Naveed Massjouni.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

k that's the whole page, bestie 💖 — this was perl v5.42.0, dated 2020-11-04, page Dancer2...in::DBIC(3), and that's the tea 🦋 periodt.

📦 where this page comes from