クラスの利用法

さて、クラスの定義はうまくいきました。では、どのように使えばよいのでしょう か？ 上で定義したクラスについて考えてみましょう。

新たなオブジェクト (あるいは新たな行) を作るには、以下のようにしてクラスの インスタンスを生成します:

>>> Person(firstName="John", lastName="Doe")
<Person 1 firstName='John' middleInitial=None lastName='Doe'>

firstName や lastName といった列にはデフォルト値がないので、これら の引数の指定を忘れるとエラーになります (middleInitial はデータベースに おける None に相当するデフォルト値 NULL が設定されます)。

.get() メソッドを使うと、すでにテーブルに入っているインスタンスを取得 (fetch) します:

>>> Person.get(1)
<Person 1 firstName='John' middleInitial=None lastName='Doe'>

オブジェクトを生成すると、その内容はすぐにデータベースに挿入されます。他の システムではユーザがオブジェクトを明示的にデータベースに挿入せねばなりませ んが、SQLObject はデータベースを即時性 (immediate) のストレージとして扱う点 が異なります。

クラスを使ったもう少し長い例を紹介しましょう:

>>> p = Person.get(1)
>>> p
<Person 1 firstName='John' middleInitial=None lastName='Doe'>
>>> p.firstName
'John'
>>> p.middleInitial = 'Q'
>>> p.middleInitial
'Q'
>>> p2 = Person.get(1)
>>> p2
<Person 1 firstName='John' middleInitial='Q' lastName='Doe'>
>>> p is p2
True

ここでは、列データを属性のようにアクセスしています。(この機能は、属性値の取 り出し時や設定時にコードを実行できる、Python 2.2 の プロパティ (property) を使っています。) また、各オブジェクトが一意に表現さてれいる --- ある id を持った Person のインスタンスはメモリ上に一つしかない --- ことにも注意してください。 ある id を持った Person インスタンスを複数生成しても、得られるインスタンス は同じになります。このため、複数スレッドが同じデータにアクセスしているよう な状況でも (もちろんプロセス間の場合には同じインスタンスを共有したりできま せんが) 一定の一貫性を確保できます。ただし、 トランザクション を使ってい る場合にはあてはまりません。

SQLObject の内部で何が起こっているかを理解するために、実際に送信されている SQL をコメント付きで示しましょう:

>>> # This will make SQLObject print out the SQL it executes:
>>> Person._connection.debug = True
>>> p = Person(firstName='Bob', lastName='Hope')
 1/QueryIns:  INSERT INTO person (last_name, middle_initial, first_name) VALU\
ES ('Hope', NULL, 'Bob')
 1/COMMIT  :  auto
 1/QueryOne:  SELECT first_name, middle_initial, last_name FROM person WHERE \
id = 2
 1/COMMIT  :  auto
>>> p
<Person 2 firstName='Bob' middleInitial=None lastName='Hope'>
>>> p.middleInitial = 'Q'
 1/Query   :  UPDATE person SET middle_initial = 'Q' WHERE id = 2
 1/COMMIT  :  auto
>>> p2 = Person.get(1)
>>> # Note: no database access, since we're just grabbing the same
>>> # instance we already had.

おそらく、分かりやすく、予想通りの SQL が送信されていると思ったことでしょう。 送信される SQL を見るには、接続 URI に ?debug=t を追加するか、キーワー ド引数 debug=1 を接続オブジェクトに渡してください。全ての SQL をコンソー ルに出力します。これは心強い機能で、ぜひ試してみるようお勧めします。

各属性を個別に代入する代わりに、以下のように set メソッドを使って複数の 属性に代入を行うと、ちょっとした最適化になります:

>>> p.set(firstName='Robert', lastName='Hope Jr.')

この方法では、 UPDATE 文を一度しか発行しません。 set はデータベースと 関係のないプロパティにも適用できます (特に利点があるわけではありませんが、 データベース関連とそうでない属性との違いを隠蔽する手助けにはなります)。

更新の遅延

デフォルトでは、 SQLObject はオブジェクトの属性に代入したり、 .set() メ ソッドを使うたびに、 UPDATE をデータベースに送信します。何度も更新が起 きるのを避けたければ、 _lazyUpdate = True をクラス定義に追加してくださ い。これによって、 inst.syncUpdate() や obj.sync() を呼び出したとき にだけ更新を行うようになります: .sync() はデータベースからデータを再取 得し、 .syncUpdate() はしません。

