Bio::D...DBI::Pg(3pm)

💖 Bio::D...DBI::Pg(3pm) 💖

okay bestie, so this is the manual page for Bio::DB::SeqFeature::Store::DBI::Pg — it lives in the Bio::D...DBI::Pg(3pm) slot in the Perl docs, and it's the whole vibe guide for the PostgreSQL adaptor. pull up a chair, grab a strawberry 🍓, we're doing this.

---

✨ NAME ✨

Bio::DB::SeqFeature::Store::DBI::Pg — the PostgreSQL implementation of Bio::DB::SeqFeature::Store. that's it, that's the whole thing, she's a Postgres girlie 💅

---

🌸 SYNOPSIS 🌸

here's the whole flow, copy-paste ready, no cap:

  use Bio::DB::SeqFeature::Store;

  # Open the sequence database
  my $db = Bio::DB::SeqFeature::Store->new(-adaptor => 'DBI::Pg',
                                          -dsn     => 'dbi:Pg:test');

  # get a feature from somewhere
  my $feature = Bio::SeqFeature::Generic->new(...);

  # store it
  $db->store($feature) or die "Couldn't store!";

  # primary ID of the feature is changed to indicate its primary ID
  # in the database...
  my $id = $feature->primary_id;

  # get the feature back out
  my $f  = $db->fetch($id);

  # change the feature and update it
  $f->start(100);
  $db->update($f) or die "Couldn't update!";

  # searching...
  # ...by id
  my @features = $db->fetch_many(@list_of_ids);

  # ...by name
  @features = $db->get_features_by_name('ZK909');

  # ...by alias
  @features = $db->get_features_by_alias('sma-3');

  # ...by type
  @features = $db->get_features_by_name('gene');

  # ...by location
  @features = $db->get_features_by_location(-seq_id=>'Chr1',-start=>4000,-end=>600000);

  # ...by attribute
  @features = $db->get_features_by_attribute({description => 'protein kinase'})

  # ...by the GFF "Note" field
  @result_list = $db->search_notes('kinase');

  # ...by arbitrary combinations of selectors
  @features = $db->features(-name => $name,
                            -type => $types,
                            -seq_id => $seqid,
                            -start  => $start,
                            -end    => $end,
                            -attributes => $attributes);

  # ...using an iterator
  my $iterator = $db->get_seq_stream(-name => $name,
                                     -type => $types,
                                     -seq_id => $seqid,
                                     -start  => $start,
                                     -end    => $end,
                                     -attributes => $attributes);

  while (my $feature = $iterator->next_seq) {
    # do something with the feature
  }

  # ...limiting the search to a particular region
  my $segment  = $db->segment('Chr1',5000=>6000);
  my @features = $segment->features(-type=>['mRNA','match']);

  # getting & storing sequence information
  # Warning: this returns a string, and not a PrimarySeq object
  $db->insert_sequence('Chr1','GATCCCCCGGGATTCCAAAA...');
  my $sequence = $db->fetch_sequence('Chr1',5000=>6000);

  # what feature types are defined in the database?
  my @types    = $db->types;

  # create a new feature in the database
  my $feature = $db->new_feature(-primary_tag => 'mRNA',
                                 -seq_id      => 'chr3',
                                 -start      => 10000,
                                 -end        => 11000);

store it, fetch it, update it, search it every which way, insert some sequence, peek at the types, spin up a brand new feature — it's giving full lifecycle, and we're obsessed. 🦋

---

👑 DESCRIPTION 👑

Bio::DB::SeqFeature::Store::Pg is the Pg adaptor for Bio::DB::SeqFeature::Store. and here's the thing — you do not create it directly, bestie. like, don't even try. you go through Bio::DB::SeqFeature::Store->new() and let it handle the adaptor situation. that's the way.

for the complete usage instructions, go read Bio::DB::SeqFeature::Store. she's the main character, this page is just her Pg-flavored bestie. 💜

🎀 Using the Pg adaptor 🎀

before you can even use the adaptor, you've gotta use the Pgadmin tool to create a database and set up a user account with write permission. and listen — if you want to use "fast" loading, that user account must have "file" privileges. non-negotiable, fr fr. 🔥

to establish a connection to the database, call Bio::DB::SeqFeature::Store->new(-adaptor=>'DBI::Pg',@more_args). and the extra args? here's the whole menu, bestie:

• -dsn — the database name. you can abbreviate "dbi:Pg:foo" as "foo" if you want, lowkey convenient.
• -user — username for authentication.
• -pass — password for authentication.
• -namespace — creates a SCHEMA for the tables. this lets you have several virtual databases living inside the same physical database. like roommates but for schemas. 🏠
• -temp — boolean flag. if true, a temporary database gets created and destroyed as soon as the Store object goes out of scope. (synonym -temporary) — she's ephemeral, she's a ghost, she's gone the second you look away. 💀
• -autoindex — boolean flag. if true, features in the database get reindexed every time they change. this is the default. yes, by default, every single time. she's thorough like that. ✨
• -tmpdir — directory in which to place temporary files during "fast" loading. defaults to File::Spec->tmpdir(). (synonyms -dump_dir, -dumpdir, -tmp)
• -dbi_options — a hashref to pass to DBI->connect's 4th argument, the "attributes." (synonyms -options, -dbi_attr)
• -write — pass true to open the database for writing or updating.

and if all that works out? you get back a shiny new instance of Bio::DB::SeqFeature::Store::DBI::Pg. slay. 🫶

on top of the standard methods that every well-behaved Bio::DB::SeqFeature::Store database supports, this adaptor also brings a few of her own special moves. those get their own sections, keep scrolling bestie. ⬇️

🌈 types 🌈

 Title   : types
 Usage   : @type_list = $db->types
 Function: Get all the types in the database
 Returns : array of Bio::DB::GFF::Typename objects
 Args    : none
 Status  : public

no args, public, returns you a whole array of Bio::DB::GFF::Typename objects — it's literally just "hey what types are in this database" and she delivers. iconic. 👑

---

and that's the whole page, bestie! 🎀 this one came from perl v5.40.0, dated 2024-10-11, and it's filed under Bio::D...DBI::Pg(3pm). go forth and Postgres responsibly. mwah. 💖✨