From: Mike Bayer Date: Thu, 27 Oct 2005 06:25:03 +0000 (+0000) Subject: (no commit message) X-Git-Tag: rel_0_1_0~433 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6ae64c4470eb809f401a2712a0e2439fe207b7ae;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git --- diff --git a/doc/build/components/formatting.myt b/doc/build/components/formatting.myt index 4be0c12cc5..1572998924 100644 --- a/doc/build/components/formatting.myt +++ b/doc/build/components/formatting.myt @@ -296,6 +296,7 @@ % if flip: flipper({"light":"dark", "dark": "light"}[flipper()]) <% m.content() %> + <%method codeline trim="both"> diff --git a/doc/build/content/metadata.myt b/doc/build/content/metadata.myt index 09cd24aa1c..ec2d63de36 100644 --- a/doc/build/content/metadata.myt +++ b/doc/build/content/metadata.myt @@ -1,11 +1,11 @@ <%flags>inherit='document_base.myt' <&|doclib.myt:item, name="metadata", description="Database Meta Data" &> <&|doclib.myt:item, name="tables", description="Describing Tables with MetaData" &> -

The core of SQLAlchemy's query and object mapping operations is table metadata, which are Python objects that describe tables. Metadata objects can be created by explicitly naming the table and all its properties, using the Table, Column, and ForeignKey objects imported from sqlalchemy.schema, and datatype identifiers imported from <&formatting.myt:link, path="types", text="sqlalchemy.types"&>:

+

The core of SQLAlchemy's query and object mapping operations is table metadata, which are Python objects that describe tables. Metadata objects can be created by explicitly naming the table and all its properties, using the Table, Column, ForeignKey, and Sequence objects imported from sqlalchemy.schema, and a database engine constructed as described in the previous section, or they can be automatically pulled from an existing database schema. First, the explicit version:

<&|formatting.myt:code&> from sqlalchemy.schema import * - import sqlalchemy.sqlite as sqlite - engine = sqllite.engine(':memory:', {}) + import sqlalchemy.engine as engine + engine = engine.create_engine('sqlite', ':memory:', {}, **opts) users = Table('users', engine, Column('user_id', Integer, primary_key = True), @@ -21,7 +21,58 @@ Column('pref_value', String(100)) ) - +

The specific datatypes, such as Integer, String, etc. are defined in <&formatting.myt:link, path="types", text="sqlalchemy.types"&> and are automatically pulled in when you import * from sqlalchemy.schema. Note that for Column objects, an altername name can be specified via the "key" parameter; if this parameter is given, then all programmatic references to this Column object will be based on its key, instead of its actual column name.

+ +

Once constructed, the Table object provides a clean interface to the table's properties as well as that of its columns: + + <&|formatting.myt:code&> + employees = Table('employees', engine, + Column('employee_id', Integer, primary_key=True), + Column('employee_name', String(60), nullable=False, key='name'), + Column('employee_dept', Integer, ForeignKey("departments.department_id")) + ) + + # access the column "EMPLOYEE_ID": + employees.columns.employee_id + + # or just + employees.c.employee_id + + # iterate through all columns + for c in employees.c: + # ... + + # get the table's primary key columns + for primary_key in employees.primary_keys: + # ... + + # get the table's foreign key objects: + for fkey in employees.foreign_keys: + # ... + + # access the table's SQLEngine object: + employees.engine + + # access a column's name, type, nullable, primary key, foreign key + employees.c.employee_id.name + employees.c.employee_id.type + employees.c.employee_id.nullable + employees.c.employee_id.primary_key + employees.c.employee_dept.foreign_key + + # get the "key" of a column, which defaults to its name, but can + # be any user-defined string: + employees.c.name.key + + # access a column's table: + employees.c.employee_id.table is employees + >>> True + + # get the table related by a foreign key + fcolumn = employees.c.employee_dept.foreign_key.column.table + +

+

Metadata objects can also be reflected from tables that already exist in the database. Reflection means based on a table name, the names, datatypes, and attributes of all columns, including foreign keys, will be loaded automatically. This feature is supported by all database engines:

<&|formatting.myt:code&> >>> messages = Table('messages', engine, autoload = True) @@ -57,10 +108,61 @@ - <&|doclib.myt:item, name="building", description="Building and Dropping Database Tables" &> + <&|doclib.myt:item, name="creating", description="Creating and Dropping Database Tables" &> +

Creating and dropping is easy, just use the create() and drop() methods: + <&|formatting.myt:code&> + employees = Table('employees', engine, + Column('employee_id', Integer, primary_key=True), + Column('employee_name', String(60), nullable=False, key='name'), + Column('employee_dept', Integer, ForeignKey("departments.department_id")) + ) + employees.create() <&|formatting.myt:codepopper, link="sql" &> +CREATE TABLE employees( + employee_id SERIAL NOT NULL PRIMARY KEY, + employee_name VARCHAR(60) NOT NULL, + employee_dept INTEGER REFERENCES departments(department_id) +) + +{} + + employees.drop() <&|formatting.myt:codepopper, link="sql" &> +DROP TABLE employees +{} + <&|doclib.myt:item, name="adapting", description="Adapting Tables to Alternate Engines" &> +

Occasionally an application will need to reference the same tables within multiple databases simultaneously. Since a Table object is specific to a SQLEngine, an extra method is provided to create copies of the Table object for a different SQLEngine instance, which can represent a different set of connection parameters, or a totally different database driver: + + <&|formatting.myt:code&> + # create two engines + sqlite_engine = engine.create_engine('sqlite', 'querytest.db', {}) + postgres_engine = engine.create_engine('postgres', + {'database':'test', + 'host':'127.0.0.1', 'user':'scott', 'password':'tiger'}) + + # load 'users' from the sqlite engine + users = Table('users', sqlite_engine, autoload=True) + + # create the same Table object for the other engine + pg_users = users.toengine(postgres_engine) + + +

You can also create tables using a "database neutral" engine, which can serve as a starting point for tables that are then adapted to specific engines:

+ <&|formatting.myt:code&> + import sqlalchemy.ansisql as ansisql + generic_engine = ansisql.engine() + + users = Table('users', generic_engine, + Column('user_id', Integer), + Column('user_name', String(50)) + ) + + sqlite_engine = engine.create_engine('sqlite', 'querytest.db', {}) + sqlite_users = users.toengine(sqlite_engine) + sqlite_users.create() + + <&|doclib.myt:item, name="sequences", description="Defining Sequences" &>