更新の遅延を有効にすると、インスタンスに反映待ちの更新が存在するかどうかを 表す .sqlmeta.dirty というプロパティが追加されます。更新の遅延が有効で も、行の挿入は即座に行われます。現時点では、挿入を遅延させる方法はありませ ん。

一対多のリレーション

ところで、アドレスの入っていないアドレスブックなど、全く意味がありません。 そこで、アドレス用のテーブルを新たに定義しましょう。いうまでもなく、ある人 (People オブジェクト) は、複数のアドレスを持ち得ます:

>>> class Address(SQLObject):
...
...     street = StringCol()
...     city = StringCol()
...     state = StringCol(length=2)
...     zip = StringCol(length=9)
...     person = ForeignKey('Person')
>>> Address.createTable()

列定義 person = ForeignKey("Person") に注意してください。ここでは Person オブジェクトに対して参照を行っています。 SQLObject では他のクラスを (文字列の) 名前で参照します。データベースには persion_id という列が作られ、 person 列を示す INT 型の 値になります。

さて、ある人のアドレスを表現するための属性が必要です。本来なら、クラス定義 で以下のようにすべきでした:

class Person(SQLObject):
    ...
    addresses = MultipleJoin('Address')

とはいえ、すでにクラスは生成済みなので、その場でクラスに追加しましょう:

>>> Person.sqlmeta.addJoin(MultipleJoin('Address',
...                        joinMethodName='addresses'))

さて、これで aPerson.addresses を使って逆参照 (backreference) を行える ようになりました。この逆参照は以下の例のようにリストを返します:

>>> p.addresses
[]
>>> Address(street='123 W Main St', city='Smallsville',
...         state='MN', zip='55407', person=p)
<Address 1 ...>
>>> p.addresses
[<Address 1 ...>]

多対多のリレーション

Many-to-Many Relationships

この節の例では、ユーザ (user) と役割 (role) オブジェクトを使います。これら 二つのオブジェクトは、互いに多対多に対応しています。多対多の対応は RelatedJoin で表現します。

>>> class User(SQLObject):
...
...     class sqlmeta:
...         # user is a reserved word in some databases, so we won't
...         # use that for the table name:
...         table = "user_table"
...
...     username = StringCol(alternateID=True, length=20)
...     # We'd probably define more attributes, but we'll leave
...     # that exercise to the reader...
...
...     roles = RelatedJoin('Role')

>>> class Role(SQLObject):
...
...     name = StringCol(alternateID=True, length=20)
...
...     users = RelatedJoin('User')

>>> User.createTable()
>>> Role.createTable()

sqlmeta クラスを使っていることに注意してください。このクラスは様々なメ タデータを保存しておく (そして table のような既存のメタデータをオーバラ イドする) ためのクラスです。この機能は SQLObject 0.7 で新たに追加されたもの です。 sqlmeta クラスのからくりや特殊な意味を持つ属性については、 sqlmeta クラス を参照してください。

使い方は以下の通りです:

>>> bob = User(username='bob')
>>> tim = User(username='tim')
>>> jay = User(username='jay')
>>> admin = Role(name='admin')
>>> editor = Role(name='editor')
>>> bob.addRole(admin)
>>> bob.addRole(editor)
>>> tim.addRole(editor)
>>> bob.roles
[<Role 1 name='admin'>, <Role 2 name='editor'>]
>>> tim.roles
[<Role 2 name='editor'>]
>>> jay.roles
[]
>>> admin.users
[<User 1 username='bob'>]
>>> editor.users
[<User 1 username='bob'>, <User 2 username='tim'>]

処理の過程で、両方のオブジェクトに対して参照を持つような、 role_user と いう中間テーブルが生成されます。このテーブルはクラスの形で表に出ることはな く、テーブルの行レコードに対応した Python オブジェクトもありません。これに よって、多対多の関係にまつわる厄介事を隠蔽しておけます。

列に alternateID というキーワード引数があることにお気づきでしょうか。 alternateID=True にすると、その列はある行を一意に指定できるような値を持 つことを示します -- あるユーザ名があるユーザを一意に指定するようなものです。 とはいえ、この識別子は主キー (id) に対する追加情報にすぎず、主キーを置 き換えるわけではありません。

alternateID を指定すると、例えば username という列名に対して byUsername のような名前のクラスメソッドが作られます (キーワード引数 alternateMethodName を指定すればメソッド名を上書きできます)。 byUsername は以下のようにして使います:

>>> User.byUsername('bob')
<User 1 username='bob'>
>>> Role.byName('admin')
<Role 1 name='admin'>

