metadata = BoundMetaData(db)

Before creating our Table definitions, we need to create the object that will manage them. Table definitions (what the columns are called, what their data types are) are an example of "metadata" -- information about your data. So the object that manages this collection of metadata is called a MetaData object. There are two varietes, BoundMetaData which is tied to a specific database connection, or DynamicMetaData which can be created before the database connection has been established.

If you don't know why you'd want to use DynamicMetaData, or if you didn't really understand the previous paragraph, don't worry about it. Just remember that you'll need a BoundMetaData to keep your Table objects in, and move on to the rest of the tutorial.

New in 0.2: In SQLAlchemy 0.1, you'd pass the db object to your Tables; and, in fact, this is still allowed; it will automatically create a BoundMetaData object for you. It's better to create theBoundMetaData object explicitly, though, because that makes it a lot easier to do operations like metadata.create_all() to create all your tables at once.

users = Table('users', metadata,
    Column('user_id', Integer, primary_key=True),
    Column('name', String(40)),
    Column('age', Integer),
    Column('password', String),
)
users.create()

This should be pretty self-explanatory: we've just created a users table in our database, with four columns. If the users table already existed, we could instead have done:

users = Table('users', metadata, autoload=True)

and SQLAlchemy would have automatically figured out the table's structure from the database.

i = users.insert()
i.execute(name='Mary', age=30, password='secret')
i.execute({'name': 'John', 'age': 42},
          {'name': 'Susan', 'age': 57},
          {'name': 'Carl', 'age': 33})

SQLAlchemy's SQL construction methods are beautiful. You'll almost never need to write SQL by hand. Instead, you create an "SQL statement object", build the SQL query you want, and call itsexecute() method. Here we ask for an INSERT statement referencing the users table:

i = users.insert()

Now when we do i.execute(), SQLAlchemy will generate the appropriate "INSERT INTO users VALUES (...)" statement for the values we pass into execute(). Notice the two different ways of executing an INSERT statement. We can either pass it keyword parameters, to insert a single object:

i.execute(name='Mary', age=30, password='secret')

or else we can pass it multiple dictionaries, to insert multiple objects:

i.execute({'name': 'John', 'age': 42},
          {'name': 'Susan', 'age': 57},
          {'name': 'Carl', 'age': 33})

If you have any "special" characters (such as semicolons or apostrophes) in your data, they will be automatically quoted for you by the SQLEngine object, so you don't have to worry about quoting. This also means that unless you deliberately bypass SQLAlchemy's quoting mechanisms, SQL-injection attacks are basically impossible.