Committed version bump to DBIx::Class

[dbsrgits/DBIx-Class.git] / README

diff --git a/README b/README
index 7083759..4dcaf62 100644 (file)
--- a/README
+++ b/README
@@ -8,10 +8,12 @@ DESCRIPTION
     and making it possible to support some new features like self-joins,
     distinct, group bys and more.
 
-    It's currently considered EXPERIMENTAL - bring this near a production
-    database at your own risk! The API is *not* fixed yet, although most of
-    the primitives should be good for the future and any API changes will be
-    posted to the mailing list before they're committed.
+    This project is still at an early stage so the maintainers don't make
+    any absolute promise that full backwards-compatibility will be
+    supported; however if we can without compromising the improvements we're
+    trying to make, we will, and any non-compatible changes will merit a
+    full justification on the mailing list and a CPAN developer release for
+    people to test against.
 
     The community can be found via -
 
@@ -24,32 +26,47 @@ DESCRIPTION
       IRC: irc.perl.org#dbix-class
 
 QUICKSTART
-    If you're using Class::DBI, replacing
+    If you're using Class::DBI, and want an easy and fast way of migrating
+    to DBIx::Class look at DBIx::Class::CDBICompat.
 
-      use base qw/Class::DBI/;
+    There are two ways of using DBIx::Class, the 'simple' and the 'schema'
+    one.
 
-    with
+    The 'simple' way of using DBIx::Class needs less classes than the
+    'schema' way but doesn't give you the ability to use different database
+    connections.
 
-      use base qw/DBIx::Class/;
-      __PACKAGE__->load_components(qw/CDBICompat Core DB/);
+    Some examples where different database connections are useful are:
 
-    will probably get you started.
+    different users with different rights different databases with the same
+    schema.
 
-    If you're using AUTO_INCREMENT for your primary columns, you'll also
-    want yo load the approriate PK::Auto subclass - e.g.
+Simple
+    First you need to create a base class all other classes inherit from.
 
-      __PACKAGE__->load_components(qw/CDBICompat PK::Auto::SQLite Core DB/);
+    Look at DBIx::Class::DB how to do this
 
-    (with is what ::Test::SQLite does to present the
-    Class::DBI::Test::SQLite interface)
+    Next you need to create a class for every table you want to use with
+    DBIx::Class.
 
-    If you fancy playing around with DBIx::Class from scratch, then read the
-    docs for DBIx::Class::Table, ::Row, ::Schema, ::DB and ::Relationship,
+    Look at DBIx::Class::Table how to do this.
 
-      use base qw/DBIx::Class/;
-      __PACKAGE__->load_components(qw/Core DB/);
+  Schema
+    With this approach the table classes inherit directly from
+    DBIx::Class::Core, although it might be a good idea to create a 'parent'
+    class for all table classes which inherits from DBIx::Class::Core and
+    adds additional methods needed by all table classes, e.g. reading a
+    config file, loading auto primary key support.
 
-    and have a look at t/lib/DBICTest.pm for a brief example.
+    Look at DBIx::Class::Schema how to do this.
+
+    If you need more hand-holding, check out the introduction in the manual
+    below.
+
+SEE ALSO
+    DBIx::Class::Core - DBIC Core Classes
+    DBIx::Class::CDBICompat - Class::DBI Compat layer.
+    DBIx::Class::Manual - User's manual.
 
 AUTHOR
     Matt S. Trout <mst@shadowcatsystems.co.uk>