複数オブジェクトの選択

Selecting Multiple Objects

SQLObject では、関係データベースで使える全ての種類の結合 (join) のパワーを 完全に引き出せるようにする代わりに、簡単な SELECT を使えるようにしてい ます。

select はクラスメソッドで、以下のようにして呼び出します (生成された SQL を一緒に示します):

>>> Person._connection.debug = True
>>> peeps = Person.select(Person.q.firstName=="John")
>>> list(peeps)
 1/Select  :  SELECT person.id, person.first_name, person.middle_initial, per\
son.last_name FROM person WHERE (person.first_name = 'John')
 1/COMMIT  :  auto
[<Person 1 firstName='John' middleInitial='Q' lastName='Doe'>]

この例では、ファーストネームが John の人を全て返します。もっと複雑な条件式 も使えます:

>>> peeps = Person.select(
...         AND(Address.q.personID == Person.q.id,
...             Address.q.zip.startswith('504')))
>>> list(peeps)
 1/Select  :  SELECT person.id, person.first_name, person.middle_initial, per\
son.last_name FROM person, address WHERE ((address.person_id = person.id) AND\
(address.zip LIKE '504%'))
 1/COMMIT  :  auto
[]

クラスに q という属性があるのにお気づきでしょうか。この属性は、問い合わ せ文の各節を構築するための特殊なオブジェクトです。 q を介して属性を参照 すると列名を返し、この値で論理式を作ると、それに対応した SQL 文を生成するよ うになっているのです。同じような操作はもっと用手的に SQL 文を作成することで も実現できます:

>>> peeps = Person.select("""address.id = person.id AND
...                          address.zip LIKE '504%'""",
...                       clauseTables=['address'])

select を行うテーブル以外のテーブルを使う場合には、 clauseTables を指定 せねばならないことに注意してください。属性 q を使うと、どのクラスを使う かを SQLObject が自動的に判断します。

SQL 文を手動で生成させる時には、 MyClass.sqlrepr を使って値をクオート せねばなりません (q を使えば自動的にクオートされます) 。

キーワード引数 orderBy を使えば、 select 文に ORDER BY が入ります: orderBy は文字列を引数にとりますが、これは列の データベース上の 名前か、 Person.q.firstName 形式の名前でなければなりません。逆順にした ければ、 "-colname" の形式にするか、 MyClass.select().reversed() を 呼び出してください。

特殊なクラス変数 _defaultOrder を使うと、 select 操作全てに対するデフォル トの並べ規則を指定できます。 _defaultOrder が指定されている状態で並べ変え なしの結果を取り出したい場合には、 orderBy=None を使います。

select の結果はジェネレータであり、値は遅延して評価 (lazily evaluate) されます。すなわち、 select 結果に対して反復処理を実行したり、 list() を使って強制しないかぎり、 SQL は実行されません。 select 結果に対する反復処 理を行う場合には、各行は一度に一行づつ取り出されます。これにより、巨大な select 結果に対する反復処理で、結果全体をメモリに保持する必要がなくなります。 .reversed() のような操作も、結果全体を取り出して反転したりせずに実行で きます -- SQLObject はそうする代わりに、同じ結果が得られるように SQL を変更 します。

また、 select 結果に対するスライスも行えます。スライス操作は SQL クエリの 変更の形をとります。例えば peeps[:10] とすると、 SQL クエリには LIMIT 10 が追加されることになります。 SQL で実現できないスライス (例え ば peeps[:-10]) の場合、一度 select を実行して、結果のリストに対してスライ スを行います。この処理が行われるのは負のインデクスを使ったときだけです。

join を行ったときなど、場合によっては一つのオブジェクトが select 結果に何度 も出現する場合があります。これを抑制したい場合、キーワード引数 MyClass.select(..., distinct=True) を追加します。この操作は、 SQL 文を SELECT DISTINCT 呼び出しにします。

MyClass.select().count() のように、結果のオブジェクトに対して count を呼び出すと、結果を全て取り出さなくても得られた結果の数を取得できます。 これには COUNT(*) クエリが使われ、実際のオブジェクトはデータベースから 取り出されません。こうした機能をスライスと合わせると、バッチ問い合わせを簡 単に書けるようになります:

start = 20 size = 10 query = Table.select() results = query[start:start+size] total = query.count() print "Showing page %i of %i" % (start/size + 1, total/size + 1)

問い合わせ時の where 節の利用については、 SQLBuilder ドキュメント も参照 してください。

>>> peeps = Person.selectBy(firstName="John", lastName="Doe")

