Dancer...::DBIC(3pm)

📦
version 0.2104 · 4 versions
, in ubuntu resolute, ubuntu stonking

💖 Dancer::Plugin::DBIC 💖

okay bestie, welcome to Dancer::Plugin::DBIC(3pm) — that's the manual page, the label at the bottom is perl v5.40.1 from 2025-08-15, and it lives in the User Contributed Perl Documentation corner of the world. this plugin? the whole entire point is making your Dancer app talk to a database without you crying. it's giving "we got you." ✨

version: 0.2104 🎀

✨ SYNOPSIS ✨

use Dancer;
use Dancer::Plugin::DBIC qw(schema resultset rset);

get '/users/:user_id' => sub {
    my $user_id = param 'user_id';
    my $user;

    # all of the following are equivalent:
    $user = schema('default')->resultset('User')->find($user_id);
    $user = schema->resultset('User')->find($user_id);
    $user = resultset('User')->find($user_id);
    $user = rset('User')->find($user_id);

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

dance;

like. look at that. four whole ways to do the exact same thing and every single one of them is valid. we love options 💅

🌸 DESCRIPTION 🌸

so this plugin is literally here to make building Dancer apps that talk to databases super easy. it automatically exports the keyword schema, and schema hands you back a DBIx::Class::Schema object. you just configure your database connection info and go.

and for performance? schema objects are cached in memory and they're lazy loaded — so they don't even get built until the first time you actually touch them. main character energy, honestly. 👑

also real talk: this plugin is now just a thin wrapper around DBICx::Sugar. that's it. that's the tea 🍓

💅 CONFIGURATION 💅

you do all your configuring right in your Dancer config file. let's go 🦋

🎀 simple example 🎀

here's a lil baby example. it defines one database named default:

plugins:
  DBIC:
    default:
      dsn: dbi:SQLite:dbname=myapp.db
      schema_class: MyApp::Schema

one db, one config, slay ✨

😭 multiple schemas 😭

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

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

okay so important: every database you configure must have at least a dsn option. the dsn is supposed to be the DBI driver connection string. everything else? optional, babe. truly optional.

if you only have one schema configured — or one of them is named default — then you can just call schema with no argument and you'll get the only one, or the default one respectively. no arguments needed, we're chill like that 🫶

and 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 that matches your dsn value. fair warning though: you need DBIx::Class::Schema::Loader installed for that to even work. 🫠

🚨 WARNING: dynamic loading is not recommended for production environments. it is almost always better to provide a schema_class option. periodt.

the schema_class option should be the name of your DBIx::Class::Schema class. see "SCHEMA GENERATION" for more. optionally, a database configuration can also have user, password, and options parameters as described in the documentation for connect() in DBI. iykyk 📚

🧚 connect_info 🧚

alternatively — and this is iconic — you may also declare your connection information inside an array named connect_info:

plugins:
  DBIC:
    default:
      schema_class: MyApp::Schema
      connect_info:
        - dbi:Pg:dbname=foo
        - bob
        - secret
        -
          RaiseError: 1
          PrintError: 1

look at her. an array. a whole vibe. 💜

🌈 replicated 🌈

you can also add database read slaves to your configuration with the replicated config option!! this automatically makes your read queries go to a slave and your write queries go to the master. obsessed.

keep in mind though — this requires additional dependencies: DBIx::Class::Optional::Dependencies#Storage::Replicated. see DBIx::Class::Storage::DBI::Replicated for more deets. here's an example config that adds two read slaves:

plugins:
  DBIC:
    default:
      schema_class: MyApp::Schema
      dsn: dbi:Pg:dbname=master
      replicated:
        balancer_type: ::Random     # optional
        balancer_args:              # optional
            auto_validate_every: 5  # optional
            master_read_weight:1    # optional
        # pool_type and pool_args are also allowed and are also optional
        replicants:
          -
            - dbi:Pg:dbname=slave1
            - user1
            - password1
            -
              quote_names: 1
              pg_enable_utf8: 1
          -
            - dbi:Pg:dbname=slave2
            - user2
            - password2
            -
              quote_names: 1
              pg_enable_utf8: 1

two slaves. one master. balance. we stan a symmetrical setup ⚖️✨

🌸 alias 🌸

schema aliases let you reference the same underlying database by multiple names. so basically, one database, several nicknames. very "we go by many names" of it. for example:

plugins:
  DBIC:
    default:
      dsn: dbi:Pg:dbname=master
      schema_class: MyApp::Schema
    slave1:
      alias: default

now you can access the default schema with schema(), schema('default'), or schema('slave1'). 💖

this comes in clutch if, like, you have master/slave replication in production but only a single database in development. you can keep referencing schema('slave1') in your code in both environments by just creating a schema alias in your development.yml config file, exactly like what's shown above. chef's kiss 🎀

👑 FUNCTIONS 👑

⭐ schema ⭐

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

the schema keyword returns a DBIx::Class::Schema object, all ready for you to use. 💅

if you configured only one database, you can simply call schema with no arguments — easy. if you configured multiple databases, you can still call schema with no arguments as long as there's a database named default in the config. with no argument, the default schema is what comes back. otherwise? you must provide schema() with the name of the database:

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

name it or it's not coming home with you 🫶

🦋 resultset 🦋

this is a convenience method that'll save you some typing. use it only when you're accessing the default schema, okay?

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

is equivalent to:

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

same thing, fewer characters, we love efficiency ✨

🍓 rset 🍓

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

this is simply an alias for resultset. that's it. that's the whole section. iconic brevity 💜

🌈 SCHEMA GENERATION 🌈

setting the schema_class option and having proper DBIx::Class classes is the recommended approach for performance and stability. do it. trust. 💖

you can use the dbicdump command line tool that comes with DBIx::Class::Schema::Loader to help you out. for example, if your app were named Foo, then 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 this example, your "schema_class" setting would be 'Foo::Schema'. 🎀

✨ SEE ALSO ✨

  • DBICx::Sugar

🫶 CONTRIBUTORS 🫶

💖 AUTHORS 💖

  • Al Newkirk <awncorp@cpan.org>
  • Naveed Massjouni <naveed@vt.edu>

this software is copyright (c) 2010 by awncorp.

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

and that's the whole page bestie!! 💕 this was Dancer::Plugin::DBIC(3pm) from the User Contributed Perl Documentation, sitting at version 0.2104, served up fresh on 2025-08-15 alongside perl v5.40.1. now go configure a database, you absolute legend 🔥👑✨

📦 where this page comes from