annotation `Athena::ORM::Annotations::Column` #

Maps an instance variable to a column of the entity's table. Only instance variables with this annotation, or an association annotation such as AORMA::ManyToOne, are persisted.

@[AORMA::Entity]
class Message < AORM::Entity
  @[AORMA::Column]
  @[AORMA::ID]
  @[AORMA::GeneratedValue]
  property! id : Int64

  @[AORMA::Column(length: 140)]
  property! text : String

  @[AORMA::Column(name: "posted_at")]
  property! posted : Time
end

In this example:

id maps to the id column using the bigint type
text maps to the text column using the string type
posted maps to the posted_at column using the datetime type

Column Types#

A column's type converts values between their Crystal and database representations, see AORM::Types::Type. When no type is given, it's inferred from the instance variable's Crystal type:

Crystal Type	Column Type
`String`	`string`
`Bool`	`boolean`
`Int16`	`smallint`
`Int32`	`integer`
`Int64`	`bigint`
`Float32`	`smallfloat`
`Float64`	`float`
`Time`	`datetime`
`UUID`	`guid`
`Bytes`	`blob`
`BigDecimal`	`number`
`Enum`	`integer`, or `bigint` if the enum's base type is wider than `Int32`

A nilable instance variable, such as one declared with property!, maps the same way as its non-nilable type. Any other Crystal type requires an explicit type, such as the name of a custom type, otherwise an exception is raised when the entity's metadata is built.

Note

BigDecimal is only mapped when the program defines it, i.e. it requires "big".

Enums#

Enum instance variables are stored as the integer value of their member, and hydrated back into the enum. A database value that isn't a member of the enum raises an ArgumentError when it's hydrated.

enum PostStatus
  Draft
  Published
end

@[AORMA::Entity]
class Post < AORM::Entity
  # ...

  @[AORMA::Column]
  property status : PostStatus = PostStatus::Draft
end

em.repository(Post).find_by status: PostStatus::Published

The keyword argument finders of AORM::EntityRepository accept enum members, as shown above. Criteria given as a Hash need the member's integer value instead.

Todo

Storing an enum member by its name isn't supported yet.

Quoting Reserved Words#

Table and column names are used in SQL as written, without quoting them. Quoting isn't automatic because it changes which table or column a name refers to on some databases; e.g. Postgres folds unquoted names to lowercase, but matches quoted names exactly. If a name is a reserved word, wrap it in backticks to have it quoted, using the quoting style of the database in use:

@[AORMA::Column(name: "`order`")]
property! order : Int32

The same applies to the names given to AORMA::Table, AORMA::JoinColumn, AORMA::InverseJoinColumn, and AORMA::JoinTable.

Configuration#

Optional Arguments#

name#

Type: String Default: the name of the instance variable

The name of the column.

type#

Type: String Default: inferred from the instance variable's type

The name of the AORM::Types::Type used to convert the column's values. See AORM::Types for the names of the built-in types.

insertable#

Type: Bool Default: true

Whether the column is included in the INSERT statement of a new entity. Values the database stores instead, such as a column default, aren't read back into the entity; use AORM::EntityManager#refresh to load them.

updatable#

Type: Bool Default: true

Whether the column is included in the UPDATE statement of a changed entity.

nullable#

Type: Bool Default: false

Whether the column allows NULL values.

Todo

Only used to generate a schema, which isn't supported yet. Whether an instance variable can be nil comes from its Crystal type.