sqlmeta クラス

This new class is available starting with SQLObject 0.7 and allows specifying metadata in a clearer way, without polluting the class namespace with more attributes.

There are some special attributes that can be used inside this class that will change the behaviour of the class that contains it. Those values are:

table:

データベースのテーブル名です。 名前を明示的に指定しなかった場合、 style とクラス名からテーブル名を決めます。名前を指定せず、かつ style を定義していない場合、 MixedCase から mixed_case のような標準の変換規則を使います。

idName:

主キーのカラム名です。名前を明示的に指定しなかった場合、 style をもとに決めます。デフォルトの名前は id です。

idType:

ID を設定する時に、 ID の値を型強制/正規化するための関数です。 デフォルトでは int (全ての ID が整数に正規化される) です。

style:

style オブジェクトです。このオブジェクトを使うと、Python の属性名やクラ ス名を，データベースのカラム名やテーブル名に変換するための方法をデフォ ルトとは別のものに指定できます。詳しくは 名前づけスタイルの変更 をご 覧下さい。値は IStyle インタフェースをもつインスタンスになります。

lazyUpdate:

ブール値 (デフォルト値は False) です。値が真の場合、属性値の設定 (あるい は inst.set(.) の呼び出し) を行っても、すぐに UPDATE クエリを送 信しません (更新には inst.syncUpdates() や inst.sync() を呼び出 します)。

defaultOrder:

オブジェクトの select 時に並び順を明示的に指定していない場合、この属性に 従ってデフォルトの並び順を決めます。この値は .select() や関連のメソッ ドに値を渡すのと同じです。詳しくは該当メソッドのドキュメントを参照してく ださい。

cacheValues:

ブール値 (デフォルト値は True) です。値が真の場合、インスタンスが保持さ れている間 (あるいは inst.expire() を呼び出すまでの間) 行内の値を キャッシュします。

値を False に指定すると、データベース上の値をキャッシュしません。そ のため、オブジェクトの属性値にアクセスするたびに、データベースへの問い合 わせ、例えば SELECT が発行されます。複数プロセスからの同一オブジェク トへのアクセスを処理したいなら、この方法を使って下さい。 (必ずというわけ ではありませんが トランザクション も使うことになるはずです。

registry:

Because SQLObject uses strings to relate classes, and these strings do not respect module names, name clashes will occur if you put different systems together. This string value serves as a namespace for classes.

fromDatabase:

A boolean (default false). If true, then on class creation the database will be queried for the table's columns, and any missing columns (possible all columns) will be added automatically.

columns:

A dictionary of {columnName: anSOColInstance}. You can get information on the columns via this read-only attribute.

columnList:

A list of the values in columns. Sometimes a stable, ordered version of the columns is necessary; this is used for that.

columnDefinitions:

A dictionary like columns, but contains the original column definitions (which are not class-specific, and have no logic).

joins:

このクラスに対する全ての Join オブジェクトからなるリストです。

indexes:

このクラスの全てのインデクスからなるリストです。

インスタンス属性も一つだけあります:

expired:

ブール値です。真の場合、次にオブジェクト属性へのアクセスが生じるとクエリ を発行します。

While in previous versions of SQLObject those attributes were defined directly at the class that will map your database data to Python and all of them were prefixed with an underscore, now it is suggested that you change your code to this new style. The old way will be removed when SQLObject 0.8 is out and you'll receive lots of warning messages saying that if you're not using the sqlmeta class you're doing things in a deprecated way.

class MyClass(SQLObject):

    class sqlmeta:
        lazyUpdate = True
        cacheValues = False

    columnA = StringCol()
    columnB = IntCol()

    def _set_attr1(self, value):
        # do something with value

    def _get_attr1(self):
        # do something to retrieve value

SQLObject クラス

Besides sqlmeta and columns specifications, there are a number of other special attributes you can set in your class. Those are listed below but, except for the _connection attribute, all other are superseded by the implementation shown before with sqlmeta. If you use them with SQLObject 0.7 you'll get warnings about their deprecation and you'll probably have to convert your code in future releases, when these are dropped.

_connection:

DBConnection クラスから生成された接続オブジェクトです。 クラスを定義しているモジュール内で __connection__ を指定しておく こともでき、その場合には __connection__ の値を使います (クラス定義の前に __connection__ が定義されているようにして下さい) トランザクション でも述べたように、接続オブジェクトはインスタンス生 成時に渡せます。

sqlhub.processConnection が指定されている場合、この属性がクラス内で 定義されていても無視され、 sqlhub の値を使うようになります。この機能は、 同じ接続オブジェクトを使えるような複数のクラスがある場合に、単にタイプ 数を減らす以上に役立つはずです。

_table:

以前使われていた属性で、 sqlmeta クラスの table 属性と同じよう に機能します。

_joins:

以前使われていた属性で、 sqlmeta クラスの joins 属性と同じよう に機能します。

_cacheValues:

以前使われていた属性で、 sqlmeta クラスの cacheValues 属性と同じよう に機能します。

_idName:

以前使われていた属性で、 sqlmeta クラスの idName 属性と同じように機 能します。

_style:

以前使われていた属性で、 sqlmeta クラスの style 属性と同じように機 能します。

オブジェクトのカスタマイズ

これまでの例題にはありませんでしたが、クラス定義には自作のメソッドも入れら れます。自作のメソッドを書く方法は明確 (単に他のクラスと同じように定義する だけ) ですが、気を付けておかねばならない点がいくつかあります。

class Person(SQLObject):
    # ...

    def imageFilename(self):
        return 'images/person-%s.jpg' % self.id

    def _get_image(self):
        if not os.path.exists(self.imageFilename()):
            return None
        f = open(self.imageFilename())
        v = f.read()
        f.close()
        return v

    def _set_image(self, value):
        # assume we get a string for the image
        f = open(self.imageFilename(), 'w')
        f.write(value)
        f.close()

    def _del_image(self, value):
        # I usually wouldn't include a method like this, but for
        # instructional purposes...
        os.unlink(self.imageFilename())

class Person(SQLObject):
    lastName = StringCol()
    firstName = StringCol()

    def _set_lastName(self, value):
        self.notifyLastNameChange(value)
        self._SO_set_lastName(value)

import re

class PhoneNumber(SQLObject):
    phoneNumber = StringCol(length=30)

    _garbageCharactersRE = re.compile(r'[\-\.\(\) ]')
    _phoneNumberRE = re.compile(r'^[0-9]+$')
    def _set_phoneNumber(self, value):
        value = self._garbageCharactersRE.sub('', value)
        if not len(value) >= 10:
            raise ValueError(
                'Phone numbers must be at least 10 digits long')
        if not self._phoneNumberRE.match(value):
            raise ValueError, 'Phone numbers can contain only digits'
        self._SO_set_phoneNumber(value)

    def _get_phoneNumber(self):
        value = self._SO_get_phoneNumber()
        number = '(%s) %s-%s' % (value[0:3], value[3:6], value[6:10])
        if len(value) > 10:
            number += ' ext.%s' % value[10:]
        return number

Col クラス: カラムを定義する

一連のカラムは Col オブジェクトのリストとして記述します。 このオブジェク トは機能は持たず、カラムを定義するために利用します。

dbName:

データベース上のカラム名です。名前を指定しない場合、大文字，小文字で単 語に区切られたクラス名をアンダースコアで単語を区切った文字列に変換して カラム名として利用します。

default:

カラムのデフォルト値です。列が新規に作成された場合に利用します。呼び出 し可能オブジェクトか関数を指定すると，関数が呼び出されて，返り値を利用 します。 DateTime.now と指定すると，現在時刻をデフォルト値として指定できます。 SQLBuilder.func.NOW() を指定すると，データベース内部の NOW() 関 数を利用します。デフォルト値を指定していなくて，`new`を呼び出したときに カラムに値を指定していない場合は、例外が発生します。

alternateID:

この boolean (デフォルトは False) で，カラムをプライマリ・キーでない ID (たとえばユーザ名のような) として利用できるかどうかを指定します。この値 が True の場合，``byUsername`` のようなクラス関数が追加されます。この関 数はカラムのオブジェクトを返します。もし by* 意外の関数名を利用した い場合は、 alternateMethodName を利用して下さい( alternateMethodName="username" のように指定します )。

この値が True の場合，カラムはスキーマで UNIQUE属性 を伴って定義する 必要があります。

unique:

Trueにすると SQLObject はこのカラムを, UNNIQUEなカラム として扱います。

notNone:

Trueにすると，このカラムに None や NULL を割り当てることができなく なります。SQLObject がテーブルを作成する場合に役立つでしょう。

sqlType:

カラムの型 ( INT ， BOOLEAN といった ) を定義します。型の定義に は以下に解説するクラスを利用しますが，適する型がない場合には sqlType を指定すればいいでしょう。 SQLObject がテーブルを作成する場合に利用しま す。

クラス，テーブル間のリレーション

ForeignKey を使うと，テーブル間のリレーションを定義できます。逆参照や多対 多のリレーションには Join を使って下さい。

CREATE TABLE person (
    id SERIAL,
    username VARCHAR(100) NOT NULL UNIQUE
);

CREATE TABLE role (
    id SERIAL,
    name VARCHAR(50) NOT NULL UNIQUE
);

CREATE TABLE assigned_roles (
    person INT NOT NULL,
    role INT NOT NULL
);

class Person(SQLObject):
    username = StringCol(length=100, alternateID=True)
    roles = RelatedJoin('Role', joinColumn='person', otherColumn='role', 
                        intermediateTable='assigned_roles')
class Role(SQLObject):
    name = StringCol(length=50, alternateID=True)
    roles = RelatedJoin('Person', joinColumn='role', otherColumn='person', 
                        intermediateTable='assigned_roles')

トランザクション

SQLObject のトランザクションサポートはデータベース依存となります。トランザ クションは以下のように使います:

conn = DBConnection.PostgresConnection('yada')
trans = conn.transaction()
p = Person.get(1, trans)
p.firstName = 'Bob'
trans.commit()
p.firstName = 'Billy'
trans.rollback()

ここにある trans オブジェクトは個別のデータベースコネクションオブジェク トのラッバで， commit と rollback は単に低水準のコネクションオブジェク トにメッセージを渡しているだけです。

.rollback() の後で新たなトランザクションを開始したければ、 .begin() を呼び 出してください。

トランザクションを利用する場合，`_cacheValues` を以下のように無効にする必要 があります:

class Person(SQLObject):
    _cacheValue = False
    # ...

スキーマを自動生成する

すべてのデータベース接続で，クラス定義からテーブルを作成したり削除する機能 をサポートしています。最初に，カラムに対する型の定義を含んだクラスを定義し てください。

firstLastIndex = DatabaseIndex('firstName', 'lastName')

lastNameIndex = DatabaseIndex({'expression': 'lower(last_name)'})

lastNameIndex = DatabaseIndex({'column': lastName, 'length': 10})

クラスの自動生成

SQLObject はデータベースからテーブル定義を読み込み，クラスのカラムを自動生 成できます。(_columns というアトリビュートに定義を記述してゆきます)

以下のようにします:

class Person(SQLObject):

    _fromDatabase = True

ここからさらにカラムを指定 ( _columns を使って) でき，存在しないカラムは, 追加されます。

• この機能は SQLite ではサポートされていません *

実行時間中にカラムを変更する

• この機能は SQLite ではサポートされていません *

実行時間中に，クラスを追加したり削除したりできます。クラス定義が変更される ため，変更は全部クラスインスタンスに影響を与えます。 addColumn と delColumn という 2 つの関数があり，どちらも Col オブジェクト (またはサ ブクラス) を引数として取ります。オプションの引数として， changeSchema が あります。 True にすると，カラムを追加したり削除したりします (たいていは ALTER コマンドを利用します)。

カラムを追加する場合， StringCol("username", length=20) のようにしてカ ラム名をカラムのコンストラクタに渡す必要があります。カラムを削除する場合も， Col オブジェクト ( _columns`に定義されているか， `addColumn で追加したも の) を利用できます。また，カラム名も使えます ( MyClass.delColumn("username") のようにします)。

MyClass.addJoin(MultipleJoin("MyOtherClass")) のようにして Joins を追 加することも出来ます。 delJoin を使うとJOINを削除できます。 delJoin に は文字列を渡さず， _joins アトリビュートにあるオブジェクトを指定してます。

SQLObject の制限

SQLObject はスキーマに対して多くの制限を設けないように作られていますが，い くつか前提条件があります。前提条件のうちいくつかは将来的に取り除かれるかも 知れません。

クラスに変換するテーブルはすべて整数の主キーを持っている必要があります。主 キーは以下のように定義する必要があります:

MySQL:

INT PRIMARY KEY AUTO_INCREMENT

Postgres:

SERIAL PRIMARY KEY

SQLite:

INTEGER PRIMARY KEY

SQLObject は複数カラムからなる主キーをサポートしません (この仕様は恐らく今 後も変わらないでしょう)。また、基本的には、主キーが何らかの実用的な意味 (business meaning) を持つようなテーブルもサポートしません -- すなわち、主キー は不変のものと想定しています (この仕様は今後決して変更されません)。

今の時点では，外部キーのカラム名は "ID" で終わっている必要があります (必ず大文字で記述します)。この制限は次のリリースで取り除く予定です。

名前づけスタイルの変更

デフォルトでは，SQLObject の名前付けは Python 風に大文字小文字が混在した表 記 (たとえば mixedCase ) か，アンダースコアで区切られた SQL 風の表記 (たとえば mixed_case )となります。このルールはテーブル名とカラム名に適 用されます。主キーは単純に id として扱います。

別のスタイルも存在します。典型的な例は大文字小文字混在のカラム名，それに主 キーにテーブル名が含まれているスタイルでしょう。別の "Style" オブジェクトを 使って，命名規則を変更できます。例えば以下のようにします:

class Person(SQLObject):
    _style = MixedCaseStyle(longID=True)

    firstName = StringCol()
    lastName = StringCol()

Person.createTable() を使う場合，以下のようにします:

CREATE TABLE Person (
    PersonID INT PRIMARY KEY,
    FirstName Text,
    LastName Text
)

MixedCaseStyle オブジェクトが単語の最初の文字を大文字にし，それ以外はその ままにします。 longID=True とすることで，主キーをよく見るスタイルに変更 します。(MixedCaseStyle を使うと PersonID になりますが，デフォルトで は person_id のようになります)

スタイルを全体に渡って変更したい場合には，コネクションオブジェクト (connection) に適用します。以下のようになります:

__connection__.style = MixedCaseStyle(longID=True)

不正な名前づけの扱い

命名規則は便利ですが，常に利用できるとは限りません。Pythonの利用する名前意 外であれば，SQLObject が利用する名前のほとんどをコントロールできます。

以下が簡単な例です:

class User(SQLObject):
    _table = "user_table"
    _idName = "userid"
    username = StringCol(length=20, dbName='name')

_table というアトリビュートはテーブル名をオーバーライドします。 _idName を定義すると id の代わりに利用する文字列を指定できます。 dbName と いうキーワード引数はカラム名を与えます。

非整数のキー

キーとして整数意外を利用している場合，主キーの扱いをすべて別途行う必要があ ります。テーブルを自分自身で作成する必要がありますし，コンストラクタに常に id というキーワード引数を与える必要があります ( Person(id='555-55-5555', ...) のようにします)。

MySQL

MySQLConnection は host ， port ， db ， user ， passwd という キーワード引数を取ります。引数の意味は MySQLdb.connect と同じです。

MySQLConnection は SQLObject のすべての機能をサポートします。InnoDB を利用 している場合にのみ トランザクション をサポートします。 SQLObject は現状 createTable を使った明示的なテーブル定義をサポートしていません。

PostgreSQL

PostgresConnection には "dbname=something user=some_user" のような接 続文字列をひとつだけ渡します。 psycopg.connect のとる引数と同様です。 MySQLConnection が取るキーワード引数を利用することもでき， dns を生成しま す。

PostgresConnection はトランザクションを含めすべての機能をサポートします。

SQLite

SQLiteConnection は単一のキーワード引数をとり，データベースファイルのパス を渡します。

SQLite は全データをひとつのファイルに書き込み，また処理中は記録用のファイル をデータファイルと同一のフォルダに作成します(プログラムが終了するとファイル は消されます)。 SQLite ではカラムに記入するタイプの制限はありません -- 整数 型のカラムに文字列を記入することもできますし，日付を記入することなどもでき ます。

SQLiteConnection は クラスの自動生成 をサポートしません。また， 実行時間中にカラムを変更する 機能もサポートしません。

マルチスレッドで利用する場合，SQLite では同時実行の問題が発生するかも知れま せん。

Firebird

FirebirdConnection は host ， db ， user (デフォルトは "sysdba" )， passwd (デフォルトは "masterkey") の引数をサポートします。 Firebird は SQLObject の全機能をサポートします。全機能をサポートするように なって日が浅く，不具合が潜んでいるかも知れません。特にマルチスレッド稼働時 や lazy select を利用する際には注意してください。マルチスレッドでカーソルを 利用中，問題が発生したら list(MyClass.select()) を試してみて下さい ( list() を利用すると選択結果を事前にすべて取得します)。

Firebird は Pythonライブラリ kinterbasedb の利用をサポートしています。

インデックスを利用していて， key size exceeds implementation restriction for index (キーのサイズがインデックスに実装されている値より大きい) というエラーが発 生したら， このページ を見てインデックスについての制限を理解して下さい。

SybaseConnection

SybaseConnection は host ， db ， user ，と passwd という引数を取 ります。 locking というBooleanの引数を加えることができ，(デフォルトは True) 接続を確立する際に利用します。マルチスレッドで利用しない場合，False を指定すると少しだけ実行が早くなります。

SybaseConnection は Sybase モジュールを使います。

MAX DB

MAX DB は， SAP DB としても知られ， SAP と MySQL が共同で開発しています。 MAX DB 用の接続オブジェクトは以下の典型的な引数を伴います。 host ， database ， user ， password です。 sqlmode という引数を渡すことも でき，(デフォルトは "internal")， isolation ，および timeout を渡す と，データベースとの接続時に利用されます。

MAX DBは sapdb モジュールを利用しています。

LEFT JOIN and other JOINs

First look in the FAQ, question "How can I do a LEFT JOIN?"

Still here? Well. To perform a JOIN use one of the JOIN helpers from SQLBuilder. Pass an instance of the helper to .select() method. For example:

from sqlobject.sqlbuilder import LEFTJOINOn
MyTable.select(
    join=LEFTJOINOn(Table1, Table2,
                    Table1.q.name == Table2.q.value))

will generate the query:

SELECT * FROM my_table, table1
LEFT JOIN table2 ON table1.name = table2.value;

If you want to join with the primary table - leave the first table None:

MyTable.select(
    join=LEFTJOINOn(None, Table1,
                    MyTable.q.name == Table1.q.value))

will generate the query:

SELECT * FROM my_table
LEFT JOIN table2 ON my_table.name = table1.value;

The join argument for .select() can be a JOIN() or a sequence (list/tuple) of JOIN()s.

Available joins are JOIN, INNERJOIN, CROSSJOIN, STRAIGHTJOIN, LEFTJOIN, LEFTOUTERJOIN, NATURALJOIN, NATURALLEFTJOIN, NATURALLEFTOUTERJOIN, RIGHTJOIN, RIGHTOUTERJOIN, NATURALRIGHTJOIN, NATURALRIGHTOUTERJOIN, FULLJOIN, FULLOUTERJOIN, NATURALFULLJOIN, NATURALFULLOUTERJOIN, INNERJOINOn, LEFTJOINOn, LEFTOUTERJOINOn, RIGHTJOINOn, RIGHTOUTERJOINOn, FULLJOINOn, FULLOUTERJOINOn, INNERJOINUsing, LEFTJOINUsing, LEFTOUTERJOINUsing, RIGHTJOINUsing, RIGHTOUTERJOINUsing, FULLJOINUsing, FULLOUTERJOINUsing.

How can I join a table with itself?

Use Alias from SQLBuilder. Example:

from sqlobject.sqlbuilder import Alias
alias = Alias(MyTable, "my_table_alias")
MyTable.select(MyTable.q.name == alias.q.value)

will generate the query:

SELECT * FROM my_table, my_table AS my_table_alias
WHERE my_table.name = my_table_alias.value;

Can I use a JOIN() with aliases?

Sure! That's a situation the JOINs and aliases were primary developed for. Code:

from sqlobject.sqlbuilder import LEFTJOINOn, Alias
alias = Alias(OtherTable, "other_table_alias")
MyTable.select(MyTable.q.name == OtherTable.q.value,
    join=LEFTJOINOn(MyTable, alias, MyTable.col1 == alias.q.col2))

will result in the query:

SELECT * FROM other_table,
    my_table LEFT JOIN other_table AS other_table_alias
WHERE my_table.name == other_table.value AND
    my_table.col1 = other_table_alias.col2.

Subqueries (subselects)

You can run queries with subqueries (subselects) on those DBMS that can do subqueries (MySQL supports subqueries from version 4.1).

Use corresponding classes and functions from SQLBuilder:

from sqlobject.sqlbuilder import EXISTS, Select
select = Test1.select(EXISTS(Select(Test2.q.col2, where=(Outer(Test1).q.col1 \
== Test2.q.col2))))

generates the query:

SELECT test1.id, test1.col1 FROM test1 WHERE
EXISTS (SELECT test2.col2 FROM test2 WHERE (test1.col1 = test2.col2))

Note the usage of Outer - it is a helper to allow referring to a table in the outer query.

Select() is used instead of .select() because you need to control what columns the inner query returns.

Available queries are IN(), NOTIN(), EXISTS(), NOTEXISTS(), SOME(), ANY() and ALL(). The last 3 are used with comparison operators, like this: "somevalue = ANY(Select(...))".

SQLBuilder

SQLBuilder の詳細については SQLBuilder ドキュメント を参照してください。